rhachet-roles-ehmpathy 1.0.0 → 1.1.0

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`

package/dist/logic/roles/mechanic/.briefs/codestyle/flow.single-responsibility.md

@@ -0,0 +1,67 @@
+### .tactic = codestyle:single-responsibility
+
+#### .what
+enforce that every code file and procedure has a singular, clearly-defined responsibility
+
+#### .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
+
+#### .rules
+
+✅ required
+- every file must export **exactly one** named procedure
+- filename must match the exported procedure
+- all logic in the file must directly support the procedure’s **domain intent**
+- runtime typechecks are only allowed **if** the file's sole purpose is validation
+
+❌ forbidden
+- more than one exported procedure per file
+- co-locating validation, parsing, 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)
+
+
+#### .examples
+
+**✅ good**
+```ts
+// getCustomerInvoices.ts
+/**
+ * .what = retrieves all invoices for a given customer
+ * .why = isolates domain logic for invoice lookup by customer
+ */
+export const getCustomerInvoices = ({ customerId }: { customerId: string }) => {
+  return invoiceDao.findMany({ customerId });
+};
+```
+
+
+
+**⛔ bad**
+```ts
+// customerUtils.ts
+// utility file that contains many things
+
+export const getCustomerInvoices = (...) => { ... }
+
+export const validateCustomer = (...) => { ... }  // ❌ multiple responsibilities
+
+// random comment about edge cases — ❌ unrelated noise
+
+```
+
+
+**⛔ bad**
+```ts
+// getCustomerInvoices.ts
+export const getCustomerInvoices = ({ customerId }: { customerId: string }) => {
+  if (typeof customerId !== 'string')  // ❌ redundant runtime check
+    throw new Error('bad id');
+
+  return invoiceDao.findMany({ customerId });
+};
+```
+

package/dist/logic/roles/mechanic/.briefs/codestyle/mech.args.input-context.md

@@ -0,0 +1,61 @@
+### .tactic = args:input-context
+
+#### .what
+enforce hard requirement that all procedure args to follow the canonical pattern: `(input, context?)` — even for simple one-liners
+
+#### .why
+- promotes long-term clarity and change-resilience over short-term brevity
+- 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
+
+#### .where
+- applies to **all function definitions** (sync or async)
+- required for all exported and internal functions in production code
+- expected in tests, hooks, utils, and logic modules
+- only anonymous inline callbacks are **exempt** if tightly scoped
+
+#### .how
+
+##### ✅ required
+- every function must accept exactly:
+  - one `input` arg — a destructurable object
+  - optional second `context` arg — also a destructurable object
+
+- **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`)
+
+##### ❌ forbidden
+- more than 2 positional args
+- non-destructurable inputs
+- context blended into input
+- inline positional args unless anonymous
+
+
+---
+
+### .examples
+
+##### ✅ positive
+```ts
+// standard function
+export const genRoute = async (input: { slug: string }, context?: { traceId?: string }) => { ... }
+
+// internal logic
+const updateUser = ({ userId }: { userId: string }, context: { userDao: UserDao }) => { ... }
+
+// test
+expect(hasChanges({ before, after })).toBe(true);
+```ts
+
+##### ❌ negative
+```ts
+export function doThing(a, b, c) {}              // ⛔ positional args & function keyword
+
+handleRequest(input, options, env)               // ⛔ more than two args
+
+export const getTotal = (invoice) => ...         // ⛔ input not typed
+```

package/dist/logic/roles/mechanic/.briefs/codestyle/mech.arrowonly.md

@@ -0,0 +1,47 @@
+### .tactic = funcs:arrow-only
+
+#### .what
+enforce that all procedures are declared using 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)
+
+#### .why
+- enforces lexical `this` binding 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
+
+#### .how
+
+##### .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
+- always destructure input as the first arg if applicable
+
+##### .examples
+
+###### .positive
+```ts
+export const setCustomerPhone = ({ customer, phone }) => {
+  return { ...customer, phone };
+};
+
+const getName = (input) => input.name;
+```
+
+
+###### .negative
+```ts
+function setCustomerPhone({ customer, phone }) {   // ⛔ function keyword
+  return { ...customer, phone };
+}
+
+export function doWork() {                     // ⛔ export with function
+  ...
+}
+```

package/dist/logic/roles/mechanic/.briefs/codestyle/mech.clear-contracts.md

@@ -0,0 +1,53 @@
+
+.tactic = mech:contract-before-implementation
+
+.what = declare the shape and expectations of behavior (the contract) before writing its implementation
+
+.why:
+- forces clarity about what is being built and why
+- prevents premature optimization and over-engineering
+- 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
+
+.how:
+- always begin with a **procedure type** that defines:
+  - function signature or interface
+  - expected inputs and output shape
+  - error modes and invariants
+  - why it exists (motivation or business rule)
+
+.examples:
+
+✅ good
+    // domain/procedures/sendInvoice.ts
+
+    /**
+     * .what = sends an invoice to the customer and marks it as sent
+     * .why = required for customer billing compliance and automation
+     */
+    export const sendInvoice = async ({
+      invoice,
+      customer,
+    }: {
+      invoice: Invoice;
+      customer: Customer;
+    }): Promise<{ success: true }> => {
+      // ...
+    };
+
+❌ bad
+    // logic/sendInvoice.ts
+
+    export const sendInvoice = async (invoice, customer) => {
+      // suddenly starts doing 4 things 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**
+

package/dist/logic/roles/mechanic/.briefs/codestyle/mech.tests.given-when-then.md

@@ -0,0 +1,62 @@
+### .tactic = tests:given-when-then
+
+#### .what
+use `jest` in combination with `test-fns` to structure tests with `given / when / then` hierarchy
+
+#### .where
+- applies to all test suites across core logic and modules
+- required for integration tests and expected for unit tests
+- recommended for test readability, maintainability, and intent traceability
+
+#### .why
+- expresses test intent and flow in human-readable structure
+- aligns test structure with natural reasoning: context → action → result
+- improves ability to isolate, debug, and extend test scenarios
+- keeps test surface minimal and expressive, especially for high-context logic
+
+#### .how
+
+##### .rules
+- use `describe()` for grouping related logic (e.g., a route or stitcher)
+- use `given()` to describe the setup scenario
+  - must establish all required input (e.g., files, threads, role context)
+- use `when()` to declare the act or trigger
+  - should define one clear execution path
+- use `then()` to assert outcomes
+  - may include async calls, file checks, or output inspection
+
+##### .examples
+
+###### .positive
+```ts
+import { given, when, then } from 'test-fns';
+
+given('a mechanic with ask, claim, and coderefs', () => {
+  const coderef = genArtifactGitFile({ uri: 'file.md' });
+
+  beforeEach(async () => {
+    await coderef.set({ content: '...' });
+  });
+
+  when('executed', () => {
+    const threads = { /* setup threads */ };
+
+    then('updates the claims artifact', async () => {
+      const result = await enweaveOneStitcher({ stitcher, threads }, context);
+      const content = await claimsArt.get();
+      expect(content).toContain('...');
+    });
+
+    then('throws on invalid input', async () => {
+      const error = await getError(enweaveOneStitcher({ stitcher, threads: {} }, context));
+      expect(error).toBeInstanceOf(ThreadMissError)
+    });
+  });
+});
+```
+
+```ts
+when('executed', async () => {        // ⛔ async not allowed in when()
+  const result = await doSomething();
+});
+```

package/dist/logic/roles/mechanic/.briefs/codestyle/mech.what-why.md

@@ -0,0 +1,88 @@
+
+### .tactic = funcs:what-why-comments
+
+#### .what
+require `.what` and `.why` comments to prefix every named procedure and code paragraph
+
+#### .why
+- improves readability for future travelers
+- captures intent behind decisions, not just behavior
+- speeds up audits, refactors, and onboarding
+- reinforces consistent communication in code
+
+---
+
+#### .how
+
+##### .procedure headers
+
+every named function must begin with a jsdoc block like:
+
+```ts
+/**
+ * .what = summarize the intent of the procedure
+ * .why = explain why it exists or why it matters
+ * .note = optional; record special behaviors, edge cases, caveats
+ */
+```
+
+- mandatory for all exported procedures => this is a BLOCKER
+- required for helpers that aren’t self-evident
+- optional for anonymous one-liners or trivial passthroughs
+
+
+##### .paragraph summaries
+
+every logical paragraph (group of lines) must be prefixed with a `//` comment summarizing its purpose:
+
+```ts
+// load invoice from database, for status check later in flow
+const invoice = await getInvoiceById(invoiceId);
+```
+
+- avoid duplicating code — focus on *intent*
+- explain why something matters, not just what it is
+- group related lines under a shared summary
+- important: compress into one line. if a paragraph summary is multiline, then the code paragraph is complex enough to need its own procedure and testsuite
+
+
+#### .examples
+
+##### ✅ positive
+
+```ts
+/**
+ * .what = generates a proposal by iterating until a releasable version is judged
+ * .why = ensures only clean code reaches the reviewer, via mechanic feedback loop
+ */
+export const proposeCode = async ({ threads }) => {
+  // iterate to gather feedback and judgment on inflight code
+  const result = await runIterateCycle({ threads });
+
+  // expose artifact for downstream routes
+  return result.threads.artist.context.stash.art.inflight;
+};
+```
+
+##### ❌ negative
+
+```ts
+// run flow  ⛔ unclear
+const r = await run();
+
+return r.artifact; // ⛔ what is this? why return this?
+
+// very long comment describing why this block exists
+// and what it does and why it's written in this particular way
+// suggests the code below is too complex and should be split out
+const result = someLogic(input);
+const adjusted = adjustResult(result);
+const validated = validate(adjusted);
+const final = finalize(validated);
+```
+
+#### .where
+
+- applies to all production code: modules, utilities, logic, and exports
+- expected in test files for setup blocks and assertions
+- exempt only for tiny, obviously self-contained expressions

package/dist/logic/roles/mechanic/.briefs/codestyle/mech.what-why.v2.md

@@ -0,0 +1,98 @@
+
+### .tactic = comment-discipline
+
+#### .what
+require jsdoc style `.what` and `.why` comments to prefix every named procedure
+require oneliner summaries of .what and why comments to precede every code paragraph
+
+#### .why
+- improves readability for future travelers
+- captures intent behind decisions, not just behavior
+- speeds up audits, refactors, and onboarding
+- reinforces consistent communication in code
+
+
+### .comment discipline
+
+comments are a hard requirement — they must follow precise structure and length:
+
+✅ required
+- /** .what, .why */ block above all named procedures
+- // one-liner before every logical paragraph of code
+
+❌ forbidden
+- missing .what or .why above a procedure
+- multiline // paragraph comments
+- vague, redundant, or “code-shaped” comments
+
+##### .procedure headers
+every named function must begin with:
+
+```ts
+/**
+ * .what = intent summary
+ * .why = reason it exists or matters
+ * .note = optional; caveats or special behavior
+ */
+const doThing = (input: {}, context) => { ... }
+```
+
+rules:
+- both .what and .why are mandatory — missing either = BLOCKER
+- .what must be 1line max, clear and scan-friendly
+- .why must be 3lines max, clear and scan-friendly
+- .note is optional but must be concise
+
+
+##### .code paragraphs
+
+every meaningful block of lines must start with a one-line summary:
+
+```ts
+// load invoice and raise on pastdue
+const invoice = await getInvoiceById(invoiceId);
+if (invoice.status === 'PASTDUE') UnexpectedCodePathError.throw(...)
+```
+
+rules:
+- must summarize intent (why this block exists), not echo code
+- strictly one line — if it needs more, extract into its own procedure
+- comment must precede the code it describes and have a newline predecessor (think of it like a paragraph title)
+
+## .examples
+
+expected, positive examples
+```ts
+/**
+ * .what = generates a proposal via mechanic-reviewer feedback loop
+ * .why = ensures code reaches quality bar before review
+ */
+export const proposeCode = async ({ threads }) => {
+  // gather mechanic feedback through iteration
+  const result = await runIterateCycle({ threads });
+
+  // expose artifact for downstream use
+  return result.threads.artist.context.stash.art.inflight;
+};
+```
+
+
+forbidden, negative examples
+```ts
+// missing .what/.why above export      ⛔ blocker
+export const doStuff = () => { ... }
+
+// vague comment                        ⛔ no intent
+// run flow
+const r = run();
+
+// multiline paragraph comment          ⛔ must extract into procedure
+// handle logic for retries because retries are complicated
+// and they sometimes need to be skipped on failure
+const result = retry(input);
+```
+
+## .where
+- required across all prod code (logic, utils, exports)
+- expected in tests for setup/assert blocks
+- exempt only for tiny expressions or internal lambdas