rhachet-roles-ehmpathy 1.0.0 → 1.2.0

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`

package/dist/logic/roles/mechanic/.briefs/engineer/dependency-injection.md

@@ -0,0 +1,118 @@
+## 🧠 `.brief.designer.dependency-injection`
+
+### 🧠 topic: dependency injection
+**why we pass in dependencies instead of hardcoding them**
+
+---
+
+### 🎯 goal
+build software that is **flexible, testable, and decoupled**,
+by making dependencies **explicit, swappable, and controlled from the outside**.
+
+---
+
+### 🛠 what it is
+
+> **dependency injection** = giving a function, class, or module what it needs from the outside,
+> rather than letting it construct or look up those tools internally.
+
+for example, instead of having a function reach for its own dependencies:
+
+```ts
+// ❌ tightly coupled and side-effect prone
+import { log } from '@/utils/logger';
+import { getDatabaseConnection } from '@/utils/database';
+
+export const upsert = async ({ cost }: { cost: JobLeadCost }) => {
+  log.debug('began.upsert', { cost });
+  const dbConnection = await getDatabaseConnection();
+  const result = await dbConnection.query('SELECT * FROM ...');
+}
+```
+
+you inject those dependencies via the standard `(input, context)` pattern:
+
+```ts
+// ✅ dependency injection via context
+export const upsert = async (
+  { cost }: { cost: JobLeadCost },
+  context: { dbConnection: DatabaseConnection, log: LogMethods }, // note how the .context pattern cleanly separates inputs from dependencies
+) => {
+  context.log.debug("began.upsert", { cost });
+  const updated = await context.dbConnection.query('SELECT * FROM ...');
+  await emitJobLeadCostSetEvent(result, context); // note how easy it is to reuse dependencies via the context pattern
+  return updated;
+};
+```
+
+- the function doesn’t reach into globals or construct its own tools
+- everything it needs is **passed in from the outside**, making it testable, predictable, and side-effect free
+
+---
+
+### 🔑 paved pattern: `(input, context)`
+dependency injection is best done by following the **standard procedure contract**:
+
+```ts
+export const doThing = async (
+  input: SomeInput,
+  context: { db: Db; log: Logger } & OtherContext
+) => { ... }
+```
+
+- all dependencies go in the `context` argument
+- keeps `input` clean, and `context` flexible
+- enables composition, tracing, and full test control
+
+
+---
+
+### 🤝 why it matters
+
+- **testability** — swap real dependencies with mocks/fakes
+- **flexibility** — easily change implementations without changing core logic
+- **separation of concerns** — business logic doesn't manage its own plumbing
+- **explicitness** — makes system wiring visible and intentional
+- **reusability** — same logic can be reused with different behaviors
+
+---
+
+### 🧱 core principle
+
+> **don’t make decisions deep inside the system.**
+> instead, **let the outer layers decide what gets injected**.
+
+you keep **policies and tools separate from behaviors**.
+
+---
+
+### 🔍 mental model
+
+> dependency injection is like **plugging in a tool** instead of **building one every time**.
+
+your procedures say:
+> “give me what I need — I don’t care where it came from.”
+
+---
+
+### 🔄 practical benefits
+
+| without DI                             | with DI                                    |
+|----------------------------------------|--------------------------------------------|
+| hardcoded database inside procedures   | database passed in as via parameters       |
+| requires real API in tests             | can inject mock/fake API for testing       |
+| logic tied to concrete tools           | logic works with any compatible tool       |
+| hard to switch infra/tools             | swappable with config or environment setup |
+
+---
+
+### 🧩 final synthesis
+
+we inject dependencies to build systems that are easier to **test**, **scale**, and **evolve**.
+
+> dependency injection is about building **pure, decoupled, and testable** systems.
+> it eliminates shared state, surfaces side effects, and makes your logic portable and composable.
+> it enables **modularity**, **testability**, and **control**,
+> by making **dependencies external** instead of hidden inside.
+
+done right, it's **invisible during use**, and **invaluable during testing, scaling, and evolution**.

package/dist/logic/roles/mechanic/.briefs/engineer/dependency-injection.stub.md

@@ -0,0 +1,11 @@
+todo: declare why dependency injection leads to a pit of success && why global shared state should be avoided
+
+via dependency injection, you always know what's referncing what. no side effects
+
+persistance is the only global shared state that should exist - and even that should be managed cautiously (e.g., to avoid race conditions)
+
+---
+
+via dependency injection, either via context or input params, you craft safer, easier to test, and more reliable code
+
+a significant contributor to the pit-of-success we strive for

package/dist/logic/roles/mechanic/.briefs/style.compressed.md

@@ -0,0 +1,29 @@
+// style:tactics (compressed)
+
+- name:ubiqlang
+  - use one canonical term per concept (e.g., always use `customer`, never `client`, `user`, or `account`)
+  - eliminate overloads: each term must refer to exactly one thing (e.g., do not use `update` for both "save" and "fetch")
+  - when introducing a new term:
+    - define its interface and role
+    - document its meaning clearly
+    - ensure consistent usage across code, docs, and tests
+
+- name:treestruct
+  - for mechanisms (procedures, steps, transforms), use `[Verb][NounHierarchy]` format
+    - verb must come first and be atomic (e.g., `gen`, `set`, `get`, `map`, `submit`)
+    - examples: `genStepImagineViaTemplate`, `setCustomerPhone`
+  - for resources (records, results), use `[NounHierarchy][State]?` format
+    - `State` is optional and should clarify the form or phase (e.g., `Found`, `Updated`, `Draft`, `Final`)
+    - examples: `contentFound`, `invoiceDraft`, `customer`
+  - group nouns by domain to maintain treesorted file and symbol organization
+
+- words:lowercase
+  - use lowercase for all non-code text (comments, prompts, markdown, logs)
+  - never capitalize:
+    - the start of a sentence
+    - generic nouns (`customer`, `step`)
+    - verbs (`set`, `submit`, `handle`)
+    - system messages or instructions
+  - only capitalize:
+    - code symbols (e.g., `StitchStepImagine`, `GitRepo`)
+    - proper nouns or brand names (e.g., OpenAI, GitHub)

package/dist/logic/roles/mechanic/.briefs/style.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/style.names.treestruct.md

@@ -0,0 +1,48 @@
+.tactic = name:treestruct
+
+.what = enforce `[verb][...noun]` for mechanisms and `[...noun][state]?` for resources
+.where:
+  - `verb` = exactly one leading verb (e.g., `gen`, `set`, `get`, `map`)
+  - `...noun` = hierarchy of nouns reflecting the domain treestruct
+  - `state` = optional suffix representing state or outcome (e.g., `Updated`, `Found`, `After`, `Draft`)
+  - this tactic applies to all named functions, types, files, folders, and slugs
+
+.why:
+  - maximizes autocomplete grouping by domain or action
+  - enables tree-sorted navigation in IDEs and file explorers
+  - avoids ambiguity and naming drift across boundaries (design, dev, product)
+
+.how:
+  .rules:
+    - For **mechanisms** (functions, generators, procedures):
+      - use format: `[Verb][...NounHierarchy]`
+      - the verb must come **first**, and be **exactly one** action (e.g., `gen`, `set`, `get`, `map`, `submit`)
+      - e.g., `genStepImagineViaTemplate`, `setCustomerPhone`, `mapJobQuoteToEstimate`
+    - For **resources** (stateful data, outcomes, snapshots):
+      - use format: `[...NounHierarchy][State]?`
+      - the optional `State` suffix:
+        - is used when disambiguating multiple forms (e.g., `InvoiceDraft` vs `InvoiceFinal`)
+        - is typically a past participle or state label (e.g., `Found`, `After`, `Draft`)
+        - may be omitted if the base noun already implies a single clear meaning
+      - e.g., `contentFound`, `customer`, `invoiceDraft`
+
+  .examples:
+    .positive:
+      // mechanisms
+      - `genStepImagineViaTemplate`   // generates a StitchStepImagine from a template
+      - `setCustomerPhone`            // sets the customer's phone number
+      - `mapGitRepoToWorkspace`       // maps a Git repo into a workspace domain
+      - `getInvoiceFinalizedState`    // retrieves the final state of an invoice
+
+      // resources
+      - `contentFound`                // content retrieved from a source
+      - `customer`                    // single canonical term for a user of services
+      - `invoiceDraft`                // invoice in editable state
+      - `invoice`                     // base noun with implicit meaning
+
+    .negative:
+      - `stepImagineGenFromTemplate`  // ⛔ wrong order — verb must come first
+      - `customerSet`                 // ⛔ vague mechanism — better as `setCustomer` or `setCustomerPhone`
+      - `FoundContent`                // ⛔ reversed word order and PascalCase — should be `contentFound`
+      - `submitQuoteJob`              // ⛔ noun hierarchy flipped — should be `submitJobQuote`
+      - `update()`                    // ⛔ unscoped verb — must include noun domain (e.g., `updateInvoice`)

package/dist/logic/roles/mechanic/.briefs/style.names.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 term stacking across all code (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/style.words.lowercase.md

@@ -0,0 +1,36 @@
+.tactic = words:lowercase
+
+.what = enforce lowercase for all words unless capitalization is required by code or naming convention
+.where:
+  - applies to comments, docstrings, markdown, logs, and prompt copy
+  - only exceptions are code constructs (e.g., class names) and proper nouns (e.g., OpenAI)
+
+.why:
+  - keeps language neutral, minimal, and machine-aligned
+  - prevents inconsistent or performative emphasis via caps
+  - improves scanability and reduces visual noise across surfaces
+
+.how:
+  .rules:
+    - do not capitalize the first word of a sentence
+    - only use capitalization when:
+      - referencing a class, type, or constant (e.g., `StitchStepImagine`, `GitRepo`)
+      - writing a proper noun or brand (e.g., OpenAI, GitHub, AWS)
+    - never capitalize:
+      - generic nouns (`customer`, `invoice`, `step`)
+      - verbs (`set`, `get`, `submit`, `handle`)
+      - system comments or instructions, even at the beginning of a line
+
+  .examples:
+    .positive:
+      - `// returns a new invoice if customer exists`
+      - `// handled in gitrepo.init()`
+      - `// fallback if no customer was found`
+      - `// pass into StitchStepImagine to generate`
+      - `// openai prompt requires flattened string`
+    .negative:
+      - `// Returns a new invoice`       // ⛔ capitalized sentence start
+      - `// This is handled in GitRepo`  // ⛔ capitalized sentence + verb
+      - `// Submit the job for approval` // ⛔ capitalized imperative
+      - `// Customer must exist first`   // ⛔ capitalized domain noun
+      - `// GitHub Repository`           // ⛔ capitalized generic noun

package/dist/logic/roles/mechanic/codediff/routeArtistCodeDiff.template.md

@@ -0,0 +1,46 @@
+directive
+- <codediff><imagine> the [ask] against the [inflight]
+  - input = [inflight], [ask], [claims], [feedback]?
+  - output = new [inflight] .ts contents (all thoughts should go in comments, output should be valid typescript); no markdown codeblock, just code
+    - write only the production logic and comments required; no demo code unless it's in the jsdoc comment
+
+context.role.traits
+- maximally concise; prefer treestructs and outlines; maximize signal, minimize words
+- systematically distill scenes with ubiquitous language
+- uses treestructs and bullet points to maximize signal-to-noise
+- explain .what and .why with comments for each code paragraph // and each code procedure /**
+$.rhachet{inherit.traits}
+
+context.role.skills
+$.rhachet{inherit.skills}
+
+context.scene
+$.rhachet{scene}
+
+directive
+- <codediff><imagine> the [ask] against the [inflight]
+  - input = [ask], [claims], [feedback]?
+  - output = new [inflight] .ts contents (all thoughts should go in comments, output should be valid typescript); no markdown codeblock, just code
+
+--------------------------
+
+codestyle rules to enforce:
+$.rhachet{codestyle}
+
+--------------------------
+
+claims =
+$.rhachet{claims}
+
+feedback =
+$.rhachet{feedback}
+
+ask =
+$.rhachet{ask}
+
+--------------------------
+
+inflight =
+```ts
+$.rhachet{inflight}
+```

package/dist/logic/roles/mechanic/codediff/routeCriticCodeReviewArchitecture.template.md

@@ -0,0 +1,78 @@
+directive
+- <critic><review><architecture> the [subject] focused on architecture violations only
+  - input = [subject], [claims]
+  - output = json list of suggestions
+    - each suggestion must be:
+      {
+        kind: "blocker" | "nitpick" | "chance" | "praise",
+        scope: "technical.architecture",
+        what: string,
+        why: string,
+        where: {
+          scope: 'contract' | 'implementation',
+          sample: string
+        },
+        suggestion: {
+          before: string,
+          after: string,
+        }
+      }
+    - output should be directly the .json file contents. no markdown or code blocks
+
+context.role.traits
+- think like a precise code reviewer
+- optimize for signal, minimize words
+$.rhachet{inherit.traits}
+
+context.role.skills
+$.rhachet{inherit.skills}
+
+--------------------------
+
+architecture rules to enforce:
+```md
+$.rhachet{architecture.rules}
+```
+
+--------------------------
+
+architectural domain relevant:
+
+  domain.terms established (for ubiqlang)
+  ```md
+  $.rhachet{architecture.domain.terms}
+  ```
+
+  domain.bounds established (for bounded contexts & separation of concerns)
+  ```md
+  $.rhachet{architecture.domain.bounds}
+  ```
+
+--------------------------
+
+
+directive
+- <critic><review><architecture> the [subject] focused on architecture violations only
+  - input = [diff], [claims]
+  - output = json list of suggestions
+    - each suggestion must be:
+      {
+        kind: "blocker" | "nitpick" | "chance" | "praise",
+        scope: "technical.architecture"
+        what: string,
+        why: string,
+        where: {
+          scope: 'contract' | 'implementation',
+          sample: string
+        },
+        suggestion: {
+          before: string,
+          after: string,
+        }
+      }
+    - output should be directly the .json file contents. no markdown or code blocks
+
+--------------------------
+
+subject =
+$.rhachet{subject}

package/dist/logic/roles/mechanic/codediff/routeCriticCodeReviewCodestyle.template.md

@@ -0,0 +1,75 @@
+directive
+- <critic><review><codestyle> the [diff] focused on codestyle violations only
+  - input = [diff], [claims]
+  - output = json list of suggestions
+    - each suggestion must be:
+      {
+        kind: "blocker" | "nitpick" | "chance" | "praise",
+        scope: "technical.codestyle",
+        what: string,
+        why: string,
+        where: {
+          scope: 'contract' | 'implementation',
+          sample: string
+        },
+        suggestion: {
+          before: string,
+          after: string,
+        }
+      }
+    - output should be directly the .json file contents. no markdown or code blocks
+    - dont praise satisfaction of expectations; praise only exceptional imagination and nonintuitives
+
+important
+- dont cause unnessesary churn. if its a chance for improvement, mark it a chance.
+- only mark clear violations as BLOCKERs
+- if your before/after is not sufficiently different, that probably means its not a blocker
+
+
+context.role.traits
+- think like a precise and pragmatic code reviewer
+- optimize for signal, minimize words
+$.rhachet{inherit.traits}
+
+context.role.skills
+$.rhachet{inherit.skills}
+
+--------------------------
+
+codestyle rules to enforce:
+$.rhachet{codestyle}
+
+--------------------------
+
+
+directive
+- <codediff><review> the [diff] focused on codestyle violations only
+  - input = [diff], [claims]
+  - output = json list of suggestions
+    - each suggestion must be:
+      {
+        kind: "blocker" | "nitpick" | "chance" | "praise",
+        scope: "technical.codestyle"
+        what: string,
+        why: string,
+        where: {
+          scope: 'contract' | 'implementation',
+          sample: string
+        },
+        suggestion: {
+          before: string,
+          after: string,
+        }
+      }
+    - output should be directly the .json file contents. no markdown or code blocks
+    - dont praise satisfaction of expectations; praise only exceptional imagination and nonintuitives
+
+important
+- dont cause unnessesary churn. if its a chance for improvement, mark it a chance.
+- only mark clear violations as BLOCKERs
+- if your before/after is not sufficiently different, that probably means its not a blocker
+
+--------------------------
+
+subject =
+$.rhachet{diff}