fdeops 5.0.0 → 5.1.1

package/skills/fde/references/connect.md

@@ -1,34 +1,24 @@
 # connect - Connect a source
 
-**Enter when:** the FDE says "I want to connect a new MCP", "connect Granola / Slack / Notion", "how do I pull from …", or a pull request fails because no source tools exist.
+**Enter when:** the user asks to connect a notes, chat or document source, or an expected source cannot be read.
 
-**Read first:** `references/ingest.md` (sink contract). Recipes: `mcp/recipes/` (file, granola, slack, notion).
-
-**Who runs setup:** you guide; the **host** (Cursor/Claude) must save MCP config. You cannot silently install servers into the host.
-
-## Honest contract
-
-- **Daily work does not need a source MCP.** Paste notes → debrief. File on disk → `fde ingest`.
-- **Connect means a source**, not FDEOps. Granola/Slack/Notion credentials stay with that MCP. FDEOps never pushes, never ambient-syncs, never stores their tokens.
-- **Sink is the CLI in this bound workspace** (`fde ingest`). `fdeops-ingest` MCP is optional. If you use it, pass `engagement` as the `.fde/` path from `fde resume --bind` (MCP servers often do not inherit the workspace bind).
-- Never invent that Granola/Slack is available if tools are missing. Never auto-apply to `.fde/`.
+Apply [task context](task-context.md). Source setup can run independently of a customer record. Follow [source setup](source-setup.md) for permitted tools, credentials, connectivity checks and export alternatives.
 
 ## Method
 
-1. **Ask one question** - which source? (`file` / `granola` / `slack` / `notion` / other). If "other", ask for the MCP they intend to use. If they just want paste → send them to debrief and stop.
-2. **Capability check (current session)** - list MCP tools you can actually call:
-   - Sink: `fde ingest` CLI (preferred) and/or `ingest_stage`
-   - Source: anything that can **fetch** that system's content (not post)
-   - Say clearly: *available now* vs *needs config*.
-3. **Emit config for the source only** - open `mcp/recipes/<source>.md`. Fill placeholders from *that product's* docs. Tell them to paste secrets into host env - never into `.fde/`.
-4. **Tell them where to paste** - Cursor MCP settings / `mcp.json`. Claude Code: their MCP config. Save → reload MCP / restart session.
-5. **Verify** - after reload: re-run capability check. If source tools appear, offer a **test pull** staged to `.inbox/` only. Stop before apply unless they ask to propose.
-6. **Handoff phrase** - e.g. `@fde pull today's Acme Granola into the fieldbook`.
+1. Identify the source and the material the user wants to read. Inspect the host's actual available tools before recommending setup.
+2. If the source already works, use a narrowly scoped requested read. Do not install another connector.
+3. If setup is needed, verify current provider and host documentation, explain the required access, and make only authorized configuration changes. Never put credentials into prompts or customer records.
+4. Test the selected source and distinguish configuration from successful retrieval. If access is blocked, report the specific limitation and an available file or paste alternative.
+5. If the user also wants to update a customer record, continue with [ingest](ingest.md) after selecting that record. Otherwise stop after the requested setup or read.
 
-## If they only want paste / files
+## Checkpoint
 
-Do not add MCP. Use debrief or [mcp/recipes/file.md](../../../mcp/recipes/file.md).
+Return what is connected, what read was verified, any access gap, and how to request the next pull. Do not claim an integration works from configuration alone or write customer records during setup.
 
-## Checkpoint
+## Principles
 
-Before ending connect: (1) they know paste still works, (2) source reachable or honest gap, (3) they know the pull phrase. Do not write `.fde/` during connect.
+- Existing source tools first; configuration only when needed.
+- Minimum requested read, no ambient synchronization.
+- Credentials stay in supported secret storage.
+- Record updates require their own review and confirmation.

package/skills/fde/references/debrief.md

@@ -2,6 +2,8 @@
 
 **Enter when:** the FDE just left a meeting/call and dumps raw notes, a transcript, or "they said…". Highest-frequency moment in FDE life. Capture within the hour.
 
+**Standalone review:** apply [task context](task-context.md). If the user supplies notes and wants a summary or review, interpret them using **Prepare one update** below and return a draft. Keep requests, confirmed decisions, reported results and unknowns distinct. No CLI or customer record is needed; do not claim anything was saved. Use the bound-record path below only when updating an existing record or when the user asks to start one.
+
 **Large transcripts or emails** sitting in Granola/Gmail/Notion → prefer **`fde ingest stage`** first (via source MCPs the FDE configured), then the same propose → confirm → **`fde ingest apply`** path. See `references/ingest.md`. Pasted short notes stay on this debrief verb.
 
 **Read first:** the bounded `fde resume` packet for the bound client. Use `fde recall` for the specific prior decision, action, or delivery result needed to reconcile this update. Do not reload the whole engagement.

package/skills/fde/references/earn-trust.md

@@ -2,52 +2,39 @@
 
 **Enter when:** new engagement where you don't have full access yet, trust is thin, the customer said "let's start small," or you need to navigate "we don't trust AI-generated code."
 
-**Read first:** `trust-profile.md`, `stakeholders.md`, `context.md`. The trust profile tells you where the walls are; the stakeholder map tells you who built them.
+**Read first:** apply [task context](task-context.md), then retrieve permitted trust constraints, stakeholder evidence and current context. Never read raw private blocks.
 
-Trust is the currency of FDE work. Code quality gets you a second week; trust gets you the engagement. It's earned in small, visible moves - never demanded, never assumed, and never recovered once burned.
+Build confidence through useful work, clear evidence and respect for the customer's process. Relationship confidence and access permissions are separate: a strong relationship does not grant production authority.
 
 ## Method (you do this work)
 
-**1. The trust ladder - every engagement climbs it in order:**
+**1. Establish the access needed now.** Identify the next task, the minimum relevant access, and its actual policy or authorization source. Read-only access, reviewed PRs, branch writes and deployment rights can be granted independently. Reuse permissions already granted for the same scope; do not impose a ladder or ask the customer to re-earn established access. Record missing or disputed rights and continue work that does not depend on them.
 
-```
-Level 0: Observer     → read-only access, watching
-Level 1: Advisor      → recommendations, no code changes
-Level 2: Contributor  → PRs reviewed by their team
-Level 3: Committer    → direct push to feature branches
-Level 4: Owner        → production access, deploy authority
-Level 5: Trusted      → they call you before making decisions
-```
-
-**Never skip a level.** The FDE who asks for production access on day two gets observer access for a month. The FDE who ships a clean PR on day two gets committer access by week two. Each level is earned by demonstrating competence AND respect at the current level.
+**2. Make progress visible.** Choose useful actions for the engagement's stage and agreed cadence:
 
-**2. The first-week trust plays - specific, not generic:**
-
-| Day | Move | Why it works |
-|-----|------|-------------|
-| 1 | Fix a small, visible, annoying bug - something the team has been stepping over (only after `success.md` has a signer, or the FDE overrides with the unknown still visible) | Proves you can ship in their environment without breaking things |
-| 1 | Ask the passed-over team what naming conventions they use - then use them | Shows respect before competence |
-| 2 | Send a one-paragraph status to the sponsor without being asked | Sets the pattern: they hear from you before they have to ask |
-| 3 | Find a genuine risk and flag it without drama | Demonstrates you're protecting them, not performing |
-| 5 | Show a small win to the champion so they can share it upward | Gives them evidence their bet on you was right |
+- Deliver a small verified result within scope, or clarify a consequential unknown when implementation is premature. A quick win does not bypass release gates.
+- Ask the existing team about conventions and prior attempts; credit their contributions without assuming they were passed over.
+- Prepare a concise status update using the agreed channel and audience. Send only within existing communication authority.
+- Flag a supported risk and its consequence without exaggerating urgency.
+- Show results the intended users can evaluate, distinguishing demonstrated behavior from reported satisfaction.
 
 **3. Navigate "we don't trust AI-generated code":**
 
 This is increasingly common. The right response is respect, not persuasion:
 
 - **Ask the policy, don't assume.** "Does your organisation have a position on AI-assisted code in production?"
-- **If prohibited:** work without AI on their code. Use fdeops for engagement memory (`.fde/` files) and your own planning - that's your tooling, not theirs.
+- **If prohibited:** do not load or work on their code with the model. Engagement notes and planning may also contain restricted data; use FDEOps on them only when that use is permitted. Continue with generic or explicitly permitted material, and identify what must be handled outside the AI workflow.
 - **If permitted with review:** every AI-touched line goes through their normal review process. Flag it: "AI-assisted, human-reviewed" in commit messages if they want traceability.
-- **If grey area:** treat as prohibited until someone with authority says otherwise. The cost of asking is zero; the cost of guessing wrong is the engagement.
-- **Never hide it.** An FDE caught using prohibited AI tools loses the engagement and the reputation. Full stop.
+- **If grey area:** treat as prohibited until someone with authority says otherwise. Clarify only the policy needed for the next action and continue work on already permitted material.
+- **Never hide it.** Disclose AI involvement according to the agreed policy; do not represent prohibited use as ordinary local tooling.
 
 **4. Trust recovery - when you've made a mistake:**
 
 Mistakes happen. What matters is speed and honesty:
 
-- **Own it in the first hour.** Not "we found an issue" - "I introduced this bug." Passive voice erodes trust faster than the mistake.
+- **Report promptly under the incident process.** State the known impact and your confirmed contribution. Do not assign yourself or another person a cause before evidence supports it.
 - **Show the fix AND the prevention.** "Here's what happened, here's the fix, here's the test that prevents it next time."
-- **One visible win within 48 hours.** Trust recovery needs a concrete success close to the mistake - not weeks later.
+- **Agree a recovery checkpoint.** Use a verified corrective result and a realistic next update; do not promise a win within an arbitrary window.
 - **Never minimise.** "It was a small bug" is your assessment, not theirs. Let them size it.
 
 **5. The trust account - deposits and withdrawals:**
@@ -65,36 +52,30 @@ Mistakes happen. What matters is speed and honesty:
 
 **`trust-profile.md`** - updated sections:
 ```markdown
-## Trust level
-Current: <level 0-5> as of <date>
-Evidence: <what earned this level>
-Next target: <level> - requires: <specific action>
+## Access and working agreement
+Current: <permitted task, system/environment and limits>
+Source: <actual authorization/policy and date>
+Next need: <access gap or none; responsible decision-maker if known>
 
 ## AI policy
 Status: <prohibited / permitted-with-review / grey-area-treating-as-prohibited>
 Source: <who confirmed, when>
 ```
 
-**`decisions.md`** - log trust-significant moves: "Flagged migration risk to ops lead before they discovered it (Day 3) - trust deposit."
+**`decisions.md`** - record consequential confirmed agreements with their sources. A risk raised is an observed action; increased trust is not established unless supported by the customer's response.
 
 ## Checkpoint
 
-One question to the FDE: "Are we at the right trust level for what we need to do next week?" If not: name the gap, name the move, and put it in `context.md` as the next action.
-
-## The week 2-4 valley
+Check whether the next task has the required access and agreement. Reuse current evidence; if a material gap remains, name the applicable decision and next action.
 
-Week 1 is the honeymoon - everyone's excited, access is fresh, the brief is new. Weeks 2-4 are the valley: novelty wears off, real problems surface, the sponsor's patience shifts from "take your time" to "when do we see results." Most engagements silently fail here, not at ship.
+## Keep expectations current
 
-Counter it:
-- Ship one visible artifact per week, even if discovery isn't done. A terrain map, a risk register, a stakeholder signal update - something the sponsor can point to.
-- Proactive status update at end of week 2 - explicitly name what discovery revealed that wasn't in the brief. This resets expectations with evidence.
-- If still in discovery at week 3: the conversation with the sponsor about scope or timeline reset is overdue. Don't wait for them to ask.
+At the agreed checkpoints, explain what changed, what has been demonstrated and what remains uncertain. If discovery invalidates the expected scope or timeline, surface the evidence when it affects the next decision. A long discovery phase may be appropriate for the work; week numbers alone do not establish impatience or failure.
 
 ## Principles
 
-- Trust is earned in small moves, lost in one. Never skip the ladder.
-- The first-week plays are specific and deliberate - not "be helpful."
-- AI policy: ask, never assume. Prohibited until confirmed.
-- Mistakes happen; hiding them doesn't. Own it in the first hour.
-- The FDE who makes the internal team look right earns trust faster than the FDE who ships the most code.
-- Weeks 2-4 are where engagements silently die. Ship visible artifacts weekly to survive the valley.
+- Earn confidence through observable work; permissions come from applicable authority.
+- Use the customer's conventions and credit actual contributions.
+- AI policy applies to the data and use, including engagement memory.
+- Report mistakes promptly, distinguish known causes from hypotheses, and verify recovery.
+- Choose updates and follow-up timing from impact and the agreed cadence.

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

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

package/skills/fde/references/ingest.md

@@ -2,7 +2,9 @@
 
 **Enter when:** the FDE wants to catch the engagement up from external sources - "make sure Acme is up to date," "pull what's relevant," "grab today's Granola and Denise's last email." Raw transcripts and long emails that are too big to paste usefully.
 
-**Connect / capability (different entry):** "connect a new MCP", "connect Granola/Slack/Notion", "what can you pull?" → `references/connect.md` first. Recipes: `mcp/recipes/` (file, granola, slack, notion).
+**Connect / capability (different entry):** "connect a new MCP", "connect Granola/Slack/Notion", "what can you pull?" → `references/connect.md` first. Use [source setup](source-setup.md) for files and supported source tools.
+
+**Review only:** requested source reads and a sourced draft can proceed without a customer record. Use [source setup](source-setup.md) and [debrief](debrief.md). Do not stage or apply anything until the intended customer is selected; do not silently create a record for a review-only request.
 
 **Read first:** the bounded `fde resume` packet and targeted recall for affected prior facts. Bind the engagement before staging anything.
 
@@ -60,7 +62,7 @@ Carry an actual `[source: ...]` locator on each consequential fact. Preserve ups
 
 ## MCP sink + recipes
 
-Optional `mcp/fdeops-ingest` wraps the same verbs over stdio. Source MCPs remain separate - the FDE adds whichever fetch tools they trust. Setup coach: `connect.md`. Copy-paste recipes: `mcp/recipes/`.
+Optional `mcp/fdeops-ingest` wraps the same verbs over stdio. Source MCPs remain separate - the FDE adds whichever fetch tools they trust. Setup coach: `connect.md`. Portable setup guidance: [source setup](source-setup.md).
 
 ## Checkpoint
 

package/skills/fde/references/integrate.md

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

package/skills/fde/references/land.md

@@ -2,7 +2,7 @@
 
 **Enter when:** new customer, first meeting, just got the brief, nothing started yet.
 
-**Read first:** `context.md` if it exists, then the supplied brief. Once the engagement type and AI/access policy are known, inspect the supplied repo/docs relevant to the ask before asking questions they can answer. This is a bounded evidence check, not a full discovery scan.
+**Read first:** apply [task context](task-context.md), then permitted `context.md` evidence if it exists and the supplied brief. Once the engagement type and AI/access policy are known, inspect the supplied repo/docs relevant to the ask before asking questions they can answer. This is a bounded evidence check, not a full discovery scan.
 
 ## Validation gate (confirm understanding, clarify where it elevates)
 
@@ -26,27 +26,27 @@ Format - one question at a time, with a guess the FDE can correct:
 
 ```
 READ: <one sentence - what you think they actually need>
-CONFIDENCE: ~NN% - missing: <what still blocks a safe start>
+MISSING: <fact or authority that changes the next action>
 Q: <one focused question>
-GUESS: <your best answer, so they can push back fast>
+POSSIBLE READ: <clearly labeled interpretation, if useful; never guessed authority>
 ```
 
-Wait for the reaction before the next question. Stop when confidence is high enough to write `success.md` without inventing names, or when the FDE says move on. Every answer that is still unknown stays `unknown - ask:` in the artifact - never fill the gap with a plausible stakeholder.
+Wait for the reaction before the next question. Stop when the next authorized action is clear, or when the FDE says move on; unanswered material gaps remain visible. Every answer that is still unknown stays `unknown - ask:` in the artifact - never fill the gap with a plausible stakeholder.
 
 ## Method - part 1: interrogate the brief (you do this work)
 
 Read the brief the FDE gives you. Separate **observed** (source/path and date), **reported** (who said it), and **hypothesis** (how to test it). A requested solution such as “build an agent” is not evidence of the cause. Ask only about gaps that change scope, access, acceptance, or the next investigation. What is **not** in the brief matters as much as what is. Produce the gap list yourself:
 
-- **No named decision-maker** → the FDE will spend two weeks building for someone who can't say yes. Flag it.
-- **"Straightforward cleanup" on an 8-year-old system** → the previous attempt is still visible in git history as a revert. Flag it.
-- **Very tight timeline** → someone already promised the outcome before hiring the FDE. Flag it.
-- **No out-of-scope section** → scope creep is pre-authorized. Flag it.
+- **No named decision-maker** → identify who or what can accept the outcome and the source of that authority; keep it unknown until established.
+- **"Straightforward cleanup" on an 8-year-old system** → inspect permitted relevant history and tests for prior attempts and constraints; age alone proves neither complexity nor a previous failure.
+- **Very tight timeline** → establish the deadline, its source and which commitments are actually agreed.
+- **No out-of-scope section** → clarify material boundaries against the existing agreement. An omission does not authorize additional work.
 
 Write these into `brief.md` as **questions to answer**, not problems - they're what the FDE is walking in to resolve.
 
 Pre-arrival checks to run through with the FDE:
-- Access confirmed? Repo, environment, docs. Waiting for access on day two burns trust.
-- Has someone tried this before? Find out why it failed before assuming this approach is different.
+- Access confirmed for the next task? Repo, environment and docs may have different permissions; identify gaps before dependent work.
+- Has someone tried this before? Establish what happened and what evidence remains; do not assume the attempt failed.
 - Other vendors/teams in scope? Then the FDE is not the only one in the room, even when alone in the meeting.
 - Tech stack recon: job postings, GitHub org - know the stack before they say it.
 
@@ -59,21 +59,21 @@ Intent: coach the FDE's first *customer* conversation - what keeps the sponsor u
 - "Who loses credibility if this goes wrong?"
 - "If nothing changes over the agreed timeframe, what happens, and who bears it?" Record the consequence and its source in `brief.md`; distinguish reported impact from measured cost. Unknown cost stays unknown, not an invented ROI.
 
-Let silence sit. If their fear doesn't match the written brief, the brief is wrong - say so plainly, log it.
+Allow time for an answer. If a stated concern differs from the brief, record the difference and clarify whether it changes the agreed outcome; neither statement automatically supersedes the other.
 
 **Listen for, and capture as you hear it:**
-- **The real decision-maker** - whoever others mention most, especially if not yet met. That's who judges the work.
-- **The previous attempt** - "we tried something similar last year" is the most important sentence in the first meeting. Who was involved? Still there and protective, or gone because of it?
-- **The passed-over internal team** - they know exactly what's wrong, and they resent the FDE's presence. Find them before the first standup, ask what they tried, use their language in every meeting. Make them look right and they protect you; ignore them and they wait for the mistake.
-- **The sacred thing** - "Is there anything in this environment I should treat as untouchable?" The hesitation before the answer is the answer.
+- **Decision rights** - who can approve scope, accept the result and authorize release, as relevant. A frequently mentioned person may be influential; confirm their actual authority and scope.
+- **The previous attempt** - "we tried something similar last year" identifies evidence to investigate. Who was involved, what happened, and which constraints still apply? Do not infer why someone left.
+- **The existing internal team** - ask what they tried, what they know and what they expect to own. Use established terminology and credit their work. Do not assume resentment, displacement or complete knowledge of the problem.
+- **The sacred thing** - "Is there anything in this environment I should treat as untouchable?" Capture the stated boundary and applicable policy; hesitation alone does not identify a restriction.
 - **Exception path (operating map seed)** - "When the happy path breaks this week, what do people actually do - who do they call, what spreadsheet opens, what do they skip?" Capture the break → workaround → who owns it. Do not build a full map on day 1; seed rows later in `terrain.md` → `## Operating map (exception-led)` during discover. Unknowns stay `unknown - ask:`.
 - **AI posture and policy** - tools already in use (sanctioned or shadow), and: "Does your organisation have a policy on AI-generated code? Are there decisions where you would not be comfortable with AI involvement?"
 - **Future operator** - "Who will run this after we leave, and have they agreed?" Record the proposed operator and unresolved ownership in `success.md`, separately from the signer. A sponsor naming a team is not that team accepting responsibility; verify with the operator during discover.
 - **Boundaries in multi-vendor rooms** - who owns what surface, who signs off before a change crosses it.
 
-## The day 1 deliverable
+## An early deliverable
 
-After `success.md` names a signer (or the FDE explicitly overrides with `unknown - ask:` still visible), ship one visible thing before the end of day 1: a small bug fix, a cleanup the team has stepped over, a dashboard tweak, a config improvement. Not because it matters technically - because it proves you can ship in their environment without breaking things. The first deploy sets the trust trajectory for the entire engagement. A day-1 deliverable earns more credibility than a week-3 architecture deck. Skip it until the land gate is met.
+Choose an early useful result within confirmed scope: a verified small fix, a permitted diagnostic, or a concise map of an unresolved problem. Reuse the existing outcome and authority for routine work. A first-day deadline does not grant deployment permission or waive verification; use `ship` for a release. If a missing signer blocks a consequential decision, keep it visible and continue independent preparation.
 
 ## Artifact (write as the conversation is debriefed)
 
@@ -81,7 +81,7 @@ After `success.md` names a signer (or the FDE explicitly overrides with `unknown
 
 **`success.md`** - what done looks like, **primary value bucket** (`cost-save` | `risk-mitigation` | `revenue-uplift`), baseline → target, who actually signs off, what is explicitly out of scope. Record agreement only with its source and scope; otherwise label the target proposed. For each baseline, record source, date/window, environment, and sample size when relevant. An operator recollection is reported, not measured. If no baseline exists, name the measurement owner and cheapest way to obtain it; do not manufacture a number.
 
-For every target number, run the **gaming check** before it is written down: *how could this metric hit its target without the customer being any better off?* There is always an answer, and the answer is what the org will drift toward under pressure. Write the guard next to the metric:
+For every target number, run the **gaming check** before it is written down: *how could this metric hit its target without the customer being any better off?* Identify plausible failure modes without predicting that the customer will exploit them. Write a relevant guard next to the metric:
 
 ```markdown
 | Metric | Baseline → target | Gamed by | Guard |
@@ -89,19 +89,19 @@ For every target number, run the **gaming check** before it is written down: *ho
 | reconciliation alert latency | 4h → 15min | alerting on everything, so nobody reads them | alerts acked by a named owner, ≤2/week |
 ```
 
-A metric with no gaming check is a metric the FDE will be held to and cannot defend. If the customer resists the guard, that is the real conversation - they are attached to the number, not the outcome.
+If a proposed guard is disputed, capture the stated reason and assess its cost and effect on the outcome. Do not infer that the customer values the number over the result.
 
 **`stakeholders.md`**:
 ```markdown
 | Who | Role | Signal | Notes |
 |-----|------|--------|-------|
-| <name> | sponsor / champion / resistor / veto / passed-over | green/amber/red | <evidence, day> |
+| <name> | <observed participation role; authority recorded separately> | green/amber/red | <evidence, day> |
 ```
 If `stakeholders.md` already has a `## Signal history` section (it does from the template), **never delete or overwrite it** when you rewrite this file - it holds the dated `[signal:...]` tokens `fde log contact --signal` and `fde debrief` write, and `fde status`/`fde receipts`/the dashboard read only from that section. Edit the table above it freely; keep the section below intact.
 
 **`trust-profile.md`** - sacred data (`<private>` tagged), fears heard, AI policy, approval chain. Sensitive: skip for status reads; use CLI/redacted surfaces; never paste raw `<private>` into prompts or subagents.
 
-**`assumptions.md`** - seed every unverified claim from the brief (and the day-1 hypothesis) as rows with Kind `UNKNOWN` (or `CONVENTION` if they said "we always"), blast radius CRITICAL / LOAD-BEARING / CONVENIENCE, and status `OPEN`. Do not wait for test-assumptions - land makes the register exist. Example:
+**`assumptions.md`** - seed consequential unverified claims from the brief (and the initial hypothesis) as rows with Kind `UNKNOWN` (or `CONVENTION` if they said "we always"), blast radius CRITICAL / LOAD-BEARING / CONVENIENCE, and status `OPEN`. Do not wait for test-assumptions - land makes the register exist. Example:
 
 ```markdown
 | # | Assumption | Kind | Blast radius | How we test | Status | Evidence |
@@ -113,7 +113,7 @@ One falsifiable hypothesis about the real problem also goes at the bottom of `br
 
 ## Checkpoint
 
-One page back to the FDE: success + value bucket + sign-off owner, out-of-scope boundary, sacred data, stakeholder map with veto power, AI posture, the hypothesis, the top CRITICAL assumptions still OPEN, and any exception-path seeds heard (break → workaround → owner) for discover to map into `terrain.md`. If it doesn't fit one page, the engagement isn't understood yet.
+One page back to the FDE: success + value bucket + sign-off owner, out-of-scope boundary, sacred data, stakeholder map with veto power, AI posture, the hypothesis, the top CRITICAL assumptions still OPEN, and any exception-path seeds heard (break → workaround → owner) for discover to map into `terrain.md`. Keep the summary short and link necessary detail; a complex engagement may need supporting evidence.
 
 If remote: agree how progress and blockers will be shared; use a short call when asynchronous context is insufficient.
 
@@ -121,16 +121,16 @@ If remote: agree how progress and blockers will be shared; use a short call when
 
 Kickoff at Acme payments. Priya (VP Eng) sponsors; the brief says "add monitoring to the reconciliation service."
 
-Asking what happens the week after a perfect delivery gets: "I stop hearing about it from finance." That is the real success statement - not monitoring. The previous attempt surfaces too: the platform team built alerting last year, it was turned off. Raj, who built it, is still there and was not in the kickoff - the passed-over team, found on day 1 rather than at the first standup.
+Asking what happens the week after a perfect delivery gets: "I stop hearing about it from finance." That suggests a concern to clarify alongside the monitoring request. The previous attempt surfaces too: the platform team built alerting last year, it was turned off. Raj, who built it, is still there and was not in the kickoff. Ask for his account of the earlier attempt; his absence does not explain his views.
 
-What gets written: `success.md` with bucket `risk-mitigation`, `reconciliation failures reach a named owner within 15 min (baseline: 4h, found by finance)`, gaming check `alerting on everything so nobody reads them` → guard `≤2 alerts/week, acked by name`, sign-off Priya. `brief.md` carries the gap list and the hypothesis: *the job is not unmonitored, it is unowned*. `assumptions.md` seeds `"finance would act on an alert" - CRITICAL - OPEN - (stated, unverified)`. `trust-profile.md` records the sacred thing Priya hesitated before naming.
+In this example Priya reports a four-hour baseline and proposes the following target; her acceptance authority still needs its source. What gets written: `success.md` with proposed bucket `risk-mitigation`, `reconciliation failures reach a named owner within 15 min (baseline: 4h, found by finance)`, gaming check `alerting on everything so nobody reads them` → guard `≤2 alerts/week, acked by name`, proposed sign-off Priya until confirmed. `brief.md` carries the gap list and the hypothesis: *the job is not unmonitored, it is unowned*. `assumptions.md` seeds `"finance would act on an alert" - CRITICAL - OPEN - (stated, unverified)`. `trust-profile.md` records the boundary Priya explicitly names, through the permitted privacy-safe workflow.
 
-Day-1 deliverable: fix the log line that swallows the job's exit code. Small, visible, in their environment.
+Early deliverable: verify and fix the log line that swallows the job's exit code within the existing scope. Deployment remains subject to the established release authority and checks.
 
 ## Principles
 
-- Never start technical work before `success.md` exists.
+- Establish the outcome and authority needed for the next action; missing record files do not block useful standalone work.
 - Sacred data tagged `<private>` stays out of model context: use CLI/redacted reads; never paste raw private blocks.
-- The brief is a hypothesis; discover confirms it. Seed `assumptions.md` on day one.
-- The passed-over internal team is the best source of truth, not an obstacle.
+- Treat unverified parts of the brief as hypotheses; discovery may support or overturn them. Record consequential assumptions.
+- Learn from the existing team and verify consequential claims without guessing motives.
 - If the customer cannot define success, that is the first problem to solve.

package/skills/fde/references/plan.md

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