rhachet-roles-ehmpathy 1.17.20 → 1.17.22

package/dist/domain.roles/mechanic/briefs/practices/code.test/scope.unit/rule.forbid.remote-boundaries.md

@@ -0,0 +1,153 @@
+# rule.forbid.remote-boundaries
+
+## .what
+
+unit tests must not cross remote boundaries — if a test touches external resources, it is an integration test, not a unit test
+
+## .why
+
+- **unit tests verify atomic logic** — pure functions with injected dependencies
+- **remote boundaries introduce flake** — network timeouts, file locks, db state
+- **remote boundaries introduce latency** — disk i/o, connection overhead, query time
+- **remote boundaries hide in mocks** — mocks create false confidence; the mock behaves differently than reality
+- **test classification matters** — `npm run test:unit` must be fast, deterministic, and parallelizable
+
+## .scope
+
+applies to all files with `.test.ts` extension (unit tests)
+
+does NOT apply to `.integration.test.ts` or `.acceptance.test.ts`
+
+## .remote boundaries
+
+a remote boundary is any resource external to the process memory:
+
+| boundary   | examples                                                      | why it's remote                                    |
+| ---------- | ------------------------------------------------------------- | -------------------------------------------------- |
+| filesystem | `fs.readFile`, `fs.writeFile`, `path.resolve` with real paths | disk i/o, file locks, path differences across os   |
+| database   | `pg.query`, `mysql.execute`, dao calls                        | connection state, query latency, data dependencies |
+| network    | `fetch`, `axios`, http clients, sdk calls                     | latency, availability, rate limits                 |
+
+## .how
+
+### 👍 unit test — pure logic leaf
+
+```ts
+// computeInvoiceTotal.test.ts
+describe('computeInvoiceTotal', () => {
+  it('sums line items correctly', () => {
+    const result = computeInvoiceTotal({
+      lineItems: [
+        { amount: 100 },
+        { amount: 50 },
+      ],
+    });
+    expect(result).toEqual(150);
+  });
+});
+```
+
+### 👍 unit test — dependency injection enables isolation
+
+```ts
+// sendInvoice.test.ts
+describe('sendInvoice', () => {
+  it('returns sent status when email succeeds', async () => {
+    // inject a fake, not a mock of a real service
+    const svcEmailDemo = {
+      send: async () => ({ success: true }),
+    };
+
+    const result = await sendInvoice(
+      { invoice: exampleInvoice }, // input stays pure as always
+      { svcEmail: svcEmailDemo }, // context has remote interfaces injected; makes it clear that _any_ shape that fits this contract is allowed
+    );
+
+    expect(result.sent).toEqual(true);
+  });
+});
+```
+
+### 👎 bad — crosses filesystem boundary
+
+```ts
+// ❌ this is an integration test, not a unit test
+describe('loadConfig', () => {
+  it('reads config from disk', async () => {
+    const config = await loadConfig({ path: './config.json' }); // fs access
+    expect(config.apiKey).toBeDefined();
+  });
+});
+```
+
+### 👎 bad — crosses database boundary
+
+```ts
+// ❌ this is an integration test, not a unit test
+describe('getUserById', () => {
+  it('fetches user from database', async () => {
+    const user = await getUserById({ id: '123' }, { dbConnection }); // db access
+    expect(user.name).toEqual('alice');
+  });
+});
+```
+
+### 👎 bad — mocks hide the boundary (antipattern)
+
+```ts
+// ❌ mocks are an antipattern — they create false confidence
+jest.mock('fs');
+const fs = require('fs');
+
+describe('loadConfig', () => {
+  it('reads config', async () => {
+    fs.readFile.mockResolvedValue('{"key": "value"}');
+    const config = await loadConfig({ path: './config.json' });
+    expect(config.key).toEqual('value');
+    // 👎 this test passes but real fs.readFile behaves differently
+    // 👎 the mock doesn't validate encode, error handler, path resolution
+  });
+});
+```
+
+## .what to do instead
+
+| if your test needs... | then...                        |
+| --------------------- | ------------------------------ |
+| filesystem access     | move to `.integration.test.ts` |
+| database queries      | move to `.integration.test.ts` |
+| network calls         | move to `.integration.test.ts` |
+
+## .the mock antipattern
+
+mocks are forbidden because:
+
+1. **mocks lie** — they return what you tell them, not what the real dependency returns
+2. **mocks drift** — when the real dependency changes, the mock doesn't
+3. **mocks hide bugs** — the test passes but production fails
+4. **mocks test the mock** — you verify your mock setup, not your logic
+
+### instead of mocks, use:
+
+- **fakes** — simplified implementations that behave like the real dependency
+- **dependency injection** — pass the dependency as a parameter
+- **integration tests** — test the real dependency in `.integration.test.ts`
+
+## .classification guide
+
+| test characteristics                   | classification | file extension         |
+| -------------------------------------- | -------------- | ---------------------- |
+| pure logic, no i/o, injected deps      | unit           | `.test.ts`             |
+| touches db, fs, network                | integration    | `.integration.test.ts` |
+| blackbox via built artifact's contract | acceptance     | `.acceptance.test.ts`  |
+
+## .enforcement
+
+unit test that crosses remote boundary = **BLOCKER**
+
+mock usage in unit tests = **BLOCKER**
+
+---
+
+> unit tests are fast, deterministic, and test logic in isolation.
+> if it touches the outside world, it's not a unit test.

package/dist/domain.roles/mechanic/briefs/practices/lang.tones/rule.forbid.buzzwords.md

@@ -0,0 +1,49 @@
+### .rule = forbid-buzzwords
+
+#### .what
+buzzwords must be avoided — they obscure intent
+
+#### .scope
+- code: variable names, function names, type names, comments
+- docs: markdown, briefs, prompts, commit messages
+- comms: pr descriptions, reviews, discussions
+
+#### .why
+buzzwords have **large gravity** — they pull the mind toward them
+
+this gravity causes **semantic diffusion**:
+- the word feels meaningful, so thought stops
+- precision erodes because the term is overloaded
+- ambiguity creeps in because everyone maps it to their own interpretation
+- communication degrades because we think we agree when we don't
+
+it's a smell. flies buzz around smells. we don't like smells -> we dont like buzz.
+
+#### .instead
+think from the core. build the concept from the ground up.
+
+find the most appropriate non-buzz word:
+- what specifically do you mean?
+- what is the precise action, object, or attribute?
+- what word captures exactly this, with no surplus baggage?
+
+precision > familiarity. clarity > trendiness.
+
+#### .enforcement
+buzzwords = **BLOCKER** on first encounter. if retry with justification, allow.
+
+#### .the test
+if you remove the buzzword and the sentence still makes sense — you didn't need it.
+if you replace it with a concrete term and meaning is preserved — use the concrete term.
+if you can't replace it with anything concrete — you don't know what you mean yet.
+
+#### .note: context matters
+some terms are buzzwords in one context but precise in another:
+- `scalable` in marketing = buzz
+- `scalable` in distributed systems with defined semantics = maybe ok (but still prefer specifics)
+
+when in doubt, be more specific.
+
+#### .see also
+- `rule.prefer.lowercase` — no shouts
+- `rule.require.ubiqlang` — consistent terminology

package/package.json

@@ -2,7 +2,7 @@
   "name": "rhachet-roles-ehmpathy",
   "author": "ehmpathy",
   "description": "empathetic software construction roles and skills, via rhachet",
-  "version": "1.17.20",
+  "version": "1.17.22",
   "repository": "ehmpathy/rhachet-roles-ehmpathy",
   "homepage": "https://github.com/ehmpathy/rhachet-roles-ehmpathy",
   "keywords": [
@@ -52,7 +52,7 @@
     "prepare:husky": "husky install && chmod ug+x .husky/*",
     "prepare": "if [ -e .git ] && [ -z $CI ]; then npm run prepare:husky && npm run prepare:rhachet; fi",
     "test:format:biome": "biome format",
-    "prepare:rhachet": "rhachet init && rhachet roles link --role mechanic && rhachet roles init --role mechanic && rhachet roles link --role behaver && rhachet roles init --role behaver"
+    "prepare:rhachet": "rhachet init --roles behaver mechanic reviewer"
   },
   "dependencies": {
     "@ehmpathy/as-command": "1.0.3",
@@ -92,10 +92,10 @@
     "esbuild-register": "3.6.0",
     "husky": "8.0.3",
     "jest": "30.2.0",
-    "rhachet": "1.22.0",
-    "rhachet-roles-bhrain": "0.5.9",
-    "rhachet-roles-bhuild": "0.6.4",
-    "rhachet-roles-ehmpathy": "link:.",
+    "rhachet": "1.22.7",
+    "rhachet-roles-bhrain": "0.5.11",
+    "rhachet-roles-bhuild": "0.6.6",
+    "rhachet-roles-ehmpathy": "1.17.20",
     "test-fns": "1.6.0",
     "tsc-alias": "1.8.10",
     "tsx": "4.20.6",