rhachet-roles-bhrain 0.3.0 → 0.5.1

package/dist/roles/brain/skills/act/stepAct.ts

@@ -0,0 +1,123 @@
+import * as fs from 'fs/promises';
+import {
+  asStitcherFlat,
+  type GStitcher,
+  genStitchRoute,
+  type RoleContext,
+  StitchStepCompute,
+  type Threads,
+} from 'rhachet';
+import type { Artifact } from 'rhachet-artifact';
+import type { GitFile } from 'rhachet-artifact-git';
+
+import type { BrainArch1Actor } from '@src/domain.objects/BrainArch1/BrainArch1Actor';
+import type { BrainArch1Context } from '@src/domain.objects/BrainArch1/BrainArch1Context';
+import { invokeBrainArch1 } from '@src/domain.operations/brain.replic.arch1/core/invokeBrainArch1';
+
+/**
+ * .what = stitcher type for the act skill
+ * .why = defines the input/output contract for agentic task completion
+ */
+export type StitcherAct = GStitcher<
+  Threads<{
+    caller: RoleContext<
+      'caller',
+      {
+        ask: string;
+        art: {
+          result: Artifact<typeof GitFile>;
+          log: Artifact<typeof GitFile>;
+        };
+      }
+    >;
+    brain: RoleContext<
+      'brain',
+      {
+        actor: BrainArch1Actor;
+        systemPromptPath: string | null;
+      }
+    >;
+  }>,
+  BrainArch1Context & GStitcher['context']
+>;
+
+/**
+ * .what = step to invoke brain and persist results
+ * .why = core step for agentic task completion
+ */
+const stepInvokeBrain = new StitchStepCompute<StitcherAct>({
+  form: 'COMPUTE',
+  readme: 'invokes brain agentic loop and persists results',
+  slug: '@[brain]<act>',
+  stitchee: 'brain',
+  invoke: async ({ threads }, context) => {
+    const { caller, brain } = threads;
+
+    // load custom system prompt if specified
+    let systemPrompt = brain.context.stash.actor.role.systemPrompt;
+    if (brain.context.stash.systemPromptPath) {
+      systemPrompt = await fs.readFile(
+        brain.context.stash.systemPromptPath,
+        'utf-8',
+      );
+    }
+
+    // invoke the brain
+    const result = await invokeBrainArch1(
+      {
+        actor: {
+          ...brain.context.stash.actor,
+          role: {
+            ...brain.context.stash.actor.role,
+            systemPrompt,
+          },
+        },
+        userInput: caller.context.stash.ask,
+      },
+      context,
+    );
+
+    // write result to output artifact
+    await caller.context.stash.art.result.set({
+      content: result.finalResponse ?? '',
+    });
+
+    // write execution log to log artifact
+    const logContent = [
+      `# brain act execution log`,
+      '',
+      `## summary`,
+      `- termination: ${result.terminationReason}`,
+      `- iterations: ${result.iterationCount}`,
+      `- tokens: ${result.totalTokenUsage.totalTokens}`,
+      '',
+      `## final response`,
+      '```',
+      result.finalResponse ?? '(no response)',
+      '```',
+      '',
+      result.error ? `## error\n${result.error}` : '',
+    ]
+      .filter(Boolean)
+      .join('\n');
+
+    await caller.context.stash.art.log.set({ content: logContent });
+
+    return {
+      input: { ask: caller.context.stash.ask },
+      output: { content: result.finalResponse ?? '' },
+    };
+  },
+});
+
+/**
+ * .what = executes agentic task completion via brain invocation
+ * .why = enables llm with tools to autonomously complete tasks
+ */
+export const stepAct = asStitcherFlat<StitcherAct>(
+  genStitchRoute({
+    slug: '@[brain]<act>',
+    readme: '@[brain]<act> -> agentic task completion',
+    sequence: [stepInvokeBrain],
+  }),
+);

package/dist/roles/getRoleRegistry.js

@@ -2,9 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getRoleRegistry = void 0;
 const rhachet_1 = require("rhachet");
-const getRoleRegistry_readme_1 = require("./getRoleRegistry.readme");
-const getReviewerRole_1 = require("./reviewer/getReviewerRole");
-const getThinkerRole_1 = require("./thinker/getThinkerRole");
+const getBrainRole_1 = require("../roles/brain/getBrainRole");
+const getRoleRegistry_readme_1 = require("../roles/getRoleRegistry.readme");
+const getReviewerRole_1 = require("../roles/reviewer/getReviewerRole");
+const getThinkerRole_1 = require("../roles/thinker/getThinkerRole");
 /**
  * .what = returns the core registry of predefined roles and skills
  * .why =
@@ -14,7 +15,7 @@ const getThinkerRole_1 = require("./thinker/getThinkerRole");
 const getRoleRegistry = () => new rhachet_1.RoleRegistry({
     slug: 'bhrain',
     readme: getRoleRegistry_readme_1.BHRAIN_REGISTRY_README,
-    roles: [getThinkerRole_1.ROLE_THINKER, getReviewerRole_1.ROLE_REVIEWER],
+    roles: [getThinkerRole_1.ROLE_THINKER, getReviewerRole_1.ROLE_REVIEWER, getBrainRole_1.ROLE_BRAIN],
 });
 exports.getRoleRegistry = getRoleRegistry;
 //# sourceMappingURL=getRoleRegistry.js.map

package/dist/roles/getRoleRegistry.js.map

@@ -1 +1 @@
-{"version":3,"file":"getRoleRegistry.js","sourceRoot":"","sources":["../../src/roles/getRoleRegistry.ts"],"names":[],"mappings":";;;AAAA,qCAAuC;AAEvC,qEAAkE;AAClE,gEAA2D;AAC3D,6DAAwD;AAExD;;;;;GAKG;AACI,MAAM,eAAe,GAAG,GAAiB,EAAE,CAChD,IAAI,sBAAY,CAAC;IACf,IAAI,EAAE,QAAQ;IACd,MAAM,EAAE,+CAAsB;IAC9B,KAAK,EAAE,CAAC,6BAAY,EAAE,+BAAa,CAAC;CACrC,CAAC,CAAC;AALQ,QAAA,eAAe,mBAKvB"}
+{"version":3,"file":"getRoleRegistry.js","sourceRoot":"","sources":["../../src/roles/getRoleRegistry.ts"],"names":[],"mappings":";;;AAAA,qCAAuC;AAEvC,gEAA2D;AAC3D,8EAA2E;AAC3E,yEAAoE;AACpE,sEAAiE;AAEjE;;;;;GAKG;AACI,MAAM,eAAe,GAAG,GAAiB,EAAE,CAChD,IAAI,sBAAY,CAAC;IACf,IAAI,EAAE,QAAQ;IACd,MAAM,EAAE,+CAAsB;IAC9B,KAAK,EAAE,CAAC,6BAAY,EAAE,+BAAa,EAAE,yBAAU,CAAC;CACjD,CAAC,CAAC;AALQ,QAAA,eAAe,mBAKvB"}

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

@@ -0,0 +1,41 @@
+# rules
+
+## .what
+
+rules are materialized feedback patterns that encode best practices and quality standards for a domain.
+
+each rule represents a generalized insight extracted from real feedback - a distillation of lessons learned from actual experience.
+
+## .why
+
+rules enable consistent quality by making implicit knowledge explicit:
+
+- capture hard-won lessons from feedback cycles
+- prevent repeat mistakes across team members and projects
+- provide a shared vocabulary for discussing quality
+- enable automated review and validation
+
+## .how rules relate to practices
+
+practices organize rules by domain concern. each practice directory contains rules that apply to that domain. rules within the same practice share context and may reference each other.
+
+the specific practice domains vary by project and role - there is no prescribed set of practices.
+
+## .how rules materialize from feedback
+
+feedback flows through a reflection process to become rules:
+
+1. **feedback occurs** - human provides guidance on specific artifact
+2. **pattern emerges** - similar feedback repeats across contexts
+3. **rule crystallizes** - generalized rule extracted from pattern
+4. **citation traces** - each rule links back to origin feedback
+
+this materialization process ensures rules are grounded in real needs, not imagined requirements.
+
+## .note
+
+rules are living documents. as new feedback emerges, rules may be:
+- refined (clarify edge cases)
+- updated (incorporate new insights)
+- deprecated (superseded by better understanding)
+- split (single rule becomes multiple specific rules)

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

@@ -0,0 +1,88 @@
+# rules citations
+
+## .what
+
+citations trace rules back to their origin feedback, providing provenance and context for why each rule exists.
+
+## citation format
+
+citations appear in the `## .citations` section of the `# deets` block:
+
+```md
+## .citations
+
+> exact quote from the feedback that led to this rule
+
+source: https://github.com/org/repo/blob/commit/path/to/feedback.md
+```
+
+## github url format
+
+citation urls must be permanent github links that include:
+
+- organization/owner
+- repository name
+- commit hash or branch
+- full file path
+
+### url pattern
+
+```
+https://github.com/{org}/{repo}/blob/{ref}/{path}
+```
+
+### examples
+
+```md
+source: https://github.com/ehmpathy/declastruct-aws/blob/main/.behavior/v2025_12_05.aws-account-provision/5.1.execution.phase0_to_phaseN.v1.i1.md.%5Bfeedback%5D.v1.%5Bgiven%5D.by_human.md
+
+source: https://github.com/acme/project/blob/abc123/.behavior/v2025_01_01.feature/execution.md.[feedback].v2.[given].by_human.md
+```
+
+## quote inclusion
+
+quotes capture the specific feedback that inspired the rule:
+
+### single quote
+
+```md
+## .citations
+
+> never hide errors in try/catch blocks without explicit handling
+
+source: https://github.com/...
+```
+
+### multiple quotes
+
+when a rule consolidates multiple feedback instances:
+
+```md
+## .citations
+
+> always use named arguments for readability
+
+source: https://github.com/org/repo1/blob/.../feedback.v1.md
+
+---
+
+> positional args are a maintenance nightmare
+
+source: https://github.com/org/repo2/blob/.../feedback.v3.md
+```
+
+## provenance track
+
+citations enable:
+
+- **audit trail** - trace any rule back to real experience
+- **context recovery** - understand the situation that prompted the rule
+- **credibility** - rules grounded in actual feedback, not theory
+- **evolution** - track how rules emerged and refined over time
+
+## .note
+
+- always use the full github url, not relative paths
+- prefer permalinks with commit hashes for immutable references
+- when feedback files are renamed or moved, update citations
+- if origin feedback is deleted, preserve the quote with a note about the removed source

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.