rhachet-roles-ehmpathy 1.15.21 → 1.15.23

package/dist/domain.roles/mechanic/briefs/.archive/_mech.compressed.md

@@ -14,7 +14,7 @@
 - ### **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
+  - object methods are allowed only inside class or api contracts
   - always destructure `input` as first argument when applicable
   - **example:**
     ```ts

package/dist/domain.roles/mechanic/briefs/practices/code.prod/consistent.contracts/ref.package.as-command.[ref].md

@@ -1,4 +1,4 @@
-when using `@ehmpathy/as-command`, no need to manage output dirs yourslef
+with `@ehmpathy/as-command`, no need to manage output dirs yourself
 
 simply use context.out.write()
 

package/dist/domain.roles/mechanic/briefs/practices/code.prod/evolvable.architecture/rule.require.bounded-contexts.md

@@ -1,6 +1,6 @@
 .tactic = arch:bounded-contexts
 
-.what = enforce clear separation of concerns using bounded contexts — each domain must own its logic, models, and procedures
+.what = enforce clear separation of concerns via bounded contexts — each domain must own its logic, models, and procedures
 
 .scope:
   - applies to all modules, folders, stitched routes, domain objects, and services
@@ -8,7 +8,7 @@
 
 .why:
   - upholds the **single responsibility principle** at the system level:
-    - each context owns exactly one domain concern (e.g. invoicing, job management, customer data)
+    - each context owns exactly one domain concern (e.g. invoice, job, 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**
@@ -40,7 +40,7 @@
   .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
+    - `routes/submitJob.ts` orchestrates job + invoice via stitch, not via import of both
 
   .negative:
     - `job.ts` imports `from '../../invoice/utils.ts'` ⛔ reach-in

package/dist/domain.roles/mechanic/briefs/practices/code.prod/evolvable.architecture/rule.require.domain-driven-design.md

@@ -1,6 +1,6 @@
 .tactic = arch:domain-driven-design
 
-.what = model all business logic using well-defined domain objects, procedures, and contracts — never loose bags of properties
+.what = model all business logic via 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
@@ -28,16 +28,16 @@
     - 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
+  - define `.unique` and `.updatable` fields for identity and change detection
+  - expose immutable behaviors via `.clone()` and `.build()` for safe updates
+  - procedures with more than 2 scalar arguments that represent **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
+  - tests should validate domain behavior, not just json shape
   - imports from `domain-objects` are required for any core domain concept
 
 .examples:
@@ -52,8 +52,8 @@
   .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
+    - `type UserData = { ... }` that duplicates `Customer` shape
+    - stored json blobs that replicate prior domain models
     - `update()` method used on raw DTOs
 
 .links:

package/dist/domain.roles/mechanic/briefs/practices/code.prod/evolvable.domain.objects/rule.forbid.undefined-attributes.md

@@ -4,7 +4,7 @@ never allow "undefined" attributes for domain objects UNLESS they are database-g
 i.e.,
 - ids, createdAt, updatedAt, etc - these are allowed to be undefined, since they're metadata, and only known on read
 
-however, everything else should be explicitly knowable
+however, all else should be explicitly knowable
 - if we know that it is null, then set it as null
   - however, we should be really clear as to WHY it can be null; if there is no good domain reason for null, forbid it
 - otherwise, define the exact type

package/dist/domain.roles/mechanic/briefs/practices/code.prod/evolvable.domain.operations/define.domain-operation-core-variants.md

@@ -0,0 +1,122 @@
+### .define = domain-operation-core-variants
+
+#### .what
+domain.operations contains two fundamental variants of leaf operations:
+- **compute*** = deterministic computed work (pure functions, no external dependencies)
+- **imagine*** = probabilistic creative work via `context.brain.repl.imagine({ role })`
+
+#### .when
+- most projects only have deterministic operations — no `brain.repl` invocations
+- in these cases, the `compute*` prefix is **not required** (no ambiguity exists)
+- enforcement becomes **mandatory** when a project contains both variants
+- once `imagine*` operations exist in a codebase, `compute*` prefixes become required for clarity
+
+#### .scope
+- the `compute*`/`imagine*` prefix applies only to **leaf operations**
+- leaf operations = the ones that actually perform the computation or imagination
+- **composer operations** that orchestrate leaf operations use normal names (e.g., `getInvoice`, `setCustomerPhone`, `syncUserFromProvider`)
+- the prefix signals *what kind of work is done*, not *what kind of work is called*
+
+#### .why
+when both variants exist in a codebase, the prefix:
+- clarifies the nature of each leaf operation at a glance
+- sets expectations for testability (deterministic vs probabilistic)
+- signals dependency requirements (pure vs requires brain context)
+- enables appropriate error strategies for each type
+- guides code review focus (logic correctness vs prompt quality)
+
+#### .how
+
+##### compute* leaf operations
+- prefix with `compute` (e.g., `computeInvoiceTotal`, `computeHashFromContent`)
+- must be **pure functions** — same input always produces same output
+- **no external dependencies** — no network, no database, no randomness
+- trivially testable with simple input/output assertions
+- can be safely memoized or cached
+
+##### imagine* leaf operations
+- prefix with `imagine` (e.g., `imagineChapterOutline`, `imagineCodeReview`)
+- invoke `context.brain.repl.imagine({ role })` for LLM-powered generation
+- **probabilistic** — same input may produce different valid outputs
+- require snapshot tests or semantic assertions
+- depend on `context.brain` provision
+
+##### composer operations
+- use normal verb prefixes (e.g., `get*`, `set*`, `sync*`, ...)
+- orchestrate one or more leaf operations
+- no special prefix required — their behavior is defined by what they compose
+
+#### .examples
+
+**✅ good — leaf operations with proper prefixes**
+```ts
+// computeInvoiceTotal.ts — leaf, deterministic
+export const computeInvoiceTotal = (input: { lineItems: LineItem[] }) => {
+  return input.lineItems.reduce((sum, item) => sum + item.amount, 0);
+};
+
+// imagineChapterSummary.ts — leaf, probabilistic
+export const imagineChapterSummary = async (
+  input: { chapter: string },
+  context: { brain: Brain },
+) => {
+  return context.brain.repl.imagine({
+    role: 'summarizer',
+    prompt: `summarize this chapter: ${input.chapter}`,
+  });
+};
+```
+
+**✅ good — composer operation with normal name**
+```ts
+// getInvoiceWithSummary.ts — composes both variants
+export const getInvoiceWithSummary = async (
+  input: { invoiceId: string },
+  context: { brain: Brain; invoiceDao: InvoiceDao },
+) => {
+  const invoice = await context.invoiceDao.findById(input.invoiceId);
+  const total = computeInvoiceTotal({ lineItems: invoice.lineItems });
+  const summary = await imagineChapterSummary({ chapter: invoice.notes }, context);
+  return { ...invoice, total, summary };
+};
+```
+
+**⛔ bad — prefix misleads**
+```ts
+// computeResponse.ts — "compute" but actually calls LLM
+export const computeResponse = async (input, context) => {
+  return context.brain.repl.imagine({ ... }); // ⛔ prefix misleads
+};
+```
+
+**⛔ bad — ambiguous leaf name (only when both variants exist)**
+```ts
+// generateTotal.ts — unclear if deterministic or probabilistic
+export const generateTotal = (...) => { ... }
+
+// processChapter.ts — verb doesn't signal operation type
+export const processChapter = (...) => { ... }
+```
+
+#### .enforcement
+- leaf operations that call `context.brain` must use `imagine*` prefix
+- leaf operations prefixed with `compute*` must be pure and deterministic
+- prefix mismatch vs implementation = **BLOCKER**
+- ambiguous leaf names in a codebase with both variants = **BLOCKER**
+
+---
+
+#### .appendix: brain terminology
+
+##### brain.atom
+- the atomic unit of LLM interaction
+- a single LLM api call (e.g., one completion request)
+- stateless, no memory of prior calls
+- e.g., **Claude api** = one `messages.create()` call
+
+##### brain.repl
+- **r**ead, **e**xecute, **p**rint, **l**oop
+- orchestrates `brain.atom` calls within a tooluse loop
+- enables multi-turn reason with tool execution between steps
+- `brain.repl.imagine({ role })` = invoke the repl to imagine/generate via the specified role
+- e.g., **Claude Code** = agentic loop that reads files, executes tools, prints results, loops until done

package/dist/domain.roles/mechanic/briefs/practices/code.prod/evolvable.procedures/rule.forbid.positional-args.md.pt1.md

@@ -36,8 +36,8 @@ vs
 
 
 
-  - Self-documenting: You can see what each parameter is at the call site
+  - Self-documented: You can see what each parameter is at the call site
   - Order-independent: Arguments can be passed in any order
-  - Easier to maintain: Adding new optional parameters won't break existing calls
+  - Easier to maintain: New optional parameters won't break prior calls
   - Validation: Each function validates required parameters
   - Usage examples: Included in function headers

package/dist/domain.roles/mechanic/briefs/practices/code.prod/evolvable.procedures/rule.require.arrow-only.md

@@ -1,16 +1,16 @@
 ### .tactic = funcs:arrow-only
 
 #### .what
-enforce that all procedures are declared using arrow functions
+enforce that all procedures are declared via arrow functions
 disallow use of `function` keyword for any procedure
 
 #### .where
 - applies to all exported and internal functions across codebase
 - required in modules, utilities, hooks, logic, and test declarations
-- exempt only for class methods or dynamic `this` binding (rare)
+- exempt only for class methods or dynamic `this` bind (rare)
 
 #### .why
-- enforces lexical `this` binding for predictable behavior
+- enforces lexical `this` bind for predictable behavior
 - aligns code structure with uniform declaration style
 - improves visual clarity and reduces syntactic noise
 - simplifies use with higher-order functions, closures, and composability
@@ -20,7 +20,7 @@ disallow use of `function` keyword for any procedure
 ##### .rules
 - use arrow syntax (`const fn = (input) => {}`) for all functions
 - never use `function` keyword for standalone or inline functions
-- use object methods only when tied to a `class` or API contract
+- use object methods only when tied to a `class` or api contract
 - always destructure input as the first arg if applicable
 
 ##### .examples

package/dist/domain.roles/mechanic/briefs/practices/code.prod/evolvable.procedures/rule.require.clear-contracts.md

@@ -1,20 +1,20 @@
 
 .tactic = mech:contract-before-implementation
 
-.what = declare the shape and expectations of behavior (the contract) before writing its implementation
+.what = declare the shape and expectations of behavior (the contract) before the implementation is written
 
 .why:
-- forces clarity about what is being built and why
-- prevents premature optimization and over-engineering
+- forces clarity about what to build and why
+- prevents premature optimization and over-engineer
 - creates a shared agreement for both the builder and consumer
 - enables parallel work (e.g., backend + frontend, or logic + UI)
 
 .scope:
 - applies to procedures, stitched flows, and any domain mechanisms
-- applies at both macro (API endpoint, service) and micro (function, component) levels
+- applies at both macro (api endpoint, service) and micro (function, component) levels
 
 .how:
-- always begin with a **procedure type** that defines:
+- always start with a **procedure type** that defines:
   - function signature or interface
   - expected inputs and output shape
   - error modes and invariants
@@ -27,7 +27,7 @@
 
     /**
      * .what = sends an invoice to the customer and marks it as sent
-     * .why = required for customer billing compliance and automation
+     * .why = required for customer bill compliance and automation
      */
     export const sendInvoice = async ({
       invoice,
@@ -43,11 +43,11 @@
     // logic/sendInvoice.ts
 
     export const sendInvoice = async (invoice, customer) => {
-      // suddenly starts doing 4 things and mutates stuff randomly
+      // suddenly starts to do 4 tasks and mutates stuff randomly
     };
 
 .enforcement:
 - if a PR implements logic without any visible contract: **blocker**
 - if types are vague or inferred (e.g. `any`, `unknown`): **blocker**
-- if behavior differs from contract or lacks a test: **blocker**
+- if behavior differs from contract or a test is absent: **blocker**
 

package/dist/domain.roles/mechanic/briefs/practices/code.prod/evolvable.procedures/rule.require.dependency-injection.md.pt1.md

@@ -1,22 +1,22 @@
 ## 🧠 `.brief.designer.dependency-injection`
 
 ### 🧠 topic: dependency injection
-**why we pass in dependencies instead of hardcoding them**
+**why we pass in dependencies instead of hardcode them**
 
 ---
 
 ### 🎯 goal
 build software that is **flexible, testable, and decoupled**,
-by making dependencies **explicit, swappable, and controlled from the outside**.
+via dependencies that are **explicit, swappable, and controlled from the outside**.
 
 ---
 
 ### 🛠 what it is
 
-> **dependency injection** = giving a function, class, or module what it needs from the outside,
-> rather than letting it construct or look up those tools internally.
+> **dependency injection** = to give a function, class, or module what it needs from the outside,
+> rather than to let it construct or look up those tools internally.
 
-for example, instead of having a function reach for its own dependencies:
+for example, instead of a function that reaches for its own dependencies:
 
 ```ts
 // ❌ tightly coupled and side-effect prone
@@ -46,12 +46,12 @@ export const upsert = async (
 ```
 
 - the function doesn’t reach into globals or construct its own tools
-- everything it needs is **passed in from the outside**, making it testable, predictable, and side-effect free
+- all it needs is **passed in from the outside**, which makes it testable, predictable, and side-effect free
 
 ---
 
 ### 🔑 paved pattern: `(input, context)`
-dependency injection is best done by following the **standard procedure contract**:
+dependency injection is best done via the **standard procedure contract**:
 
 ```ts
 export const doThing = async (
@@ -62,7 +62,7 @@ export const doThing = async (
 
 - all dependencies go in the `context` argument
 - keeps `input` clean, and `context` flexible
-- enables composition, tracing, and full test control
+- enables composition, trace, and full test control
 
 
 ---
@@ -70,9 +70,9 @@ export const doThing = async (
 ### 🤝 why it matters
 
 - **testability** — swap real dependencies with mocks/fakes
-- **flexibility** — easily change implementations without changing core logic
-- **separation of concerns** — business logic doesn't manage its own plumbing
-- **explicitness** — makes system wiring visible and intentional
+- **flexibility** — easily change implementations without core logic change
+- **separation of concerns** — business logic doesn't manage its own plumb
+- **explicitness** — makes system wires visible and intentional
 - **reusability** — same logic can be reused with different behaviors
 
 ---
@@ -88,7 +88,7 @@ you keep **policies and tools separate from behaviors**.
 
 ### 🔍 mental model
 
-> dependency injection is like **plugging in a tool** instead of **building one every time**.
+> dependency injection is like to **plug in a tool** instead of to **build one every time**.
 
 your procedures say:
 > “give me what I need — I don’t care where it came from.”
@@ -100,7 +100,7 @@ your procedures say:
 | without DI                             | with DI                                    |
 |----------------------------------------|--------------------------------------------|
 | hardcoded database inside procedures   | database passed in as via parameters       |
-| requires real API in tests             | can inject mock/fake API for testing       |
+| requires real api in tests             | can inject mock/fake api for tests         |
 | logic tied to concrete tools           | logic works with any compatible tool       |
 | hard to switch infra/tools             | swappable with config or environment setup |
 
@@ -110,9 +110,9 @@ your procedures say:
 
 we inject dependencies to build systems that are easier to **test**, **scale**, and **evolve**.
 
-> dependency injection is about building **pure, decoupled, and testable** systems.
+> dependency injection is about to build **pure, decoupled, and testable** systems.
 > it eliminates shared state, surfaces side effects, and makes your logic portable and composable.
 > it enables **modularity**, **testability**, and **control**,
-> by making **dependencies external** instead of hidden inside.
+> via **external dependencies** instead of hidden inside.
 
-done right, it's **invisible during use**, and **invaluable during testing, scaling, and evolution**.
+done right, it's **invisible when used**, and **invaluable for tests, scale, and evolution**.

package/dist/domain.roles/mechanic/briefs/practices/code.prod/evolvable.procedures/rule.require.dependency-injection.md.pt2.md

@@ -1,6 +1,6 @@
 todo: declare why dependency injection leads to a pit of success && why global shared state should be avoided
 
-via dependency injection, you always know what's referncing what. no side effects
+via dependency injection, you always know what references what. no side effects
 
 persistance is the only global shared state that should exist - and even that should be managed cautiously (e.g., to avoid race conditions)
 

package/dist/domain.roles/mechanic/briefs/practices/code.prod/evolvable.procedures/rule.require.input-context-pattern.md.pt1.md

@@ -8,7 +8,7 @@ enforce hard requirement that all procedure args to follow the canonical pattern
 - prevents positional argument confusion
 - supports context injection without argument churn
 - aligns with domain patterns: input = upstream data, context = runtime environment
-- enables safe refactoring and consistent documentation across codebase
+- enables safe refactors and consistent documentation across codebase
 
 #### .where
 - applies to **all function definitions** (sync or async)
@@ -26,7 +26,7 @@ enforce hard requirement that all procedure args to follow the canonical pattern
 - **hard requirement** — applies even to trivial utilities, pure transforms, and data extractors
 
 - `input` does **not** need to be destructured at the function boundary; shape like `(input: { ... })` is fine
-- `function` keyword is forbidden unless implementing class methods (see `.tactic:funcs:arrow-only`)
+- `function` keyword is forbidden unless to implement class methods (see `.tactic:funcs:arrow-only`)
 
 ##### ❌ forbidden
 - more than 2 positional args

package/dist/domain.roles/mechanic/briefs/practices/code.prod/evolvable.procedures/rule.require.input-context-pattern.md.pt2.md

@@ -17,22 +17,22 @@ export const doSomething = (input: { foo: string; bar: number }): void => {
 ## .why
 this pattern maximizes **maintainability** and **readability** by:
 
-1. **keeping type info local**
+1. **keep type info local**
    - no need to jump to another file or scroll to find the interface/type definition.
    - changes to argument structure are quick and visible in one place.
 
-2. **reinforcing origin clarity**
-   - variables from `input` are always referenced as `input.foo` or `input.bar`, making their provenance explicit.
+2. **reinforce origin clarity**
+   - variables from `input` are always referenced as `input.foo` or `input.bar`, which makes their provenance explicit.
    - this avoids ambiguity in larger scopes, especially when a function mixes locals, constants, and context values.
 
-3. **avoiding premature fragmentation**
+3. **avoid premature fragmentation**
    - not all shapes deserve a named type. we only extract to `type` or `interface` when the same shape is reused across multiple functions or modules.
 
 ---
 
 ## 📏 rules
 - declare the first parameter as `(input: { ... })` with inline types by default.
-- destructuring is allowed **inside** the function body, never in the parameter list.
+- to destructure is allowed **inside** the function body, never in the parameter list.
 - optional `context` parameter follows the same pattern `(context?: { ... })` and is always second.
 - if the type is reused in 3+ places, extract to a named `type` but keep the `input` wrapper.
 

package/dist/domain.roles/mechanic/briefs/practices/code.prod/evolvable.procedures/rule.require.named-args.md

@@ -1,6 +1,6 @@
 always used named arguments on inputs
 
-they make it clear when reading what the arguments are used for
+they make it clear when you read what the arguments are used for
 
-they also make it possible to reorder arguments without breaking the contract (great for refactors, deprecations, renames, etc)
+they also make it possible to reorder arguments without to break the contract (great for refactors, deprecations, renames, etc)
 

package/dist/domain.roles/mechanic/briefs/practices/code.prod/evolvable.procedures/rule.require.single-responsibility.md

@@ -6,7 +6,7 @@ enforce that every code file and procedure has a singular, clearly-defined respo
 #### .why
 - makes code easier to locate, understand, and test
 - ensures separation of concerns between logic, validation, and orchestration
-- prevents files from bloating with unrelated logic or creeping concerns
+- prevents files from bloat with unrelated logic or creep concerns
 
 #### .rules
 
@@ -18,7 +18,7 @@ enforce that every code file and procedure has a singular, clearly-defined respo
 
 ❌ forbidden
 - more than one exported procedure per file
-- co-locating validation, parsing, or orchestration logic alongside domain logic
+- co-located validation, parse, or orchestration logic alongside domain logic
 - runtime type assertions or guards inside general-purpose logic
 - dead code, TODOs, or unrelated comments in the file
 - guards that apply redundant runtime typechecks (we trust typescript)

package/dist/domain.roles/mechanic/briefs/practices/code.prod/evolvable.repo.structure/rule.forbid.barrel-exports.md

@@ -22,9 +22,9 @@ they add zero value
 
 ---
 
-the only thing that's allowed is
+the only case that's allowed is
 
-within an index.ts file, exporting one object
+within an index.ts file, to export one object
 
 e.g.,
 

package/dist/domain.roles/mechanic/briefs/practices/code.prod/evolvable.repo.structure/rule.require.directional-deps.md

@@ -39,11 +39,11 @@ src/
   - `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
+  - `domain.objects/` must not depend on any module outside its own layer
+  - `infra/` must not depend on any module 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/`)
+- never import upward across layers (e.g., `domain.objects/` that imports `access/`)
 - shared types must follow the same directional rules
 
 .enforcement

package/dist/domain.roles/mechanic/briefs/practices/code.prod/pitofsuccess.errors/rule.forbid.error-hiding.md.pt1.md

@@ -6,9 +6,9 @@ try/catch
 
 ---
 
-the only cases where a trycatch is allowed is if the catch has an allowlist of the errors it catches and CAREFULLY handles those, while throwing the rest up
+the only cases where a trycatch is allowed is if the catch has an allowlist of the errors it catches and CAREFULLY handles those, while it throws the rest up
 
-otherwise, its a failhide hazard, where real errors will be silently hidden, leading to defects or hours of pointless debugging
+otherwise, its a failhide hazard, where real errors will be silently hidden, which leads to defects or hours of pointless debug
 
 never failhide
 

package/dist/domain.roles/mechanic/briefs/practices/code.prod/pitofsuccess.errors/rule.prefer.helpful-error-wrap.md

@@ -10,7 +10,7 @@ e.g.,
 
 ```ts
 try {
-  // do something that throws
+  // do task that throws
   await doSomething({ userUuid })
 } catch (error) {
   if (!(error instanceof Error)) throw error;

package/dist/domain.roles/mechanic/briefs/practices/code.prod/pitofsuccess.errors/rule.require.fail-fast.md

@@ -1,32 +1,32 @@
 .tactic = flow:fail-fast
 
-.what = enforce fail-fast logic using early exits and HelpfulError subclasses to reject invalid state or input immediately
+.what = enforce fail-fast logic via 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
+  - applies to guard checks, validations, and branch paths
 
 .why:
-  - improves readability by collapsing failure paths early
+  - improves readability via early collapse of failure paths
   - 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`
+  - increases safety via clear documentation and halt on invalid input
+  - makes bugs easier to debug with rich context via `helpful-errors`
 
 .how:
   - use **early returns or throws** for all guard clauses
-    - never use `if (...) else` or deep nesting to control flow
+    - never use `if (...) else` or deep nested blocks 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
+  - prefer `BadRequestError.throw(...)` to reject 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(...)`
+  - include **context objects** in all thrown errors to aid debug
+  - validate error behavior in tests via `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
+    - must be preceded by a comment that summarizes *why* the guard exists
+    - blank line after each guard before main logic continues
 
   ```ts
   // reject if user does not exist

package/dist/domain.roles/mechanic/briefs/practices/code.prod/pitofsuccess.procedures/rule.require.idempotency.[seed].md

@@ -9,7 +9,7 @@ idempotency means that the same request duplicated will succeed as if it only ra
 
 ---
 
-the main methods of doing so are via
+the main methods to do so are via
 
 - findsert = find or insert
   - const before = dao.findByRef()

package/dist/domain.roles/mechanic/briefs/practices/code.prod/pitofsuccess.procedures/rule.require.idempotent-procedures.md

@@ -1,6 +1,6 @@
 .tactic = proc:require-idempotency
 
-.what = all procedures must be idempotent unless explicitly marked otherwise — calling the same logic twice must not cause double effects
+.what = all procedures must be idempotent unless explicitly marked otherwise — to call the same logic twice must not cause double effects
 
 .scope:
   - applies to all stitched procedures, exports, and service logic
@@ -13,10 +13,10 @@
 
 .how:
   - all procedures must **guard against re-entry**
-    - check whether the action has already occurred before executing
+    - check whether the action has already occurred before execute
     - 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)
+  - any **side-effect-produce operation** must:
+    - check for a prior result (e.g. prior 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
@@ -29,7 +29,7 @@
   - 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
+  - test cases must show repeat-call has no additional effect
 
 .examples: