rhachet-roles-bhrain 0.2.0 → 0.3.0

package/dist/domain.operations/review/invokeClaudeCode.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.invokeClaudeCode = void 0;
+const child_process_1 = require("child_process");
+const helpful_errors_1 = require("helpful-errors");
+/**
+ * .what = invokes claude-code cli with the prompt
+ * .why = executes the review via the specified brain (claude-code)
+ */
+const invokeClaudeCode = async (input) => {
+    // invoke claude-code cli via stdin to avoid E2BIG on large prompts
+    const output = await new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)('claude', ['-p', '-', '--output-format', 'json'], {
+            cwd: input.cwd,
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (data) => {
+            stdout += data.toString();
+        });
+        child.stderr.on('data', (data) => {
+            stderr += data.toString();
+        });
+        child.on('error', reject);
+        child.on('close', (code) => {
+            if (code !== 0) {
+                // check for prompt too long error
+                if (stdout.includes('Prompt is too long')) {
+                    reject(new helpful_errors_1.BadRequestError('prompt is too long for claude context window; reduce --rules or --paths scope', {
+                        status: code,
+                        hint: 'try narrowing your glob patterns or excluding large files',
+                    }));
+                    return;
+                }
+                reject(new helpful_errors_1.UnexpectedCodePathError('claude-code exited with non-zero', {
+                    status: code,
+                    stdout: stdout.slice(0, 2000),
+                    stderr: stderr.slice(0, 2000),
+                }));
+                return;
+            }
+            resolve(stdout);
+        });
+        // write prompt to stdin and close
+        child.stdin.write(input.prompt);
+        child.stdin.end();
+    });
+    // parse the json response
+    const response = (() => {
+        try {
+            return JSON.parse(output);
+        }
+        catch {
+            throw new helpful_errors_1.UnexpectedCodePathError('failed to parse claude-code response', {
+                output,
+            });
+        }
+    })();
+    // extract review content from response
+    const review = (() => {
+        // claude-code json output has a 'result' field with the text content
+        if (response.result && typeof response.result === 'string') {
+            return response.result;
+        }
+        // fallback: look for text in message content
+        if (response.content && Array.isArray(response.content)) {
+            const textContent = response.content.find((c) => c.type === 'text');
+            if (textContent?.text) {
+                return textContent.text;
+            }
+        }
+        throw new helpful_errors_1.UnexpectedCodePathError('failed to extract review from response', {
+            response,
+        });
+    })();
+    // extract usage from response
+    const usage = (() => {
+        if (!response.usage)
+            throw new helpful_errors_1.UnexpectedCodePathError('response.usage not found', {
+                response,
+            });
+        return {
+            inputTokens: response.usage.input_tokens ?? 0,
+            inputTokensCacheCreation: response.usage.cache_creation_input_tokens ?? 0,
+            inputTokensCacheRead: response.usage.cache_read_input_tokens ?? 0,
+            outputTokens: response.usage.output_tokens ?? 0,
+        };
+    })();
+    return { response, review, usage };
+};
+exports.invokeClaudeCode = invokeClaudeCode;
+//# sourceMappingURL=invokeClaudeCode.js.map

package/dist/domain.operations/review/invokeClaudeCode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invokeClaudeCode.js","sourceRoot":"","sources":["../../../src/domain.operations/review/invokeClaudeCode.ts"],"names":[],"mappings":"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"}

package/dist/domain.operations/review/writeInputArtifacts.d.ts

@@ -0,0 +1,27 @@
+/**
+ * .what = writes input artifacts to log directory for auditability
+ * .why = enables debugging, replay, and audit of review invocations
+ */
+export declare const writeInputArtifacts: (input: {
+    logDir: string;
+    args: {
+        rules: string | string[];
+        diffs?: string;
+        paths?: string | string[];
+        output: string;
+        mode: 'soft' | 'hard';
+    };
+    scope: {
+        ruleFiles: string[];
+        targetFiles: string[];
+    };
+    metrics: {
+        tokenEstimate: number;
+        contextWindowPercent: number;
+        costEstimate: number;
+    };
+    prompt: string;
+}) => Promise<{
+    argsPath: string;
+    promptPath: string;
+}>;

package/dist/domain.operations/review/writeInputArtifacts.js

@@ -0,0 +1,50 @@
+"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.writeInputArtifacts = void 0;
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+/**
+ * .what = writes input artifacts to log directory for auditability
+ * .why = enables debugging, replay, and audit of review invocations
+ */
+const writeInputArtifacts = async (input) => {
+    // ensure log directory exists
+    await fs.mkdir(input.logDir, { recursive: true });
+    // write input.args.json
+    const argsPath = path.join(input.logDir, 'input.args.json');
+    const argsContent = JSON.stringify({
+        args: input.args,
+        scope: input.scope,
+        metrics: input.metrics,
+    }, null, 2);
+    await fs.writeFile(argsPath, argsContent, 'utf-8');
+    // write input.prompt.md
+    const promptPath = path.join(input.logDir, 'input.prompt.md');
+    await fs.writeFile(promptPath, input.prompt, 'utf-8');
+    return { argsPath, promptPath };
+};
+exports.writeInputArtifacts = writeInputArtifacts;
+//# sourceMappingURL=writeInputArtifacts.js.map

package/dist/domain.operations/review/writeInputArtifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeInputArtifacts.js","sourceRoot":"","sources":["../../../src/domain.operations/review/writeInputArtifacts.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,gDAAkC;AAClC,2CAA6B;AAE7B;;;GAGG;AACI,MAAM,mBAAmB,GAAG,KAAK,EAAE,KAmBzC,EAAqD,EAAE;IACtD,8BAA8B;IAC9B,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAElD,wBAAwB;IACxB,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC5D,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,CAChC;QACE,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,OAAO,EAAE,KAAK,CAAC,OAAO;KACvB,EACD,IAAI,EACJ,CAAC,CACF,CAAC;IACF,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;IAEnD,wBAAwB;IACxB,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC9D,MAAM,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEtD,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;AAClC,CAAC,CAAC;AAzCW,QAAA,mBAAmB,uBAyC9B"}

package/dist/domain.operations/review/writeOutputArtifacts.d.ts

@@ -0,0 +1,12 @@
+/**
+ * .what = writes output artifacts to log directory for auditability
+ * .why = enables debugging, replay, and audit of review results
+ */
+export declare const writeOutputArtifacts: (input: {
+    logDir: string;
+    response: object;
+    review: string;
+}) => Promise<{
+    responsePath: string;
+    reviewPath: string;
+}>;

package/dist/domain.operations/review/writeOutputArtifacts.js

@@ -0,0 +1,46 @@
+"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.writeOutputArtifacts = void 0;
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+/**
+ * .what = writes output artifacts to log directory for auditability
+ * .why = enables debugging, replay, and audit of review results
+ */
+const writeOutputArtifacts = async (input) => {
+    // ensure log directory exists (should already exist from writeInputArtifacts)
+    await fs.mkdir(input.logDir, { recursive: true });
+    // write output.response.json
+    const responsePath = path.join(input.logDir, 'output.response.json');
+    const responseContent = JSON.stringify(input.response, null, 2);
+    await fs.writeFile(responsePath, responseContent, 'utf-8');
+    // write output.review.md
+    const reviewPath = path.join(input.logDir, 'output.review.md');
+    await fs.writeFile(reviewPath, input.review, 'utf-8');
+    return { responsePath, reviewPath };
+};
+exports.writeOutputArtifacts = writeOutputArtifacts;
+//# sourceMappingURL=writeOutputArtifacts.js.map

package/dist/domain.operations/review/writeOutputArtifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeOutputArtifacts.js","sourceRoot":"","sources":["../../../src/domain.operations/review/writeOutputArtifacts.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,gDAAkC;AAClC,2CAA6B;AAE7B;;;GAGG;AACI,MAAM,oBAAoB,GAAG,KAAK,EAAE,KAI1C,EAAyD,EAAE;IAC1D,8EAA8E;IAC9E,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAElD,6BAA6B;IAC7B,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IACrE,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAChE,MAAM,EAAE,CAAC,SAAS,CAAC,YAAY,EAAE,eAAe,EAAE,OAAO,CAAC,CAAC;IAE3D,yBAAyB;IACzB,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC/D,MAAM,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEtD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC;AACtC,CAAC,CAAC;AAlBW,QAAA,oBAAoB,wBAkB/B"}

package/dist/roles/getRoleRegistry.js

@@ -3,6 +3,7 @@ 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");
 /**
  * .what = returns the core registry of predefined roles and skills
@@ -13,7 +14,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],
 });
 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,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"}

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/review.tactics.md

@@ -0,0 +1,60 @@
+# review tactics
+
+## purpose
+
+the reviewer role performs automated code review against declared rules, using claude-code as the underlying brain.
+
+## modes
+
+### soft mode
+
+- includes only file paths in the prompt
+- instructs brain to read files directly
+- lower token usage
+- best for: large codebases, exploratory reviews
+
+### hard mode
+
+- includes full file contents in the prompt
+- no additional file reads required
+- higher token usage, faster execution
+- best for: focused reviews, smaller scopes
+
+## mode selection criteria
+
+use `--soft` when:
+- scope is large (>50 files)
+- context window would exceed 60%
+- reviewing for general patterns
+
+use `--hard` when:
+- scope is small (<20 files)
+- precision is critical
+- reviewing specific changes
+
+## context window thresholds
+
+- **60% warning**: emits warning but continues
+- **75% failfast**: throws error with recommendation to reduce scope or use soft mode
+
+## scope combination
+
+targets are the union of `--diffs` and `--paths`:
+- `--diffs uptil-main`: files changed since main branch
+- `--diffs uptil-staged`: only staged files
+- `--paths`: explicit glob patterns
+
+## artifacts
+
+all invocations log to `.log/bhrain/review/$timestamp/`:
+- `input.args.json`: original arguments and computed metrics
+- `input.prompt.md`: exact prompt sent to brain
+- `output.response.json`: raw brain response
+- `output.review.md`: formatted review output
+
+## output format
+
+reviews follow the feedback template format:
+- blockers appear first (severity: blocker)
+- nitpicks appear second (severity: nitpick)
+- each finding includes file path and line number when available

package/dist/roles/reviewer/getReviewerRole.d.ts

@@ -0,0 +1,6 @@
+import { Role } from 'rhachet';
+/**
+ * .what = reviewer role definition
+ * .why = enables code review against declared rules via brain invocation
+ */
+export declare const ROLE_REVIEWER: Role;

package/dist/roles/reviewer/getReviewerRole.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROLE_REVIEWER = void 0;
+const rhachet_1 = require("rhachet");
+/**
+ * .what = reviewer role definition
+ * .why = enables code review against declared rules via brain invocation
+ */
+exports.ROLE_REVIEWER = rhachet_1.Role.build({
+    slug: 'reviewer',
+    name: 'Reviewer',
+    purpose: 'review artifacts against declared rules',
+    readme: `
+## 🔍 Reviewer
+
+- **scale**: repo-level, artifact quality
+- **focus**: rule compliance, best practices enforcement
+- **maximizes**: artifact quality and consistency
+
+used to review artifacts against declared rules and best practices.
+invokes claude-code brain to perform intelligent review.
+designed to be composed into review skills for other roles.
+
+### usage
+
+\`\`\`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
+\`\`\`
+  `.trim(),
+    traits: [],
+    skills: {
+        dirs: [{ uri: __dirname + '/skills' }],
+        refs: [],
+    },
+    briefs: {
+        dirs: [{ uri: __dirname + '/briefs' }],
+    },
+});
+//# sourceMappingURL=getReviewerRole.js.map

package/dist/roles/reviewer/getReviewerRole.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getReviewerRole.js","sourceRoot":"","sources":["../../../src/roles/reviewer/getReviewerRole.ts"],"names":[],"mappings":";;;AAAA,qCAA+B;AAE/B;;;GAGG;AACU,QAAA,aAAa,GAAS,cAAI,CAAC,KAAK,CAAC;IAC5C,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,yCAAyC;IAClD,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDP,CAAC,IAAI,EAAE;IACR,MAAM,EAAE,EAAE;IACV,MAAM,EAAE;QACN,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;QACtC,IAAI,EAAE,EAAE;KACT;IACD,MAAM,EAAE;QACN,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;KACvC;CACF,CAAC,CAAC"}

package/dist/roles/reviewer/skills/review/review.d.ts

@@ -0,0 +1,57 @@
+/**
+ * .what = result of stepReview execution
+ * .why = enables caller to inspect review outcome and artifacts
+ */
+export type StepReviewResult = {
+    review: {
+        formatted: string;
+    };
+    log: {
+        dir: string;
+    };
+    output: {
+        path: string;
+    };
+    metrics: {
+        files: {
+            rulesCount: number;
+            targetsCount: number;
+        };
+        expected: {
+            tokens: {
+                estimate: number;
+                contextWindowPercent: number;
+            };
+            cost: {
+                estimate: number;
+            };
+        };
+        realized: {
+            tokens: {
+                input: number;
+                inputCacheCreation: number;
+                inputCacheRead: number;
+                output: number;
+            };
+            cost: {
+                input: number;
+                cacheWrite: number;
+                cacheRead: number;
+                output: number;
+                total: number;
+            };
+        };
+    };
+};
+/**
+ * .what = executes a code review against specified rules and targets
+ * .why = core orchestration flow for reviewer role
+ */
+export declare const stepReview: (input: {
+    rules: string | string[];
+    diffs?: string;
+    paths?: string | string[];
+    output: string;
+    mode: 'soft' | 'hard';
+    cwd?: string;
+}) => Promise<StepReviewResult>;