rhachet-roles-ehmpathy 1.13.2 → 1.13.3

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/flow.transformers_over_conditionals.[lesson].md

@@ -0,0 +1,97 @@
+# 🧩 .brief.lesson: prefer transformer:pipelines over conditional:mazes
+
+---
+
+## 🌳 conditional:mazes
+
+you treat each case as a fork in the road:
+
+\`\`\`ts
+if (dotfileNoExt) {
+  return ...
+} else if (hasExt) {
+  return ...
+} else {
+  return ...
+}
+\`\`\`
+
+- **pros**
+  - explicit, easy to follow with 2–3 cases
+
+- **cons**
+  - grows fast: every new edge case means a new twist in the maze
+  - fragmented: “which corridor am i in right now?”
+  - more test cases: you need one per branch
+
+> conditionals are a **maze** — each new edge case adds another turn,
+> and you can get lost tracing which branch leads where.
+
+---
+
+## 🌊 transformer:pipelines
+
+normalize the data into a *sequence* and let transformations filter, drop, or join pieces:
+
+\`\`\`ts
+return [parts.name, \`i\${attempt}\`, parts.ext.replace(/^\./, '') || null]
+  .filter(isPresent)
+  .join('.');
+\`\`\`
+
+- **pros**
+  - handles dotfiles, no-ext, and normal files with the same flow
+  - future-proof: if `ext` is empty, the pipeline just drops it
+  - fewer "paths" → less test explosion
+  - intent is clear: *“take parts, add attempt, add ext if present, join with dots”*
+
+- **cons**
+  - sometimes less explicit about special rules (e.g. `.env` → `env.i7`)
+  - requires discipline: not every problem is pipeline-friendly
+
+> pipelines are **transformers** — they take data in, apply consistent stages,
+> and yield output without needing to remember the map.
+
+---
+
+## 🔍 why pipelines shine here
+
+1. **fewer moving parts** — single expression instead of scattered branches
+2. **symmetry** — all inputs flow through the same transformation
+3. **readability** — you immediately see the intent
+4. **testability** — one flow, many inputs, fewer branches to cover
+
+---
+
+## 🧩 comparison
+
+### conditional:maze
+\`\`\`ts
+if (ext) {
+  return \`\${name}.i\${attempt}.\${ext}\`;
+}
+if (dotfile) {
+  return \`\${base.slice(1)}.i\${attempt}\`;
+}
+return \`\${base}.i\${attempt}\`;
+\`\`\`
+
+### transformer:pipeline
+\`\`\`ts
+return [name, \`i\${attempt}\`, ext?.replace(/^\./, '')]
+  .filter(Boolean)
+  .join('.');
+\`\`\`
+
+- pipeline covers **all cases at once**
+- conditional maze scatters logic across multiple passages
+
+---
+
+## 🔑 general lesson
+
+> **prefer transformer:pipelines over conditional:mazes**
+
+- replace `if/else` with **optional data elements**
+- use a pipeline (`map` / `filter` / `join`) to combine them
+- outcome: shorter, more composable, easier to test, harder to get lost

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

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

package/dist/logic/roles/mechanic/.briefs/codestyle/pit-of-success.via.minimize-surface-area.md

@@ -0,0 +1,58 @@
+# 🧩 .brief: `tactic.pit-of-success.via.minimum-surface-area`
+
+## .what
+`tactic.pit-of-success.via.minimum-surface-area` is a design strategy where the default interface exposes only the **fewest necessary inputs** to achieve a correct, useful outcome. it reduces configuration complexity so users succeed **without deciding everything** up front.
+
+---
+
+## 🎯 goal
+- maximize success-by-default
+- minimize misuse and confusion
+- reduce time-to-first-win
+
+---
+
+## 📜 principles
+1. **eliminate before you default** — if an option isn’t needed, remove it entirely. a missing knob is safer than a defaulted one.
+2. **default everything that remains** — provide sensible, production-safe defaults for the rare knobs that survive elimination.
+3. **hide until needed** — reveal additional controls only when the user’s context clearly justifies the complexity (progressive disclosure).
+4. **bias to action** — the shortest path from “call function” to “successful result” should be the default path.
+5. **remove footguns** — defer or delete inputs that commonly lead to error.
+6. **inline the common case** — the most frequent usage should fit in one glance, without doc-diving.
+
+---
+
+## 🛠 example
+
+### before
+\\`\\`\\`ts
+createUser({
+  name,
+  email,
+  validateEmail = true,
+  sendWelcomeEmail = true,
+  welcomeTemplate = 'default',
+  timezone = 'UTC',
+  retries = 3,
+});
+\\`\\`\\`
+
+### after (minimum surface area)
+\\`\\`\\`ts
+createUser({ name, email });
+\\`\\`\\`
+- validation is on, welcome email is sent with the default template, timezone is utc, retries = 3.
+- if possible, **delete** those options entirely and make them behavior, not configuration.
+
+---
+
+## 💡 why it works
+- **lower cognitive load** — fewer decisions up front
+- **higher reliability** — default paths get the most testing and hardening
+- **faster adoption** — quick wins encourage deeper usage later
+
+---
+
+## 🔄 related tactics
+- complements `tactic.progressive-disclosure` (reveal complexity as needed)
+- overlaps with `tactic.safe-defaults`