rhachet-roles-ehmpathy 1.13.0 → 1.13.2

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

@@ -1,67 +0,0 @@
-### .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

@@ -1,97 +0,0 @@
-# 🧩 .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

@@ -1,61 +0,0 @@
-### .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

@@ -1,63 +0,0 @@
-# 🧩 .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

@@ -1,47 +0,0 @@
-### .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

@@ -1,53 +0,0 @@
-
-.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

@@ -1,62 +0,0 @@
-### .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

@@ -1,88 +0,0 @@
-
-### .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

@@ -1,98 +0,0 @@
-
-### .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

@@ -1,58 +0,0 @@
-# 🧩 .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`