@bolloon/bolloon-agent 0.1.0

package/dist/bollharness-integration/bollharness-integration/gate-state-machine.js

@@ -0,0 +1,231 @@
+/**
+ * Gate State Machine - Implements Bollharness's 8-Gate workflow governance
+ *
+ * Port of bollharness's lead skill Gate system to Bolloon's multi-agent architecture.
+ *
+ * Gates:
+ * G0 → G1 → G2* → G3 → G4* → G5 → G6* → G7 → G8*
+ *              审查门            审查门            审查门            审查门
+ * (* = 独立审查者，使用独立的agent上下文)
+ */
+import { AgentCoordinator } from '@bolloon/constraint-runtime';
+import { executeGateTransitionHooks, initializeGateHooks } from './gate-transition-hooks.js';
+const GATE_CONFIGS = {
+    0: {
+        entryCondition: '用户提出需求',
+        requiredArtifact: '问题陈述 + Change Classification',
+        requiredNextSkill: 'arch',
+        isReviewGate: false,
+    },
+    1: {
+        entryCondition: 'Gate 0 产物存在',
+        requiredArtifact: 'ADR 草稿 + 消费方清单',
+        requiredNextSkill: 'arch',
+        isReviewGate: false,
+    },
+    2: {
+        entryCondition: 'ADR 草稿完成',
+        requiredArtifact: '审查报告 (verdict: PASS/BLOCK)',
+        requiredNextSkill: 'review',
+        requiredReviewSubstrate: 'ref-review-sop.md 阶段②维度',
+        isReviewGate: true,
+    },
+    3: {
+        entryCondition: 'Gate 2 PASS',
+        requiredArtifact: 'PLAN 文档 + 架构覆盖矩阵',
+        requiredNextSkill: 'harness-eng',
+        isReviewGate: false,
+    },
+    4: {
+        entryCondition: 'PLAN vN-final 冻结',
+        requiredArtifact: '审查报告 + plan-lock 确认',
+        requiredNextSkill: 'review',
+        requiredReviewSubstrate: 'ref-review-sop.md 阶段④维度 + C/D/E/F',
+        isReviewGate: true,
+    },
+    5: {
+        entryCondition: 'Gate 4 PASS + plan-lock',
+        requiredArtifact: 'WP 拆分 + TASK.md',
+        requiredNextSkill: 'task-arch',
+        isReviewGate: false,
+    },
+    6: {
+        entryCondition: '全部 TASK.md 完成',
+        requiredArtifact: '审查报告 (verdict: PASS/BLOCK)',
+        requiredNextSkill: 'review',
+        requiredReviewSubstrate: 'ref-review-sop.md WP 拆分专项',
+        isReviewGate: true,
+    },
+    7: {
+        entryCondition: 'Gate 6 PASS',
+        requiredArtifact: '代码 + LOG.md',
+        requiredNextSkill: 'harness-eng',
+        isReviewGate: false,
+    },
+    8: {
+        entryCondition: '全部 WP 代码 + LOG.md 存在',
+        requiredArtifact: '审查报告 + 验收确认',
+        requiredNextSkill: 'harness-eng-test',
+        requiredReviewSubstrate: 'ref-review-sop.md 阶段⑤⑥维度',
+        isReviewGate: true,
+    },
+};
+export class GateStateMachine {
+    state;
+    coordinator;
+    reviewAgentContext = new Map();
+    constructor() {
+        this.state = this.initState();
+        this.coordinator = new AgentCoordinator(3);
+        initializeGateHooks();
+    }
+    initState() {
+        return {
+            currentGate: 0,
+            entrySatisfied: true,
+            blockers: [],
+            requiredArtifact: GATE_CONFIGS[0].requiredArtifact,
+            requiredNextSkill: GATE_CONFIGS[0].requiredNextSkill,
+            artifacts: new Map(),
+        };
+    }
+    getState() {
+        return { ...this.state, artifacts: new Map(this.state.artifacts) };
+    }
+    getCurrentGate() {
+        return this.state.currentGate;
+    }
+    getGateConfig(gate) {
+        return GATE_CONFIGS[gate];
+    }
+    /**
+     * 检查是否可以进入下一个Gate
+     */
+    canTransition() {
+        return this.state.entrySatisfied && this.state.blockers.length === 0;
+    }
+    /**
+     * 提交产物到当前Gate
+     */
+    submitArtifact(name, artifact) {
+        this.state.artifacts.set(name, artifact);
+        this.checkEntryCondition();
+    }
+    /**
+     * 获取Gate包 - 用于skill输出
+     */
+    getGatePack() {
+        return {
+            current_gate: this.state.currentGate,
+            entry_satisfied: this.state.entrySatisfied,
+            blockers: [...this.state.blockers],
+            required_artifact: this.state.requiredArtifact,
+            required_next_skill: this.state.requiredNextSkill,
+            required_review_substrate: this.state.requiredReviewSubstrate,
+        };
+    }
+    /**
+     * 尝试转移到下一个Gate
+     */
+    async transition(reviewResult) {
+        const currentGate = this.state.currentGate;
+        const blockers = [];
+        // 检查审查门是否需要独立审查
+        if (GATE_CONFIGS[currentGate].isReviewGate) {
+            if (!reviewResult) {
+                return {
+                    from: currentGate,
+                    to: currentGate,
+                    blockers: ['审查门需要审查结果'],
+                };
+            }
+            if (reviewResult.verdict === 'BLOCK') {
+                blockers.push(reviewResult.details || '审查未通过');
+            }
+        }
+        // 检查entry condition
+        if (!this.state.entrySatisfied) {
+            blockers.push('入口条件未满足');
+        }
+        if (blockers.length > 0) {
+            return { from: currentGate, to: currentGate, blockers };
+        }
+        // 执行转移
+        const nextGate = (currentGate + 1);
+        this.state.currentGate = nextGate;
+        this.updateStateForGate(nextGate);
+        // Execute gate transition hooks
+        await executeGateTransitionHooks(currentGate, nextGate, true, []);
+        return {
+            from: currentGate,
+            to: nextGate,
+            blockers: [],
+            artifact: this.getGatePack(),
+        };
+    }
+    /**
+     * 回退到指定Gate
+     */
+    rollback(gate) {
+        if (gate < this.state.currentGate) {
+            this.state.currentGate = gate;
+            this.updateStateForGate(gate);
+        }
+    }
+    /**
+     * 检查快速通道条件
+     */
+    checkFastTrack(changeClassification) {
+        if (changeClassification !== 'implementation')
+            return false;
+        // 5条全部满足才允许快速通道
+        // 1. 改动不超过3个文件
+        // 2. 无契约变更
+        // 3. 无跨模块接缝
+        // 4. 不影响用户心智或产品语义
+        // 5. 不引入新的架构决策
+        return true; // 需要实际检查实现
+    }
+    checkEntryCondition() {
+        const config = GATE_CONFIGS[this.state.currentGate];
+        // 这里应该检查具体的entry condition
+        // 简化实现
+        this.state.entrySatisfied = true;
+    }
+    updateStateForGate(gate) {
+        const config = GATE_CONFIGS[gate];
+        this.state.entrySatisfied = true;
+        this.state.blockers = [];
+        this.state.requiredArtifact = config.requiredArtifact;
+        this.state.requiredNextSkill = config.requiredNextSkill;
+        this.state.requiredReviewSubstrate = config.requiredReviewSubstrate;
+    }
+    /**
+     * 执行独立审查（用于审查门）
+     * 使用独立的agent上下文
+     */
+    async executeIndependentReview(task, substrate) {
+        // 使用AgentCoordinator执行独立审查任务
+        const subtasks = [
+            {
+                id: `review-gate-${this.state.currentGate}`,
+                description: task,
+                priority: 1,
+            },
+        ];
+        try {
+            const results = await this.coordinator.dispatch(subtasks.map(t => t.description).join(' ||| '), 1);
+            // 简化处理 - 实际应该解析审查结果
+            return {
+                verdict: 'PASS',
+                details: '审查完成',
+            };
+        }
+        catch {
+            return {
+                verdict: 'BLOCK',
+                details: '审查执行失败',
+            };
+        }
+    }
+}

package/dist/bollharness-integration/bollharness-integration/gate-transition-hooks.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Gate Transition Hook Manager
+ *
+ * Handles PreGateTransition and PostGateTransition hooks.
+ * Hooks are triggered when a gate transition occurs.
+ */
+export interface GateHookConfig {
+    gates?: number[];
+    matcher?: string;
+    type: 'command' | 'skill';
+    command?: string;
+    skill?: string;
+    action?: string;
+    timeout?: number;
+}
+export interface GateTransitionEvent {
+    from: number;
+    to: number;
+    success: boolean;
+    blockers: string[];
+}
+export declare function initializeGateHooks(): void;
+export declare function onGateTransition(phase: 'PreGateTransition' | 'PostGateTransition', callback: (event: GateTransitionEvent) => void): void;
+export declare function offGateTransition(phase: 'PreGateTransition' | 'PostGateTransition', callback: (event: GateTransitionEvent) => void): void;
+export declare function emitGateTransition(event: GateTransitionEvent): void;
+export declare function runGateHooks(phase: 'PreGateTransition' | 'PostGateTransition', event: GateTransitionEvent): Promise<void>;
+export declare function executeGateTransitionHooks(from: number, to: number, success: boolean, blockers: string[]): Promise<void>;
+export declare function addGateHook(config: GateHookConfig): void;
+export declare function clearGateHooks(): void;
+export declare function listGateHooks(): GateHookConfig[];

package/dist/bollharness-integration/bollharness-integration/gate-transition-hooks.js

@@ -0,0 +1,91 @@
+/**
+ * Gate Transition Hook Manager
+ *
+ * Handles PreGateTransition and PostGateTransition hooks.
+ * Hooks are triggered when a gate transition occurs.
+ */
+import { EventEmitter } from 'events';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import * as path from 'path';
+import * as fs from 'fs';
+const execAsync = promisify(exec);
+class GateTransitionEmitter extends EventEmitter {
+}
+const transitionEmitter = new GateTransitionEmitter();
+const GATE_HOOKS = [];
+let initialized = false;
+export function initializeGateHooks() {
+    if (initialized)
+        return;
+    initialized = true;
+    loadGateHooksFromSettings();
+}
+function loadGateHooksFromSettings() {
+    try {
+        const settingsPath = path.join(process.cwd(), 'src', 'bollharness', '.boll', 'settings.json');
+        if (!fs.existsSync(settingsPath))
+            return;
+        const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+        const gateHooks = settings.hooks?.PreGateTransition || settings.hooks?.PostGateTransition || [];
+        for (const hook of gateHooks) {
+            if (hook.type === 'command' || hook.type === 'skill') {
+                GATE_HOOKS.push(hook);
+            }
+        }
+    }
+    catch (e) {
+        console.warn('[GateHooks] Failed to load gate hooks from settings:', e);
+    }
+}
+export function onGateTransition(phase, callback) {
+    transitionEmitter.on(phase, callback);
+}
+export function offGateTransition(phase, callback) {
+    transitionEmitter.off(phase, callback);
+}
+export function emitGateTransition(event) {
+    transitionEmitter.emit('PreGateTransition', event);
+    transitionEmitter.emit('PostGateTransition', event);
+}
+function matchGate(gates, to) {
+    if (!gates || gates.length === 0)
+        return true;
+    return gates.includes(to);
+}
+export async function runGateHooks(phase, event) {
+    for (const hook of GATE_HOOKS) {
+        if (!matchGate(hook.gates, event.to))
+            continue;
+        try {
+            if (hook.type === 'command' && hook.command) {
+                const timeout = hook.timeout || 10;
+                await execAsync(hook.command, { timeout: timeout * 1000, cwd: process.cwd() });
+            }
+            else if (hook.type === 'skill' && hook.skill) {
+                await runSkillHook(hook.skill, hook.action || 'default', event);
+            }
+        }
+        catch (e) {
+            console.error(`[GateHooks] Hook failed (${phase}):`, e);
+        }
+    }
+}
+async function runSkillHook(skill, action, event) {
+    console.log(`[GateHooks] Running skill hook: ${skill} action=${action} for Gate ${event.from} -> ${event.to}`);
+}
+export async function executeGateTransitionHooks(from, to, success, blockers) {
+    const event = { from, to, success, blockers };
+    await runGateHooks('PreGateTransition', event);
+    emitGateTransition(event);
+    await runGateHooks('PostGateTransition', event);
+}
+export function addGateHook(config) {
+    GATE_HOOKS.push(config);
+}
+export function clearGateHooks() {
+    GATE_HOOKS.length = 0;
+}
+export function listGateHooks() {
+    return [...GATE_HOOKS];
+}

package/dist/bollharness-integration/bollharness-integration/guard-checker.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Guard Checker - Port of Bollharness checks to Bolloon guardrails
+ *
+ * Transforms bollharness's 15+ check functions into Bolloon's guardrail system.
+ *
+ * Key concepts:
+ * - Finding: bollharness's issue report structure
+ * - Guardrail: Bolloon's pre/post execution check interface
+ * - Guard Map: Path → Check[] routing
+ */
+export type Severity = 'P0' | 'P1' | 'P2';
+export interface Finding {
+    severity: Severity;
+    message: string;
+    file: string;
+    line?: number;
+    blocking: boolean;
+    category: string;
+    problem_class: string;
+    required_skills: string[];
+    required_reads: string[];
+}
+export interface GuardFinding extends Finding {
+    checkName: string;
+    checkPath: string;
+}
+export interface GuardResult {
+    passed: boolean;
+    findings: GuardFinding[];
+    blockingCount: number;
+    highestSeverity: Severity | null;
+}
+export interface GuardConfig {
+    name: string;
+    description: string;
+    run: (repoRoot: string, mode?: string) => Finding[];
+    category?: string;
+}
+export interface GuardCheck {
+    name: string;
+    description: string;
+    paths: string[] | RegExp[];
+    run: (filePath: string, content?: string) => GuardFinding[];
+}
+/**
+ * Port of bollharness's Finding interface
+ */
+export declare function createFinding(params: {
+    severity: Severity;
+    message: string;
+    file: string;
+    line?: number;
+    blocking?: boolean;
+    category?: string;
+    problem_class?: string;
+    required_skills?: string[];
+    required_reads?: string[];
+}): Finding;
+/**
+ * Guard Map - Maps file paths to relevant checks
+ * Adapted from bollharness's guard_router.ts
+ */
+export declare const GUARD_MAP: Record<string, string[]>;
+/**
+ * Default guards that run for all files
+ */
+export declare const DEFAULT_GUARDS: string[];
+/**
+ * Category to Skills mapping
+ * Maps guard categories to required bollharness skills
+ */
+export declare const CATEGORY_TO_SKILLS: Record<string, string[]>;
+/**
+ * Check implementations - Ported from bollharness checks
+ */
+export declare function checkApiTypes(filePath: string): GuardFinding[];
+export declare function checkDocFreshness(filePath: string): GuardFinding[];
+export declare function checkSkillParity(filePath: string): GuardFinding[];
+export declare function checkVersions(filePath: string): GuardFinding[];
+export declare function checkHookInstalled(filePath: string): GuardFinding[];
+export declare function checkArtifactLink(filePath: string): GuardFinding[];
+/**
+ * All available checks
+ */
+export declare const ALL_CHECKS: Record<string, (filePath: string) => GuardFinding[]>;
+/**
+ * Route file path to relevant checks
+ * Adapted from bollharness's route() function
+ */
+export declare function route(filePath: string): string[];
+/**
+ * Run guards for a file
+ */
+export declare function runGuards(filePath: string): Promise<GuardResult>;
+/**
+ * GuardChecker class for integration with Bolloon's constraint system
+ */
+export declare class GuardChecker {
+    private checksDir;
+    private enabledChecks;
+    constructor(checksDir?: string);
+    enableCheck(name: string): void;
+    disableCheck(name: string): void;
+    check(filePath: string): Promise<GuardResult>;
+}