fdeops 4.0.3 → 4.1.0

package/skills/fde/references/business-case.md

@@ -1,5 +1,7 @@
 # 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.
@@ -12,7 +14,7 @@ Technical FDEs lose engagements by shipping good code without business justifica
 
 | Cost type | How to find it | Example |
 |-----------|---------------|---------|
-| **Direct cost** | Ask: "What does this problem cost per month in money?" | Manual reconciliation: 3 people × 8h/week × loaded cost = $X/month |
+| **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 |
@@ -22,17 +24,17 @@ Technical FDEs lose engagements by shipping good code without business justifica
 ```
 Investment: <hours × rate, or fixed cost>
   → Delivers: <specific outcome from success.md>
-    → Saves: <cost-of-nothing × probability of success>
-      → Net: savings - investment over <time horizon>
+    → Benefit: <capacity released, avoidable cash spend, revenue, or risk reduction>
+      → Net cash: realizable incremental cash benefit - full costs over <time horizon>
 ```
 
-Keep the drivers explicit. "We estimate $200K savings" means nothing. "3 people × 8h/week × $75/h × 52 weeks = $93.6K/year, minus $40K build cost = $53.6K net year one" is defensible.
+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:
 
-> "This case holds if the team actually reclaims 6+ hours/week per person. If it's only 3 hours, the payback extends from 5 months to 14 months. The validation: measure time-spent before and after pilot with 2 team members."
+> "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.
 
@@ -53,7 +55,7 @@ The sponsor who sees you've identified where the case could break trusts the cas
 **The problem costs:** <one line, quantified>
 **The investment:** <hours and cost>
 **The return:** <quantified, with time horizon>
-**Payback:** <months>
+**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>
@@ -67,7 +69,7 @@ The sponsor who sees you've identified where the case could break trusts the cas
 
 ## 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" - ask what number they would believe and work backwards from there.
+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
 

package/skills/fde/references/close.md

@@ -1,5 +1,7 @@
 # close - Transfer operations
 
+**Context:** apply [task context and evidence](task-context.md) before using the named records below.
+
 **Enter when:** the engagement is ending - the customer team must run this without the FDE.
 
 **Read first:** bounded `fde handoff` or `fde resume`, then targeted `fde recall` for missing evidence. Build the full picture through relevant excerpts, not a full-directory load. Consult `terrain.md` only for the code paths needed by the successor.
@@ -20,10 +22,10 @@ The engagement doesn't end at ship. It ends when the customer can maintain what
 **1b. Value + receipts close gate (refuse green close if any fail):**
 - Primary value bucket in `success.md` matches what the sponsor funded; at least one ledger row has **Measured** (not forever-`pending`) with evidence **and a named customer-side owner in Accepted by** for that bucket - or the retrospective explicitly records “not measured; sponsor accepted pending.” A measured-but-unaccepted number closes as `claimed`; say so in the retrospective rather than closing green on arithmetic nobody signed.
 - Audit receipt exists for the final shipped path (exceptions/operating map walked; cite file).
-- Eval receipt: **n/a if no AI**, else final golden/eval result + HITL owner recorded; kill switch / fallback named in `handoff.md`.
+- Eval receipt: **n/a if no AI**, else final scoped eval result + operating owner and required human-review or bounded-automation authority recorded; kill switch / fallback named in `handoff.md`.
 - One line in the retrospective: which bucket moved, by how much, vs baseline.
 
-**2. The pattern.** Anything that happened here and will happen again - a compliance approach, a migration pattern, a stakeholder dynamic - gets encoded for reuse. **If you do it twice, encode it.**
+**2. The pattern.** Anything that happened here and will happen again - a compliance approach, a migration pattern, a stakeholder dynamic - gets encoded for reuse. Use [encode-pattern](encode-pattern.md) to distinguish candidate patterns from supported ones and protect customer data.
 
 **3. The handoff.** Operational knowledge for the person woken at 2am, not technical documentation: the 3 things that will break and the fix for each · who holds the tribal knowledge · what each alert means · deploy and rollback in plain language. AI components additionally: model version, what normal output looks like (so drift is recognisable), fallback behaviour, who owns retraining, **how to disable the AI path without taking down the feature** - without this the team turns it off at the first misbehaviour and it stays off.
 
@@ -41,7 +43,7 @@ The engagement doesn't end at ship. It ends when the customer can maintain what
 
 **Check the handoff as a lookup tool.** Give the intended operator one realistic task, such as finding the owner and recovery steps for a failed run. Can they locate the answer and its source in the permitted handoff without your explanation? A reader finding the instructions is not proof they can execute them; verify operation separately in the agreed safe environment. Correct the passage they could not use, rather than adding a longer introduction.
 
-If the operator is unavailable, a fresh reviewer can attempt the same lookup using only the permitted draft and task. Report this as a simulated clarity check, not operator validation, customer approval, or a green close. Use one focused pass for a consequential handoff; do not add a committee or a second approval ritual.
+If the operator is unavailable, a fresh reviewer can attempt the same lookup using only the permitted draft and task. Report this as a simulated clarity check, not operator validation, customer approval, or a green close. Claim independent review only if a separate reviewer actually performed it; identify the reviewer and evidence available. If none is available, perform a labeled self-check and report independent review as unperformed. Use one focused pass for a consequential handoff; do not add a committee or a second approval ritual.
 
 Direct assessment to the FDE: did the engagement achieve `success.md` · 2-3 lessons that matter · is the pattern worth encoding · is the handoff complete or where are the gaps. Also: value bucket + audit receipt green; eval **n/a or green**. Pending Measured without sponsor acceptance = gap, not green close. Honest - a gap named now is cheaper than a callback in six weeks.
 

package/skills/fde/references/debug.md

@@ -0,0 +1,18 @@
+# debug - Find and repair the cause
+
+**Enter when:** a reproducible failure, regression, incident symptom, or misleading output needs investigation.
+
+Use [task context](task-context.md). Work from supplied permitted evidence without requiring `.fde/`. During an active incident, follow the authorized containment procedure before diagnosis; investigation authority alone does not authorize production writes.
+
+## Method
+
+1. Capture expected and observed behavior, exact input or trigger, affected revision/environment, and the last known working state. Preserve useful errors and timestamps without copying secrets or raw private data. Mark reports you have not reproduced as reports.
+2. Inspect the failing path, callers, recent relevant changes, and existing tests. Reproduce in a permitted environment with the smallest representative case. If reproduction is unavailable, identify what observation would distinguish causes and gather safe evidence; do not claim a hypothesis is proven.
+3. Keep a short hypothesis list. For each, name the predicted observation and a discriminating check. Change one relevant variable at a time. Trace values and control flow across the actual boundary instead of repeatedly changing code until the symptom disappears.
+4. Fix the cause at the appropriate layer. Check whether the proposed fix changes behavior for other callers, stale data, retries, concurrency, or permissions. Preserve evidence of the original failure and avoid unrelated cleanup.
+5. Add a regression check when it can meaningfully reproduce the bug; show that it fails before the fix and passes after when practical. If the check cannot run against the before-state, say so. Run affected adjacent and required checks using [verification](verification.md).
+6. Review the final diff and exercise the original journey. For substantial or risky fixes use [review](review.md). After two unsuccessful repair cycles, reassess the hypothesis and evidence instead of repeating the same attempt; continue useful investigation and isolate the missing decision or access.
+
+## Deliverable and acceptance
+
+Report the cause with its evidence, the fix, the original reproducer's result, adjacent checks, and unresolved uncertainty. A disappearing symptom with no discriminating evidence is a mitigation, not a demonstrated root cause. In engagement mode record the incident/fix receipt in the appropriate existing record; standalone work may return it directly. Release or rollback requires the existing operational authority and [ship](ship.md) or recovery procedure.

package/skills/fde/references/encode-pattern.md

@@ -1,5 +1,7 @@
 # encode-pattern - Encode the pattern
 
+**Context:** apply [task context and evidence](task-context.md) before using the named records below.
+
 **Enter when:** the engagement is closing and reusable patterns exist, a technique worked well and will apply to future clients, the FDE notices themselves doing the same thing on a second engagement, or close identified a pattern worth preserving.
 
 **Read first:** `decisions.md`, `reality.md`, `delivery.md`, `retrospectives/`, `context.md`. Patterns live in what was *done*, not what was planned.
@@ -36,7 +38,7 @@ The difference between a 5-year FDE and a 15-year FDE is not talent - it's encod
 <The failure mode or edge case that makes the pattern not apply.>
 
 ### Evidence
-<Which engagement, what happened, what the result was. Specific, not generic.>
+<Permitted source, what happened, measured result, and limits. Keep identifying evidence in its original customer record.>
 ```
 
 **3. The pattern quality test.** Before encoding:
@@ -63,21 +65,21 @@ The difference between a 5-year FDE and a 15-year FDE is not talent - it's encod
 **5. Version and evolve.** Patterns are living documents:
 
 - First use: **v0.1** - hypothesis based on one engagement
-- Second use: **v1.0** - confirmed pattern, refined from two experiences
+- Later uses: record context, observed results, failures, and refinements. Repetition supplies evidence; it does not automatically validate the pattern. Promote a version when a substantive revision warrants it, not at a fixed use count.
 - After modification: increment minor version with what changed and why
 - After contradiction: note the counter-example, adjust the "watch out for" section
 
-**6. Cross-engagement pattern mining.** When the FDE has multiple engagements in `.fde/`:
+**6. Cross-engagement pattern mining.** Only when explicitly authorized for the named engagements and permitted by each customer's data policy. Keep records separate; use sanitized CLI packets or targeted recall in each authorized context, never raw file comparisons. Otherwise extract a candidate from the current permitted context only.
 
-- Compare `reality.md` across engagements - do the same problems recur?
-- Compare `decisions.md` - are the same decisions being made?
-- Compare `retrospectives/` - are the same lessons being "learned" twice?
+- Compare permitted problem summaries - do the same problems recur?
+- Compare permitted decision summaries - are the same decisions being made?
+- Compare permitted lessons - are the same lessons being learned twice?
 
 A pattern learned twice is a process failure. Encoding it prevents the third time.
 
 ## Artifact
 
-**`patterns.md`** - the pattern library, growing across engagements. Each pattern in the format above. Indexed by stage and situation trigger.
+**`patterns.md`** - candidates and evidence for this engagement, indexed by stage and situation trigger. A shared library is a separate, authorized export: remove names, identifiers, distinctive operational details, secrets, and confidential code or data. Keep source receipts in the original record and export only permitted generalizations.
 
 **`retrospectives/YYYY-MM-DD-<engagement>.md`** - reference to which patterns were extracted from this engagement.
 
@@ -90,5 +92,5 @@ Present the extracted patterns to the FDE: "From this engagement, I've identifie
 - If you did it twice, encode it. The same lesson learned three times is a failure.
 - Patterns are steps, not principles. "Build trust" isn't a pattern; "fix a small visible bug on day one" is.
 - Every pattern needs a situation trigger - the FDE must recognise when it applies.
-- Version patterns. A pattern from one engagement is a hypothesis; from two, it's confirmed.
+- Version substantive changes. State the evidence and limits; repeated use is not automatic confirmation.
 - The pattern library is the FDE's compound interest. It's what separates 5 years of experience from 1 year repeated 5 times.

package/skills/fde/references/eval-pack.md

@@ -1,43 +1,26 @@
-# eval-pack - Gate the model before it acts
+# eval-pack - Evaluate the model's allowed behavior
 
-**Enter when:** the work touches AI/LLM/agents/RAG, or they need to POC a model, or ship/close is blocked because there is no evidence the non-deterministic path is safe. Activate alongside `ai.md`, `poc`, or `ship` - not instead of them.
+**Enter when:** AI, LLM, RAG, or agent behavior needs evidence before an experiment, release, or material expansion. Non-AI work skips this method.
 
-**Read first:** `trust-profile.md` (AI policy + HITL), `terrain.md` (operating map), `delivery.md`. Create or extend `evals.md`.
+Use [task context](task-context.md). Supplied permitted context and an evaluation report are sufficient without `.fde/`. In a coordinated engagement, use the existing trust/terrain context and keep the report in `evals.md`; read only privacy-safe views.
 
-Non-AI engagements skip this pack entirely.
+## Method
 
-## Why this exists
+1. **Define the evaluated surface.** Name the model judgment, inputs, outputs, downstream actions, environment, and relevant failure impact. Separate model quality from deterministic tool authorization and application checks. Document the actual allowed action boundary and its source; missing authority remains unknown.
+2. **Choose cases by risk and coverage.** Use permitted historical examples, expert-labeled cases, or clearly marked synthetic fixtures. Cover relevant segments, boundary conditions, known failure modes, and critical harms. Record input, expected outcome/rubric, provenance, and critical-failure rule per case. Keep evaluation cases separate from tuning where possible; no fixed case count proves safety.
+3. **Agree the pass rule before the run.** Define quality thresholds, critical failures, coverage expectations, and acceptable uncertainty for this use. Use deterministic checks where possible and inspect subjective labels or judge reliability. Propose missing criteria for agreement; do not manufacture acceptance from the observed scores.
+4. **Run the actual evaluated path.** Record model/provider version, prompts/configuration, retrieval corpus or tools, application revision, environment, fixtures, and run date. Repeat where variability matters. Report totals, per-segment results, critical failures, and limitations using [verification](verification.md). A model-only run does not prove the agent's tool boundary works.
+5. **Verify action authority and controls.** Human approval is required where the user's policy or task requires it. Already agreed bounded automation may run within its documented actions, identities, environments, and limits; do not require fresh approval for every authorized action. Check enforcement outside the model, least privilege, input/output validation, cost/rate limits, stop conditions, observability, and recovery as applicable. Unknown or exceeded authority blocks those actions. Evaluation success never grants new authority.
+6. **Make a scoped verdict.** Report **SHIP** only when agreed criteria pass, critical failures are zero, applicable authority/control checks pass, and material coverage gaps are resolved or the release is explicitly narrowed by the responsible decision-maker. Otherwise report **NO-SHIP** with the smallest corrective step: fix, gather evidence, descope, or reconsider the judgment surface. A SHIP verdict is technical evidence for the stated scope, not permission to deploy.
 
-Intelligence without evidence is token-maxing with a nicer name. An FDE earns trust by showing: golden cases, failure modes, and a human gate before action.
+## Deliverable and acceptance
 
-## Method (you do this work)
+Return the suite/source, thresholds, counts and segments, top failure modes, control evidence, human-review gate or bounded automation authority, limitations, and dated verdict. Record unknown values honestly. Reevaluate after changes that affect model behavior, retrieval, tool permissions, or data conditions; cite why unchanged evidence remains applicable rather than implying a rerun.
 
-**1. Scope the judgement surface.** One sentence: which step uses model judgement, and what must never be autonomous.
-
-**2. Build a golden set sized to risk and coverage.** A pilot may start with 5-20 cases; neither that range nor 50-100 proves broad-scale safety. Include representative segments, boundary cases, and known critical failures. Expand based on observed failure modes and uncertainty; hold out cases from tuning and repeat runs when variability matters. For each case:
-- input (sanitized - no `<private>` raw values)
-- expected outcome or expert-approved acceptance note
-- pass rule (exact / contains / short rubric)
-- source: real historical example / expert label / staged fixture
-
-**3. Score pass/fail, not vibes.** Define the quality threshold and critical failure rules before running the suite. Run it; record count pass / fail, segment coverage, and limitations. Failures get a failure-mode tag (missing data, wrong record, format drift, hallucination, retrieval miss, unsafe action, other).
-
-**4. Human-in-the-loop gate.** Name which outcomes require human approve before side effects. Judgement that has a side effect (write, send, transfer, ticket, deploy, pay, page) is **NO-SHIP** without a named human on their side in the loop. Do not write "none - allowed under policy" to bless lights-out write-access. Staging may run a supervised loop with a kill switch, a cost cap, and a golden set from **their** failures. Production stays gated until they have a written policy, a named owner, and dated eval receipts on real traffic.
-
-**5. Ship rule.** Until `evals.md` shows Verdict **SHIP** with a dated run (critical fails = 0) and HITL filled, AI-touching ship stays **fix-first**. Eval fails do not sit in a backlog - they reopen plan (descope, move the judgement, or kill the path). Log a one-line eval receipt in `delivery.md` → `## Ship receipts`. No "probably fine."
-
-## Artifact - `evals.md`
-
-Create on first AI-touching slice (not at `resume --init`). Use the stub in `templates/.fde/evals.md`. Every claim needs a source. Missing evidence → leave the cell `unknown - ask:`, never invent scores.
-
-## Checkpoint
-
-Present to the FDE: suite size, pass rate, top failure mode, HITL gate, Verdict SHIP/NO-SHIP. If they want to ship without a run: say no, and offer the smallest suite that would unblock.
+When coordinated, append a concise eval receipt to delivery records. For release use [ship](ship.md). For ongoing use define the drift signals, sample policy permitted by data handling rules, owner, and conditions that suspend or narrow automation. Do not store secrets, raw `<private>` data, or hidden chain-of-thought in reports.
 
 ## Principles
 
-- No golden set, no AI ship.
-- Pass/fail beats “looks good.”
-- Failure modes are the product - the happy path is table stakes.
-- HITL is a gate, not a slide. Side effects without a named human on their side are NO-SHIP.
-- Non-AI work does not need this file.
+- Thresholds and authority come from the agreed contract, never from a convenient observed result.
+- Critical failures block the evaluated release scope; disclose coverage and uncertainty.
+- Bound automation with enforceable controls, and require human review where the policy requires it.

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

@@ -1,5 +1,7 @@
 # hold-scope - Hold scope
 
+**Context:** apply [task context and evidence](task-context.md) before using the named records below.
+
 **Enter when:** "also can you…" mid-build, a stakeholder adds requirements without adjusting timeline, the FDE feels scope creeping but can't name it, or `success.md` no longer matches what's being asked.
 
 **Read first:** `success.md` (the agreed boundary), `decisions.md`, `context.md`. Load `stakeholders.md` to know who's asking and their signal.
@@ -11,7 +13,7 @@ Scope creep is the leading cause of FDE engagement failure - not technical compl
 **1. Detect before it compounds.** Three patterns that signal creep before it's named:
 
 | Pattern | What it sounds like | What's actually happening |
-|---------|--------------------|--------------------------| 
+|---------|--------------------|--------------------------|
 | **The friendly addition** | "While you're in there, could you also…" | Adjacent work getting absorbed without timeline adjustment |
 | **The evolved requirement** | "Oh, what I actually meant was…" | The original scope was never clear enough - `success.md` needs updating |
 | **The stakeholder swap** | A new person starts requesting features the original sponsor didn't | Power shifted; the real scope is being rewritten informally |
@@ -38,7 +40,7 @@ Log via `fde log decision "scope change: <summary> - requested by <who>, impact:
 
 **The key phrase: "Let me place it."** Not "that's out of scope" (adversarial) or "sure" (absorbed). "Let me place it" signals you're taking it seriously while buying time to assess the real cost.
 
-**4. The accumulation conversation.** When the scope receipts show a pattern - typically 3-5 absorbed changes - the FDE needs a conversation with the sponsor:
+**4. The accumulation conversation.** When the scope receipts show a pattern - a material cumulative impact on delivery, cost, risk, or acceptance - the FDE needs a conversation with the sponsor:
 
 Frame it as **protection, not complaint:**
 > "We've absorbed five changes since the original agreement. Each one made sense individually. Together, they've added roughly two weeks. I want to make sure the timeline expectation still matches - should we adjust the delivery date, or reprioritise to keep the original date?"
@@ -59,23 +61,23 @@ Evidence-based: point to `decisions.md` scope receipts with dates and requesters
 
 ## Checkpoint
 
-Weekly check: count the scope receipts since last conversation. Three or more unaddressed → recommend the accumulation conversation to the FDE. Zero → "scope holding, `success.md` current."
+Check cumulative impact against the agreed scope and remaining capacity. Recommend a conversation as soon as delivery, cost, risk, or acceptance changes materially; one consequential request may suffice. No logged requests alone does not prove scope is holding.
 
 ## Worked example
 
 Acme, week 5. Nothing has been formally added, and the slice is a week late.
 
-The pattern shows in three receipts, not one argument: a "quick" finance CSV export (Jun 20, half a day, from Denise directly), retry-logic cleanup asked for mid-build (Jun 24, one day, Tom), and a dashboard tile "while you're in there" (Jun 27, half a day). Each was individually reasonable; together they are the slip.
+The pattern shows in three requests: a "quick" finance CSV export (Jun 20, half a day, from Denise directly), retry-logic cleanup asked for mid-build (Jun 24, one day, Tom), and a dashboard tile "while you're in there" (Jun 27, half a day). Each sounds reasonable; their cumulative estimates explain part of the slip and need a scope decision.
 
-Three-bucket response, applied at the moment of the third ask rather than in a retrospective: the CSV export goes to Next with an accepted trade (it displaces the runbook polish), the retry cleanup goes to the kill list in `decisions.md` with the what-breaks reason, and the tile is absorbed because it is genuinely twenty minutes - logged anyway, since an unlogged absorption is the one that gets forgotten in the accumulation conversation.
+Three-bucket response, applied while the requests can still be placed: the CSV export fits this phase only with an accepted trade (it displaces the runbook polish), the retry cleanup goes to the kill list in `decisions.md` with the what-breaks reason, and the tile is absorbed because it is genuinely twenty minutes - logged anyway, since an unlogged absorption is the one that gets forgotten in the accumulation conversation.
 
-That conversation happens with Priya at three receipts, with the dates on screen: "these are the four asks, here is the two days, here is what moved." Not a complaint - a decision she gets to make, with evidence, before the deadline makes it for her.
+That conversation happens with Priya when the added work threatens the date, with the receipts on screen: "here are the asks, their estimated impact, and what moved." Not a complaint - a decision she gets to make, with evidence, before the deadline makes it for her.
 
 ## Principles
 
 - "Let me place it" is the phrase. Not "no," not "sure."
 - Every scope change gets a receipt. The receipt is the evidence.
-- Three unaddressed scope changes → accumulation conversation.
+- Escalate material impact, not an arbitrary count of requests.
 - Scope creep kills engagements that technical failure couldn't.
 - `success.md` is a contract - update it explicitly or defend it.
 - The FDE who absorbs everything is liked for three weeks and blamed for three months.

package/skills/fde/references/integrate.md

@@ -0,0 +1,18 @@
+# integrate - Prove the system boundary
+
+**Enter when:** connecting an API, data source, SDK, event stream, tool, or service, or changing its contract.
+
+Start from [task context](task-context.md). Permitted supplied context is enough; `.fde/` is optional. Use the customer's existing clients, authentication, fixtures, and diagnostic tools. Do not create another integration platform to make one connection.
+
+## 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.
+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.
+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.
+
+## 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/fde/references/plan.md

@@ -1,10 +1,12 @@
 # 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.
 
-**Before a new delivery plan or material scope change:** run `fde doctor --ready`. 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 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)
 
@@ -24,7 +26,7 @@ An FDE plan is not a sprint backlog. The technical sequence is the easy part. Th
 
 ## Method (you do this work)
 
-**0. Lock scope first.** Read `success.md`, `assumptions.md`, and the **Question** on `reality.md`. If out-of-scope is undefined, define it now with the FDE - a plan on undefined scope accumulates silent commitments. If any CRITICAL assumption is still `OPEN`, stop and run test-assumptions / discover before sequencing work. If `reality.md` has no Question, stop and finish discover - you are sequencing trivia.
+**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.
 

package/skills/fde/references/poc.md

@@ -1,5 +1,7 @@
 # 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.
@@ -8,7 +10,7 @@ A green check on synthetic data is not a validated solution. The person who can
 
 ## 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` just ran: the cheapest test is for the recommended option first, unless they pick another.
+**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.
 
@@ -22,13 +24,13 @@ A green check on synthetic data is not a validated solution. The person who can
 - 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. Kill it immediately if:** the assumption is disproven · the customer ignores it (indifference is a signal, not neutrality) · 3 iterations and feedback isn't converging · it works but the customer can't explain or trust the output (unexplainable AI in a high-stakes context is not a solution). When killed: write down what was *learned*, not what was built. The learning is the asset.
+**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` and `ship` workflow. A working demo does not establish production readiness or customer acceptance.
+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.
 

package/skills/fde/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/references/review.md

@@ -1,77 +1,39 @@
-# review - Review the change
+# review - Assess the actual change
 
-**Enter when:** a change needs review before merge - "is this safe," "does it match what we agreed." Their team commented on the PR: same skill. Comments are to check, not to obey.
+**Enter when:** a diff, proposed merge, or review comment needs assessment against agreed behavior and constraints.
 
-**Read first:** `context.md`, `decisions.md`, `trust-profile.md`, `terrain.md`. Not `reality.md`/`stakeholders.md` - irrelevant to reviewing code against agreed scope.
+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.
 
-Engagement review ≠ product-company review: a codebase you don't own, systems you can't fully see, a customer who can't afford a bad release.
+## Establish what was reviewed
 
-## Pre-flight: is this reviewable?
+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.
 
-Check whether the diff has one agreed intent and can be reviewed with the available evidence. Split unrelated work; for a large cohesive change, separate generated/mechanical output from behavioral changes and review in bounded sections. Size is a warning to investigate, not a universal stop threshold.
+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.
 
-## Stage 1 - did we build what we agreed? (you do this work)
+## Check scope, then behavior
 
-Check the diff against the **one-line intent** in `decisions.md` / acceptance criteria - what was *explicitly decided*, not what seems right:
+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.
 
-```bash
-git diff <base>...HEAD --stat
-```
+Trace the changed path through its consumers and failure cases:
 
-For each touched path (or logical hunk), assign one verdict:
+- **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).
 
-| Verdict | Meaning |
-|---------|---------|
-| **KEEP** | Required for the stated intent |
-| **JUSTIFY** | Adjacent but must ship now - write one sentence why, or SPLIT |
-| **SPLIT** | Real work for another PR / Next / kill list - do not merge with this slice |
-| **DROP** | Noise / drive-by - revert before Pass |
+## Findings and repair
 
-Also check:
-- Any sacred system from `trust-profile.md` touched?
-- Any sensitive data newly in scope?
-- Rollback path defined before build still honoured?
+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.
 
-**Stage 1 fails → stop** if any SPLIT/DROP remains, or JUSTIFY lacks a written sentence. Quality review on out-of-scope code is wasted work. Record the mismatch (and the KEEP/JUSTIFY/SPLIT/DROP tally) in `decisions.md`.
+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.
 
-Stakeholder "also can you…" mid-build is `hold-scope` - different axis. This stage is **code vs claim**.
+## Deliverable and acceptance
 
-## Stage 2 - is it safe to live with?
-
-Five dimensions, line-specific ("line 47 fails under concurrent writes - no lock"), never "could be better":
-
-- **Correctness** - does what it says; edge cases; error paths traced.
-- **Blast radius** - what breaks at 2am; downstream systems; failure mode loud (errors surface) or silent (data corrupts over time)?
-- **Security** - input validation at boundaries; no secrets in logs; no new attack surface; `trust-profile.md` sensitivity classes respected.
-- **Recovery** - can the documented, tested rollback or recovery path meet the agreed recovery-time and data-loss limits? For irreversible changes, require explicit authority, compatibility checks, and a tested restore/compensation or roll-forward plan; a code revert alone is not proof.
-- **AI policy & components** - human-review requirements honoured; model output treated as untrusted until validated; fallback exists; privacy-safe execution evidence retained under the client’s data policy (no secrets, raw private data, or hidden chain-of-thought); outputs bounded so a hallucination can't cascade; check applicable explanation and human-review requirements with the client’s responsible owner; provide source evidence and concise rationale without claiming access to hidden reasoning.
-
-**Structural pass on AI-heavy or data-touching changes:** migration compatibility and tested recovery · destructive SQL guarded · PII/PCI/PHI paths match `trust-profile.md` · side effects (flags, webhooks, emails, jobs) fire only when intended · magic strings that break on rename · new behaviour has a test or an explicit reason it can't yet. One line problem, one line fix.
-
-## The review-fix loop (until clean)
-
-1. Read the full diff before commenting.
-2. Verdicts: **Stage 1: Pass / Blocked (reason)** · **Stage 2: Pass / Concerns (line-specific)**.
-3. Fix only **real** findings tied to this change - no drive-by refactors. Reject false positives with one sentence why. Their comments are to check, not to obey. Restate each against the one-line intent and `trust-profile.md`. An unclear item waits for clarification; continue independent, understood fixes. If it breaks a signed constraint, a sacred system, or nothing calls it: one-sentence pushback, then wait.
-4. Add or update a test per bug found where possible.
-5. Re-run tests/typechecks - state what ran.
-6. Re-review. If two repair/review cycles do not converge, reassess the evidence and approach; continue independent fixes and escalate concrete scope/product decisions.
-
-## Before the PR - thinking for the next reader
-
-Code alone loses the "why." Before you call the change reviewable, run the **session digest** from the memory contract (SKILL.md Session digest): TL;DR, key decisions & rationale, scope + how you verified, gotchas. Confirm with the FDE, then write into `.fde/` - `decisions.md` / `delivery.md` / `context.md`. Reviewers (or Monday-you) should answer "why this approach?" from the fieldbook, not from a chat transcript. Do **not** dump agent logs into the product repo.
-
-## Artifact
-
-**`decisions.md`** - each cycle logged: what was reviewed, flagged, fixed, verified. Stage 1 failures recorded with the specific mismatch. Digest decisions (with *why*) land here too when the slice ships.
-
-**`delivery.md`** - scope + verification from the digest when a PR is opening; intent-vs-diff receipt stays the ship gate.
+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
 
-- Stage 1 before Stage 2. Wrong scope reviewed well is still wrong scope.
-- KEEP / JUSTIFY / SPLIT / DROP - every path gets a verdict; silent extras fail Stage 1.
-- Specific or silent - vague concerns waste everyone's time.
-- No viable tested recovery path = a release blocker.
-- A clean review proves this diff is safe as agreed - not that the feature was right.
-- Judgment in `.fde/` beats transcript in git.
+- 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.