rhachet-roles-bhrain 0.2.0 → 0.5.1

package/dist/roles/reviewer/briefs/on.rules/rules101.collocated.[article].md

@@ -0,0 +1,97 @@
+# rules collocated
+
+## .what
+
+collocated documents are support materials that live alongside rule files, providing examples, references, and educational content.
+
+## collocation pattern
+
+support documents follow the rule file name with a suffix:
+
+```
+rule.$directive.$topic.[suffix].$qualifier.md
+```
+
+- **[suffix]** = document type: `[demo]`, `[ref]`, `[lesson]`
+- **$qualifier** = distinguishing name for multiple documents
+
+## suffix types
+
+### [demo] - examples and demonstrations
+
+concrete examples showing the rule in action:
+
+```
+rule.forbid.error_hiding.[demo].try_catch.md
+rule.prefer.early_returns.[demo].guard_clauses.md
+rule.require.tests.[demo].integration.md
+```
+
+demos typically include:
+- working code samples
+- before/after comparisons
+- annotated walkthroughs
+
+### [ref] - reference materials
+
+supporting documentation and external references:
+
+```
+rule.require.domain_objects.[ref].package.md
+rule.prefer.dependency_injection.[ref].article.md
+rule.forbid.barrel_exports.[ref].circular_deps.md
+```
+
+refs typically include:
+- links to external documentation
+- package usage guides
+- architectural diagrams
+
+### [lesson] - educational content
+
+teaching materials that explain concepts in depth:
+
+```
+rule.require.narrative_flow.[lesson].code_paragraphs.md
+rule.prefer.transformers.[lesson].pipelines_vs_conditionals.md
+rule.require.idempotency.[lesson].findsert_upsert.md
+```
+
+lessons typically include:
+- conceptual explanations
+- mental models
+- learning progressions
+
+## directory layout
+
+collocated documents appear alongside their parent rule:
+
+```
+practices/code.prod/evolvable.procedures/
+├── rule.forbid.positional_args.md
+├── rule.forbid.positional_args.[demo].shell.md
+├── rule.forbid.positional_args.[lesson].named_args.md
+├── rule.require.input_context_pattern.md
+├── rule.require.input_context_pattern.[ref].package.md
+└── rule.require.dependency_injection.md
+```
+
+## .when to collocate
+
+collocate when:
+- a rule benefits from concrete examples
+- external resources clarify the rule
+- deeper explanation aids understanding
+- multiple examples illustrate different aspects
+
+keep separate when:
+- the document applies to multiple rules
+- the content is general reference (put in briefs/knowledge/)
+- the document is too large to be a quick supplement
+
+## .note
+
+- collocated documents inherit context from their parent rule
+- multiple suffixed documents can exist for one rule
+- qualifiers should be descriptive but concise
+- load order: rule first, then demos, refs, lessons

package/dist/roles/reviewer/briefs/on.rules/rules101.content.[article].md

@@ -0,0 +1,228 @@
+# rules content
+
+## .what
+
+rules follow a two-section structure that separates quick reference from detailed guidance.
+
+## two-section structure
+
+every rule has two sections separated by a triple separator:
+
+```md
+# tldr
+
+[quick reference content]
+
+---
+---
+---
+
+# deets
+
+[detailed content]
+```
+
+## # tldr section
+
+the tldr section provides at-a-glance understanding:
+
+### ## severity header
+
+```md
+## severity: blocker
+```
+
+or
+
+```md
+## severity: nitpick
+```
+
+the severity must match the directive:
+- `forbid` / `require` → `blocker`
+- `avoid` / `prefer` → `nitpick`
+
+### .what summary
+
+immediately after severity, state what the rule is:
+
+```md
+## severity: blocker
+
+never use positional arguments in procedure signatures
+
+use named arguments via destructured input objects instead
+```
+
+### .why rationale
+
+explain why this rule matters:
+
+```md
+positional arguments are fragile - adding, removing, or reordering parameters breaks callers.
+named arguments are self-documenting and order-independent.
+```
+
+## # deets section
+
+the deets section provides expanded guidance:
+
+### ## .what (optional)
+
+expanded explanation of what the rule covers.
+
+### ## .why (optional)
+
+deeper rationale, including tradeoffs and edge cases.
+
+### ## severity (required)
+
+repeat the severity and explain why this level was chosen, tying to hazard, time cost, and money cost.
+
+for negative directives (`forbid`/`avoid`), explain the cost of violation:
+
+```md
+## severity: blocker
+
+hidden errors reach production and cost hours to debug, damaging customer trust.
+```
+
+for positive directives (`require`/`prefer`), explain the benefit of compliance:
+
+```md
+## severity: blocker
+
+fail-fast surfaces errors immediately with rich context, cutting debug time from hours to minutes.
+```
+
+### ## .where (optional)
+
+scope or location where this rule applies:
+
+```md
+## .where
+
+- all exported procedures in domain.operations/
+- all public API endpoints
+- exempt: anonymous inline callbacks
+```
+
+### ## .when (optional)
+
+conditions under which the rule applies:
+
+```md
+## .when
+
+- applies when defining function signatures
+- applies when refactoring existing code
+- does not apply to third-party API callbacks
+```
+
+### ## .how (optional)
+
+guidance on detecting violations and applying the rule:
+
+```md
+## .how
+
+search for patterns like:
+- `function foo(a, b, c)`
+- `const bar = (x, y) =>`
+
+refactor to:
+- `const foo = ({ a, b, c }: Input) =>`
+```
+
+### ## .note (optional)
+
+caveats, edge cases, or special considerations:
+
+```md
+## .note
+
+legacy code may still use positional args.
+prioritize new code; refactor legacy opportunistically.
+```
+
+### ## .examples (optional)
+
+concrete positive and negative patterns:
+
+```md
+## .examples
+
+### positive
+
+const setCustomerPhone = ({ customer, phone }: Input) => {
+  return { ...customer, phone };
+};
+
+### negative
+
+function setCustomerPhone(customer, phone) {  // forbidden
+  return { ...customer, phone };
+}
+```
+
+## complete template
+
+```md
+# tldr
+
+## severity: blocker|nitpick
+
+[.what summary - what the rule is]
+
+[.why rationale - why it matters]
+
+---
+---
+---
+
+# deets
+
+## .what
+
+[expanded summary]
+
+## .why
+
+[expanded rationale]
+
+## severity: blocker|nitpick
+
+[for forbid/avoid: cost of violation | for require/prefer: benefit of compliance]
+
+## .where
+
+[scope/location]
+
+## .when
+
+[conditions]
+
+## .how
+
+[detection and usage guidance]
+
+## .note
+
+[caveats]
+
+## .examples
+
+### positive
+
+[correct usage]
+
+### negative
+
+[violation]
+
+## .citations
+
+> [quote from origin feedback]
+
+source: [github url]
+```

package/dist/roles/reviewer/briefs/on.rules/rules101.content.[demo].forbid.failhide.md

@@ -0,0 +1,87 @@
+# tldr
+
+## severity: blocker
+
+never hide errors via blanket try/catch blocks.
+
+hidden errors lead to silent defects and hours of pointless debugging. if an error is thrown, it must be rethrown unless explicitly allowlisted and carefully handled.
+
+---
+---
+---
+
+# deets
+
+## .what
+
+forbid any scenario where real errors are silently swallowed or hidden, commonly via try/catch blocks that catch all errors without rethrowing unexpected ones.
+
+## .why
+
+- hidden errors cause silent defects that are extremely hard to diagnose
+- blanket catch blocks mask the root cause of failures
+- debugging becomes exponentially harder when errors don't surface
+- fail-fast is impossible when errors are swallowed
+
+## severity: blocker
+
+swallowed exceptions cause silent defects that cost hours or days to diagnose and erode customer trust.
+
+## .when
+
+the only acceptable try/catch pattern:
+- the catch has an explicit allowlist of expected errors
+- those specific errors are carefully handled
+- all other errors are rethrown
+
+## .how
+
+search for patterns:
+- `try { ... } catch (e) { }` — empty catch blocks
+- `try { ... } catch (e) { return null; }` — swallowing with fallback
+- `try { ... } catch (e) { console.log(e); }` — logging without rethrowing
+
+## .examples
+
+### positive
+
+```ts
+try {
+  await doSomething({ userUuid });
+} catch (error) {
+  if (!(error instanceof Error)) throw error;
+
+  // only handle specific expected error
+  if (error.message.includes('NOT_FOUND')) {
+    return null; // expected case: resource doesn't exist
+  }
+
+  // rethrow all unexpected errors
+  throw error;
+}
+```
+
+### negative
+
+```ts
+// ⛔ blanket catch hides all errors
+try {
+  await doSomething({ userUuid });
+} catch (error) {
+  console.log('something went wrong');
+  return null;
+}
+```
+
+```ts
+// ⛔ empty catch block
+try {
+  await riskyOperation();
+} catch (e) {
+  // silently swallowed
+}
+```
+
+## .note
+
+this is a mega blocker. any detection of failhide patterns should immediately halt review until resolved.

package/dist/roles/reviewer/briefs/on.rules/rules101.content.[demo].forbid.gerunds.md

@@ -0,0 +1,85 @@
+# tldr
+
+## severity: blocker
+
+never use gerunds like `existing` in variable names.
+
+gerunds signal unclear domain thought. use explicit names like `userBefore`, `userFound`, or `orderCreated` that force clarity about the domain model.
+
+---
+---
+---
+
+# deets
+
+## .what
+
+forbid gerund forms (words ending in `-ing`) in variable names. they signal unclear domain thought.
+
+## .why
+
+- gerunds indicate the domain model was not thought through
+- vague names like `existing` hide temporal state: existing when? before or after?
+- they are a lead indicator of domain model issues that compound downstream
+- explicit names (`userBefore`, `userFound`) force clarity about the domain
+
+## severity: blocker
+
+gerunds signal unclear domain thought. they are a lead indicator of domain model issues that compound into costly refactors.
+
+## .where
+
+- applies to all variable names in business logic
+- especially important in update/upsert flows where before/after state matters
+- applies to domain object references and database query results
+
+## .how
+
+search for patterns:
+- `existing*` — replace with `foundBefore` or `*Before`
+- `running*` — replace with `isActive` or `hasStarted`
+- `pending*` — replace with `needsApproval` or explicit state
+
+common replacements:
+| gerund            | replacement                       |
+| ----------------- | --------------------------------- |
+| `existingUser`    | `userBefore`, `userFound`         |
+| `existingInvoice` | `invoiceBefore`, `invoiceFound`   |
+| `runningProcess`  | `processActive`, `processStarted` |
+
+## .examples
+
+### positive
+
+```ts
+// clear temporal state
+const userBefore = await userDao.findByUuid({ uuid });
+const userAfter = userBefore.clone({ phone: newPhone });
+
+// clear capture point
+const invoiceFound = await invoiceDao.findByRef({ ref });
+if (!invoiceFound) return BadRequestError.throw('invoice not found');
+
+// clear lifecycle state
+const orderCreated = await orderDao.insert({ order });
+```
+
+### negative
+
+```ts
+// ⛔ "existing" is vague
+const existingUser = await userDao.findByUuid({ uuid });
+// existing when? before what operation?
+
+// ⛔ gerund hides state
+const runningJobs = await jobDao.findActive();
+// are these currently running or were they running?
+```
+
+## .note
+
+prefer `[noun][state]` order per the `name:treestruct` tactic:
+- `userFound` not `foundUser`
+- `invoiceBefore` not `beforeInvoice`
+
+this enables autocomplete groups by domain noun.

package/dist/roles/reviewer/briefs/on.rules/rules101.content.[demo].require.failfast.md

@@ -0,0 +1,73 @@
+# tldr
+
+## severity: blocker
+
+fail fast using early exits and HelpfulError subclasses to reject invalid state or input immediately.
+
+early returns and throws collapse failure paths, eliminate nested branches, and make core logic shine. rich error context via `helpful-errors` makes bugs easier to debug.
+
+---
+---
+---
+
+# deets
+
+## .what
+
+enforce fail-fast logic in all procedures by using guard clauses with early returns or throws.
+
+## .why
+
+- improves readability by collapsing failure paths early
+- eliminates nested branches and lets core logic shine
+- increases safety by clearly documenting and halting on invalid input
+- makes bugs easier to debug with rich context using `helpful-errors`
+
+## severity: blocker
+
+fail-fast surfaces errors immediately with rich context, cutting debug time from hours to minutes.
+
+## .where
+
+- required in all stitched logic, business procedures, and service flows
+- applies to guard checks, validations, and branching paths
+
+## .how
+
+- use early returns or throws for all guard clauses
+- never use `if (...) else` or deep nesting to control flow
+- prefer `UnexpectedCodePathError.throw(...)` for internal invariant violations
+- prefer `BadRequestError.throw(...)` for rejecting invalid input
+- include context objects in all thrown errors to aid debugging
+
+## .examples
+
+### positive
+
+```ts
+// reject if user does not exist
+if (!user) return BadRequestError.throw('user not found', { userUuid });
+
+// halt if state is invalid
+if (!input.customer.phone)
+  UnexpectedCodePathError.throw('customer lacks phone, invalid state', { customer });
+
+// continue with core logic after guards
+const result = await processCustomer(input.customer);
+```
+
+### negative
+
+```ts
+// ⛔ nested branches hide the core logic
+if (user) {
+  if (input.customer.phone) {
+    const result = await processCustomer(input.customer);
+    return result;
+  } else {
+    throw new Error('no phone');
+  }
+} else {
+  throw new Error('no user');
+}
+```

package/dist/roles/reviewer/briefs/on.rules/rules101.structure.[article].md

@@ -0,0 +1,70 @@
+# rules structure
+
+## .what
+
+rules follow a strict file name convention and directory organization that encodes semantics into the file system.
+
+## file name convention
+
+rule files follow the pattern:
+
+```
+rule.$directive.$topic.md
+```
+
+- **rule** = literal prefix identifying the file as a rule
+- **$directive** = severity and action: `forbid`, `avoid`, `prefer`, `require`
+- **$topic** = snake_case description of what the rule addresses
+
+### examples
+
+```
+rule.forbid.positional_args.md
+rule.avoid.gerunds.md
+rule.prefer.early_returns.md
+rule.require.tests.md
+```
+
+## directive taxonomy
+
+directives indicate what action to take and at what severity:
+
+| directive | action           | severity | description             |
+|-----------|------------------|----------|-------------------------|
+| `forbid`  | must not do      | blocker  | violation blocks merge  |
+| `require` | must do          | blocker  | absence blocks merge    |
+| `avoid`   | discouraged      | nitpick  | flag but don't block    |
+| `prefer`  | encouraged       | nitpick  | suggest but don't block |
+
+### severity map
+
+| severity  | directives         | review impact                |
+|-----------|--------------------|-----------------------------|
+| blocker   | forbid, require    | must resolve before merge   |
+| nitpick   | avoid, prefer      | optional to resolve         |
+
+## practices directory structure
+
+rules are organized into practice directories by domain concern. the specific practice domains vary by project and role - there is no prescribed set.
+
+typical patterns include:
+- group by artifact type (e.g., code, docs, config)
+- group by quality dimension (e.g., readability, reliability)
+- group by lifecycle stage (e.g., design, test, deploy)
+
+nested subdirectories further refine the domain:
+
+```
+practices/
+└── $domain/
+    └── $subdomain/
+        ├── rule.$directive.$topic.md
+        └── rule.$directive.$topic.[demo].$qualifier.md
+```
+
+## .note
+
+the directory structure groups related rules, making it easier to:
+- discover rules relevant to a domain
+- maintain consistent naming within a practice
+- navigate rules by concern rather than alphabetically

package/dist/roles/reviewer/briefs/review.tactics.md

@@ -0,0 +1,60 @@
+# review tactics
+
+## purpose
+
+the reviewer role performs automated code review against declared rules, using claude-code as the underlying brain.
+
+## modes
+
+### soft mode
+
+- includes only file paths in the prompt
+- instructs brain to read files directly
+- lower token usage
+- best for: large codebases, exploratory reviews
+
+### hard mode
+
+- includes full file contents in the prompt
+- no additional file reads required
+- higher token usage, faster execution
+- best for: focused reviews, smaller scopes
+
+## mode selection criteria
+
+use `--soft` when:
+- scope is large (>50 files)
+- context window would exceed 60%
+- reviewing for general patterns
+
+use `--hard` when:
+- scope is small (<20 files)
+- precision is critical
+- reviewing specific changes
+
+## context window thresholds
+
+- **60% warning**: emits warning but continues
+- **75% failfast**: throws error with recommendation to reduce scope or use soft mode
+
+## scope combination
+
+targets are the union of `--diffs` and `--paths`:
+- `--diffs uptil-main`: files changed since main branch
+- `--diffs uptil-staged`: only staged files
+- `--paths`: explicit glob patterns
+
+## artifacts
+
+all invocations log to `.log/bhrain/review/$timestamp/`:
+- `input.args.json`: original arguments and computed metrics
+- `input.prompt.md`: exact prompt sent to brain
+- `output.response.json`: raw brain response
+- `output.review.md`: formatted review output
+
+## output format
+
+reviews follow the feedback template format:
+- blockers appear first (severity: blocker)
+- nitpicks appear second (severity: nitpick)
+- each finding includes file path and line number when available

package/dist/roles/reviewer/getReviewerRole.d.ts

@@ -0,0 +1,6 @@
+import { Role } from 'rhachet';
+/**
+ * .what = reviewer role definition
+ * .why = enables code review against declared rules via brain invocation
+ */
+export declare const ROLE_REVIEWER: Role;