rhachet-roles-bhrain 0.2.0 → 0.5.1

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

@@ -0,0 +1,186 @@
+import { enrollThread, genContextStitchTrail, genRoleSkill } from 'rhachet';
+import { genArtifactGitFile, getArtifactObsDir } from 'rhachet-artifact-git';
+
+import { genContextLogTrail } from '@src/.test/genContextLogTrail';
+import { BrainArch1Actor } from '@src/domain.objects/BrainArch1/BrainArch1Actor';
+import { genAtomAnthropic } from '@src/domain.operations/brain.replic.arch1/plugins/atoms/anthropic';
+import { genAtomOpenai } from '@src/domain.operations/brain.replic.arch1/plugins/atoms/openai';
+import { genAtomQwen } from '@src/domain.operations/brain.replic.arch1/plugins/atoms/qwen';
+import { permissionGuardReadOnly } from '@src/domain.operations/brain.replic.arch1/plugins/permissionGuards/readOnly';
+import { toolboxFiles } from '@src/domain.operations/brain.replic.arch1/plugins/toolboxes/files';
+
+import { stepAct } from './stepAct';
+
+/**
+ * .what = skill definition for agentic task completion
+ * .why = enables rhachet roles to leverage brain capabilities for autonomous task execution
+ */
+export const SKILL_ACT = genRoleSkill({
+  slug: 'act',
+  route: stepAct,
+  threads: {
+    lookup: {
+      target: {
+        source: 'process.argv',
+        char: 't',
+        desc: 'the target file to write the result to',
+        type: 'string',
+      },
+      provider: {
+        source: 'process.argv',
+        char: 'p',
+        desc: 'the llm provider to use (anthropic, openai, qwen)',
+        type: '?string',
+      },
+      model: {
+        source: 'process.argv',
+        char: 'm',
+        desc: 'the model to use',
+        type: '?string',
+      },
+      system: {
+        source: 'process.argv',
+        char: 's',
+        desc: 'path to system prompt file',
+        type: '?string',
+      },
+    },
+    assess: (
+      input,
+    ): input is {
+      target: string;
+      provider: string;
+      model: string;
+      system: string;
+      ask: string;
+    } => typeof input.target === 'string',
+    instantiate: async (input: {
+      target: string;
+      provider: string;
+      model: string;
+      system: string;
+      ask: string;
+    }) => {
+      const obsDir = getArtifactObsDir({ uri: input.target });
+
+      // build brain actor from inputs
+      const provider = (input.provider ?? 'anthropic') as
+        | 'anthropic'
+        | 'openai'
+        | 'qwen';
+      const model = input.model ?? 'claude-3-5-sonnet-latest';
+
+      // create atom based on provider
+      const atom =
+        provider === 'anthropic'
+          ? genAtomAnthropic({ model })
+          : provider === 'openai'
+            ? genAtomOpenai({ model })
+            : genAtomQwen({ model });
+
+      const actor = new BrainArch1Actor({
+        atom,
+        toolboxes: [toolboxFiles],
+        memory: null,
+        permission: permissionGuardReadOnly,
+        constraints: {
+          maxIterations: 100,
+          maxTokens: 8192,
+        },
+        role: {
+          systemPrompt: null,
+        },
+      });
+
+      return {
+        caller: await enrollThread({
+          role: 'caller',
+          stash: {
+            ask: input.ask,
+            art: {
+              result: genArtifactGitFile(
+                { uri: input.target },
+                { versions: true },
+              ),
+              log: genArtifactGitFile(
+                { uri: obsDir + '.log.md' },
+                { versions: true },
+              ),
+            },
+          },
+        }),
+        brain: await enrollThread({
+          role: 'brain',
+          stash: {
+            actor,
+            systemPromptPath: input.system ?? null,
+          },
+        }),
+      };
+    },
+  },
+  context: {
+    lookup: {
+      apiKeyAnthropic: {
+        source: 'process.env',
+        envar: 'ANTHROPIC_API_KEY',
+        desc: 'the anthropic api key',
+        type: '?string',
+      },
+      apiKeyOpenai: {
+        source: 'process.env',
+        envar: 'OPENAI_API_KEY',
+        desc: 'the openai api key',
+        type: '?string',
+      },
+      apiKeyQwen: {
+        source: 'process.env',
+        envar: 'QWEN_API_KEY',
+        desc: 'the qwen api key',
+        type: '?string',
+      },
+      apiKeyTavily: {
+        source: 'process.env',
+        envar: 'TAVILY_API_KEY',
+        desc: 'the tavily api key for web search',
+        type: '?string',
+      },
+    },
+    assess: (
+      input,
+    ): input is {
+      apiKeyAnthropic: string;
+      apiKeyOpenai: string;
+      apiKeyQwen: string;
+      apiKeyTavily: string;
+    } => true,
+    instantiate: (input: {
+      apiKeyAnthropic: string;
+      apiKeyOpenai: string;
+      apiKeyQwen: string;
+      apiKeyTavily: string;
+    }) => {
+      return {
+        creds: {
+          anthropic: { apiKey: input.apiKeyAnthropic ?? '', url: null },
+          openai: { apiKey: input.apiKeyOpenai ?? '', url: null },
+          qwen: { apiKey: input.apiKeyQwen ?? '', url: null },
+          tavily: { apiKey: input.apiKeyTavily ?? '' },
+        },
+        ...genContextLogTrail(),
+        ...genContextStitchTrail(),
+      };
+    },
+  },
+  readme: `
+# act
+
+invokes the agentic brain loop to complete a task
+
+## usage
+
+\`\`\`bash
+npx rhachet skills run act -t ./output.md "your task here"
+\`\`\`
+  `.trim(),
+});

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,8 +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 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 =
@@ -13,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],
+    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,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,CAAC;CACtB,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/getRoleRegistry.readme.js

@@ -18,5 +18,11 @@ 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.
   `.trim();
 //# sourceMappingURL=getRoleRegistry.readme.js.map

package/dist/roles/getRoleRegistry.readme.js.map

@@ -1 +1 @@
-{"version":3,"file":"getRoleRegistry.readme.js","sourceRoot":"","sources":["../../src/roles/getRoleRegistry.readme.ts"],"names":[],"mappings":";;;AAAA,mDAAmD;AACtC,QAAA,sBAAsB,GAAG;;;;;;;;;;;;;;;;GAgBnC,CAAC,IAAI,EAAE,CAAC"}
+{"version":3,"file":"getRoleRegistry.readme.js","sourceRoot":"","sources":["../../src/roles/getRoleRegistry.readme.ts"],"names":[],"mappings":";;;AAAA,mDAAmD;AACtC,QAAA,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;GAsBnC,CAAC,IAAI,EAAE,CAAC"}

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