rhachet-roles-bhrain 0.2.0 → 0.5.1

package/dist/roles/thinker/skills/khue.triage/stepTriage.skill.ts

@@ -0,0 +1,174 @@
+import { enrollThread, genRoleSkill } from 'rhachet';
+import { genArtifactGitFile, getArtifactObsDir } from 'rhachet-artifact-git';
+
+import { genContextLogTrail } from '@src/.test/genContextLogTrail';
+import { genContextStitchTrail } from '@src/.test/genContextStitchTrail';
+import { getContextOpenAI } from '@src/.test/getContextOpenAI';
+
+import { BRIEFS_FOR_TRIAGE, loopTriage } from './stepTriage';
+
+export const SKILL_TRIAGE = genRoleSkill({
+  slug: 'triage',
+  route: loopTriage,
+  threads: {
+    lookup: {
+      output: {
+        source: 'process.argv',
+        char: 'o',
+        desc: 'the output file to write against',
+        type: 'string',
+      },
+      input: {
+        source: 'process.argv',
+        char: 'i',
+        desc: 'the input file to seed from',
+        type: 'string',
+      },
+      goal: {
+        source: 'process.argv',
+        char: 'g',
+        desc: 'the goal of the request',
+        type: '?string',
+      },
+      references: {
+        source: 'process.argv',
+        char: 'f',
+        desc: 'reference files to to use, if any; delimit with commas',
+        type: '?string',
+      },
+      briefs: {
+        source: 'process.argv',
+        char: 'b',
+        desc: 'brief files to to use, if any; delimit with commas',
+        type: '?string',
+      },
+    },
+    assess: (
+      input,
+    ): input is {
+      output: string;
+      input: string;
+      goal: string;
+      references: string;
+      briefs: string;
+      ask: string;
+    } => typeof input.output === 'string',
+    instantiate: async (input: {
+      output: string;
+      input: string;
+      goal: string;
+      references: string;
+      briefs: string;
+      ask: string;
+    }) => {
+      // declare where all the artifacts will be found
+      const obsDir = getArtifactObsDir({ uri: input.output });
+      const artifacts = {
+        goal: {
+          concept: genArtifactGitFile(
+            { uri: obsDir + '.goal.concept.md' },
+            { versions: true },
+          ),
+          context: genArtifactGitFile(
+            { uri: obsDir + '.goal.context.md' },
+            { versions: true },
+          ),
+        },
+        feedback: genArtifactGitFile(
+          { uri: obsDir + '.feedback.md' },
+          { versions: true },
+        ),
+        'focus.context': genArtifactGitFile(
+          { uri: obsDir + '.focus.context.md' },
+          { versions: true },
+        ),
+        'focus.concept': genArtifactGitFile(
+          { uri: input.output },
+          { versions: true },
+        ),
+        input: genArtifactGitFile({ uri: input.input }, { versions: true }),
+        references:
+          input.references
+            ?.split(',')
+            .filter((uri) => !!uri)
+            .map((reference) =>
+              genArtifactGitFile({ uri: reference }, { access: 'readonly' }),
+            ) ?? [],
+        briefs:
+          input.briefs
+            ?.split(',')
+            .filter((uri) => !!uri)
+            .map((brief) =>
+              genArtifactGitFile({ uri: brief }, { access: 'readonly' }),
+            ) ?? [],
+      };
+
+      // detect the goal of the caller
+      const goalConcept: string = await (async () => {
+        // if goal explicitly defined, use it
+        if (input.goal)
+          return (
+            (
+              await genArtifactGitFile(
+                { uri: input.goal },
+                { access: 'readonly' },
+              ).get()
+            )?.content ?? input.ask
+          );
+
+        // otherwise, assume its the ask
+        return input.ask;
+      })();
+      await artifacts.goal.concept.set({ content: goalConcept });
+
+      return {
+        caller: await enrollThread({
+          role: 'caller',
+          stash: {
+            ask: '',
+            art: {
+              'foci.goal.concept': artifacts.goal.concept,
+              'foci.goal.context': artifacts.goal.context,
+              'foci.input.concept': artifacts.input,
+              feedback: artifacts.feedback,
+            },
+            refs: artifacts.references,
+          },
+        }),
+        thinker: await enrollThread({
+          role: 'thinker',
+          stash: {
+            art: {
+              'focus.context': artifacts['focus.context'],
+              'focus.concept': artifacts['focus.concept'],
+            },
+            briefs: [
+              ...artifacts.briefs,
+              ...BRIEFS_FOR_TRIAGE, // flow the triage briefs down so that <ponder> has them in context too; this approach does cause duplicate briefs for triage, but thats no biggie
+            ],
+          },
+        }),
+      };
+    },
+  },
+  context: {
+    lookup: {
+      apiKeyOpenai: {
+        source: 'process.env',
+        envar: 'OPENAI_API_KEY',
+        desc: 'the openai key to use',
+        type: 'string',
+      },
+    },
+    assess: (input): input is { apiKeyOpenai: string } =>
+      typeof input.apiKeyOpenai === 'string',
+    instantiate: () => {
+      return {
+        ...getContextOpenAI(),
+        ...genContextLogTrail(),
+        ...genContextStitchTrail(),
+      };
+    },
+  },
+  readme: '',
+});

package/dist/roles/thinker/skills/khue.triage/stepTriage.ts

@@ -0,0 +1,153 @@
+import { UnexpectedCodePathError } from 'helpful-errors';
+import {
+  asStitcherFlat,
+  type GStitcher,
+  genStepImagineViaTemplate,
+  genStitchRoute,
+  genTemplate,
+  getTemplatePathByCallerPath,
+  getTemplateValFromArtifacts,
+  getTemplateVarsFromRoleInherit,
+  type RoleContext,
+  type Threads,
+} from 'rhachet';
+import type { Artifact } from 'rhachet-artifact';
+import type { GitFile } from 'rhachet-artifact-git';
+import { withRetry, withTimeout } from 'wrapper-fns';
+
+import type { Focus } from '@src/_topublish/rhachet-roles-bhrain/src/domain/objects/Focus';
+import { type ContextOpenAI, sdkOpenAi } from '@src/access/sdk/sdkOpenAi';
+import { genLoopFeedback } from '@src/domain.operations/artifact/genLoopFeedback';
+import { genStepArtSet } from '@src/domain.operations/artifact/genStepArtSet';
+import { getThinkerBriefs } from '@src/roles/thinker/getThinkerBrief';
+
+// exported so that we can pass them through to <ponder> too
+export const BRIEFS_FOR_TRIAGE = getThinkerBriefs([
+  'trait.ocd.md',
+  'cognition/cog401.questions.._.md',
+  'cognition/cog000.overview.and.premise.md',
+  'cognition/cog101.concept.treestruct._.md',
+  'cognition/cog201.cortal.focus.p1.definition.md',
+  'cognition/cog301.traversal.1.motion.primitives._.md',
+  'cognition/cog401.questions.._.md',
+  'cognition/cog401.questions.2.1.primitives.rough._.md',
+  'librarian.tactics/<articulate>._.[article].frame.cognitive.md', // todo: keep or remove
+  'librarian.tactics/<articulate>._.[article].frame.tactical.md',
+  'cognition/cog201.cortal.focus.p2.breadth.md',
+  'cognition/cog301.traversal.1.motion.primitives.breadth.md',
+  'cognition/cog301.traversal.1.motion.primitives.breadth.vary.md',
+  'thinker.tactics/<triage>._.[article].frame.tactical.md',
+  'thinker.tactics/<triage>.persp.implicit_question.[article].md',
+  'thinker.tactics/<triage>.persp.grades_from_context.[article].md',
+  'librarian.tactics/[brief].verbiage.outline.over.narrative.md',
+]);
+
+type StitcherDesired = GStitcher<
+  Threads<{
+    caller: RoleContext<
+      'caller',
+      {
+        art: {
+          feedback: Artifact<typeof GitFile>;
+          'foci.goal.concept': Focus['concept'];
+          'foci.goal.context': Focus['context'];
+          'foci.input.concept': Focus['concept'];
+        };
+        refs: Artifact<typeof GitFile>[];
+      }
+    >;
+    thinker: RoleContext<
+      'thinker',
+      {
+        art: {
+          'focus.concept': Focus['concept'];
+          'focus.context': Focus['context'];
+        };
+        briefs: Artifact<typeof GitFile>[];
+      }
+    >;
+  }>,
+  ContextOpenAI & GStitcher['context'],
+  { content: string }
+>;
+
+const template = genTemplate<StitcherDesired['threads']>({
+  ref: { uri: getTemplatePathByCallerPath({ auto: true }) },
+  getVariables: async ({ threads }) => ({
+    ...(await getTemplateVarsFromRoleInherit({ thread: threads.thinker })),
+
+    guide: {
+      goal:
+        (await threads.caller.context.stash.art['foci.goal.concept'].get())
+          ?.content ||
+        UnexpectedCodePathError.throw('goal not declared', {
+          art: threads.caller.context.stash.art['foci.goal.concept'],
+        }),
+      feedback:
+        (await threads.caller.context.stash.art.feedback.get())?.content || '',
+    },
+
+    focus: {
+      context:
+        (await threads.thinker.context.stash.art['focus.context'].get())
+          ?.content ||
+        (await threads.caller.context.stash.art['foci.goal.context'].get()) // fallback to @[caller].focus[goal].context
+          ?.content ||
+        '',
+      concept:
+        (await threads.thinker.context.stash.art['focus.concept'].get())
+          ?.content || '',
+    },
+
+    seed: {
+      concepts:
+        (await threads.caller.context.stash.art['foci.input.concept'].get())
+          ?.content ||
+        UnexpectedCodePathError.throw('input not declared', {
+          art: threads.caller.context.stash.art['foci.input.concept'],
+        }),
+    },
+
+    skill: {
+      briefs: await getTemplateValFromArtifacts({
+        artifacts: [
+          ...BRIEFS_FOR_TRIAGE,
+          ...threads.thinker.context.stash.briefs,
+        ],
+      }),
+    },
+
+    references: await getTemplateValFromArtifacts({
+      artifacts: threads.caller.context.stash.refs,
+    }),
+  }),
+});
+
+const stepImagine = genStepImagineViaTemplate<StitcherDesired>({
+  slug: '@[thinker]<triage>',
+  stitchee: 'thinker',
+  readme: '',
+  template,
+  imagine: withRetry(
+    withTimeout(sdkOpenAi.imagine, { threshold: { seconds: 60 } }), // allow up to 60 sec, for longer files
+  ),
+});
+
+const stepPersist = genStepArtSet({
+  stitchee: 'thinker',
+  artee: 'focus.concept',
+});
+
+export const stepTriage = asStitcherFlat<StitcherDesired>(
+  genStitchRoute({
+    slug: '@[thinker]<triage>',
+    readme: '@[thinker]<triage> -> [article]',
+    sequence: [stepImagine, stepPersist],
+  }),
+);
+
+export const loopTriage = genLoopFeedback({
+  stitchee: 'thinker',
+  artee: 'focus.concept',
+  repeatee: stepTriage,
+});

package/package.json

@@ -2,7 +2,7 @@
   "name": "rhachet-roles-bhrain",
   "author": "ehmpathy",
   "description": "reliable thought concept navigation roles, briefs, and skills, via rhachet",
-  "version": "0.2.0",
+  "version": "0.5.1",
   "repository": "ehmpathy/rhachet-roles-bhrain",
   "homepage": "https://github.com/ehmpathy/rhachet-roles-bhrain",
   "keywords": [
@@ -25,20 +25,19 @@
     "fix:format": "npm run fix:format:biome",
     "fix:lint": "biome check --write",
     "fix": "npm run fix:format && npm run fix:lint",
-    "build:clean": "rm dist/ -rf",
+    "build:clean": "chmod -R u+w dist 2>/dev/null; rm -rf dist/",
     "build:compile": "tsc -p ./tsconfig.build.json && tsc-alias -p ./tsconfig.build.json",
-    "build:complete": "rsync -a --prune-empty-dirs --include='*/' --exclude='**/.route/**' --exclude='**/.scratch/**' --exclude='**/.behavior/**' --exclude='**/*.test.sh' --include='**/*.template.md' --include='**/briefs/**/*.md' --include='**/briefs/*.md' --include='**/skills/**/*.sh' --include='**/skills/*.sh' --include='**/skills/**/*.jsonc' --include='**/skills/*.jsonc' --exclude='*' src/ dist/",
+    "build:complete": "rsync -a --prune-empty-dirs --exclude='.test' --exclude='.route' --exclude='.scratch' --exclude='.behavior' --exclude='*.test.*' --include='*/' --include='briefs/**' --include='skills/**' --exclude='*' src/ dist/",
     "build": "npm run build:clean && npm run build:compile && npm run build:complete --if-present",
     "test:commits": "LAST_TAG=$(git describe --tags --abbrev=0 @^ 2> /dev/null || git rev-list --max-parents=0 HEAD) && npx commitlint --from $LAST_TAG --to HEAD --verbose",
     "test:types": "tsc -p ./tsconfig.json --noEmit",
     "test:format": "npm run test:format:biome",
     "test:lint:deps": "npx depcheck -c ./.depcheckrc.yml",
-    "test:integration:hold": "jest -c ./jest.integration.config.ts --forceExit --verbose --passWithNoTests $([ -z $THOROUGH ] && echo '--changedSince=main')",
     "test:lint:biome": "biome check --diagnostic-level=error",
     "test:lint:biome:all": "biome check",
     "test:lint": "npm run test:lint:biome && npm run test:lint:deps",
     "test:unit": "jest -c ./jest.unit.config.ts --forceExit --verbose --passWithNoTests $([ -z $THOROUGH ] && echo '--changedSince=main') $([ -n $RESNAP ] && echo '--updateSnapshot')",
-    "test:integration": "echo 'todo: release'",
+    "test:integration": "jest -c ./jest.integration.config.ts --forceExit --verbose --passWithNoTests $([ -z $THOROUGH ] && echo '--changedSince=main') $([ -n $RESNAP ] && echo '--updateSnapshot')",
     "test:acceptance:locally": "npm run build && LOCALLY=true jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ -n $RESNAP ] && echo '--updateSnapshot')",
     "test": "npm run test:commits && npm run test:types && npm run test:format && npm run test:lint && npm run test:unit && npm run test:integration && npm run test:acceptance:locally",
     "test:acceptance": "npm run build && jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ -n $RESNAP ] && echo '--updateSnapshot')",
@@ -52,6 +51,7 @@
     "prepare:rhachet": "rhachet init && rhachet roles link --role mechanic && rhachet roles link --role behaver && rhachet roles init --role mechanic"
   },
   "dependencies": {
+    "@anthropic-ai/sdk": "0.51.0",
     "@ehmpathy/as-command": "1.0.3",
     "@ehmpathy/uni-time": "1.8.1",
     "as-procedure": "1.1.7",
@@ -67,9 +67,12 @@
     "simple-in-memory-cache": "0.4.0",
     "type-fns": "1.21.0",
     "with-simple-caching": "0.14.2",
-    "wrapper-fns": "1.1.0"
+    "wrapper-fns": "1.1.0",
+    "zod": "3.25.76",
+    "zod-to-json-schema": "3.25.0"
   },
   "devDependencies": {
+    "@anthropic-ai/claude-code": "2.0.76",
     "@biomejs/biome": "2.3.8",
     "@commitlint/cli": "19.5.0",
     "@commitlint/config-conventional": "19.5.0",
@@ -89,8 +92,8 @@
     "husky": "8.0.3",
     "jest": "30.2.0",
     "rhachet": "1.15.0",
-    "rhachet-roles-ehmpathy": "1.15.14",
-    "test-fns": "1.6.0",
+    "rhachet-roles-ehmpathy": "1.15.15",
+    "test-fns": "1.7.2",
     "tsc-alias": "1.8.10",
     "tsx": "4.20.6",
     "typescript": "5.4.5",

package/readme.md

@@ -38,6 +38,12 @@ Used to navigate through concept space. See src/roles/thinker/briefs/cognition f
 ## 📚 Librarian
 
 Used to curate knowledge and context. see src/roles/thinker/briefs/librarian.context and src/roles/thinker/briefs/librarian.tactics for details.
+
+---
+
+## 🔍 Reviewer
+
+Used to review artifacts against declared rules. Designed to be composed into review skills for other roles.
 ```
 
 ## `ask -r thinker -s instantiate`
@@ -89,3 +95,52 @@ npx rhachet ask -r thinker -s articulate \
     how to identify a sea turtle?
   "
 ```
+
+## `run --repo bhrain --skill review`
+
+reviews artifacts against rules using claude-code as the brain. designed to be composed into review skills for other roles.
+
+```sh
+npx rhachet run --repo bhrain --skill review --mode hard --diffs uptil-main --paths '!pnpm-lock.yaml'
+```
+
+produces
+
+```
+🌊 skill "review" from repo=bhrain role=reviewer
+
+🔭 metrics.expected
+   ├─ files
+   │  ├─ rules: 60
+   │  └─ targets: 69
+   ├─ tokens
+   │  ├─ estimate: 73122
+   │  └─ context: 36.6%
+   └─ cost
+      └─ estimate: $0.3290
+
+🪵 logs
+   ├─ scope: .log/bhrain/review/2025-12-23T00-39-00-673Z/input.scope.json
+   ├─ metrics: .log/bhrain/review/2025-12-23T00-39-00-673Z/metrics.expected.json
+   └─ tokens: .log/bhrain/review/2025-12-23T00-39-00-673Z/tokens.expected.md
+
+🐢 let's review!
+   └─ elapsed: 85s ✓
+
+✨ metrics.realized
+   ├─ tokens
+   │  ├─ input: 2
+   │  ├─ cache.write: 144578
+   │  ├─ cache.read: 14316
+   │  └─ output: 1090
+   └─ cost
+      ├─ input: $0.0000
+      ├─ cache.write: $0.5422
+      ├─ cache.read: $0.0043
+      ├─ output: $0.0164
+      └─ total: $0.5629
+
+🌊 output
+   ├─ logs: .log/bhrain/review/2025-12-23T00-39-00-673Z
+   └─ review: .review/bhrain/v2025-12-23T00-39-00-645Z/[feedback].[given].by_robot.md
+```