@tenkara/afm-linux-arm64 0.0.0-stage → 4.0.0-alpha.7

package/content/ops/update.md

@@ -0,0 +1,223 @@
+---
+type: op
+description: Brings a materialized instance up to the current plugin version.
+load: warm
+writes: ["docs/.afm-version", "docs/evolution/*.md"]
+composes: []
+---
+# Sub-flow: sync of the materialized instance with the current plugin version (`update`)
+
+> **In this file:** What update is / is not · Procedure · What the codemods can do · Instances older than 4.0 · 1.6 Language migration · Opt-in deltas · Post-conditions · Suppression contract · Anti-patterns
+
+> **Form** — effect: deltas in the instance + bump · trigger: `afm update`, composition · precondition: pin ≠ the shipped version · composed by: `evolve` 2.2 · **degree of freedom: low**
+
+Triggers: `afm update`, or natural language for **version bump / sync with the plugin**. Examples:
+"update AFM here", "bump the methodology version", "sync `docs/` with the new plugin", "migrate to the new
+AFM version", "my `.afm-version` is behind".
+
+> **The write target is the local docs (`docs/`), NEVER the plugin.** `afm update` reads the shipped
+> content only to **discover the deltas**. It **materializes** the consumer-facing ones
+> in the local instance. It never edits the plugin (bright line #7). See `afm path ops/evolve` § The
+> target of evolution.
+>
+> **Sync mechanism, not orchestrator.** `update` resolves the **instance-to-plugin version drift** (axis
+> A3, which `afm diagnose` *detects* but does not fix). It runs à la carte (this doc, with its own gate)
+> or inside the `evolve` cycle, which composes it when `afm diagnose` flags A3, with the own gate
+> suppressed (see § Suppression contract).
+
+The command owns everything mechanical: reading the pin, comparing versions, running the **codemod
+registry** of every release between the pin and the binary (ADR-0013), proving each op, keeping the manifest
+and moving the pin at the end. This op owns the three things it cannot do: the agent tasks, the language
+migration and the post-conditions.
+
+## When it is another op instead
+
+- `init` / `refactor` (bootstrap) **create** the instance from zero. `update` assumes the instance
+  **already exists** and only brings it forward. `afm refactor` refuses a project with `.afm-version`;
+  `update` is the correct path for that case.
+- `diagnose` only **detects** A3 (read-only). `update` **resolves** it. Diagnose finds it, update fixes it.
+- `evolve` is the full health cycle. `update` is **one lens** (version sync), composed when A3 fires.
+- `promote` **logs** a finding meant for the plugin. `update` goes plugin to **instance**. Neither op
+  touches the shipped content: an absolute boundary (#7).
+- Not a resolver of `[TBD]`. Not an inventor of product content (#4/#5). It materializes only what the
+  plugin already provides: stack-agnostic rubrics, hygiene rules, template sections. It never fills in a
+  product decision.
+
+## Procedure
+
+1. **Preview:** `afm update --dry-run`. It runs the pre-check and prints every codemod with its result
+   against an overlay of the docs, writing nothing:
+   - Exit 3: no `docs/.afm-version`. Stop and run `afm init` (greenfield) or `afm refactor` (brownfield).
+   - Exit 5: the pin and the binary differ by a major version. Run `afm migrate` (the 3.x to 4.0 bridge),
+     then `afm update` again.
+   - *already up to date*: no drift means nothing to do, and an empty diagnosis is a valid result.
+   - *anomaly*: the pin is **ahead** of the binary. Someone edited the instance by hand, or the binary
+     is old. Report it, upgrade the binary, and never roll the pin back.
+2. **Read the preview as one package, not N loose items.** The tally counts what each op did:
+   - *applied*: the op wrote (a literal replacement, a move, a created or synced file, a frontmatter key,
+     a section, a regenerated surface).
+   - *already applied or absent*: the proof of need failed (the old text is not there), so the delta was
+     already applied or never existed in this instance. Silent, and not work done.
+   - *held*: `[TBD]` content protects the text (#4), or the owner edited a file a codemod would delete.
+     **Stop and report it**: the owner's stance wins.
+   - *failed*: a proof of application did not hold. The pin stays; fix the cause and run again.
+   - *agent task(s) pending*: work only judgment can do (below).
+   - a release with nothing to materialize counts toward the bump and prints no line. Do not invent work
+     where the plugin declared there is none.
+3. **Own gate (à la carte).** Show the preview as evidence (which version to which version, what each
+   codemod changes in the instance), then ask `afm ask update` (questions in
+   `content/questions/update.questions.yaml`). Under the `evolve` cycle this gate is **suppressed**: the
+   migration item moves up to the orchestrator's single gate.
+4. **Apply:** `afm update`. It runs every codemod, proves each one, prints the tally and **moves
+   `docs/.afm-version` only at the end**. The exit code tells what is left:
+   - Exit 0: done, the pin moved.
+   - Exit 1: a codemod failed (or the pin is ahead). The pin stays (marker honesty: never bump as if the
+     migration were complete). Fix it and run again.
+   - **Exit 6: agent tasks are pending.** Do them (step 5), then run `afm update` again. The pin stays until
+     every task passes its check.
+   - **Protected surfaces** are never materialized by an update: the shipped content itself,
+     `PRINCIPLES`, `[TBD]` content, the format the hooks parse, the rubric that decides when the evolution
+     cycle runs (`when-to-evolve-methodology`) and the `triggers` entries that fire the evolution
+     mechanisms. That is self-reference: the sync does not materialize the document that decides when
+     the cycle runs. New stack-agnostic rubrics, yes.
+5. **Do each agent task** listed after the tally. A line reads `agent <codemod>: <brief> (scope: <paths>)`
+   followed by the lines of its check that still fail. Work only inside the scope, through the write ops
+   (`afm adr`, `afm gotcha`, `afm rule`, `afm new <type>`), suppressing each op's own per-artifact
+   question. Run `afm lint <path>` to see the frontmatter findings and `afm lint --fix <path>` to fix
+   the ones that have one exact answer. Never invent content: what the operator did not say stays `[TBD]`.
+   A `[TBD]` placeholder alone lints clean and does not hold the pin.
+6. **Close a sync on an edited file** with `afm update --accept <path>`. When a codemod would overwrite a
+   materialized file the owner edited (its hash in the manifest no longer matches), it hands the merge to
+   the agent instead. Merge the new shipped text into the owner's file, then run
+   `afm update --accept docs/<path>`: it records the file as it is now as the accepted version. It never
+   edits the file.
+7. **Run `afm update` again** until it prints `pin: <from> -> <to>` (or *already up to date*). Then the
+   **post-conditions** (below) and the **log**.
+
+## What the codemods can do
+
+A release is a module in `packages/core/src/features/codemod-releases/data/` with an ordered list of typed ops. The rules that
+make them safe are 0/1 and none depends on judgment:
+
+| Op | What it does | Proof of need | When it hands over |
+| --- | --- | --- | --- |
+| `replace` | literal substitution in one file | the old text is in the file | `[TBD]` there: *held* |
+| `move` | renames a file or a folder | the source exists | a target that already exists |
+| `create` | writes a shipped file the instance lacks | the file is absent | never overwrites |
+| `sync` | overwrites a materialized file with the new shipped text | the manifest hash still equals the file | an edited file becomes an agent task (`--accept`) |
+| `delete` | removes a file the plugin retired | the manifest hash still equals the file | an edited file is *held* |
+| `frontmatter` | sets or renames a key | the key is missing or old | `[TBD]` there: *held* |
+| `section` | adds a section to a doc | the heading is absent | never rewrites an existing one |
+| `regenerate` | rebuilds a generated surface (agents block, stubs, index) | the surface is stale | none |
+| `custom` | a program for what the others cannot say (the OKF lift) | its own | its own agent tasks |
+| `agent` | what only judgment can do (a rewrite, a merge) | its own | always, with a mechanical check |
+
+**The rules:**
+
+1. **Proof of need before a file is touched.** Zero matches means already applied: skip it silently.
+2. **Literal substitution, never a regular expression.** A pattern on an instance the owner edited by
+   hand is how a sync destroys text nobody asked to change.
+3. **Proof of application afterwards.** The old text is gone **and** the new text appears at least as often.
+4. **A file missing from the instance is skipped.** A doc the consumer never materialized does not arrive
+   through the back door, except through an explicit `create`.
+5. **`[TBD]` is untouchable** (#4): text inside a block the owner marked this way is *held*.
+6. **The manifest is the memory of what AFM wrote.** `docs/.afm-manifest.json` maps each file AFM wrote to
+   the hash of the text it wrote. `sync` and `delete` act only on a file whose hash still matches. A file
+   the owner changed is never overwritten or removed silently: the old "update never deletes" is now
+   "update never deletes what the owner changed". Commit the manifest with the docs.
+7. **The proof of need decides, not only the pin.** A codemod whose precondition still holds runs even when
+   the pin is past its release.
+8. **The pin moves last**, and only when every agent task passes its check.
+
+> **Discover-first (#2):** the proof of need is the discover-first rule. A delta the operator already copied
+> by hand never reappears.
+
+## Instances older than 4.0
+
+`afm update` refuses to cross a major version (exit 5). A 3.x instance goes through `afm migrate` first
+(`--dry-run` to preview): the bridge to 4.0, the split of `docs/gotchas.md` into `docs/gotchas/` and of
+`afm.md` section 3 into `docs/rules/`, and the report names. Run it once and **commit before anything
+else** (a structural migration mixed with a content edit hides both in the diff). Then run `afm update`
+to receive the codemods of the 4.x releases (the OKF frontmatter lift among them), and
+`afm index --materialize` (hard rule 39 fails on a missing or stale index).
+
+## 1.6 Language migration (runs when the instance is not English)
+
+Artifacts are English: the docs, the code, the comments, the tests, the rule text. The ONE exception is
+the strings the product shows its own users, and that is a product decision.
+
+**The order below is the mechanism, and reversing it is the defect.** Read the field. Derive the excluded
+scope. Only then read a file. "Scan first, remember to skip" makes the exclusion depend on the agent
+noticing during the work, and that is the branch that damages a product.
+
+1. **Read `docs/prd.md` § 11.1 FIRST.** It holds the app-facing string language. An instance
+   materialized before this field existed has no such section, which reads the same as `[TBD]`.
+2. **`[TBD]` or absent: stop and ask `afm ask update-strings`** (questions in
+   `content/questions/update-strings.questions.yaml`). Never choose a language. The irreducible mistake
+   is "no field, so nothing is a product string, so migrate everything". A translated UI is not something
+   `git revert` gives back to the user who saw it.
+3. **Derive the excluded scope from the answer, before any file is read.** The exclusion is a file and
+   directory list computed once, not a judgment made per file. An English app language makes the excluded
+   scope empty, and the rest is unchanged. `afm lang` reports the language each file is written in.
+4. **Ask ONE question about the artifacts: `afm ask update-artifacts`** (questions in
+   `content/questions/update-artifacts.questions.yaml`). Ask it once, never per file. `Keep the current language` records the choice, because the next update must not ask again.
+5. **On migrate, fan out over the artifacts outside the excluded scope**: the local `docs/`, the code
+   comments, the test names. Each file gets a rewrite. Then an adversarial check asks what fact, number,
+   path, marker or caveat disappeared. The checker reports; it never rewrites.
+6. **Never touch the excluded scope.** Not the UI strings, not the user-facing error messages, not the
+   email copy, not the seed data a user reads. An ambiguous file stays.
+
+**Post-condition.** `prd.md` § 11.1 is unchanged by this step. The migration reads that field and never
+writes it. The product language is the owner's decision, not a consequence of a version bump.
+
+## Opt-in deltas: a release that adds a capability, not a requirement
+
+A capability delta is not a migration. Nothing breaks when the operator ignores it, and `update` must not
+apply it silently, because opting in is the operator's decision. The release notes (`content/CHANGELOG.md`) name it, and no codemod applies it.
+Report an opt-in delta, and never apply it. A project that has not opted in has not decided against the
+feature: it has not been asked.
+
+| Release | Capability | How to opt in | What happens if you do nothing |
+| --- | --- | --- | --- |
+| 3.10.0 | organisation policy | set `[org] dir` in the global config, pointing at a bundle that holds `policy.md` that your user owns (it was the `AFM_GLOBAL_DIR` variable before 4.0) | nothing. Every reader returns before any file test when no bundle is set |
+| 3.11.0 | `policy_blocking` is REMOVED | delete the key if an instance added it | nothing. It decided nothing while it existed |
+
+## Post-conditions
+
+1. **Parseable format.** Re-extraction by the hooks over the touched docs must preserve the format:
+   `afm lint` exits 0, `afm index --check` returns 0 and `afm gate --audit` is no worse than before. Otherwise roll back the
+   delta and report it. Never fail silently.
+2. **The instance/plugin boundary is MECHANICAL.** Run the two-branch check in `afm path ops/evolve`
+   § Phase 4.3 at the end. The boundary must come back clean: any change in the shipped content means
+   **rollback + report CRITICAL**. `update` only reads the plugin.
+
+## Log and handoff
+
+- **À la carte:** report in chat what migrated (applied deltas, pending deltas, the newly pinned version).
+  A simple sync does not need its own `docs/evolution/` entry.
+- **Under `evolve`:** it feeds the cycle report (the A3 migration becomes one line in
+  `docs/evolution/<date>-NNN.md`).
+- **Handoff to `afm reconcile`** to watch, in the following sessions, whether the materialized delta now
+  guides well.
+
+## Suppression contract (back-pointer)
+
+`evolve` **composes `update`** on axis A3. Under the cycle, `evolve` suppresses the gate of step 3 and
+moves the item up to its single gate; the log feeds the cycle report. The authoritative table lives in
+`afm path ops/evolve` § Suppression contract. À la carte, `update` runs on its own, with its own gate.
+
+## Anti-patterns
+
+- ❌ **Editing the shipped content.** `update` only **reads** the plugin to discover deltas. It writes
+  only to the instance.
+- ❌ **Materializing a consumer-noop release.** A plugin-internal patch with no content to materialize
+  only bumps the version. Do not invent work.
+- ❌ **Re-materializing a delta that is already in the instance.** The proof of need exists for this.
+- ❌ **Overwriting or deleting a file the owner edited.** The manifest hash is the guard: merge by hand and close it with `afm update --accept <path>`.
+- ❌ **Materializing a protected surface:** the evolution cycle's own rubric, the evolution `triggers`,
+  and `[TBD]`. This is self-reference, and it is the operator's own stance.
+- ❌ **Bumping `.afm-version` as if the migration were complete.** If a delta was left out, the marker
+  must show the gap honestly.
+- ❌ **Inventing product content.** `update` materializes only what the plugin already provides
+  (stack-agnostic). A missing product decision stays `[TBD]`, for `afm reconcile` to handle (#4/#5).
+- ❌ **Running as bootstrap.** A missing instance calls for `init` or `refactor`, not `update`.

package/content/ops/verify.md

@@ -0,0 +1,69 @@
+---
+type: op
+description: Stamps a human verification on a doc, the only writer of the OKF `verified` field.
+load: warm
+writes: ["docs/**/*.md"]
+composes: []
+---
+# Sub-flow: stamp a human verification (`verify`)
+
+> **In this file:** What verify is / is not · Why only a human · Procedure · What it must never do · Invariants
+
+> **Form** — effect: adds `verified:` to the frontmatter of one file · trigger: `afm verify <path>` · precondition: `.afm-version` · **degree of freedom: low**
+
+Triggers: `afm verify <path>`. Also natural language that states a person checked a document.
+Examples: "I reviewed this rule", "mark this gotcha as verified", "sign off on this ADR".
+
+## What `verify` is, and is not
+
+OKF v0.2 §5.2 keeps two facts apart. `generated` records what PRODUCED the content. `verified`
+records who CONFIRMED it. They are separate because the writer and the checker are different
+actors, and a document can change without re-confirmation.
+
+From those two fields OKF derives a trust tier (§5.3):
+
+| `verified` | Tier |
+| --- | --- |
+| absent | **unverified** |
+| present, no `human:` actor | **machine-confirmed** |
+| present with a `human:<id>` actor | **human-reviewed** |
+
+AFM is autonomy-first. `reflect`, `reconcile` and `remediate` all WRITE documentation. Without this
+operation, "an agent wrote this and no person read it" and "a person approved it" look the same.
+
+## Why only a human, and why only here
+
+An automatic writer would destroy the field. The agent commits under the operator's git identity. A
+hook that stamps `verified` on every commit would claim human review of every agent commit. That is
+worse than no field: it converts an honest absence into a confident lie.
+
+So the rule is one line. **Absence means unverified, and only an explicit human stamp writes it.**
+The command enforces it: it refuses when `AFM_ACTOR` names a role or a machine instead of a person.
+
+## Procedure
+
+1. `afm preflight`. Exit 3: no instance, stop.
+2. **Confirm that a person read the file.** Show it, or ask `afm ask verify` (questions in
+   `content/questions/verify.questions.yaml`). Never infer review from ordinary work. `No` stops.
+3. **Stamp it:** `afm verify <path under docs/>`. The actor is `human:<id>`, where `<id>` comes from
+   `--as <id>`, from `AFM_ACTOR=human:<id>` or from the git `user.name` in lowercase with no space.
+   The command appends `verified: [{ by: "human:<id>", at: <ISO 8601 UTC> }]`, keeps every other
+   key, and adds an entry when `verified` is already a list. A second check is a second event; the
+   tier reads the latest `at`.
+4. **Report the tier that resulted**, and say what it means. The command prints it.
+
+A file with no frontmatter carries no contract to stamp, and the command says so.
+
+## What it must never do
+
+- Never stamp a file the person did not read.
+- Never write `verified` from a hook, a gate, a commit, or another op.
+- Never remove a verification. A doc that changed after a verification stays verified at that date,
+  and the date is the signal. Silently dropping it hides that the content moved.
+- Never write `generated` here. That belongs to whoever produced the content.
+
+## Invariant principles
+
+The single canonical source is `afm path PRINCIPLES`. Universals §1-8 apply. #5 applies hardest:
+this operation records a fact about a person. Inventing one is the worst kind of invention, because
+nothing downstream can tell.

package/content/patterns/adapter.md

@@ -0,0 +1,46 @@
+---
+type: pattern
+description: Wraps a vendor SDK type or payload shape at the boundary so domain and lib code depend on an owned interface instead of the vendor's.
+load: cold
+smell: 'a vendor SDK type (a Stripe object, an S3 response, an ORM row) is imported and used directly inside domain or lib code, past the boundary it arrived at'
+when_to_use: the vendor type crosses more than one file, or it is expected to change independently of the domain model that consumes it
+when_not_to_use: the vendor call happens in exactly one file and its result is consumed nowhere else
+---
+
+# Pattern — Adapter
+
+> Suggestion only. This pattern does not become project convention by existing here — it
+> materializes into `code-style/`, `ach.md`, or an ADR only when the operator accepts it for
+> this codebase.
+
+Continues DIP in `rubrics/solid-triggers.md` (domain must not import infra) and
+`rubrics/validation-boundary.md` (the parser lives at exactly 2 places). Adapter is what sits at
+that same boundary for a *type*, not a schema: it converts the vendor's shape to an owned one on
+the way in, once.
+
+## Decision
+
+| Situation | Verdict | Anti-pattern |
+| --- | --- | --- |
+| `Stripe.Customer` (or equivalent) is read in 2+ files | Adapter: one function maps it to an owned `Customer` type at the boundary, everything past that line uses the owned type | Passing the SDK type through domain and re-reading its fields in each consumer |
+| The SDK's field names or nesting are unstable across major versions (checked: it has broken before) | Adapter absorbs the next breaking change in 1 file | The breaking change ships and touches every call site that read the SDK type directly |
+| The SDK call and its one consumer live in the same file, never exported | No adapter yet — see `when-to-create-lib.md`, one caller does not earn extraction | A `StripeCustomerAdapter` class for a value read once and discarded |
+| The domain needs to call back into the vendor (not just read its output) | Wrap the vendor client behind a port your domain defines (this is DIP, Adapter's usual partner) | Domain importing the vendor SDK client directly to make the call itself |
+
+## Why this works
+
+A vendor's shape is out of your control; a domain model is not. Every field of the vendor type
+read directly in domain code is a place a vendor upgrade can break — with the adapter, an upgrade
+that renames or restructures the vendor type is absorbed in the 1 function that does the mapping,
+never in the N places that use the resulting owned type.
+
+## Anti-patterns
+
+- ❌ An adapter that just renames fields 1:1 and adds no real translation, guarding a type used in
+  exactly one place. That's indirection with no boundary to protect — see `when-to-create-lib.md`.
+- ❌ The adapter returns the vendor's own error type unchanged. Errors need the same translation as
+  data — see `error-classification.md` for what the domain-facing shape should be.
+- ❌ Two adapters for the same vendor type, one per module, silently drifting. Vendor type → owned
+  type is a boundary fact, not a per-module preference; it belongs in one shared place.
+- ❌ Calling the adapter function conditionally, so some call sites still see the raw vendor type.
+  A boundary that is optional is not a boundary.

package/content/patterns/facade.md

@@ -0,0 +1,47 @@
+---
+type: pattern
+description: Bundles a repeated sequence of calls across 3 or more collaborators, that always represents one business step, behind a single function.
+load: cold
+smell: 'a call site wires 3 or more collaborators in the same order, in more than one place, to carry out one coherent business step'
+when_to_use: the same sequence of calls across 3+ collaborators repeats at 2+ call sites and always represents one step
+when_not_to_use: the collaborators are used independently at each call site — a different subset, or a different order, each time
+---
+
+# Pattern — Facade
+
+> Suggestion only. This pattern does not become project convention by existing here — it
+> materializes into `code-style/`, `ach.md`, or an ADR only when the operator accepts it for
+> this codebase.
+
+Continues ISP in `rubrics/solid-triggers.md`, from the other direction: ISP narrows what a single
+function receives; Facade narrows what a *caller* must know to perform one step, by hiding the
+fan-out to several collaborators behind one call.
+
+## Decision
+
+| Situation | Verdict | Anti-pattern |
+| --- | --- | --- |
+| 2+ call sites each wire the same 3+ collaborators, in the same order, for the same outcome | Extract a facade function; the call sites call it once and stop knowing the collaborators exist | Each call site re-derives the correct order, one of them getting it wrong under time pressure |
+| One of the wired collaborators is itself a vendor SDK crossing a boundary | Apply Adapter to that one collaborator first, then wrap the sequence in the Facade | The Facade re-exports the raw vendor type through its own return value, leaking the boundary it should hide |
+| The call sites use *different* subsets or orders of the same collaborators | Do not extract — that variation is the actual logic, and a facade would hide it, not simplify it | A facade with a boolean flag per caller's variant — the flags are the switch this pattern was meant to avoid |
+| Only one call site exists | No facade yet — inline the sequence until a 2nd real caller needs the same one | A `CheckoutFacade` built for a single call site "to keep the handler short" |
+
+## Why this works
+
+A caller wiring C collaborators must know all C APIs, their call order, and how errors from each
+propagate — that knowledge is repeated at every call site that performs the same step. A facade
+moves it to 1 place: each call site's coupling drops from C collaborators to 1 function, and a
+change to the internal wiring (a 4th collaborator added, the order changed) touches that 1 place.
+
+## Anti-patterns
+
+- ❌ A facade over collaborators that are each already simple to call alone. If wiring them takes
+  1 line each, the facade adds a name to remember without reducing real complexity.
+- ❌ A "God facade" that grows to wrap every collaborator in the module, becoming the module's only
+  entry point for unrelated steps. Facade wraps *one* coherent business step, not the whole module
+  — see `rubrics/solid-triggers.md` § SRP if it starts doing 2+ things.
+- ❌ Swallowing or generically catching every collaborator's error inside the facade. Each
+  collaborator's failure still needs its own classification — see `error-classification.md`;
+  a facade changes who calls, not how errors are represented.
+- ❌ Building the facade before the 2nd call site exists, on the belief the sequence will repeat.
+  That is the same premature-extraction risk `when-to-create-lib.md` names for helpers in general.

package/content/patterns/factory.md

@@ -0,0 +1,46 @@
+---
+type: pattern
+description: Centralizes a multi-step object construction that is copy-pasted at 2 or more call sites into one named function.
+load: cold
+smell: 'the same multi-step construction (apply defaults, validate, wire 2+ collaborators) is copy-pasted at 2 or more call sites to build the same kind of object'
+when_to_use: constructing the object takes more than one step, and that construction already repeats at 2+ call sites
+when_not_to_use: the value is a single-field object literal, or only one call site builds it today
+---
+
+# Pattern — Factory
+
+> Suggestion only. This pattern does not become project convention by existing here — it
+> materializes into `code-style/`, `ach.md`, or an ADR only when the operator accepts it for
+> this codebase.
+
+Continues the Rule-of-Three trigger already used in `rubrics/when-to-create-lib.md`: that rubric
+extracts a helper on the 3rd caller. Factory is the same threshold applied specifically to
+*construction* logic — defaults, validation, wiring 2+ collaborators into one object.
+
+## Decision
+
+| Situation | Verdict | Anti-pattern |
+| --- | --- | --- |
+| 2+ call sites build the same kind of object with the same defaults and the same wiring steps | Extract a `create<X>()` factory function; call sites pass only what varies | Each call site re-applies the same defaults, one of them drifting when a default changes |
+| The object needs 1+ collaborator injected (a clock, an id generator, a config) to be testable | Factory takes the collaborators as parameters, with production defaults | The object reaches for `Date.now()` or a singleton internally — untestable without mocking modules |
+| Construction is a single field literal (`{ id, name }`) | No factory. A function that returns its own argument is ceremony | `createUser({ id, name })` that does nothing `{ id, name }` didn't already do |
+| Only one call site exists today | No factory yet — wait for the 2nd real caller, per `when-to-create-lib.md` | A `UserFactory` class built ahead of the 2nd caller, on the promise it is coming |
+
+## Why this works
+
+Construction logic duplicated at K call sites means a changed default, a new required field, or a
+new invariant must be applied K times — and K-1 of those edits are typically missed. A factory
+collapses that to 1 place: the invariant is enforced once, and every call site that changes still
+compiles because they pass arguments to a function, not fields to a literal.
+
+## Anti-patterns
+
+- ❌ A factory with a config object with 12 optional fields, most unused by every caller. That is
+  the object's own complexity leaking into the factory's signature — fix the object first.
+- ❌ A factory that also performs I/O (saves to the DB, calls an API) as a side effect of
+  "constructing." Construction builds a value; persistence is a separate step the caller invokes.
+- ❌ A factory function per call site (`createUserForSignup`, `createUserForAdmin`) that each
+  duplicate 90% of the same logic. That is the smell this pattern exists to remove, reintroduced
+  one layer down — collapse them into one factory with a parameter for the 10% that differs.
+- ❌ Naming it `UserFactory.getInstance()` to imitate a singleton when nothing requires only one
+  instance to exist. A plain exported function is the smaller design (KISS).

package/content/patterns/null-object.md

@@ -0,0 +1,55 @@
+---
+type: pattern
+description: Replaces a null guard repeated at 3 or more call sites with a default implementation that behaves like the absent case's known, safe outcome.
+load: cold
+smell: 'the same `if (x == null) { ...default behavior... }` guard, followed by using `x`, is repeated at 3 or more call sites'
+when_to_use: the absent case has one well-known default behavior and every caller currently branches on null to reach it
+when_not_to_use: callers must react differently to absence, or must distinguish absent from present-but-default
+---
+
+# Pattern — Null Object
+
+> Suggestion only. This pattern does not become project convention by existing here — it
+> materializes into `code-style/`, `ach.md`, or an ADR only when the operator accepts it for
+> this codebase.
+
+A narrower cousin of Strategy in this same library: instead of one implementation per real case,
+it adds exactly one extra implementation standing in for "nothing here" — so the caller's `switch`
+or `if (x == null)` collapses to zero branches, not one fewer.
+
+## Decision
+
+- ✅ 3+ call sites do `if (x == null) return fallbackValue` (or an equivalent guard) right before
+  using `x`, and `fallbackValue` is the same at every one → give the absent case a real
+  implementation of the same interface (an empty cart, a no-op logger, a zero-total invoice) and
+  stop returning `null` in the first place.
+- ✅ The type already has a real interface with 1+ methods (a `Logger`, a `Cart`) → the Null Object
+  implements that interface with safe, inert behavior (`NullLogger.log()` does nothing).
+- ❌ Fewer than 3 call sites guard the same way, or two callers want a *different* fallback → a
+  shared Null Object would force one fallback where callers legitimately need their own; keep the
+  guards local, or pass the fallback in per caller instead.
+- ❌ The caller must tell "absent" apart from "present with the default value" (e.g. a form field
+  the user explicitly cleared vs. one never touched) → collapsing both into one Null Object erases
+  that distinction; `Result`/`Option` is the honest fit — see `result-vs-exception.md`.
+
+## Why this works
+
+Every `if (x == null)` guard is a branch a reader and the compiler must both track; N call sites
+with the same guard is N places that branch identically and N places a future change to the
+fallback must be kept in sync. A Null Object moves the branch inside the 1 place that decides
+"use the real thing or the null thing" (usually the factory or lookup that produces `x`), so the
+N call sites go back to unconditional code — 1 branch total instead of N.
+
+## Anti-patterns
+
+- ❌ A Null Object that throws when any of its methods is called. That is not a null object, it is
+  a differently-shaped exception — it defeats the purpose, which is *safe* default behavior.
+- ❌ Using Null Object where the caller actually needs to know absence happened (an audit log that
+  must record "no discount was found," not silently apply a $0 discount and look identical to a
+  real $0 discount). Prefer an explicit `Option`/`Result` there instead.
+- ❌ A Null Object with mutable shared state (`NullCart` that collects items across unrelated
+  calls). The point of the pattern is a stateless, inert stand-in — shared mutable state turns it
+  into a hidden singleton bug.
+- ❌ Silently swapping `null` for a Null Object across a serialization boundary (DB, API response).
+  Null Object is an in-process convenience; a stored `null` still means "absent" to every reader
+  outside this process, so translate at that boundary instead of upstream.

package/content/patterns/result-vs-exception.md

@@ -0,0 +1,52 @@
+---
+type: pattern
+description: Replaces a thrown exception for an expected, listable failure with a typed Result value the immediate caller must handle.
+load: cold
+smell: 'a function throws for an outcome the caller already anticipates and branches on (validation failure, not-found, conflict), and the caller wraps the call in try/catch to recover that one branch'
+when_to_use: the failure modes are known, finite, and the immediate caller needs to react differently to each one
+when_not_to_use: the failure is unexpected or unrecoverable — a network drop, a timeout, a bug
+---
+
+# Pattern — Result / Either over exception-as-control-flow
+
+> Suggestion only. This pattern does not become project convention by existing here — it
+> materializes into `code-style/`, `ach.md`, or an ADR only when the operator accepts it for
+> this codebase.
+
+`rubrics/error-classification.md` already prescribes the shape (`Result<T, E>` with a literal
+`as const` code) for the Domain layer specifically. This pattern generalizes the same call: apply
+it to *any* function, domain or not, where a `try { } catch { }` exists only to recover one
+specific, anticipated branch — not to handle a genuine surprise.
+
+## Decision
+
+- ✅ The function has 2 or more named, expected outcomes (`EMAIL_TAKEN`, `NOT_FOUND`,
+  `WEAK_PASSWORD`) → return `Result<T, E>` with `E` a literal union, and force the caller to
+  `switch` with an exhaustive `never` default (see `error-classification.md`).
+- ✅ Today's code throws a custom error class only to `catch (e) { if (e instanceof X) }` one line
+  above the call → that `catch` is the tell; replace both sides with `Result`.
+- ❌ The failure is a bug, a timeout, or anything the immediate caller cannot meaningfully act on
+  → let it rise. Wrapping every infra call in `Result` just relocates the `try/catch`, it does not
+  remove it — see `error-classification.md`'s Infra-error row.
+- ❌ The function is called in exactly one place and that place already has a correct
+  `try/catch` → converting it buys nothing; the try/catch already IS the handling.
+
+## Why this works
+
+An exception's type is invisible at the call site — nothing in a function's signature says it can
+throw, so the caller either wraps every call defensively or misses a case entirely. A `Result<T,
+E>` return type puts the failure in the signature: TypeScript's exhaustiveness check on the
+`switch` (the `never` default) then makes an unhandled case a compile error instead of a runtime
+surprise, at zero added `try/catch` blocks.
+
+## Anti-patterns
+
+- ❌ Wrapping infra failures (DB down, network drop) in `Result` "for consistency." Those are not
+  anticipated outcomes — see `error-classification.md`: infra errors rise and get caught once at
+  the process boundary, they do not become a case in every caller's switch.
+- ❌ A `Result<T, string>` with a free-text message instead of a literal code. The caller cannot
+  `switch` on a string; the whole benefit (exhaustiveness) is gone. The code must be `as const`.
+- ❌ Mixing `Result` and exceptions in the same function — return `Result` for the expected branch,
+  then also `throw` for another branch of the same function. Callers must handle two mechanisms.
+- ❌ A generic `try/catch` around a `Result`-returning call "just in case." If the function no
+  longer throws for its expected failures, the surrounding `try` should not exist either.

package/content/patterns/strategy.md

@@ -0,0 +1,45 @@
+---
+type: pattern
+description: Replaces a branching conditional keyed on a kind, type, or provider field with one interface and one implementation per case, selected through a registry.
+load: cold
+smell: 'a `switch` or `if`/`else if` chain keyed on a kind, type, or provider field, duplicated across 2+ files or functions'
+when_to_use: a new case of the same kind arrives on a predictable cadence and every case can share one call shape
+when_not_to_use: only one implementation exists today, or the cases would return incompatible shapes
+---
+
+# Pattern — Strategy
+
+> Suggestion only. This pattern does not become project convention by existing here — it
+> materializes into `code-style/`, `ach.md`, or an ADR only when the operator accepts it for
+> this codebase.
+
+Continues the OCP trigger in `rubrics/solid-triggers.md`: that rubric tells you a `switch` on a
+provider is a problem the moment a 2nd `switch` on the same field appears elsewhere. Strategy is
+the concrete extraction once that trigger fires.
+
+## Decision
+
+| Situation | Verdict | Anti-pattern |
+| --- | --- | --- |
+| A `switch(kind)` selects behavior, and a second `switch(kind)` on the same field lives in another function or file | Apply Strategy: one file per case implementing a shared interface, wired through a lookup table | Adding a 4th `case` to both switches and hoping they stay in sync |
+| Every case already returns the same shape (LSP, see `solid-triggers.md`) | Safe to extract now — the interface is exactly that shared shape | Extracting before the shapes agree — the interface degrades to `any` or a union of incompatibles |
+| Only one case exists and no second is concretely planned | Do not extract. A single `if` is not a smell | A `StrategyRegistry` with one entry — OCP paid for a case that never happened |
+| The active case is fixed for the process lifetime (an env-driven backend chosen once at boot) | Plain dependency injection of the one active implementation | A registry of N strategies when exactly 1 is ever selected at runtime |
+
+## Why this works
+
+A `switch` on a variant duplicates its list of cases every time the branch is copy-pasted into a
+new function: N call sites × M cases means up to N×M places that drift when case M+1 arrives.
+Strategy collapses that to N call sites each holding one lookup, plus M single-purpose files —
+adding case M+1 then touches exactly 1 new file and 1 registry line, never the N call sites.
+
+## Anti-patterns
+
+- ❌ A `StrategyRegistry` holding one entry "for when we add the second provider." Inline the one
+  implementation. Extract on the second real case, not the imagined one.
+- ❌ Interfaces that leak the framework in the port (`RegistryAdapter.publish(ctx: TRPCContext)`).
+  The port must be as narrow as ISP allows — see `solid-triggers.md` § ISP.
+- ❌ A registry keyed by a raw `string` instead of the closed literal union of kinds. A typo in the
+  key then fails at runtime instead of at compile time.
+- ❌ Keeping the old `switch` alongside the new registry "just in case." Delete it in the same
+  change — two selection mechanisms for the same kind is worse than the one you started with.

package/content/patterns/template-method-vs-composition.md

@@ -0,0 +1,50 @@
+---
+type: pattern
+description: Chooses between an inherited algorithm skeleton with overridable steps and a plain function that takes the varying step as a parameter.
+load: cold
+smell: 'two or more functions or classes repeat the same ordered sequence of steps, differing only in 1-2 of those steps'
+when_to_use: the skeleton has 3+ fixed steps and only 1-2 vary across callers
+when_not_to_use: the varying step is the only step, or fewer than 3 callers share the skeleton
+---
+
+# Pattern — Template Method vs. composition
+
+> Suggestion only. This pattern does not become project convention by existing here — it
+> materializes into `code-style/`, `ach.md`, or an ADR only when the operator accepts it for
+> this codebase.
+
+Shares the Rule-of-Three threshold from `rubrics/when-to-create-lib.md`, applied to a *sequence*
+of steps instead of a single helper — and it decides between two ways to remove the duplication,
+not just whether to remove it.
+
+## Decision
+
+| Situation | Verdict | Anti-pattern |
+| --- | --- | --- |
+| 3+ callers share an ordered skeleton (validate → transform → persist → notify), 1-2 steps vary, and the language has first-class functions | Composition: one function takes the varying step(s) as parameters/callbacks | Copy-pasting the whole skeleton per caller so the 1 varying line can differ |
+| Same skeleton, but the varying steps need to read or mutate protected state shared across steps (a running total, an accumulator built up across the sequence) | Template Method: a base class fixes the sequence, subclasses override only the varying steps | Threading that shared state through 4 separate callback parameters to fake what inheritance gives for free |
+| Only 1-2 callers share the skeleton today | Do not extract either way — inline duplication for 2 callers costs less than an abstraction (Rule of Three, `when-to-create-lib.md`) | A base class with exactly one subclass, built ahead of the 2nd real caller |
+| The "skeleton" is actually just the 1 step that varies, wrapped in ceremony | There is no skeleton to extract — this is a Strategy situation instead, see `strategy.md` | Template Method with a base class whose every method is abstract — nothing is actually shared |
+
+## Why this works
+
+A skeleton with S total steps where V of them vary means V×N points of difference across N
+callers when duplicated in full. Extracting the skeleton — either way — reduces that to N call
+sites providing only the V varying steps, plus 1 shared definition of the S−V fixed ones.
+Composition and Template Method both hit that number; the choice between them is only about
+where the shared state between steps needs to live — a closure (composition) or `this`
+(inheritance).
+
+## Anti-patterns
+
+- ❌ Reaching for inheritance by default. Composition is the smaller design (KISS) whenever no
+  step needs shared mutable state across the sequence — prefer it, and use Template Method only
+  when composition would require threading that state through every callback.
+- ❌ A Template Method base class with a step marked `abstract` that every subclass overrides
+  identically. That step isn't varying — fold it back into the fixed skeleton.
+- ❌ Composition where the "varying step" callback secretly depends on 3+ pieces of the caller's
+  outer scope. At that point the callback IS the logic and the shared skeleton is the smaller
+  part — question whether extracting the skeleton was the right cut at all.
+- ❌ Extracting the skeleton before the 3rd caller exists. Two callers sharing steps can be
+  coincidence, not a real pattern — the same Rule-of-Three reasoning `when-to-create-lib.md` uses
+  for helpers applies here.