rhachet-roles-bhrain 0.3.0 → 0.5.2

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

@@ -0,0 +1,27 @@
+import { type GStitcher, type RoleContext, type Threads } from 'rhachet';
+import type { Artifact } from 'rhachet-artifact';
+import type { GitFile } from 'rhachet-artifact-git';
+import type { BrainArch1Actor } from '../../../../domain.objects/BrainArch1/BrainArch1Actor';
+import type { BrainArch1Context } from '../../../../domain.objects/BrainArch1/BrainArch1Context';
+/**
+ * .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 = executes agentic task completion via brain invocation
+ * .why = enables llm with tools to autonomously complete tasks
+ */
+export declare const stepAct: import("rhachet").Stitcher<StitcherAct>;

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

@@ -0,0 +1,95 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stepAct = void 0;
+const fs = __importStar(require("fs/promises"));
+const rhachet_1 = require("rhachet");
+const invokeBrainArch1_1 = require("../../../../domain.operations/brain.replic.arch1/core/invokeBrainArch1");
+/**
+ * .what = step to invoke brain and persist results
+ * .why = core step for agentic task completion
+ */
+const stepInvokeBrain = new rhachet_1.StitchStepCompute({
+    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 (0, invokeBrainArch1_1.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
+ */
+exports.stepAct = (0, rhachet_1.asStitcherFlat)((0, rhachet_1.genStitchRoute)({
+    slug: '@[brain]<act>',
+    readme: '@[brain]<act> -> agentic task completion',
+    sequence: [stepInvokeBrain],
+}));
+//# sourceMappingURL=stepAct.js.map

package/dist/roles/brain/skills/act/stepAct.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stepAct.js","sourceRoot":"","sources":["../../../../../src/roles/brain/skills/act/stepAct.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,gDAAkC;AAClC,qCAOiB;AAMjB,sGAAmG;AA6BnG;;;GAGG;AACH,MAAM,eAAe,GAAG,IAAI,2BAAiB,CAAc;IACzD,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,iDAAiD;IACzD,IAAI,EAAE,eAAe;IACrB,QAAQ,EAAE,OAAO;IACjB,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,EAAE;QACrC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;QAElC,yCAAyC;QACzC,IAAI,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC;QAC/D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,gBAAgB,EAAE,CAAC;YACzC,YAAY,GAAG,MAAM,EAAE,CAAC,QAAQ,CAC9B,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,gBAAgB,EACpC,OAAO,CACR,CAAC;QACJ,CAAC;QAED,mBAAmB;QACnB,MAAM,MAAM,GAAG,MAAM,IAAA,mCAAgB,EACnC;YACE,KAAK,EAAE;gBACL,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK;gBAC5B,IAAI,EAAE;oBACJ,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI;oBACjC,YAAY;iBACb;aACF;YACD,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG;SACpC,EACD,OAAO,CACR,CAAC;QAEF,kCAAkC;QAClC,MAAM,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC;YACxC,OAAO,EAAE,MAAM,CAAC,aAAa,IAAI,EAAE;SACpC,CAAC,CAAC;QAEH,sCAAsC;QACtC,MAAM,UAAU,GAAG;YACjB,2BAA2B;YAC3B,EAAE;YACF,YAAY;YACZ,kBAAkB,MAAM,CAAC,iBAAiB,EAAE;YAC5C,iBAAiB,MAAM,CAAC,cAAc,EAAE;YACxC,aAAa,MAAM,CAAC,eAAe,CAAC,WAAW,EAAE;YACjD,EAAE;YACF,mBAAmB;YACnB,KAAK;YACL,MAAM,CAAC,aAAa,IAAI,eAAe;YACvC,KAAK;YACL,EAAE;YACF,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE;SAChD;aACE,MAAM,CAAC,OAAO,CAAC;aACf,IAAI,CAAC,IAAI,CAAC,CAAC;QAEd,MAAM,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC;QAEhE,OAAO;YACL,KAAK,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE;YACxC,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,aAAa,IAAI,EAAE,EAAE;SAChD,CAAC;IACJ,CAAC;CACF,CAAC,CAAC;AAEH;;;GAGG;AACU,QAAA,OAAO,GAAG,IAAA,wBAAc,EACnC,IAAA,wBAAc,EAAC;IACb,IAAI,EAAE,eAAe;IACrB,MAAM,EAAE,0CAA0C;IAClD,QAAQ,EAAE,CAAC,eAAe,CAAC;CAC5B,CAAC,CACH,CAAC"}

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