rhachet-roles-ehmpathy 1.0.0 → 1.2.0

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/ecologist/getEcologistBrief.Options.codegen.d.ts

@@ -5,6 +5,6 @@
  *  npx tsx src/contract/commands/codegenBriefOptions.ts
  * ```
  */
-declare const options: readonly ["analysis.behavior-reveals-system.md", "core.term.price.v1.md", "core.term.price.v2.md", "distilisys.md", "distilisys.usecases.v1.md", "distilisys.usecases.v2.md", "distill.refine.terms.symmetry.md", "distill.refine.terms.ubiqlang.md", "eco001.overview.md", "eco101.core-system-understanding.md", "eco101.p1.ecosystem-structure.md", "eco101.p2.trophic-dynamics.md", "eco101.p3.population-ecology.md", "eco101.p4.community-interactions.md", "eco505.systems-thinking.md", "econ001.overview.md", "econ101.core-mechanics.md", "econ101.p1.supply-and-demand.md", "econ101.p2.opportunity-cost.md", "econ101.p3.marginal-analysis.md", "econ101.p4.rational-choice.md", "econ201.market-structures-and-failures.md", "econ301.production-and-growth.md", "econ401.macro-systems.md", "econ501.global-and-institutional.md", "econ501.p1.game-theory.md", "econ501.p4.behavioral-economics.md"];
+declare const options: readonly ["term.distillation.md", "ecology/eco001.overview.md", "ecology/eco101.core-system-understanding.md", "ecology/eco101.p1.ecosystem-structure.md", "ecology/eco101.p2.trophic-dynamics.md", "ecology/eco101.p3.population-ecology.md", "ecology/eco101.p4.community-interactions.md", "ecology/eco505.systems-thinking.md", "product/user.journey._.[article].i1.md", "product/user.journey._.[article].md", "product/user.journey.purpose.[article].i1.md", "product/user.journey.purpose.[article].md", "economy/econ001.overview.md", "economy/econ101.core-mechanics.md", "economy/econ101.p1.supply-and-demand.md", "economy/econ101.p2.opportunity-cost.md", "economy/econ101.p3.marginal-analysis.md", "economy/econ101.p4.rational-choice.md", "economy/econ201.market-structures-and-failures.md", "economy/econ301.production-and-growth.md", "economy/econ401.macro-systems.md", "economy/econ501.global-and-institutional.md", "economy/econ501.p1.game-theory.md", "economy/econ501.p4.behavioral-economics.md", "distilisys/sys101.distilisys.grammar.md", "distilisys/sys201.actor.motive._.summary.md", "distilisys/sys201.actor.motive.p1.reversibility.entropy.md", "distilisys/sys201.actor.motive.p2.option.chance.choice.md", "distilisys/sys201.actor.motive.p3.chance.motive.polarity.threat.md", "distilisys/sys201.actor.motive.p4.motive.horizon.md", "distilisys/sys201.actor.motive.p5.motive.grammar.md", "distilisys/sys211.actor.resources._.primitives.summary.md", "distilisys/sys211.actor.resources.pt1.primitive.time.md", "distilisys/sys211.actor.resources.pt2.primitive.energy.md", "distilisys/sys211.actor.resources.pt3.primitive.space.md", "distilisys/sys211.actor.resources.pt4.primitive.claim.md", "distilisys/sys211.actor.resources.pt5.composites.md", "distilisys/sys231.actor.claims.p1.primitive.exchange.md"];
 export type BriefOptionEcologist = typeof options[number];
 export {};

package/dist/logic/roles/ecologist/getEcologistBrief.Options.codegen.js

@@ -8,32 +8,43 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * ```
  */
 const options = [
-    'analysis.behavior-reveals-system.md',
-    'core.term.price.v1.md',
-    'core.term.price.v2.md',
-    'distilisys.md',
-    'distilisys.usecases.v1.md',
-    'distilisys.usecases.v2.md',
-    'distill.refine.terms.symmetry.md',
-    'distill.refine.terms.ubiqlang.md',
-    'eco001.overview.md',
-    'eco101.core-system-understanding.md',
-    'eco101.p1.ecosystem-structure.md',
-    'eco101.p2.trophic-dynamics.md',
-    'eco101.p3.population-ecology.md',
-    'eco101.p4.community-interactions.md',
-    'eco505.systems-thinking.md',
-    'econ001.overview.md',
-    'econ101.core-mechanics.md',
-    'econ101.p1.supply-and-demand.md',
-    'econ101.p2.opportunity-cost.md',
-    'econ101.p3.marginal-analysis.md',
-    'econ101.p4.rational-choice.md',
-    'econ201.market-structures-and-failures.md',
-    'econ301.production-and-growth.md',
-    'econ401.macro-systems.md',
-    'econ501.global-and-institutional.md',
-    'econ501.p1.game-theory.md',
-    'econ501.p4.behavioral-economics.md',
+    'term.distillation.md',
+    'ecology/eco001.overview.md',
+    'ecology/eco101.core-system-understanding.md',
+    'ecology/eco101.p1.ecosystem-structure.md',
+    'ecology/eco101.p2.trophic-dynamics.md',
+    'ecology/eco101.p3.population-ecology.md',
+    'ecology/eco101.p4.community-interactions.md',
+    'ecology/eco505.systems-thinking.md',
+    'product/user.journey._.[article].i1.md',
+    'product/user.journey._.[article].md',
+    'product/user.journey.purpose.[article].i1.md',
+    'product/user.journey.purpose.[article].md',
+    'economy/econ001.overview.md',
+    'economy/econ101.core-mechanics.md',
+    'economy/econ101.p1.supply-and-demand.md',
+    'economy/econ101.p2.opportunity-cost.md',
+    'economy/econ101.p3.marginal-analysis.md',
+    'economy/econ101.p4.rational-choice.md',
+    'economy/econ201.market-structures-and-failures.md',
+    'economy/econ301.production-and-growth.md',
+    'economy/econ401.macro-systems.md',
+    'economy/econ501.global-and-institutional.md',
+    'economy/econ501.p1.game-theory.md',
+    'economy/econ501.p4.behavioral-economics.md',
+    'distilisys/sys101.distilisys.grammar.md',
+    'distilisys/sys201.actor.motive._.summary.md',
+    'distilisys/sys201.actor.motive.p1.reversibility.entropy.md',
+    'distilisys/sys201.actor.motive.p2.option.chance.choice.md',
+    'distilisys/sys201.actor.motive.p3.chance.motive.polarity.threat.md',
+    'distilisys/sys201.actor.motive.p4.motive.horizon.md',
+    'distilisys/sys201.actor.motive.p5.motive.grammar.md',
+    'distilisys/sys211.actor.resources._.primitives.summary.md',
+    'distilisys/sys211.actor.resources.pt1.primitive.time.md',
+    'distilisys/sys211.actor.resources.pt2.primitive.energy.md',
+    'distilisys/sys211.actor.resources.pt3.primitive.space.md',
+    'distilisys/sys211.actor.resources.pt4.primitive.claim.md',
+    'distilisys/sys211.actor.resources.pt5.composites.md',
+    'distilisys/sys231.actor.claims.p1.primitive.exchange.md',
 ];
 //# sourceMappingURL=getEcologistBrief.Options.codegen.js.map

package/dist/logic/roles/ecologist/getEcologistBrief.Options.codegen.js.map

@@ -1 +1 @@
-{"version":3,"file":"getEcologistBrief.Options.codegen.js","sourceRoot":"","sources":["../../../../src/logic/roles/ecologist/getEcologistBrief.Options.codegen.ts"],"names":[],"mappings":";;AAAA;;;;;;GAMG;AACH,MAAM,OAAO,GAAG;IACd,qCAAqC;IACrC,uBAAuB;IACvB,uBAAuB;IACvB,eAAe;IACf,2BAA2B;IAC3B,2BAA2B;IAC3B,kCAAkC;IAClC,kCAAkC;IAClC,oBAAoB;IACpB,qCAAqC;IACrC,kCAAkC;IAClC,+BAA+B;IAC/B,iCAAiC;IACjC,qCAAqC;IACrC,4BAA4B;IAC5B,qBAAqB;IACrB,2BAA2B;IAC3B,iCAAiC;IACjC,gCAAgC;IAChC,iCAAiC;IACjC,+BAA+B;IAC/B,2CAA2C;IAC3C,kCAAkC;IAClC,0BAA0B;IAC1B,qCAAqC;IACrC,2BAA2B;IAC3B,oCAAoC;CAC5B,CAAC"}
+{"version":3,"file":"getEcologistBrief.Options.codegen.js","sourceRoot":"","sources":["../../../../src/logic/roles/ecologist/getEcologistBrief.Options.codegen.ts"],"names":[],"mappings":";;AAAA;;;;;;GAMG;AACH,MAAM,OAAO,GAAG;IACd,sBAAsB;IACtB,4BAA4B;IAC5B,6CAA6C;IAC7C,0CAA0C;IAC1C,uCAAuC;IACvC,yCAAyC;IACzC,6CAA6C;IAC7C,oCAAoC;IACpC,wCAAwC;IACxC,qCAAqC;IACrC,8CAA8C;IAC9C,2CAA2C;IAC3C,6BAA6B;IAC7B,mCAAmC;IACnC,yCAAyC;IACzC,wCAAwC;IACxC,yCAAyC;IACzC,uCAAuC;IACvC,mDAAmD;IACnD,0CAA0C;IAC1C,kCAAkC;IAClC,6CAA6C;IAC7C,mCAAmC;IACnC,4CAA4C;IAC5C,yCAAyC;IACzC,6CAA6C;IAC7C,4DAA4D;IAC5D,2DAA2D;IAC3D,oEAAoE;IACpE,qDAAqD;IACrD,qDAAqD;IACrD,2DAA2D;IAC3D,yDAAyD;IACzD,2DAA2D;IAC3D,0DAA0D;IAC1D,0DAA0D;IAC1D,qDAAqD;IACrD,yDAAyD;CACjD,CAAC"}

package/dist/logic/roles/ecologist/getEcologistRole.d.ts

@@ -0,0 +1,2 @@
+import { Role } from 'rhachet';
+export declare const ROLE_ECOLOGIST: import("domain-objects/dist/manipulation/immute/withImmute").WithImmute<Role>;

package/dist/logic/roles/ecologist/getEcologistRole.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROLE_ECOLOGIST = void 0;
+const rhachet_1 = require("rhachet");
+// import { SKILL_ENVISION } from './envision/stepEnvision.skill';
+exports.ROLE_ECOLOGIST = rhachet_1.Role.build({
+    slug: 'ecologist',
+    name: 'Ecologist',
+    purpose: 'write code',
+    readme: `
+
+## 🌱 Ecologist
+
+- **scale**: domain fundamentals, real-world systems
+- **focus**: what changes, what flows, what matters — ignoring software
+- **maximizes**: fidelity to the real world
+
+Used to understand the physics, incentives, and causal flows beneath the system.
+
+  `.trim(),
+    traits: [],
+    skills: [
+    // SKILL_ENVISION_JOURNEY,
+    // SKILL_STUDY_DOMAIN,
+    // SKILL_DOMAIN_TERM_COLLECT_USECASES,
+    // SKILL_DOMAIN_TERM_DISTILL,
+    ],
+});
+//# sourceMappingURL=getEcologistRole.js.map

package/dist/logic/roles/ecologist/getEcologistRole.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getEcologistRole.js","sourceRoot":"","sources":["../../../../src/logic/roles/ecologist/getEcologistRole.ts"],"names":[],"mappings":";;;AAAA,qCAA+B;AAE/B,kEAAkE;AAErD,QAAA,cAAc,GAAG,cAAI,CAAC,KAAK,CAAC;IACvC,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,WAAW;IACjB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE;;;;;;;;;;GAUP,CAAC,IAAI,EAAE;IACR,MAAM,EAAE,EAAE;IACV,MAAM,EAAE;IACN,0BAA0B;IAC1B,sBAAsB;IACtB,sCAAsC;IACtC,6BAA6B;KAC9B;CACF,CAAC,CAAC"}

package/dist/logic/roles/getRoleRegistry.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getRoleRegistry = void 0;
 const rhachet_1 = require("rhachet");
+const getBhrainRole_1 = require("./bhrain/getBhrainRole");
+// import { ROLE_ECOLOGIST } from './ecologist/getEcologistRole';
 const getRoleRegistry_readme_1 = require("./getRoleRegistry.readme");
 const getMechanicRole_1 = require("./mechanic/getMechanicRole");
 /**
@@ -13,7 +15,11 @@ const getMechanicRole_1 = require("./mechanic/getMechanicRole");
 const getRoleRegistry = () => new rhachet_1.RoleRegistry({
     slug: 'ehmpathy',
     readme: getRoleRegistry_readme_1.EHMPATHY_REGISTRY_README,
-    roles: [getMechanicRole_1.ROLE_MECHANIC],
+    roles: [
+        getBhrainRole_1.ROLE_BHRAIN, // todo: lift bhrain role into own repo
+        // ROLE_ECOLOGIST,
+        getMechanicRole_1.ROLE_MECHANIC,
+    ],
 });
 exports.getRoleRegistry = getRoleRegistry;
 //# sourceMappingURL=getRoleRegistry.js.map

package/dist/logic/roles/getRoleRegistry.js.map

@@ -1 +1 @@
-{"version":3,"file":"getRoleRegistry.js","sourceRoot":"","sources":["../../../src/logic/roles/getRoleRegistry.ts"],"names":[],"mappings":";;;AAAA,qCAAuC;AAEvC,qEAAoE;AACpE,gEAA2D;AAE3D;;;;;GAKG;AACI,MAAM,eAAe,GAAG,GAAiB,EAAE,CAChD,IAAI,sBAAY,CAAC;IACf,IAAI,EAAE,UAAU;IAChB,MAAM,EAAE,iDAAwB;IAChC,KAAK,EAAE,CAAC,+BAAa,CAAC;CACvB,CAAC,CAAC;AALQ,QAAA,eAAe,mBAKvB"}
+{"version":3,"file":"getRoleRegistry.js","sourceRoot":"","sources":["../../../src/logic/roles/getRoleRegistry.ts"],"names":[],"mappings":";;;AAAA,qCAAuC;AAEvC,0DAAqD;AACrD,iEAAiE;AACjE,qEAAoE;AACpE,gEAA2D;AAE3D;;;;;GAKG;AACI,MAAM,eAAe,GAAG,GAAiB,EAAE,CAChD,IAAI,sBAAY,CAAC;IACf,IAAI,EAAE,UAAU;IAChB,MAAM,EAAE,iDAAwB;IAChC,KAAK,EAAE;QACL,2BAAW,EAAE,uCAAuC;QACpD,kBAAkB;QAClB,+BAAa;KACd;CACF,CAAC,CAAC;AATQ,QAAA,eAAe,mBASvB"}

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,73 @@
+.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/`, `logic/`, `data/`, and `domain/` folders
+- 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
+    endpoints/     // exposed APIs
+    commands/      // internal entrypoints (e.g. CLI, scripts)
+  logic/           // application procedures, stitched flows
+  data/            // infrastructure layer (daos, sdks, services)
+    daos/          // persistence logic — may reference domain objects
+    sdks/          // external clients — may reference domain types
+  domain/          // lowest — domain models, business rules
+    objects/       // canonical domain declarations
+```
+
+.how
+- each layer may depend **only on the layers below it**
+  - `contract/` may depend on `logic/`, `data/`, `domain/`
+  - `logic/` may depend on `data/`, `domain/`
+  - `data/` may depend on `domain/`
+  - `domain/` must not depend on anything outside its own layer
+- stitched flows live in `logic/` or `contract/commands/` and orchestrate downstream only
+- never import upward across layers (e.g. `domain/` importing `data/`)
+- shared types must follow same directional rules
+
+.enforcement
+- imports that violate top-down boundary = BLOCKER
+- circular dependencies between layers = BLOCKER
+- logic in `domain/` must never reach into `data/`, `logic/`, or `contract/`
+- logic in `data/` may use `domain/`, but must stay decoupled from business rules
+
+.examples
+
+✅ positive
+```ts
+// contract/endpoints/sendInvoice.ts
+import { generateInvoice } from '@/logic/generateInvoice';
+
+// logic/submitJob.ts
+import { Job } from '@/domain/objects/Job';
+import { jobDao } from '@/data/daos/jobDao';
+
+// data/daos/jobDao.ts
+import { Job } from '@/domain/objects/Job';
+```
+
+❌ negative
+```ts
+// domain/Customer.ts
+import { customerDao } from '@/data/daos/customerDao'; // ⛔ illegal upward import
+
+// domain/Invoice.ts
+import { calculateTotal } from '@/logic/calculateTotal'; // ⛔ direction violation
+
+// data/sdkWrapper.ts
+import { dispatchFlow } from '@/logic/' // ⛔ 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 });