rhachet-roles-ehmpathy 1.15.21 → 1.15.22

package/dist/domain.roles/mechanic/briefs/practices/code.prod/evolvable.domain.operations/define.domain-operation-core-variants.md

@@ -0,0 +1,122 @@
+### .define = domain-operation-core-variants
+
+#### .what
+domain.operations contains two fundamental variants of leaf operations:
+- **compute*** = deterministic computed work (pure functions, no external dependencies)
+- **imagine*** = probabilistic creative work via `context.brain.repl.imagine({ role })`
+
+#### .when
+- most projects only have deterministic operations — no `brain.repl` invocations
+- in these cases, the `compute*` prefix is **not required** (no ambiguity exists)
+- enforcement becomes **mandatory** when a project contains both variants
+- once `imagine*` operations exist in a codebase, `compute*` prefixes become required for clarity
+
+#### .scope
+- the `compute*`/`imagine*` prefix applies only to **leaf operations**
+- leaf operations = the ones that actually perform the computation or imagination
+- **composer operations** that orchestrate leaf operations use normal names (e.g., `getInvoice`, `setCustomerPhone`, `syncUserFromProvider`)
+- the prefix signals *what kind of work is done*, not *what kind of work is called*
+
+#### .why
+when both variants exist in a codebase, the prefix:
+- clarifies the nature of each leaf operation at a glance
+- sets expectations for testability (deterministic vs probabilistic)
+- signals dependency requirements (pure vs requires brain context)
+- enables appropriate error strategies for each type
+- guides code review focus (logic correctness vs prompt quality)
+
+#### .how
+
+##### compute* leaf operations
+- prefix with `compute` (e.g., `computeInvoiceTotal`, `computeHashFromContent`)
+- must be **pure functions** — same input always produces same output
+- **no external dependencies** — no network, no database, no randomness
+- trivially testable with simple input/output assertions
+- can be safely memoized or cached
+
+##### imagine* leaf operations
+- prefix with `imagine` (e.g., `imagineChapterOutline`, `imagineCodeReview`)
+- invoke `context.brain.repl.imagine({ role })` for LLM-powered generation
+- **probabilistic** — same input may produce different valid outputs
+- require snapshot tests or semantic assertions
+- depend on `context.brain` provision
+
+##### composer operations
+- use normal verb prefixes (e.g., `get*`, `set*`, `sync*`, ...)
+- orchestrate one or more leaf operations
+- no special prefix required — their behavior is defined by what they compose
+
+#### .examples
+
+**✅ good — leaf operations with proper prefixes**
+```ts
+// computeInvoiceTotal.ts — leaf, deterministic
+export const computeInvoiceTotal = (input: { lineItems: LineItem[] }) => {
+  return input.lineItems.reduce((sum, item) => sum + item.amount, 0);
+};
+
+// imagineChapterSummary.ts — leaf, probabilistic
+export const imagineChapterSummary = async (
+  input: { chapter: string },
+  context: { brain: Brain },
+) => {
+  return context.brain.repl.imagine({
+    role: 'summarizer',
+    prompt: `summarize this chapter: ${input.chapter}`,
+  });
+};
+```
+
+**✅ good — composer operation with normal name**
+```ts
+// getInvoiceWithSummary.ts — composes both variants
+export const getInvoiceWithSummary = async (
+  input: { invoiceId: string },
+  context: { brain: Brain; invoiceDao: InvoiceDao },
+) => {
+  const invoice = await context.invoiceDao.findById(input.invoiceId);
+  const total = computeInvoiceTotal({ lineItems: invoice.lineItems });
+  const summary = await imagineChapterSummary({ chapter: invoice.notes }, context);
+  return { ...invoice, total, summary };
+};
+```
+
+**⛔ bad — prefix misleads**
+```ts
+// computeResponse.ts — "compute" but actually calls LLM
+export const computeResponse = async (input, context) => {
+  return context.brain.repl.imagine({ ... }); // ⛔ prefix misleads
+};
+```
+
+**⛔ bad — ambiguous leaf name (only when both variants exist)**
+```ts
+// generateTotal.ts — unclear if deterministic or probabilistic
+export const generateTotal = (...) => { ... }
+
+// processChapter.ts — verb doesn't signal operation type
+export const processChapter = (...) => { ... }
+```
+
+#### .enforcement
+- leaf operations that call `context.brain` must use `imagine*` prefix
+- leaf operations prefixed with `compute*` must be pure and deterministic
+- prefix mismatch vs implementation = **BLOCKER**
+- ambiguous leaf names in a codebase with both variants = **BLOCKER**
+
+---
+
+#### .appendix: brain terminology
+
+##### brain.atom
+- the atomic unit of LLM interaction
+- a single LLM API call (e.g., one completion request)
+- stateless, no memory of prior calls
+- e.g., **Claude API** = one `messages.create()` call
+
+##### brain.repl
+- **r**ead, **e**xecute, **p**rint, **l**oop
+- orchestrates `brain.atom` calls within a tooluse loop
+- enables multi-turn reason with tool execution between steps
+- `brain.repl.imagine({ role })` = invoke the repl to imagine/generate via the specified role
+- e.g., **Claude Code** = agentic loop that reads files, executes tools, prints results, loops until done

package/dist/domain.roles/mechanic/inits/init.claude.permissions.jsonc

@@ -196,9 +196,11 @@
       "Bash(npm run test:unit:*)",
       "Bash(npm run test:integration:*)",
       "Bash(npm run test:acceptance:*)",
+      "Bash(npm run test:acceptance:locally:*)",
       "Bash(npm run test:unit -- path/to/file/example.ts)",
       "Bash(npm run test:integration -- path/to/file/example.ts)",
       "Bash(npm run test:acceptance -- path/to/file/example.ts)",
+      "Bash(npm run test:acceptance:locally -- path/to/file/example.ts)",
 
       // thorough test operations
       "Bash(THOROUGH=true npm run test:*)",
@@ -208,14 +210,17 @@
       "Bash(THOROUGH=true npm run test:unit:*)",
       "Bash(THOROUGH=true npm run test:integration:*)",
       "Bash(THOROUGH=true npm run test:acceptance:*)",
+      "Bash(THOROUGH=true npm run test:acceptance:locally:*)",
 
       // resnap test operations
       "Bash(RESNAP=true npm run test:unit:*)",
       "Bash(RESNAP=true npm run test:integration:*)",
       "Bash(RESNAP=true npm run test:acceptance:*)",
+      "Bash(RESNAP=true npm run test:acceptance:locally:*)",
       "Bash(RESNAP=true THOROUGH=true npm run test:unit:*)",
       "Bash(RESNAP=true THOROUGH=true npm run test:integration:*)",
       "Bash(RESNAP=true THOROUGH=true npm run test:acceptance:*)",
+      "Bash(RESNAP=true THOROUGH=true npm run test:acceptance:locally:*)",
 
       // test list operation
       "Bash(npx jest --listTests:*)",

package/package.json

@@ -2,7 +2,7 @@
   "name": "rhachet-roles-ehmpathy",
   "author": "ehmpathy",
   "description": "empathetic software construction roles and skills, via rhachet",
-  "version": "1.15.21",
+  "version": "1.15.22",
   "repository": "ehmpathy/rhachet-roles-ehmpathy",
   "homepage": "https://github.com/ehmpathy/rhachet-roles-ehmpathy",
   "keywords": [
@@ -60,7 +60,7 @@
     "helpful-errors": "1.5.3",
     "inquirer": "12.7.0",
     "openai": "5.8.2",
-    "rhachet": "1.14.1",
+    "rhachet": "1.15.2",
     "rhachet-artifact": "1.0.0",
     "rhachet-artifact-git": "1.1.0",
     "serde-fns": "1.2.0",
@@ -89,6 +89,8 @@
     "husky": "8.0.3",
     "jest": "30.2.0",
     "rhachet": "1.13.11",
+    "rhachet-roles-bhrain": "0.5.1",
+    "rhachet-roles-bhuild": "0.4.0",
     "test-fns": "1.6.0",
     "tsc-alias": "1.8.10",
     "tsx": "4.20.6",

package/readme.md

@@ -1,4 +1,4 @@
-# rhachet-roles-ehmpathy
+# 🐢 rhachet-roles-ehmpathy
 
 ![test](https://github.com/ehmpathy/rhachet-roles-ehmpathy/workflows/test/badge.svg)
 ![publish](https://github.com/ehmpathy/rhachet-roles-ehmpathy/workflows/publish/badge.svg)