fde-framework 0.1.0__py3-none-any.whl

fde/framework/approaches/audit-only.md

@@ -0,0 +1,23 @@
+---
+id: audit-only
+name: Audit trail
+complexity: 0
+components: [governance]
+applies_when: [data_residency == may_leave]
+avoid_when: [access_model == role_based, data_residency == cannot_leave, hosting == air-gapped]
+evidence: {case_ids: [churn-scoring], confidence: high, last_verified: 2026-08-25}
+---
+A record of what happened, without a boundary around where it happened.
+
+The right answer where nothing forbids egress but actions are still taken on
+someone's behalf. Enforcing placement costs real complexity -- split
+deployments, pinned components, a build that fails on a topology change -- and
+paying for it when nothing requires it is the over-engineering the residency
+question exists to prevent.
+
+Residency and isolation are not the same requirement, and conflating them is a
+known and expensive mistake. Data staying in a region satisfies one; only
+staying inside a boundary satisfies the other.
+
+What does not change: the record names the human as subject and the agent as
+actor, and the trail never fails open into silence.

fde/framework/approaches/boundary-and-audit.md

@@ -0,0 +1,18 @@
+---
+id: boundary-and-audit
+name: Boundary and audit
+complexity: 1
+components: [governance]
+applies_when: [data_residency == cannot_leave, hosting == air-gapped]
+avoid_when: [access_model == role_based, data_residency == may_leave]
+evidence: {case_ids: [structured-extraction], confidence: high, last_verified: 2026-08-21}
+---
+Not needed where nothing forbids egress -- a boundary around data free to
+move is ceremony. Placement enforced structurally, and an append-only record of what happened.
+
+Entitlements are inherited, never granted: what an agent may do is the
+intersection of what the delegating person may do, what it is scoped to, and
+what the tool requires. Never a union.
+
+The audit names the human as subject and the agent as actor. A record saying an
+agent issued a refund has lost the accountability chain.

fde/framework/approaches/cascade.md

@@ -0,0 +1,32 @@
+---
+id: cascade
+name: Cascade
+complexity: 2
+components: [representation, retrieval, reasoning]
+applies_when: [confidence_calibrated == true and cheap_path_coverage < 0.95]
+avoid_when: [confidence_calibrated == false, interpretability_required == true]
+evidence: {case_ids: [structured-extraction], confidence: medium, last_verified: 2026-08-24}
+---
+Do the cheap confident work; escalate the rest.
+
+Four unrelated lines of practice describe this same shape. Entity resolution
+runs deterministic rules on records carrying an exact identifier and something
+probabilistic on the remainder. Model cascades try the cheapest model and
+escalate only what fails a threshold, reported at roughly half to four-fifths
+off while holding most of the quality. Active learning scores without labels and
+sends the least confident to a human. Tiered memory keeps cheaply and promotes
+deliberately.
+
+They are one pattern, and the payoff compounds: **the records the cheap tier
+could not settle are simultaneously the escalation path and the queue worth a
+human's attention** -- and once verified, the additions to the golden set. One
+residue, three uses.
+
+What separates a cascade from a router is that **the decision is made on the
+output, not the input**. The cheap tier attempts the work and is then judged.
+
+Which makes calibration the whole thing rather than a detail. Confidence scores
+are typically miscalibrated, and a threshold tuned on one workload routinely
+fails on the next, so a cascade without a measured error rate is a cost saving
+with an unknown liability attached. Ruled out where a decision must be
+explained: "the cheap path was confident" is not a reason anyone accepts.

fde/framework/approaches/classical-ml.md

@@ -0,0 +1,21 @@
+---
+id: classical-ml
+name: Classical ML
+complexity: 1
+components: [representation, reasoning]
+applies_when:
+  - output_shape == classification
+  - output_shape == ranking
+  - output_shape == decision and labelled_count >= 1000
+avoid_when: [output_shape == freeform, output_shape == structured]
+evidence: {case_ids: [churn-scoring], confidence: high, last_verified: 2026-08-21}
+---
+Gradient-boosted trees and their relatives on tabular data.
+
+Still the right answer for a numeric or class outcome from columns, and it wins
+on the three axes that usually decide: it trains on far less data, it answers in
+single-digit milliseconds, and it can say which features moved the prediction.
+
+That last one is often decisive rather than nice to have. A requirement to
+explain a decision to a regulator rules out approaches that cannot produce a
+reason, whatever their accuracy.

fde/framework/approaches/compose.md

@@ -0,0 +1,18 @@
+---
+id: compose
+name: Compose
+complexity: 1
+components: [deployment]
+applies_when: [container_competence == true]
+avoid_when: [existing_cluster == true, container_competence == false]
+evidence: {case_ids: [studio-style], confidence: high, last_verified: 2026-08-25}
+---
+Several containers on one host, declared together.
+
+The right rung for more than one long-lived process where multi-node scheduling
+is not required. Isolation and reproducible dependencies without a control
+plane, an etcd or an upgrade treadmill.
+
+Its limit is honest and worth stating up front: one host. When that host is
+being restarted, the service is down, and if that is unacceptable the next rung
+is the answer rather than a workaround here.

fde/framework/approaches/decision-log.md

@@ -0,0 +1,21 @@
+---
+id: decision-log
+name: Decision log
+complexity: 0
+components: [accountability]
+applies_when: [interpretability_required == true]
+avoid_when:
+  - output_shape == freeform
+  - output_shape == classification
+  - output_shape == ranking
+evidence: {case_ids: [structured-extraction], confidence: high, last_verified: 2026-08-25}
+---
+Every decision kept with its inputs and the rule that produced it.
+
+Enough where the decision came from a rule: replaying the rule against the
+recorded inputs reproduces the outcome exactly, which is the strongest form of
+explanation available and needs no model to generate it.
+
+Not enough where the decision came from a model. There, the inputs and the
+outcome do not reconstruct the reasoning, and something that attributes the
+outcome to its drivers is required instead.

fde/framework/approaches/deterministic-masking.md

@@ -0,0 +1,18 @@
+---
+id: deterministic-masking
+name: Deterministic masking
+complexity: 0
+components: [redaction]
+applies_when: [sensitivity_present == true]
+avoid_when: [sensitivity_present == false]
+evidence: {case_ids: [structured-extraction], confidence: medium, last_verified: 2026-08-30}
+---
+Named fields replaced by stable hashes, before anything downstream sees the
+record.
+
+Deterministic on purpose, twice over. The same value masks to the same token,
+so joins and deduplication survive masking -- a random mask would quietly
+break every downstream equality. And the field list is declared, not
+detected: a model guessing which fields are sensitive is a model that will
+one day guess wrong in the direction that matters, so the list comes from the
+contract the client's own samples marked and the FDE confirmed.

fde/framework/approaches/deterministic.md

@@ -0,0 +1,25 @@
+---
+id: deterministic
+name: Deterministic
+complexity: 0
+components: [representation]
+applies_when: [output_shape == structured, output_shape == decision]
+avoid_when:
+  - output_shape == freeform
+  - output_shape == ranking
+  - cheap_path_coverage < 0.95
+evidence: {case_ids: [structured-extraction], confidence: high, last_verified: 2026-08-21}
+---
+Entity masters, regular expressions, generated code, explicit mappings.
+
+Where correctness is not negotiable -- mapping a field, deriving a figure,
+resolving an identifier -- this is the right tool and a model is not. "The
+model will handle it" is the wrong answer in a regulated setting, and it is
+usually the wrong answer everywhere else that a rule can be written down.
+
+Right where it covers the work. Where a meaningful share of records carry no
+exact identifier, rules alone finish the ones they can and drop the rest
+quietly -- which is why coverage is asked rather than assumed.
+
+Cheapest to run, cheapest to explain, and it fails loudly rather than
+plausibly. Reach past it only when the mapping genuinely cannot be stated.

fde/framework/approaches/direct-call.md

@@ -0,0 +1,10 @@
+---
+id: direct-call
+name: Direct call
+complexity: 0
+components: [integration]
+applies_when: [external_systems < 2]
+avoid_when: [external_systems > 1]
+evidence: {case_ids: [churn-scoring], confidence: high, last_verified: 2026-08-21}
+---
+One system, called directly. A registry for a single endpoint is ceremony.

fde/framework/approaches/episodic-store.md

@@ -0,0 +1,17 @@
+---
+id: episodic-store
+name: Episodic store
+complexity: 2
+components: [memory]
+applies_when: [recall_span == across_sessions]
+avoid_when: [recall_span == within_turn, recall_span == within_session]
+evidence: {case_ids: [studio-style], confidence: medium, last_verified: 2026-08-21}
+---
+What the system learned, kept beyond the session that produced it.
+
+A different system from working state, with a different write policy, and it
+fails differently: a wrong belief written here is permanent and will be recalled
+with confidence. What gets promoted from working state to long-term is the
+decision that matters, and it should be deliberate rather than automatic.
+
+Holds client data by definition, so it inherits residency -- embeddings too.

fde/framework/approaches/explainability-record.md

@@ -0,0 +1,14 @@
+---
+id: explainability-record
+name: Explainability record
+complexity: 1
+components: [accountability]
+applies_when: [interpretability_required == true]
+avoid_when: [interpretability_required == false]
+evidence: {case_ids: [churn-scoring], confidence: high, last_verified: 2026-08-21}
+---
+Every decision keeps what drove it, in a form somebody outside the team can read
+months later.
+
+Built in from the start or not at all: reconstructing why a model decided
+something after the fact is guesswork wearing a report's formatting.

fde/framework/approaches/field-match.md

@@ -0,0 +1,15 @@
+---
+id: field-match
+name: Field-level matching
+complexity: 0
+components: [evaluation]
+applies_when: [output_shape == structured]
+avoid_when: [output_shape == freeform]
+evidence: {case_ids: [structured-extraction], confidence: high, last_verified: 2026-08-21}
+---
+Compare each field against a verified answer. Exact where the field is exact,
+tolerant where it is a date or an amount.
+
+Gives a per-field breakdown rather than one number, which is what tells you
+what to build next. Eighty-eight percent accurate says how often you fail; the
+shape of the twelve percent says why.

fde/framework/approaches/finetune.md

@@ -0,0 +1,29 @@
+---
+id: finetune
+name: Fine-tuning
+complexity: 3
+components: [reasoning, representation]
+applies_when: [output_shape == freeform and labelled_count >= 1000]
+avoid_when: [output_shape == classification, output_shape == decision]
+evidence: {case_ids: [structured-extraction], confidence: medium, last_verified: 2026-08-21}
+---
+Adapting a model's behaviour: tone, house style, output shape, schema mapping.
+
+**For behaviour, never for facts.** Fine-tuning teaches a model *how* to
+respond, not *what* is true; anything that changes weekly belongs in retrieval,
+not in weights. Train only on verified pairs -- unverified rows are an asset,
+but they are mined rather than trained on.
+
+**Reached by graduation or override, never by the first decision.** The
+prompted model is simpler and applies wherever this does, so
+simplest-first always chooses it first -- which is this corpus's own
+rule: try the model before adapting it, and let the measured gap argue
+for adaptation. Until calibrated graduation triggers exist, the road
+here is `fde override`, with the measured gap as the reason.
+
+The label count is in the applies condition because it is the whole question:
+adaptation without enough verified pairs is not available, whatever the output
+shape, and an approach that never asked how many labels exist would recommend
+training on hope.
+
+Expensive to reverse: a change means retraining and re-evaluating. Earn it.

fde/framework/approaches/fixed-sequence.md

@@ -0,0 +1,19 @@
+---
+id: fixed-sequence
+name: Fixed sequence
+complexity: 0
+components: [planning]
+applies_when: [always]
+avoid_when: [output_shape == decision]
+evidence: {case_ids: [structured-extraction], confidence: high, last_verified: 2026-08-21}
+---
+Steps written in advance, in order, by a person.
+
+Every path is enumerable, so every path can be tested. Cost and latency are
+bounded at design time rather than discovered in production. Where the work
+genuinely has a fixed shape this is not a lesser option, it is the correct one,
+and reaching past it is how a pipeline acquires a control loop it never needed.
+
+The question worth asking is not whether this counts as an agent. It is whether
+the next step can depend on the last one in a way nobody enumerated -- and if
+it cannot, this is the answer.

fde/framework/approaches/gitops.md

@@ -0,0 +1,18 @@
+---
+id: gitops
+name: Manifests in version control
+complexity: 0
+components: [provisioning]
+applies_when: [existing_cluster == true]
+avoid_when: [existing_cluster == false]
+evidence: {case_ids: [route-planning], confidence: medium, last_verified: 2026-08-25}
+---
+The desired state in a repository, reconciled onto a cluster that already exists.
+
+"Neither provisioner" as a real answer. Where the infrastructure is somebody
+else's problem, adding one provisions nothing and gives an FDE a second thing to
+hand over.
+
+What it buys instead is that the deployed state is reviewable and revertable by
+whoever already reviews changes, which is usually the property people wanted
+from a provisioning tool in the first place.

fde/framework/approaches/governed-tools.md

@@ -0,0 +1,18 @@
+---
+id: governed-tools
+name: Governed tool boundary
+complexity: 1
+components: [integration]
+applies_when: [external_systems > 1]
+avoid_when: [external_systems < 2]
+evidence: {case_ids: [route-planning], confidence: high, last_verified: 2026-08-21}
+---
+One entry point through which every outward call passes, each tool declaring a
+typed schema, the scope it requires, and whether it changes anything.
+
+Past the first system this stops being tidiness: it is the only place
+authentication, authorisation and audit can be enforced once instead of per
+caller. The mutative flag is what lets the autonomy move find the steps needing
+a gate and an idempotency key, without anyone remembering to add them.
+
+An unregistered tool cannot be called. That is the property, not a policy.

fde/framework/approaches/graph-retrieval.md

@@ -0,0 +1,22 @@
+---
+id: graph-retrieval
+name: Graph retrieval
+complexity: 3
+components: [retrieval]
+applies_when: [query_pattern == multi_hop]
+avoid_when: [query_pattern == lookup, query_pattern == comparative]
+evidence: {case_ids: [structured-extraction], confidence: medium, last_verified: 2026-08-21}
+---
+Explicit entities and edges, traversed at query time.
+
+Worth its cost only where similarity search structurally cannot answer -- how
+two things connect, rather than which text resembles a query. On single-fact
+lookup it measurably loses to plain chunks, so this is a specialised instrument
+rather than an upgrade.
+
+The costs are real: multi-pass extraction to build it, two to three times the
+end-to-end latency to use it, and an index that grows super-linearly, which is
+what makes incremental updates painful on a corpus that changes.
+
+Published gains also warrant scepticism -- judge position bias has been shown to
+swing reported win rates by tens of points. Measure on your own traffic.

fde/framework/approaches/judged.md

@@ -0,0 +1,15 @@
+---
+id: judged
+name: Judged
+complexity: 2
+components: [evaluation]
+applies_when: [output_shape == freeform]
+avoid_when: [output_shape == structured, output_shape == classification]
+evidence: {case_ids: [studio-style], confidence: medium, last_verified: 2026-08-21}
+---
+A model grades the output against a rubric, calibrated against human agreement
+before anyone trusts it.
+
+Two rules. The author never grades itself. And where nothing may leave, the
+judge runs locally -- a metric that needs a hosted model is not a metric you
+have, and finding that out at deployment is too late.

fde/framework/approaches/keyword-search.md

@@ -0,0 +1,11 @@
+---
+id: keyword-search
+name: Keyword search
+complexity: 0
+components: [retrieval]
+applies_when: [query_pattern == lookup]
+avoid_when: [query_pattern == multi_hop]
+evidence: {case_ids: [structured-extraction], confidence: high, last_verified: 2026-08-21}
+---
+Lexical matching. Unfashionable, cheap, and hard to beat when people search for
+terms that actually appear -- identifiers, part numbers, names.

fde/framework/approaches/kubernetes-manifests.md

@@ -0,0 +1,19 @@
+---
+id: kubernetes-manifests
+name: Cluster manifests
+complexity: 2
+components: [deployment]
+applies_when: [existing_cluster == true, external_systems > 2]
+avoid_when: [container_competence == false and existing_cluster == false]
+evidence: {case_ids: [route-planning], confidence: high, last_verified: 2026-08-25}
+---
+Manifests applied to a cluster that already exists.
+
+Cheap when the cluster is there and somebody else patches it -- the tenth
+workload costs almost nothing, which is the entire argument for a platform.
+
+Expensive when it is not. Standing up a cluster for one deployment buys a
+control plane, an upgrade cadence and a set of failure modes for something that
+wanted a service unit, and the cost lands on whoever is still there in a year.
+
+Competence gates this only where no cluster exists yet. A cluster already running means somebody operates it -- manifests are how that shop deploys, whatever this team's container practice, and blocking the only cluster-native option on the applying team's skills would leave a cluster shop with no way to deploy at all.

fde/framework/approaches/labelled-metrics.md

@@ -0,0 +1,14 @@
+---
+id: labelled-metrics
+name: Labelled metrics
+complexity: 0
+components: [evaluation]
+applies_when: [output_shape == classification, output_shape == ranking, output_shape == decision]
+avoid_when: [output_shape == freeform, output_shape == structured]
+evidence: {case_ids: [churn-scoring], confidence: high, last_verified: 2026-08-21}
+---
+Precision, recall and their relatives against held-out labels.
+
+Pick the metric from the cost of each error, not from convention. Where a false
+negative costs a hundred times a false positive, accuracy is the wrong number
+and will look fine while the system fails.

fde/framework/approaches/llm-extraction.md

@@ -0,0 +1,26 @@
+---
+id: llm-extraction
+name: Model extraction
+complexity: 2
+components: [representation]
+applies_when: [output_shape == structured]
+avoid_when: [interpretability_required == true]
+evidence: {case_ids: [structured-extraction], confidence: medium, last_verified: 2026-08-27}
+---
+A model decoding raw records into the declared contract.
+
+Split from the prompted-model approach deliberately, because the claim is
+narrower than "use a model": this is a *representation* move, it exists only
+where there is a contract to decode into, and freeform output has none. An
+approach whose applicability differs by component is two approaches wearing
+one name, and the seam always shows at the worst moment.
+
+The opening move for extraction before anything has been measured -- the
+deterministic path needs coverage nobody has counted and the cascade needs
+calibration that does not exist yet. Behind the same Mapper interface the
+deterministic path satisfies, so graduating when the numbers arrive is a
+swap, not a redesign.
+
+Avoided where interpretability is required: a mapping that cannot say why it
+mapped is precisely what that requirement forbids, and the deterministic
+path is the interpretable one.

fde/framework/approaches/llm-scrubbing.md

@@ -0,0 +1,20 @@
+---
+id: llm-scrubbing
+name: Model-assisted scrubbing
+complexity: 2
+components: [redaction]
+applies_when: [sensitivity_present == true]
+avoid_when: [sensitivity_present == false, data_residency == cannot_leave]
+evidence: {case_ids: [structured-extraction], confidence: low, last_verified: 2026-08-30}
+---
+A model rewrites free text with the identifying entities removed, for the
+case field-level masking cannot reach: a name living *inside* a narrative
+field, not in a field of its own.
+
+Never the first decision -- deterministic masking is simpler and wins where
+the sensitive material is field-shaped, which is the common case and the
+measurable one. Reached by override when the sample pairs show identifiers
+inside prose, and carrying its own irony to manage: the scrubbing model sees
+the unscrubbed text, so on a boundary engagement it must run inside -- and
+where data cannot leave at all, the boundary already holds everything and
+this approach is avoided outright.

fde/framework/approaches/llm.md

@@ -0,0 +1,23 @@
+---
+id: llm
+name: Prompted model
+complexity: 2
+components: [reasoning]
+applies_when: [output_shape == freeform, output_shape == structured]
+avoid_when: [output_shape == classification, output_shape == decision]
+evidence: {case_ids: [studio-style], confidence: medium, last_verified: 2026-08-21}
+---
+A capable model, prompted, with no adaptation.
+
+The right first move for open-ended generation, and the fastest thing to stand
+up. Try it before fine-tuning: the gap it leaves is what tells you whether
+adaptation is worth its cost.
+
+The same holds for structured output, where the model decodes into a declared
+schema. This is the standard opening move for extraction before anything has
+been measured -- the cascade needs calibration that does not exist yet, and
+the deterministic path needs coverage nobody has counted. Start here, measure,
+then graduate.
+
+Swapping the model rarely fixes a wrong answer -- it changes the tone of the
+wrong answer. When quality is capped, look upstream at what the model was given.

fde/framework/approaches/local-embedding.md

@@ -0,0 +1,28 @@
+---
+id: local-embedding
+name: Local embeddings
+complexity: 1
+components: [embedding]
+applies_when: [data_residency == cannot_leave, hosting == air-gapped, hosting == on-prem]
+avoid_when: [operates_after_handover == nobody_yet and data_residency == may_leave]
+evidence: {case_ids: [structured-extraction], confidence: high, last_verified: 2026-08-25}
+---
+An embedding model running inside the boundary.
+
+Chosen because something forbids the alternative rather than because it is
+better. Small embedding models are cheap to run and unremarkable to operate,
+which makes this a far lighter obligation than self-hosting a generation model
+-- but it is still a model somebody has to keep running after the engagement
+ends.
+
+Ruled out where nobody is named to operate it. A model with no owner is a
+liability handed over with a bow on it, and an embedding model whose host dies
+takes the index with it.
+
+The handover concern is stated precisely rather than broadly: with nobody
+named to operate and data free to leave, the managed alternative is
+strictly simpler and wins. But where data cannot leave, the plain
+realization is an in-process library call whose operational burden is the
+application's own -- the broad version of this avoid once treated a
+library import like a GPU fleet, and stranded every engagement inside a
+boundary.

fde/framework/approaches/managed-api.md

@@ -0,0 +1,49 @@
+---
+id: managed-api
+name: Managed API
+complexity: 0
+components: [serving]
+applies_when: [data_residency == may_leave]
+avoid_when:
+  - data_residency == cannot_leave
+  - hosting == air-gapped
+  - hosting == on-prem
+  - human_waiting == no and corpus_size > 100000
+  - human_waiting == no and arrival_rate > 50000
+  - latency_budget_ms < 100
+evidence: {case_ids: [studio-style], confidence: high, last_verified: 2026-08-21}
+---
+Somebody else's endpoint, paid per token.
+
+A p95 budget under a hundred milliseconds cannot be met across somebody
+else's network: the round trip and their queue are spent before any work
+happens. That is a physics objection, not a pricing one, which is why it is
+a rule here rather than a note in the costing.
+
+The volume objection is really about flow, not stock: fifty thousand
+requests a day with nobody waiting is sustained work that rented GPUs do
+for a fraction of per-token pricing, whatever the archive size says.
+
+The cheapest way to be wrong cheaply: no infrastructure, no cold start, nothing
+to operate. Sustained high-volume interactive traffic is where it stays cheapest
+too, because self-hosting the same load means paying for redundancy and peak
+headroom around the clock.
+
+It stops being the cheapest option on high-volume work with nobody waiting:
+per-token pricing at that scale runs several times what rented GPUs cost for
+the same job, and the cold start nobody is waiting through costs nothing.
+
+Sending data here is one-way. You cannot un-send it, which is a different
+category of decision from an expensive one.
+
+Provider prompt caching changes the arithmetic before any sizing does: reused
+prompt prefixes bill at a fraction of the input rate, but only on exact token
+match. That makes prompt hygiene a production concern, not an optimisation --
+variable content (timestamps, user names) placed early in the prompt
+invalidates every cached block after it, and rewriting history (summarising)
+re-bills the whole prefix where trimming it in place stays byte-identical. A
+semantic cache is a different animal: it returns stored responses on
+similarity, skips the model entirely, and can return a confidently wrong
+answer with a success status -- a sentence and its negation embed close
+together. It is a retrieval system wearing a cache's name, and it needs the
+same evaluation any retrieval gets.

fde/framework/approaches/managed-embedding.md

@@ -0,0 +1,22 @@
+---
+id: managed-embedding
+name: Managed embeddings
+complexity: 0
+components: [embedding]
+applies_when: [data_residency == may_leave]
+avoid_when:
+  - data_residency == cannot_leave
+  - hosting == air-gapped
+  - hosting == on-prem
+evidence: {case_ids: [studio-style], confidence: high, last_verified: 2026-08-25}
+---
+A vendor endpoint. Nothing to host, nothing to keep warm, and generally better
+quality per unit of effort than anything self-hosted at small scale.
+
+Ruled out wherever the text may not leave, and for the reason people find
+surprising: sending an embedding is sending the text. Vectors are recoverable
+to their source, so this is not a way of anonymising anything on the way out.
+
+One-way, like any vendor call. And expensive to reverse for a second reason --
+changing embedding model means reindexing everything, so leaving is a
+reindexing project rather than a configuration change.

fde/framework/approaches/manual-runbook.md

@@ -0,0 +1,32 @@
+---
+id: manual-runbook
+name: Written steps
+complexity: 2
+components: [provisioning]
+applies_when: [always]
+avoid_when:
+  - existing_cluster == true
+evidence: {case_ids: [structured-extraction], confidence: medium, last_verified: 2026-08-25}
+---
+Steps somebody follows, written down.
+
+The floor, and what nothing-known resolves to. Automating a deployment before
+anyone has performed it once tends to automate a guess -- and a runbook that has
+been followed successfully is the only honest input to a playbook worth writing.
+
+Not a permanent answer. It is the rung that costs least to be wrong about, and
+it graduates as soon as the environment is understood well enough that repeating
+the steps is tedious rather than instructive.
+
+Ruled out where the team already runs something. Handing a written procedure to
+a shop with an existing tool is asking them to do by hand what they already
+automate.
+
+Complexity 2, not 0, and the number is the design: complexity orders by
+cost of ownership, and a runbook is recurring human labour forever --
+every automated tool that applies beats it on that measure, which is the
+preference expressed without a single avoid rule. When the better tools
+are blocked (an Ansible shop with an ephemeral environment, a Terraform
+shop with no API), nothing avoids the runbook, and the floor holds.
+Ephemeral by hand is painful and is said so here; painful is not the same
+as impossible.

fde/framework/approaches/model-planner.md

@@ -0,0 +1,19 @@
+---
+id: model-planner
+name: Model planner
+complexity: 3
+components: [planning]
+applies_when: [output_shape == decision, recall_span == across_sessions]
+avoid_when: [interpretability_required == true]
+evidence: {case_ids: [route-planning], confidence: low, last_verified: 2026-08-21}
+---
+The model decomposes the goal at run time and chooses what to do next.
+
+This is the line worth drawing. Once the next step can depend on the last in a
+way nobody enumerated, paths stop being testable and cost stops being bounded --
+so crossing it obliges three things a fixed sequence never needed: a step cap, a
+budget cap, and a critic before anything irreversible.
+
+Ruled out where a decision must be explained. A plan invented at run time is
+hard to defend afterwards, and "the model decided" is not a reason a regulator
+accepts.