rhachet-roles-ehmpathy 1.13.6 → 1.13.8

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

@@ -0,0 +1,93 @@
+# 📘 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

@@ -0,0 +1,61 @@
+.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

@@ -0,0 +1,82 @@
+.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

@@ -0,0 +1,61 @@
+.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

@@ -0,0 +1,37 @@
+.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

@@ -0,0 +1,57 @@
+- ### **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

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,37 @@
+.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

@@ -0,0 +1,63 @@
+.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

@@ -0,0 +1,48 @@
+.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

@@ -0,0 +1,74 @@
+.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`