rhachet-roles-ehmpathy 1.0.0 → 1.2.0

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`

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.args.input-inline.md

@@ -0,0 +1,63 @@
+# 🧩 .brief: `args:inline-input`
+
+## .what
+**`args:inline-input`** is a declaration style for function arguments where the primary argument is a **single `input` object** with **inline type annotations**.
+
+\`\`\`ts
+export const doSomething = (input: { foo: string; bar: number }): void => {
+  // ...
+};
+\`\`\`
+
+- **inline types**: the shape of `input` is declared directly at the point of use, not as a separate named type (unless truly reused across contexts).
+- **non-destructured**: `input` remains intact in the parameter list.
+
+---
+
+## .why
+this pattern maximizes **maintainability** and **readability** by:
+
+1. **keeping 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.
+   - this avoids ambiguity in larger scopes, especially when a function mixes locals, constants, and context values.
+
+3. **avoiding 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.
+- 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.
+
+---
+
+## ✅ example
+
+\`\`\`ts
+export const sendEmail = (
+  input: { to: string; subject: string; body: string },
+  context?: { retries?: number }
+): Promise<void> => {
+  const { to, subject, body } = input;
+  // ...
+};
+\`\`\`
+
+---
+
+## ❌ anti-pattern
+
+\`\`\`ts
+// ❌ loses "input" provenance
+export const sendEmail = ({ to, subject, body }: { to: string; subject: string; body: string }) => {};
+
+// ❌ type drift — must look up the type definition elsewhere for basic usage
+export const sendEmail = (input: EmailInput) => {};
+\`\`\`

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