rhachet-roles-ehmpathy 1.13.3 → 1.13.6

package/dist/logic/roles/ecologist/.briefs/term.distillation.md

@@ -1,93 +0,0 @@
-# 📘 term-selection.brief: how to distill the best term
-
-> this brief defines a systematic method to choose the **clearest, strongest term** for a concept, pattern, or unit.
-> good terms collapse synonyms, avoid confusion, and align with intuitive grasp — enabling fluent reuse across systems.
-
----
-
-## 🧭 goals of a good term
-
-- **🧼 clarity** – avoids ambiguity and misreading
-- **🧲 gravity** – feels “right” and sticks in memory
-- **🔁 reuse** – unlocks consistent expression across contexts
-- **🧠 intuition** – fits what a first-time reader expects
-- **🧯 disambiguation** – contrasts clearly from neighbors or opposites
-
----
-
-## ⚠️ key naming hazards
-
-| hazard            | example                     | fix                                                                 |
-|-------------------|-----------------------------|----------------------------------------------------------------------|
-| ❗ ambiguity       | `target`, `value`, `state`  | clarify the type or role (e.g. `goal`, `rank`, `setting`)            |
-| 🔀 synonym clash   | `impact` vs `effect` vs `outcome` | collapse to one canonical form with clear internal grammar          |
-| 🧱 intuition gap   | `vectorize` used for ranking | choose a more vivid or grounded term (e.g. `score`, `grade`, `weigh`) |
-| ⚓ overload        | `tag` meaning many things   | constrain usage or rename distinctly (`label`, `marker`, `flag`)     |
-
----
-
-## 🧪 test criteria for term selection
-
-ask these when evaluating term candidates:
-
-1. **is it vivid?**
-   does it evoke the right imagery or mechanic?
-
-2. **is it distinct?**
-   does it clearly differ from adjacent terms?
-
-3. **is it reusable?**
-   can this term scale across similar use cases?
-
-4. **does it collapse synonyms?**
-   can it absorb nearby concepts under one roof?
-
-5. **does it pass the "blank slate" test?**
-   what would a first-time reader *assume* it means?
-
----
-
-## 🔧 process to distill best term
-
-1. **collect contenders**
-   list all possible terms, including wild ideas
-
-2. **tag each**
-   note for each: clarity, conflicts, connotations, candidates it might replace
-
-3. **simulate usage**
-   plug into real example sentences or data flows
-
-4. **eliminate and converge**
-   remove fuzzy or redundant terms; prefer intuitive clarity over cleverness
-
-5. **test opposite / inverse**
-   name the inverse or contrast (e.g. if this is `<gain>`, what’s the `<drop>`?)
-
-6. **declare and lock**
-   publish as part of `.brief` or `ubiqlang`
-
----
-
-## 📦 output format
-
-distilled term entry should include:
-
-```ts
-{
-  name: 'chance',
-  role: 'a positively motivated [option]',
-  replaces: ['opportunity', 'magnet', 'upside'],
-  inverse: 'threat',
-  test_case: '<enmotive> → <<gain>>[chance] → <choose>',
-  note: '“chance” works as a synonym for “opportunity” without implying randomness'
-}
-```
-
----
-
-## 🧭 guidance phrases
-
-- “would this confuse someone from another domain?”
-- “can this become a root word in our grammar?”
-- “if we only had one word for this… which feels truest?”

package/dist/logic/roles/mechanic/.briefs/architecture/bounded-contexts.md

@@ -1,61 +0,0 @@
-.tactic = arch:bounded-contexts
-
-.what = enforce clear separation of concerns using bounded contexts — each domain must own its logic, models, and procedures
-
-.scope:
-  - applies to all modules, folders, stitched routes, domain objects, and services
-  - especially enforced within `domain/`, `services/`, `routes/`, and stitched thread flows
-
-.why:
-  - upholds the **single responsibility principle** at the system level:
-    - each context owns exactly one domain concern (e.g. invoicing, job management, customer data)
-  - enforces **low-trust contracts** between contexts:
-    - no assumptions about internal structures or invariants of other domains
-    - all interaction must happen through **explicit, versionable contracts**
-  - prevents entanglement, duplication, and reach-in violations
-  - allows teams to reason about one domain in isolation
-
-.how:
-  - define one folder per bounded context (e.g. `invoice/`, `customer/`, `job/`)
-    - each folder must include its own domain objects, contracts, and procedures
-  - forbid imports from other domains' **internal** logic or types
-    - instead, expose explicit interfaces or shared types through `contracts/`, `shared/`, or stitched artifacts
-  - ensure that each context is **autonomous** and testable in isolation
-    - domain folders must never reach into another folder's `db/`, `logic/`, or `utils/`
-  - stitched logic must route between contexts via artifacts or high-trust gateways
-    - never directly call a foreign context’s service or procedure unless it is exported as a contract
-
-.enforcement:
-  - any import of another domain’s internal file or model = BLOCKER
-  - procedures must not assume or enforce foreign invariants directly
-  - stitched logic must respect bounded context ownership — no direct mutation of another domain's stash
-
-.definitions:
-  - **bounded context** = a named scope of ownership over a domain's concepts, contracts, and behaviors
-  - **single responsibility** = a context may only solve problems related to its own domain
-  - **low-trust contract** = cross-context interactions must rely only on validated inputs and canonical exports
-
-.examples:
-
-  .positive:
-    - `job/JobQuote.ts` imports `CustomerPhoneUpdate` from `contracts/`, not from `customer/logic/`
-    - `invoice/` has its own `InvoiceDraft`, `InvoiceFinal`, and `generateInvoice.ts`
-    - `routes/submitJob.ts` orchestrates job + invoice by stitching, not by importing both
-
-  .negative:
-    - `job.ts` imports `from '../../invoice/utils.ts'` ⛔ reach-in
-    - `invoiceService.ts` directly updates `customer.email` ⛔ cross-context mutation
-    - `customer.ts` imports `JobQuote` and infers state ⛔ ownership violation
-
-
-
-- src
-  - contract
-    - endpoints // public endpoints, deployed and exposed publically
-    - commands // internal operations, locally ran
-  - data
-    - sdks // the sdks used by this service
-    - daos // the daos owned by this service
-  - domain
-    - objects // the domain resources
-  - logic // the domain mechanisms

package/dist/logic/roles/mechanic/.briefs/architecture/directional-dependencies.md

@@ -1,82 +0,0 @@
-.tactic = arch:directional-deps
-
-.what
-enforce strict top-down dependency flow across layered system boundaries — lower layers must never import from higher ones
-
-.scope
-- applies to all folders and modules within `src/`
-- required for `contract/`, `access/`, `domain.objects/`, `domain.operations/`
-- governs imports, module references, and stitched flow boundaries
-
-.why
-- upholds **separation of concerns** and enforces **clean architecture**
-- prevents circular dependencies and tangled system boundaries
-- makes each layer easier to test, replace, and understand in isolation
-- aligns with `arch:bounded-contexts` and enables predictable top-down orchestration
-
-.structure
-\`\`\`
-src/
-  contract/            // topmost — public interfaces, local commands
-    api/               // public invocable api endpoints, deployed and exposed by the project; e.g., via `aws-lambda`
-    cmd/               // private internal use entrypoints, supported by the project; e.g., via `as-command`
-    sdk/               // public software development kit exports, supported by the project; e.g., `export ...`
-    cli/               // public command line interface contracts, supported by the project; e.g., via `commander`
-
-  access/              // infrastructure layer (daos, sdks, svcs)
-    daos/              // private persistence logic — may reference domain objects
-    sdks/              // remote third party contracts, from any alt org — may declare their own domain.objects
-    svcs/              // remote first party contracts, from our own org — may declare their own domain.objects
-
-  domain.objects/      // canonical domain declarations
-  domain.operations/   // domain behavior + business rules
-
-  infra/               // infrastructure specific adapters
-\`\`\`
-
-.how
-- each layer may depend **only on the layers below it**
-  - `contract/` may depend on `domain.objects/` and `domain.operations/`
-  - `access/` may depend on `domain.objects/` and `domain.operations/`
-  - `domain.operations/` may depend on `domain.objects/` or `infra/`
-  - `domain.objects/` must not depend on anything outside its own layer
-  - `infra/` must not depend on anything outside its own layer
-
-- stitched flows live in `domain.operations/` or `contract/commands/` and orchestrate downstream only
-- never import upward across layers (e.g., `domain.objects/` importing `access/`)
-- shared types must follow the same directional rules
-
-.enforcement
-- imports that violate top-down boundary = **BLOCKER**
-- circular dependencies between layers = **BLOCKER**
-- logic in `domain.objects/` must never reach into `access/`, `contract/`, or `domain.operations/`
-- logic in `domain.operations/` must not reference infrastructure concerns; they can can only leverage `infra/` adapters
-- logic in `access/` may use domain layers but must remain free of domain knowledge and business rules
-- logic in `infra/` must remain free of domain knowledge and business rules
-
-.examples
-
-✅ positive
-\`\`\`ts
-// contract/endpoints/sendInvoice.ts
-import { generateInvoice } from '@/domain.operations/generateInvoice';
-import { invoiceDao } from '@/access/daos/invoiceDao';
-
-// access/daos/jobDao.ts
-import { Job } from '@/domain.objects/Job';
-
-// domain.operations/calculateTotal.ts
-import { LineItem } from '@/domain.objects/LineItem';
-\`\`\`
-
-❌ negative
-\`\`\`ts
-// domain.objects/Customer.ts
-import { customerDao } from '@/access/daos/customerDao'; // ⛔ illegal upward import
-
-// domain.operations/InvoiceOps.ts
-import { runFlow } from '@/contract/commands'; // ⛔ direction violation
-
-// access/svcs/sdkWrapper.ts
-import { dispatchFlow } from '@/contract/'; // ⛔ bottom-up reference
-\`\`\`

package/dist/logic/roles/mechanic/.briefs/architecture/domain-driven-design.md

@@ -1,61 +0,0 @@
-.tactic = arch:domain-driven-design
-
-.what = model all business logic using well-defined domain objects, procedures, and contracts — never loose bags of properties
-
-.scope:
-  - applies to all business logic, application services, types, data flows, and stateful modules
-  - especially enforced within core domain folders and stitched procedures
-
-.why:
-  - ensures the system is built from **recognizable domain concepts**
-  - improves correctness through **runtime validation**
-  - enables identity comparison, change detection, and immutability by default
-  - prevents "bag-of-words" logic and accidental complexity
-
-.how:
-  - always use `domain-objects` to model the domain
-    - use `DomainLiteral<T>` for immutable value objects
-    - use `DomainEntity<T>` when identity and lifecycle matter
-    - use `DomainEvent<T>` for structured domain signals
-  - **never** pass raw `{ prop1, prop2, ... }` bags across procedure boundaries
-    - define and reuse domain objects instead
-    - compose nested models with `.nested` and `.build`
-  - distill your domain into:
-    - **domain objects** = nouns (e.g. `Customer`, `Invoice`, `RocketShip`)
-    - **domain procedures** = verbs (e.g. `generateInvoice`, `submitPayment`)
-    - **domain contracts** = shapes of external interfaces or cross-context bridges
-  - always prefer the most **specific and canonical domain object** for a given use case
-    - if a `Customer`, `Invoice`, or `Quote` already exists, reuse it — don’t make a new shape
-  - support **runtime validation** with schemas (Zod, Joi, Yup)
-    - all domain objects with external inputs must be validated on instantiation
-  - define `.unique` and `.updatable` fields for identity and change tracking
-  - expose immutable behaviors using `.clone()` and `.build()` for safe updates
-  - procedures with more than 2 scalar arguments representing **data** should be refactored to use a domain object
-    - control/options args are acceptable when clearly scoped (e.g. `{ dryRun: true }`)
-
-.enforcement:
-  - code reviews must block untyped or loosely typed `{}` logic
-  - procedures with more than 2 scalar arguments should be refactored to use domain objects
-  - stitched routes and service layers must pass domain objects explicitly
-  - tests should validate domain behavior, not just JSON shape
-  - imports from `domain-objects` are required for any core domain concept
-
-.examples:
-
-  .positive:
-    - `class Customer extends DomainEntity<Customer> implements Customer {}`
-    - `new JobQuote({ customer, lineItems, total })`
-    - `generateInvoice({ invoice: Invoice })` instead of `generateInvoice({ id, total, customerId })`
-    - `LeadSource.build({ type: 'referral' })` with schema validation on instantiation
-    - `customer.clone({ phone: '555-1234' })` for safe mutation
-
-  .negative:
-    - `{ name, email, address }` passed between modules without a domain object
-    - `function updateUser(name, email, phone)` instead of `updateCustomerInfo(Customer)`
-    - `type UserData = { ... }` duplicating `Customer` shape
-    - storing JSON blobs that replicate existing domain models
-    - `update()` method used on raw DTOs
-
-.links:
-  - see also: `name:ubiqlang`
-  - library: https://www.npmjs.com/package/domain-objects

package/dist/logic/roles/mechanic/.briefs/architecture/ubiqlang.md

@@ -1,37 +0,0 @@
-.tactic = name:ubiqlang
-
-.what = enforce a rigorous, domain-driven naming system rooted in ubiquitous language
-.where:
-  - ubiquitous language = the shared, unambiguous vocabulary used by both domain experts and developers
-  - this tactic applies to all names: types, variables, functions, slugs, and folders
-
-.why:
-  - eliminates ambiguity and cognitive friction
-  - ensures that everyone speaks the same language — in code, UI, tests, and docs
-  - prevents synonym drift (e.g., "client" vs "customer") and overload traps (e.g., "update" meaning 3 things)
-
-.how:
-  - eliminate synonyms
-    - choose one canonical word per concept (e.g., always use `customer`, never `client`, `user`, or `account`)
-  - eliminate overloads
-    - each term must refer to one concept only (e.g., avoid using `update` for both "save data" and "fetch latest")
-  - use consistent noun-verb stacking that mirrors domain intent (e.g., `customerPhoneUpdate`, not `editPhoneNumber`)
-  - whenever a new term is introduced:
-    - define its interface, expected shape, and role
-    - document its meaning clearly and visibly (ideally in context or hover docs)
-    - ensure its usage is verified across type definitions, business rules, and communication flows
-
-.examples:
-  .positive:
-    - `customer` instead of `client`, `user`, or `buyer`
-    - `jobQuote` as the single term for estimates/proposals
-    - `leadCapture` as the canonical action for inbound lead collection
-    - `customerPhoneUpdate` for updating a phone number
-    - `invoiceDraft` and `invoiceFinal` for two distinct invoice states
-
-  .negative:
-    - `client`, `user`, `account`, `buyer` all referring to the same actor
-    - `editCustomerPhone`, `changePhone`, `updateNumber` used interchangeably
-    - `job` used for both a requested service and a completed one
-    - `update()` overloaded to mean save, patch, sync, or refresh
-    - `quote`, `estimate`, `proposal`, and `bid` all floating without clear hierarchy

package/dist/logic/roles/mechanic/.briefs/codestyle/_mech.compressed.md

@@ -1,57 +0,0 @@
-- ### **args:input-context**
-  - **rule**: all procedures must follow the signature `(input, context?)`
-  - **input** and **context** must be destructurable objects
-  - positional args beyond `(input, context)` are **forbidden**
-  - inline callbacks may be exempt if anonymous + tightly scoped
-  - **example:**
-    ```ts
-    export const doWork = async (input, context) => { ... }       // ✅
-    export function legacyFunc(a, b) {}                           // ⛔
-    ```
-
----
-
-- ### **funcs:arrow-only**
-  - **rule**: all procedures must be declared as arrow functions
-  - `function` keyword is **disallowed**, even for exports
-  - object methods are allowed only inside class or API contracts
-  - always destructure `input` as first argument when applicable
-  - **example:**
-    ```ts
-    const getName = ({ name }) => name;                          // ✅
-    export function getName(name) { return name }                // ⛔
-    ```
-
----
-
-- ### **comment-discipline**
-  - **procedure headers**: every named procedure must begin with a block comment:
-    ```ts
-    /**
-     * .what = intent in 1 line
-     * .why = purpose in ≤ 3 lines
-     * .note = optional caveats (concise)
-     */
-    ```
-    - missing `.what` or `.why` = **blocker**
-
-  - **code paragraphs**: every group of related lines must begin with a one-line `//` summary
-    - must explain *why*, not echo the code
-    - **multiline `//` comments are forbidden**
-    - if more than one line is needed → extract into a named procedure
-    - comment must be preceded by a newline
-
-  - **example:**
-    ```ts
-    /**
-     * .what = proposes code by iterating until clean
-     * .why = ensures reviewer only sees finalized artifacts
-     */
-    export const proposeCode = async ({ threads }) => {
-      // run mechanic feedback loop
-      const result = await runIterateCycle({ threads });
-
-      // return artifact for downstream route
-      return result.threads.artist.context.stash.art.inflight;
-    };
-    ```

package/dist/logic/roles/mechanic/.briefs/codestyle/_mech.compressed.prompt.md

@@ -1,5 +0,0 @@
-compress these three style tactics for use in prompt context
-
-retain references to the tactics each section came from, so that it can always be dereferenced
-
-use outline form with each tactic a root bullet

package/dist/logic/roles/mechanic/.briefs/codestyle/flow.failfast.md

@@ -1,37 +0,0 @@
-.tactic = flow:fail-fast
-
-.what = enforce fail-fast logic using early exits and HelpfulError subclasses to reject invalid state or input immediately
-
-.scope:
-  - required in all stitched logic, business procedures, and service flows
-  - applies to guard checks, validations, and branching paths
-
-.why:
-  - improves readability by collapsing failure paths early
-  - eliminates nested branches and lets core logic shine
-  - increases safety by clearly documenting and halting on invalid input
-  - makes bugs easier to debug with rich context using `helpful-errors`
-
-.how:
-  - use **early returns or throws** for all guard clauses
-    - never use `if (...) else` or deep nesting to control flow
-  - prefer `UnexpectedCodePathError.throw(...)` for internal invariant violations
-    - these signal logic errors that “should never happen”
-  - prefer `BadRequestError.throw(...)` for rejecting invalid input or user requests
-    - these signal invalid calls, not system failures
-  - use `.throw(...)` syntax for clean 1-liners inside nullish chains or short circuits
-  - include **context objects** in all thrown errors to aid debugging
-  - validate error behavior in tests using `getError(...)`
-
-.code structure:
-  - treat each guard block as a **code paragraph**
-    - must be preceded by a comment summarizing *why* the guard exists
-    - blank line after each guard before continuing main logic
-
-  ```ts
-  // reject if user does not exist
-  if (!user) return BadRequestError.throw('user not found', { userUuid });
-
-  // halt if state is invalid
-  if (!input.customer.phone)
-    UnexpectedCodePathError.throw('customer lacks phone, invalid state', { customer });

package/dist/logic/roles/mechanic/.briefs/codestyle/flow.idempotency.md

@@ -1,63 +0,0 @@
-.tactic = proc:require-idempotency
-
-.what = all procedures must be idempotent unless explicitly marked otherwise — calling the same logic twice must not cause double effects
-
-.scope:
-  - applies to all stitched procedures, exports, and service logic
-  - especially required for write operations, upserts, queues, retries, and workflows
-
-.why:
-  - prevents duplicate side effects from retries, race conditions, or concurrent execution
-  - enables safe reruns, resume-after-failure, and audit-friendly execution
-  - makes all logic safer to test, stitch, compose, and scale
-
-.how:
-  - all procedures must **guard against re-entry**
-    - check whether the action has already occurred before executing
-    - e.g., `if (invoice.status === 'FINAL') return invoice;`
-  - any **side-effect-producing operation** must:
-    - check for an existing result (e.g. existing record, idempotency key, state flag)
-    - return early if already complete
-  - **external writes** (db, api, fs, queues) must be safe to call multiple times without duplication
-    - use upserts, conflict-ignore inserts, or external idempotency tokens
-  - **procedures that are not idempotent** must be marked:
-    - include `.note = non-idempotent` in header comment
-    - include a guard against accidental retries (e.g. check `context.traceId`)
-  - stitched logic should not assume “exactly once” semantics — instead, enforce “at-least once, safely”
-
-.enforcement:
-  - procedures with `set`, `push`, `post`, or other side-effect verbs must show idempotency check
-  - non-idempotent procedures must be annotated with a `.note`
-  - workflows and retry logic must assume re-entry and prove safety
-  - test cases must show repeat-calling has no additional effect
-
-.examples:
-
-  .positive:
-    ```ts
-    // skip if already finalized
-    if (invoice.status === 'FINAL') return invoice;
-
-    // finalize invoice
-    const updated = invoice.clone({ status: 'FINAL' });
-    await saveInvoice(updated);
-    return updated;
-    ```
-
-    ```ts
-    // deduplicate outbound message
-    const alreadySent = await Message.find({ idempotencyKey });
-    if (alreadySent) return alreadySent;
-
-    await sendMessage({ to, body });
-    ```
-
-  .negative:
-    ```ts
-    await sendEmail(input); // ⛔ no check for previous send
-    ```
-
-    ```ts
-    const saved = await insertLog({ ... }) // ⛔ may insert duplicate on retry
-    ```
-

package/dist/logic/roles/mechanic/.briefs/codestyle/flow.immutability.md

@@ -1,48 +0,0 @@
-.tactic = vars:require-immutable
-
-.what = require all code to use immutable variables, objects, and update patterns — mutation is a blocker
-
-.scope:
-  - applies to all variable declarations, function arguments, object updates, and data flows
-  - enforced in all modules, logic layers, stitched routes, and tests
-
-.why:
-  - eliminates side effects from shared mutable state
-  - enables predictable execution, safer concurrency, and undoable flows
-  - enforces functional purity and simplifies debugging
-  - guarantees compatibility with clone-based and parallel architectures
-
-.how:
-  - all bindings must use `const`; `let` or `var` are **forbidden** unless explicitly scoped to a mutation block
-  - input arguments must never be mutated — always treat as read-only
-  - objects must never be mutated in place:
-    - use object spreads (`{ ...original, field }`) or `.clone()` on domain objects
-  - arrays must not be mutated directly:
-    - never use `.push()`, `.pop()`, `.splice()`, or `.sort()` on the original array
-    - use spread + map/filter/reduce or copy before mutating
-  - use `withImmute()` and `.clone()` for all updates to domain objects
-  - avoid shared reference mutation:
-    - never change shared singletons or top-level config objects after import
-  - if mutation is unavoidable (e.g. caching, metrics), isolate it in a clearly scoped, documented zone with `.note = deliberate mutation` comment
-
-.enforcement:
-  - `let`, `var`, and in-place mutation are blockers unless specifically exempted
-  - mutation of input arguments or shared objects must fail review
-  - mutation of domain object instances is forbidden; use `.clone()` instead
-  - functions with mutation behavior must be annotated and justified
-
-.examples:
-
-  .positive:
-    - `const updated = { ...original, status: 'complete' }`
-    - `const newInvoice = invoice.clone({ total: 1200 })`
-    - `const next = [...current].sort(byDate)`
-
-  .negative:
-    - `let count = 0; count++`
-    - `input.customer.name = 'bob'` // ⛔ input mutation
-    - `config.debug = false` // ⛔ shared singleton mutation
-    - `arr.push(1)` // ⛔ in-place array mutation
-
-.links:
-  - see also: `arch:immutable-core`, `args:input-context`, `domain-objects.withImmute`

package/dist/logic/roles/mechanic/.briefs/codestyle/flow.narratives.md

@@ -1,74 +0,0 @@
-.tactic = flow:narrative
-
-.what = structure all logic as flat, linear code paragraphs — never nested branches — to improve clarity and scanability
-
-.scope:
-  - applies to all procedural code: stitched logic, exports, and internal helpers
-  - required for all conditional flows, validation paths, and stateful transformations
-
-.why:
-  - reduces visual complexity by eliminating indentation creep
-  - aligns code with natural narrative flow: guard clauses → main path → fallback
-  - makes logic easier to read, debug, test, and extend
-  - allows each "paragraph" of logic to be summarized with a single comment
-
-.how:
-  - eliminate `if/else` and nested `if` blocks entirely
-    - use early returns (`if (x) return`, `if (error) throw`) instead
-    - prefer `return`, `throw`, or `continue` to flatten control flow
-  - define and use **code paragraphs**:
-    - a group of 1–5 lines that do one thing together
-    - each paragraph must be preceded by a `//` one-line title explaining **what** or **why**
-    - paragraph titles act like section headers — they are not optional
-  - paragraphs must be separated by a blank line
-  - paragraph comments must **not** describe how the code works — only why this paragraph exists
-  - deeply nested branches should be broken into separate procedures if needed
-
-.enforcement:
-  - `else` and nested `if` blocks are blockers and must be refactored
-  - any multi-line logic block without a paragraph title is a violation
-  - paragraph comments must be one-liners — multiline `//` is forbidden (see `comment-discipline`)
-  - code that reads like a decision tree must be flattened into a readable narrative
-
-.definitions:
-  - **code paragraph** = a contiguous block of related lines, preceded by a single-line `//` title and separated by a blank line
-    ```ts
-    // validate input format
-    const isValid = validateShape(input);
-    if (!isValid) return failure();
-
-    // attempt fallback resolution
-    const resolved = tryToResolve(input);
-    if (!resolved) UnexpectedCodePathError.throw('resolution failed');
-    ```
-
-.examples:
-
-  .positive:
-    ```ts
-    // return early if invalid
-    if (!input.email) return failure();
-
-    // check for banned domains
-    if (input.email.endsWith('@spam.com')) return forbidden();
-
-    // process verified email
-    const result = handleVerifiedEmail(input.email);
-    ```
-
-  .negative:
-    ```ts
-    if (!input.email) {
-      return failure();
-    } else {
-      if (input.email.endsWith('@spam.com')) {
-        return forbidden();
-      } else {
-        const result = handleVerifiedEmail(input.email);
-        ...
-      }
-    }
-    ```
-
-.links:
-  - see also: `comment-discipline`, `funcs:shape-and-signal`, `flow:guard-first`