rhachet-roles-bhrain 0.3.0 → 0.5.2

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/skills/reflect/reflect.d.ts

@@ -0,0 +1,30 @@
+import type { ReviewerReflectMetrics } from '../../../../domain.objects/Reviewer/ReviewerReflectMetrics';
+/**
+ * .what = result of stepReflect execution
+ * .why = enables caller to inspect reflect outcome and artifacts
+ */
+export type StepReflectResult = {
+    draft: {
+        dir: string;
+        pureDir: string;
+        syncDir: string;
+    };
+    results: {
+        created: number;
+        updated: number;
+        appended: number;
+        omitted: number;
+    };
+    metrics: ReviewerReflectMetrics;
+};
+/**
+ * .what = extracts rules from feedback and proposes them to target
+ * .why = core orchestration flow for reviewer.reflect skill
+ */
+export declare const stepReflect: (input: {
+    source: string;
+    target: string;
+    mode?: 'soft' | 'hard';
+    force?: boolean;
+    rapid?: boolean;
+}) => Promise<StepReflectResult>;