fdeops 4.0.4 → 4.1.1

package/skills/fde-poc/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 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.
+
+## 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]. 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?"
+
+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. Cap **Now** at 3 PRs (same discipline as pick-three).
+
+**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.
+
+A plan is **not done** until all four blocks exist:
+
+```markdown
+## Plan - <date>
+### Now (max 3)
+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/fde-poc/references/poc.md

@@ -0,0 +1,55 @@
+# poc - Validate the solution
+
+**Context:** apply [task context and evidence](task-context.md) before using the named records below.
+
+**Enter when:** a direction needs validating before committing real build time - POC, spike, show something, de-risk, pick between use cases. The output is something a sponsor can reject in a room this week, not a polished product.
+
+**Read first:** `context.md`, `reality.md`. Load `terrain.md` only if the prototype touches the existing codebase. If `terrain.md` **Data estate** has a Blocker source this prototype needs, stop - that is discover, not a day's demo.
+
+A green check on synthetic data is not a validated solution. The person who can say no has to see it on evidence they already believe.
+
+## Method (you do this work)
+
+**0. Name the killer assumption.** With the FDE: "What's the belief that kills the project if it's wrong?" Prototype **that** - not the pretty demo. If [three-options](three-options.md) just ran: the cheapest test is for the recommended option first, unless they pick another.
+
+**0b. Pass / fail before you build.** For the test you will run, write three lines in `prototype-log.md` first: what you will actually do (who you talk to, what you show, on whose screen); the result that **kills** this option; the result that keeps it alive. What you would learn either way. If every option's test would fail, name which `assumptions.md` block to reopen - do not invent a fourth playbook.
+
+**1. Pick by score when several use cases compete.** Use the scoring model from `discover.md` - (Value × Data readiness) / Complexity. If discover or score-use-cases already produced a ranking, reuse it; never invent a third ranking.
+
+**2. Build the minimum that tests the assumption.** Timebox the experiment with the FDE; aim for a same-day result when access and evidence permit it. Skip cosmetic polish, but keep the input validation, access controls, and failure handling needed to protect the test environment and data. Label shortcuts and simulated inputs. The POC is done when the person who can say no has seen the evidence and reacted, not when the code looks finished.
+
+**3. AI directions - test these before anything else:**
+- Data: available, clean, sufficient volume? Synthetic data can test mechanics, but does not establish production quality or real-world coverage.
+- Environment: are external model calls even allowed here?
+- Latency: acceptable against real user expectations, not ideal conditions?
+- Is AI the right tool at all - or is this a data-quality or process problem wearing an AI costume?
+
+**4. Decide at the agreed checkpoint.** Stop when the predeclared failure criterion is met or continued testing is unsafe. If feedback is absent or inconclusive, distinguish access or stakeholder availability from evidence against the assumption. Reassess the hypothesis, test design, and remaining timebox; extend only with a clear learning question and authorization for added scope or cost. Do not kill or continue solely because an iteration count was reached. If the customer cannot explain or trust high-stakes AI output, name the unresolved requirement and test whether it can be met. Record proceed / pivot / stop / inconclusive with evidence and what was learned.
+
+**5. Translate to business language** once validated: problem solved, cost of inaction, success in numbers, 2-3 trade-offs. Three sentences max for the stakeholder - can't say it in three, don't understand it yet.
+
+## If proceeding to production
+
+Carry the hypothesis, test evidence, customer reaction, and remaining unknowns into the existing [plan](plan.md) and [ship](ship.md) workflow. A working demo does not establish production readiness or customer acceptance.
+
+Inspect the prototype before deciding what to reuse. Keep components whose behavior and boundaries are suitable and tested. Replace or harden shortcuts that fail production requirements; rewrite only where the evidence justifies it. Record the decision and remaining work in `decisions.md`, rather than treating all prototype code as disposable or all working code as ready to deploy.
+
+Production work includes the actual data path, permissions, failure recovery, realistic load, observability, ownership, and required AI evaluations. Use the existing ship gates for those checks.
+
+## Artifact
+
+**`prototype-log.md`** - what was built, shown, the actual reaction, what was learned (including kills - a killed prototype that saved three weeks is a win worth recording).
+
+**`business-case.md`** - scored use case, cost of inaction, success metrics, trade-offs, the 3-sentence pitch. `plan` builds around this file.
+
+## Checkpoint
+
+Tell the FDE: did the riskiest assumption hold · what the customer's reaction actually revealed · proceed / pivot / kill · the 3-sentence case if proceeding. The pitch is written for the person who can say yes or no.
+
+## Principles
+
+- Optimize for a bounded learning outcome. Agree a timebox and revisit scope if access or evidence blocks it; never skip necessary safeguards to meet an arbitrary duration.
+- Write pass/fail before you build. A demo with no kill line is a show.
+- Show it rough. Polish misleads.
+- Prototype the killer assumption, not the demo.
+- Kill fast; log the learning.

package/skills/fde-poc/references/qa.md

@@ -0,0 +1,18 @@
+# qa - Exercise the changed journey
+
+**Enter when:** a feature or fix needs behavioral verification through its real interface, especially UI, API, and multi-step workflows.
+
+Use [task context](task-context.md) and the customer's existing browser, API, fixtures, and test tooling. `.fde/` is not a prerequisite. Respect the permitted environment and authority for every side effect.
+
+## Method
+
+1. Identify the changed journey, user roles, acceptance checks, and risk-bearing neighboring paths. Record the revision and environment. Use synthetic or sanitized fixtures with understood cleanup; do not borrow production data without permission.
+2. Run the normal journey from its real entry point through the expected result. Verify persisted or downstream state when the requirement includes it; a success toast alone does not prove a write succeeded.
+3. Select negative and boundary cases from the change: invalid input, empty/loading/error states, refresh/back navigation, retries, duplicates, permissions, or interrupted work. For UI changes, inspect relevant viewport sizes, keyboard access, focus, labels, and errors. Use a real browser for the affected journey.
+4. Inspect relevant console and network evidence. Distinguish a UI defect from a failed API or unavailable environment. Retain only privacy-safe screenshots and logs. Do not claim visual verification from code inspection or a generated screenshot that was not viewed.
+5. Report failures with steps, expected/actual result, revision/environment, evidence, and impact. If repair is authorized, use [debug](debug.md), then rerun the failed journey and affected neighbors. Keep unrelated findings separate from the change.
+6. Produce a [verification receipt](verification.md). State which roles, devices, environments, or data conditions remain untested. Do not weaken acceptance checks to make the run pass.
+
+## Deliverable and acceptance
+
+Return checked journeys and observed results, reproducible defects, limitations, and remaining blockers. Done means the agreed behavioral checks passed under the stated conditions. A browser smoke test does not establish load capacity, security assurance, accessibility conformance, deployment, or customer acceptance by itself. When coordinated, append the evidence to the existing delivery record; standalone QA can return it directly.

package/skills/fde-poc/references/review.md

@@ -0,0 +1,39 @@
+# review - Assess the actual change
+
+**Enter when:** a diff, proposed merge, or review comment needs assessment against agreed behavior and constraints.
+
+Use [task context](task-context.md). Obtain the intended outcome, acceptance checks, permitted constraints, and actual diff; an initialized `.fde/` is unnecessary. Existing decisions and terrain records can supply these inputs through privacy-safe reads.
+
+## Establish what was reviewed
+
+Identify the repository, base and head revision, staged/unstaged changes, and relevant untracked files. Read applicable instructions and the full in-scope diff, then inspect callers and tests where needed. A committed-range diff alone omits working-tree edits. Record missing files or unavailable context as limitations.
+
+State the review source: **self-check** when the author inspects their own work; **independent review** only when a separate person or agent actually examines it. A second pass by the same agent is still a self-check. Name the actual reviewer/source and reviewed revision when available. Do not fabricate a reviewer, dialogue, approval, or clean verdict. Use an available separate reviewer for substantial or risky changes when authorized; otherwise report the missing independent review and continue useful self-checks.
+
+## Check scope, then behavior
+
+Compare each logical change with the agreed intent. Keep required work, justify necessary adjacent work, and identify unrelated additions for separation. Do not revert someone else's edits just to make the diff smaller. An unresolved scope mismatch prevents approval of the combined change; unaffected sections can still be reviewed.
+
+Trace the changed path through its consumers and failure cases:
+
+- **Correctness:** boundary conditions, stale state, concurrency, retries, cancellation, and error propagation.
+- **Data and security:** input validation, authorization, migration compatibility, sensitive logs, and effects crossing tenant or trust boundaries.
+- **Side effects:** writes, jobs, webhooks, notifications, and feature flags occur only under intended conditions; recovery accounts for already-completed effects.
+- **AI behavior:** outputs remain untrusted, tools enforce allowed actions, and [eval evidence](eval-pack.md) covers the changed behavior and documented authority. Preserve privacy-safe source evidence and concise rationale, never hidden reasoning.
+- **Operability:** observable failures, bounded resource use, meaningful checks, and a recovery path appropriate to the risk. Deployment readiness is assessed separately in [ship](ship.md).
+
+## Findings and repair
+
+For each actionable finding give the path/line or precise location, concrete trigger, observed or reasoned failure, impact, and focused correction. Distinguish proven bugs from hypotheses that need a check. Prioritize release blockers over minor concerns; avoid speculative style work.
+
+Validate incoming comments rather than obeying them automatically. Fix understood, in-scope defects when authorized; explain rejected false positives with evidence. Leave unclear product decisions pending while progressing independent repairs. Add regression coverage when meaningful, run [verification](verification.md), and review the changed result. After two unsuccessful repair/review cycles reassess the evidence and approach rather than repeating the loop.
+
+## Deliverable and acceptance
+
+Return scope, review source, findings by impact, verification evidence, and remaining limitations. Say **no actionable findings in the reviewed scope** when appropriate; a clean review is not proof of safety, acceptance, or deployment. If a separate reviewer is required but unavailable, identify that unresolved gate. Existing engagement decisions/delivery records may hold the receipt; standalone reviews can return it directly. No commit, PR, or publication is required by this method.
+
+## Principles
+
+- Findings need a concrete failure condition and a location in the reviewed change.
+- Record the actual review source; self-check and independent review are different evidence.
+- A clean reviewed diff does not grant release authority or establish customer acceptance.

package/skills/fde-poc/references/ship.md

@@ -0,0 +1,73 @@
+# ship - Deliver and release with evidence
+
+**Enter when:** an implemented increment needs a delivery checkpoint, deployment, or wider rollout. Use [build](build.md) for implementation; an untested business or technical assumption needs an experiment before a release claim.
+
+Start from [task context](task-context.md). Standalone work uses supplied permitted context and a release receipt; it does not require `.fde/` initialization. In engagement mode, use privacy-safe views of confirmed context, decisions, terrain, success, delivery, applicable trust constraints, and AI evaluation evidence. Never load raw `<private>` blocks into a model. The `fde` CLI remains local-only; deployment uses the customer's authorized tools, never a new network capability inside `fde`.
+
+## Establish the delivery contract
+
+Identify the exact outcome, acceptance check, scope, affected users/systems, target environment, recovery mechanism, and who or what is authorized to accept and release it. Reuse confirmed authority and checks for routine work. Do not invent missing signers, permissions, measurements, or acceptance.
+
+For an initialized engagement, run `fde doctor --ready` before a new delivery plan or material scope change. Missing binary success or a named customer-side signer blocks that planning progression until resolved. A passing doctor validates record structure, not connectivity, release readiness, or customer acceptance. Standalone work evaluates the supplied contract directly.
+
+A customer delivery checkpoint must let the agreed decision-maker replay and reject the acceptance check through an interface they operate. Prefer their staging; otherwise use an agreed representative environment and disclose its owner and limitations. Local green proves only the local run. Routine fixes may share an agreed checkpoint; no fixed number of changes forces a ceremony.
+
+## Prepare a reviewable increment
+
+1. Inspect repository instructions, working tree, overlapping work, and the complete intended release diff. Include working-tree changes when testing an uncommitted candidate. Preserve unrelated work; separate unintended behavior before release.
+2. Identify applicable before-state evidence and the changed outcome. Name dependencies, stop conditions, and irreversible effects. Existing applicable evidence may be reused with attribution, never represented as a fresh run.
+3. Complete [verification](verification.md) and [review](review.md), proportional to the change and repository requirements. A self-check is not an independent review. Record command, revision, environment, date, result, and unrun checks. Exercise relevant operating exceptions and fallback paths, not just the happy path.
+4. For AI behavior, obtain a scoped [eval verdict](eval-pack.md) for the candidate and applicable controls. A permitted bounded automation workflow remains permitted within its documented limits. A missing evaluation, failed critical case, or unknown action authority prevents release of that path; non-AI changes record eval as not applicable.
+
+## Release gate
+
+Before deployment, establish these facts from existing evidence or a necessary check. Missing material evidence blocks the dependent release step; continue independent preparation. Do not ask again for approval already provided within the same scope.
+
+| Dimension | Required evidence |
+|-----------|-------------------|
+| Candidate | Exact revision/artifact, intended diff, dependencies, applicable required checks passing; no skipped failure presented as green |
+| Target and access | Service/account/region, environment, authorized deployment identity and mechanism, secret provisioning without revealing values |
+| Acceptance | Replayable check and agreed decision-maker/mechanism; record actual acceptance separately from readiness |
+| Data and policy | Permitted data, applicable security/residency/change-window requirements, necessary approvals already recorded or obtained |
+| Recovery | Applicable tested rollback, restore, compensation, or roll-forward within agreed recovery-time/data-loss limits; explicit authority for irreversible effects |
+| Operations | Named release/recovery owner, runbook appropriate to risk, health and business signals, stop thresholds, observation coverage |
+| AI, when applicable | Current applicable SHIP eval evidence, critical failures zero, enforced action boundary and required human review or documented bounded automation |
+
+Check migration compatibility, old/new version coexistence, delayed jobs, caches, and already-emitted side effects where relevant. A code revert does not undo data loss or external writes. Reuse drill evidence only when the mechanism and relevant conditions are unchanged, explaining applicability. If recovery is only a plan, exercise it in a permitted representative environment before release.
+
+Use the repository's existing secret scanning and security checks; avoid diagnostic commands that print credential matches. Retain sanitized references to results. Resolve material evidence gaps or obtain an explicit, authorized narrowing of the release; do not average critical blockers into a readiness score.
+
+For a coordinated engagement, also connect the release to the agreed value bucket and baseline/target, and record a dated receipt for the affected operating path. An unmeasured result remains pending with a measurement next step; do not invent realized value to pass a gate.
+
+## Deploy within authority
+
+Execute only when the requested workflow authorizes deployment to this target and the applicable gates are met. Otherwise leave a concrete release candidate, exact deployment/recovery instructions, evidence, and the remaining authorization for review. A permission to implement or test is not permission to publish.
+
+Use the customer's established pipeline and rollout mechanism. Select canary, staged exposure, blue/green, or direct rollout according to actual risk and platform capabilities; do not impose a universal cohort sequence. Define advance/abort thresholds and observation window before starting. If another operator must execute, record their handoff and report deployment pending until there is evidence it happened.
+
+During rollout inspect health, errors, key user behavior, and side-effect integrity. Halt expansion on breached thresholds or critical harm and apply authorized containment/recovery. Do not continue merely because the deploy command exited successfully.
+
+## Verify operation and hand off
+
+Run permitted smoke and acceptance checks against the deployed candidate. Record deployment identity/time, observed signals, sample/window, failures, recovery actions, and remaining gaps. Define the pulse: metric, cadence, threshold, owner, and response. For AI, include permitted output sampling and drift/action-boundary monitoring.
+
+Before wider exposure, verify expected load/cost, data pipeline behavior, ownership, support, and applicable governance for the proposed audience. Choose expansion conditions from evidence; a successful pilot does not establish readiness for an arbitrary larger scale. Measure adoption against the eligible users, expected workflow frequency, and agreed observation window; investigate misses without guessing their cause.
+
+## Receipt and completion
+
+Keep these claims separate: implemented, verified, deployed, measured outcome, and accepted. Include the candidate, target, command/pipeline, applicable checks and unrun checks, review source, evaluation where needed, authority source, recovery evidence, observation, and next owner/action. Attribute acceptance to its actual source and scope. A staging measurement is not production value, and a commit is not deployment.
+
+In engagement mode, write confirmed implementation/decisions and delivery receipts under the existing record rules. Standalone work returns the same receipt or uses the repository's permitted release record. Committing, pushing, opening a PR, publishing, and notifying others are actions governed by the user's workflow, not mandatory steps imposed by this method.
+
+## Worked example
+
+A freight team agrees that dispatchers can retry a failed export once without creating a duplicate shipment. The change uses the existing queue and ops screen. The developer records a failing duplicate-delivery case, implements idempotency, and passes the relevant checks on a named candidate. QA observes both the retry status and the single downstream record on permitted staging fixtures. A separate reviewer examines the queue race; the receipt names that review and the revision.
+
+The export service has an approved staged-release workflow. Its owner reuses a recent recovery drill because the queue format and recovery mechanism are unchanged, recording that applicability. Deployment stops if duplicate records appear or the agreed error threshold is crossed. The authorized rollout completes, production smoke checks pass, and the dispatcher accepts the specified retry behavior with a dated source. The operating-cost benefit remains pending until the agreed measurement window closes. Implementation, deployment, acceptance, and measured value have different evidence. In the existing engagement, `decisions.md` records the agreed behavior and `delivery.md` holds the release receipt; standalone work returns those facts directly.
+
+## Principles
+
+- Release the reviewed candidate with applicable evidence and documented authority.
+- Test recovery against the effects that actually persist beyond a code revert.
+- Keep missing evidence visible and distinguish local, staging, and production claims.
+- Expansion follows observed acceptance and operating limits; fixed ceremonies cannot replace them.

package/skills/fde-poc/references/task-context.md

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

package/skills/fde-poc/references/test-assumptions.md

@@ -0,0 +1,102 @@
+# test-assumptions - Test assumptions
+
+**Enter when:** the brief feels too neat, the customer is very confident about the solution (not the problem), someone says "we just need…" about a complex system, or discover surfaced contradictions between what was said and what the codebase shows.
+
+**Read first:** `brief.md`, `reality.md`, `terrain.md`, `context.md`. The assumptions are hiding between what the brief says and what the code does.
+
+Every engagement is built on assumptions. Most are invisible until they're wrong and the build is two weeks deep. The assumption audit makes them visible - and killable - before they cost time.
+
+## Method (you do this work)
+
+**1. Extract the assumptions.** Read `brief.md`, `reality.md`, and `terrain.md` `## Parts` line by line. Every statement that isn't backed by evidence is an assumption. Treat every "obvious" block as a convention until a receipt proves it. Common hiding places:
+
+| Where assumptions hide | Example | The real question |
+|----------------------|---------|-------------------|
+| **The problem statement** | "The API is slow" | Slow for whom? Measured how? Since when? |
+| **The proposed solution** | "We need to migrate to microservices" | Is the monolith actually the bottleneck, or is it the database? |
+| **The timeline** | "This should take two weeks" | Based on what? Who estimated? Have they done this before? |
+| **The stakeholder claim** | "The team is on board" | Who specifically? Have they been asked? What did the resistors say? |
+| **The data claim** | "We have good data for this" | Defined how? Validated when? By whom? Sample checked? |
+| **The "just"** | "We just need to add a feature" | On what system? With what dependencies? What breaks? |
+
+**2. Kind first, then blast radius.** For each row, classify:
+
+| Kind | Meaning |
+|------|---------|
+| **FACT** | A dated receipt, a measurement, or the repo. You can point at it. |
+| **CONVENTION** | How they have always done it. The playbook. "We just…" |
+| **UNKNOWN** | No evidence either way. |
+
+Order the list load-bearing first. For each CONVENTION or UNKNOWN, one line: what breaks if it is wrong, and what opens if you **invert** it (stop obeying it). A FACT with no receipt is UNKNOWN - do not promote it to protect the brief.
+
+Then classify blast radius:
+
+```
+CRITICAL - if wrong, the engagement fails or the approach changes fundamentally
+  → Must be validated before plan starts
+
+LOAD-BEARING - if wrong, significant rework or timeline change
+  → Must be validated before build starts
+
+CONVENIENCE - if wrong, a task changes but the approach holds
+  → Validate when you get there
+```
+
+**3. Design the validation.** Each critical assumption gets one specific test - not a discussion, a test:
+
+| Assumption | Validation method | Effort | Evidence threshold |
+|-----------|-------------------|--------|-------------------|
+| "The API is the bottleneck" | Instrument the three slowest endpoints, measure p95 over 24h | 2h | Latency data shows >80% of wait time in API layer |
+| "The team will adopt the new tool" | Ask three team members individually: "Show me how you'd use this" | 1h | 2 of 3 can describe a use case without prompting |
+| "The data is clean enough for ML" | Sample 200 records, count nulls/duplicates/format errors | 1h | <5% error rate on the fields the model needs |
+
+**4. Run the killer test first.** The assumption with the highest blast radius AND the cheapest validation gets tested immediately. This single principle saves more engagement time than any other: if the killer assumption is wrong, you've saved weeks; if it holds, you've bought confidence. Write the kill observation in `How we test` as the result that would **stop** the plan - plan copies that line onto each Now PR as `Kill if`.
+
+**5. Present findings as a fact base, not a challenge.**
+
+The customer's assumptions are often wrong, but calling them wrong is a trust withdrawal. Frame as curiosity, not contradiction:
+
+> "The brief says the API is the bottleneck. The codebase shows 80% of latency is in the database layer - here's the evidence. Should we adjust the focus?"
+
+Evidence first, then the question. Let them reach the conclusion.
+
+## Artifact
+
+**`assumptions.md`** - this IS the register (create if land did not). Keep one live table; do not only bury results in `reality.md`:
+
+```markdown
+| # | Assumption | Kind | Blast radius | How we test | Status | Evidence |
+|---|------------|------|--------------|-------------|--------|----------|
+| 1 | API is the bottleneck | CONVENTION | CRITICAL | p95 instrumentation 24h | DISPROVED | 80% wait in DB layer (Day N) |
+| 2 | Team will adopt new tool | UNKNOWN | LOAD-BEARING | 3 individual interviews | CONFIRMED | 2/3 describe a use case unprompted |
+| 3 | Data clean enough for ML | UNKNOWN | CRITICAL | 200-record sample | PARTIAL → OPEN follow-up | 12% nulls on key field; cleaning task added |
+```
+
+Status values: `OPEN` · `TESTING` · `CONFIRMED` · `DISPROVED` · `PARKED`. A CRITICAL row still `OPEN` blocks plan.
+
+**`reality.md`** - short pointer only: which assumptions changed the approach and the implication for build.
+
+**`decisions.md`** - if an assumption was disproved and the approach changed: what shifted, why, the evidence, same day.
+
+## Checkpoint
+
+Tell the FDE: how many assumptions extracted, how many critical, which ones were tested, which changed the direction. If a critical assumption is disproved: recommend the next move (rescope, pivot, or the conversation with the sponsor) before the FDE asks. If any CRITICAL remains OPEN: do not route to plan.
+
+## Worked example
+
+Acme's brief reads cleanly, which is the signal.
+
+Extracted assumptions include one nobody said aloud: *finance would act on an alert*. The whole plan rests on it, and the evidence behind it is a sentence in a kickoff. Blast radius CRITICAL - if false, alerting changes nothing and the engagement delivers a page nobody answers.
+
+Validation is a test, not a discussion, and it is cheap: send one real failure notification to the finance channel and watch what happens. It goes first because highest blast radius × cheapest test is the killer test.
+
+Result: acked in 40 minutes, by Marco, not finance. Assumption DISPROVED, and the plan changes before six weeks are spent on it - the alert needs a rota with an owner, which is a different piece of work than the one that was funded. `assumptions.md` records the status, the evidence, and the date; the finding is presented to the FDE as a fact base, not as "the brief was wrong".
+
+## Principles
+
+- Every "just" is an assumption. Every "should" is an assumption.
+- Kind before blast radius. A FACT with no receipt is UNKNOWN.
+- Kill the riskiest, cheapest-to-test assumption first.
+- Evidence first, then the question. Let the customer reach the conclusion.
+- A brief with zero disproved assumptions wasn't audited - it was accepted.
+- Two weeks of building on a wrong assumption costs more than two hours of testing.

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

@@ -0,0 +1,90 @@
+# three-options - Generate options
+
+**Context:** apply [task context and evidence](task-context.md) before using the named records below.
+
+**Enter when:** a significant technical or strategic decision needs to be made, the FDE is asked "what should we do?", the team is stuck between approaches, or a fork in the engagement requires the sponsor's input.
+
+**Read first:** `reality.md`, `terrain.md`, `assumptions.md`, `success.md`, `context.md`. Load `business-case.md` if the decision has cost implications.
+
+Compare materially different, defensible alternatives. Three is a useful presentation shape when three viable paths exist; do not pad the set to meet a quota. Include keeping the current approach or deferring when those are credible choices.
+
+## Method (you do this work)
+
+**1. Name the decision.** One sentence: what needs to be decided, by whom, by when, and what happens if it's deferred.
+
+> "Decision: approach for the payment migration. Decided by: CTO. Needed by: Friday. Deferral cost: blocks the next sprint and delays the pilot by two weeks."
+
+**2. Generate genuine options from the evidence.** Use confirmed assumptions and known system parts; exclude disproved assumptions. If those records are absent, identify the supplied facts and unknowns. Use [test-assumptions](test-assumptions.md) only when a consequential assumption needs investigation.
+
+Alternatives should differ materially in architecture, operating model, scope, cost, or reversibility. Do not label the same plan good / medium / bad or manufacture an unsafe option to favor your recommendation.
+
+Each option must be one the FDE would genuinely recommend under different circumstances. If you cannot defend an option, replace it - padding is visible.
+
+For each option, name:
+- which surviving blocks it is built from
+- which constraint or convention it changes, if any
+- its single biggest point of failure
+- any new building block, labelled as a new assumption (`UNKNOWN` in `assumptions.md`) - do not smuggle one in as a fact
+
+If only one viable path remains, explain what ruled out the alternatives and what evidence could reopen them.
+
+**3. Structure each option identically.** Same dimensions, same format - so comparison is instant:
+
+```markdown
+### Option A: <name>
+- **Blocks:** <which surviving assumptions / parts it is built from>
+- **Constraint changed:** <constraint or convention changed, if any>
+- **What:** <the approach in one paragraph>
+- **Timeline:** <estimate with basis>
+- **Cost:** <effort, infrastructure, external>
+- **Biggest failure:** <the single point that kills this option>
+- **Trade-off:** <what you give up by choosing this>
+- **Best when:** <the condition that makes this the right choice>
+```
+
+**4. Make comparison easy.** Use consistent dimensions: expected outcome, evidence, build and operating cost, time with estimate basis, reversibility, owner, and the most consequential uncertainty. A compact table helps when alternatives need comparison; do not fill it with invented numbers or label one path universally cheapest.
+
+**5. State your recommendation - and why.** Separate supplied facts and estimates from your judgment:
+
+> "I recommend Option B. The limited team availability rules out a full rewrite this quarter, and the current hotspot makes keeping the job unchanged costly. Option B gets us to pilot in 4 weeks with a tested rollback."
+
+**6. Handle the override gracefully.** If the sponsor picks a different option:
+
+- Log it in `decisions.md`: the choice, who made it, the trade-off they accepted.
+- Adjust the plan to the chosen option. Don't passive-aggressively optimise for your preference.
+- If the chosen option has a specific risk you flagged: note the early-warning signal in `risks.md` so it's caught if it materialises.
+
+## Artifact
+
+**`decisions.md`** - the options analysis:
+```markdown
+## Decision: <name> - <date>
+Decided by: <who>
+Options presented: <viable alternatives>
+Recommended: B - <one line why>
+Chosen: <option or pending> by <actual decision-maker or unknown>
+Trade-off accepted: <what the choice gives up>
+```
+
+The full option details in the same entry or linked to a section in `reality.md`.
+
+## Checkpoint
+
+Present the viable alternatives, recommendation, and the evidence or constraint that would change it. Reuse known decision authority; if a decision remains pending, record it as pending.
+
+## Worked example
+
+Fictional example: a support team needs completed requests written back to its service system. Its product can export a file today. A supported connector is expected in six weeks; the customer wants automation in two. A custom API adapter looks feasible, but nobody has accepted its maintenance.
+
+Two defensible paths remain. Continue the approved export while checking the supported connector's fit, or investigate a bounded adapter whose delivery depends on a named owner and tested API behavior. The export is a bridge within the first path, not a third option invented for the slide. Compare manual effort, engineering effort, ongoing support, and the effect of waiting. Time released is capacity unless spending actually falls.
+
+Recommend the bridge while resolving native fit and the value of earlier automation. Reconsider the adapter if that value justifies full costs and an owner accepts it. `decisions.md` (or a standalone decision note) records the recommendation, evidence, unknowns, and pending decision. It does not claim that a sponsor chose it or that the adapter can meet the date.
+
+## Principles
+
+- Compare defensible alternatives; the number follows the evidence.
+- Build from known facts and label new assumptions. Material differences make the comparison useful.
+- Each option must be genuinely defensible - no straw men.
+- Same structure for each option. Comparison should take 30 seconds.
+- Recommend one. State why. Accept the override gracefully.
+- An override logged with its trade-off protects the FDE when the risk materialises.

package/skills/fde-poc/references/verification.md

@@ -0,0 +1,31 @@
+# verification - Make a claim replayable
+
+**Enter when:** reporting completion, evaluating an acceptance check, handing work to a reviewer, or preparing a release.
+
+Use [task context](task-context.md). This method returns evidence directly or writes an existing permitted task/engagement record; it never requires `.fde/` initialization.
+
+## Method
+
+1. Translate each claim into the observation that would support or reject it. Reuse agreed acceptance criteria and required repository checks. Select focused checks for changed behavior before broadening to release requirements.
+2. Identify the actual repository commands, fixtures, runtime, and environment. Read command behavior before executing it, especially when it can write externally. Use authorized environments and avoid leaking secrets through logs or diagnostic commands.
+3. Run the checks and inspect results, including exit status and relevant output. A running job, test discovery, a mocked response, and a successful real request are different evidence. Record asynchronous completion before claiming success.
+4. Bind evidence to the tested revision and working tree. For uncommitted changes record the base revision plus changed paths and an available diff digest or snapshot identifier. For browser/manual checks record the steps, inputs, observed result, and inspected evidence.
+5. After a change, rerun checks whose behavior or assumptions were affected. Reuse prior evidence only when the relevant code, dependencies, data, and environment remain applicable; cite the original run and reason. Never imply reused evidence was rerun.
+6. Label every required check **passed**, **failed**, **blocked**, or **not run**. Include why blocked/not run, impact, and next step. Missing evidence is unproven; it is not an observed failure or a pass.
+
+## Receipt
+
+Use one compact entry per check or a table with these fields:
+
+- Claim / acceptance check and expected result.
+- Exact command and working directory, or manual journey and inputs.
+- Environment, runtime/tool versions when relevant, and fixture/data source.
+- Revision plus working-tree identity; run date/time.
+- Observed result and exit status where available; safe evidence location.
+- Status, limitations, unrun checks, and next step.
+
+Keep implementation, verification, deployment, measured outcome, and customer acceptance distinct. A local pass supports the tested local behavior. An acceptance claim needs an attributed source from the agreed decision-maker or agreed acceptance mechanism. Record no raw `<private>` blocks, credentials, or hidden reasoning.
+
+## Acceptance
+
+A completion statement cites applicable evidence for its claims and explicitly names material gaps. If required checks fail, investigate or report the blocker; never skip them, edit expectations, or relabel the scope without authority to obtain a green result.