@bolloon/bolloon-agent 0.1.35 → 0.1.37

package/src/bollharness/scripts/hooks/stop-evaluator.md

@@ -1,83 +0,0 @@
-# Stop Hook: Completion Proposal + Independent Review (ADR-044 §3.4 L3+L4)
-
-你**不是** Evaluator。你是被评估的一方。你的工作是：
-1. 写出你做了什么（proposal）
-2. 请一个独立 agent 来评你
-
-**禁止自己给自己打分。** 自评有结构性利益冲突（Anthropic: "Agents consistently overpraise their own work"）。
-
-## Step 1: 写 Completion Proposal
-
-将以下 JSON 写入 `.boll/state/completion-proposal.json`：
-
-```json
-{
-  "session_id": "<当前 session 标识>",
-  "timestamp": "<ISO 8601>",
-  "summary": "<1-3 句话描述本 session 做了什么>",
-  "files_changed": ["<从 git diff 或 risk-snapshot 获取>"],
-  "evidence": {
-    "tests_run": "<运行了哪些测试，结果如何>",
-    "verification_commands": ["<实际执行的验证命令>"],
-    "commits": ["<本 session 的 commit hash + message>"]
-  },
-  "known_limitations": ["<诚实列出已知的未完成项或风险>"],
-  "task_reference": "<TASK.md 路径或用户原始指令摘要>"
-}
-```
-
-**要求**：
-- `files_changed` 必须从 `git diff` 或 risk-snapshot 的 `files_touched` 取，**不得凭记忆列举**
-- `evidence` 中的测试结果必须是实际运行输出，不是"应该通过"
-- `known_limitations` 必须诚实 — 这是给 reviewer 的线索，不是给自己开脱
-
-## Step 2: Spawn 独立 Reviewer
-
-写完 proposal 后，**必须** spawn 一个独立审查 agent：
-
-```
-Agent({
-  subagent_type: "review-readonly",
-  description: "Completion review",
-  prompt: `你是独立的 Completion Reviewer（ADR-044 L4）。
-你的任务是验证 agent 的 completion proposal 是否与实际代码变更一致。
-
-读取 .boll/state/completion-proposal.json，然后：
-
-1. **Proposal vs Reality**：git diff 的实际变更是否与 proposal.files_changed 一致？有遗漏吗？
-2. **Evidence 可信度**：proposal.evidence 中声称的测试/验证，结果是否真实？
-3. **半成品检查**：变更文件中有没有 TODO/FIXME/HACK？有没有 dead code？
-4. **契约一致性**：如果改了 API/config/路由，所有引用处是否同步更新？
-5. **已知限制诚实度**：proposal.known_limitations 是否遗漏了明显风险？
-
-评分（每维 1-5，任何维 < 3 = FAIL）：
-- Completeness: proposal 是否覆盖所有实际变更
-- Honesty: evidence 和 limitations 是否真实
-- Quality: 代码变更本身的质量
-- Consistency: 跨文件/跨层的一致性
-
-输出格式：
-## Verdict: PASS / FAIL
-## Scores: Completeness X/5, Honesty X/5, Quality X/5, Consistency X/5
-## Findings: [具体发现列表]
-## Recommendation: [如果 FAIL，具体要修什么]`
-})
-```
-
-## Step 3: 根据 Reviewer 裁决行动
-
-- **Reviewer 说 PASS** → 你可以 Stop
-- **Reviewer 说 FAIL** → 按 Recommendation 修复，修复后再尝试 Stop
-- **Reviewer spawn 失败**（超时/权限等）→ 降级为 PreCompletionChecklist 自检（下方），但必须在输出中声明 "独立审查未执行，以下为自检降级"
-
-## 降级 Fallback: PreCompletionChecklist（仅当 reviewer 不可用时）
-
-如果因环境限制无法 spawn reviewer，执行以下自检：
-
-1. **Git 状态**: 所有新文件是否已 `git add`？是否有未保存的变更？
-2. **测试**: 如果有代码变更，相关测试是否通过？
-3. **文档一致性**: 代码变更是否需要更新文档？
-4. **无半成品**: 是否有 TODO/FIXME/HACK 被遗留？
-5. **契约一致性**: API 类型、路由路径、配置 key 是否在所有引用处一致？
-
-**但必须标注**：这是自检降级，不是独立审查。

package/src/bollharness/scripts/sync-from-upstream.sh

@@ -1,281 +0,0 @@
-#!/bin/bash
-# sync-from-upstream.sh — Sync hook files from boll (upstream) to bollharness.
-#
-# Purpose: boll is the development/incubation repo where hooks are written
-# and tested. This script copies updated hooks to bollharness and reports
-# any discrepancies in settings.json hook registrations.
-#
-# What it does:
-#   1. Copy shared hook scripts from boll → bollharness (skip boll-only files)
-#   2. Replace find-boll-root.sh references → find-project-root.sh in copied files
-#   3. Compare settings.json hook registrations and report differences
-#   4. Sync shared scripts (guard-feedback.ts, deploy-guard.ts, context_router.ts, guard_router.ts)
-#   5. Sync context-fragments/ directory
-#
-# Usage:
-#   ./scripts/sync-from-upstream.sh                     # default boll path
-#   ./scripts/sync-from-upstream.sh /path/to/boll      # explicit upstream path
-#   ./scripts/sync-from-upstream.sh --dry-run            # show what would change
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-HARNESS_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-UPSTREAM_DEFAULT="$(cd "$HARNESS_ROOT/../boll" 2>/dev/null && pwd || echo "")"
-
-# Parse args
-DRY_RUN=false
-UPSTREAM=""
-
-for arg in "$@"; do
-    case "$arg" in
-        --dry-run) DRY_RUN=true ;;
-        *) UPSTREAM="$arg" ;;
-    esac
-done
-
-if [ -z "$UPSTREAM" ]; then
-    UPSTREAM="$UPSTREAM_DEFAULT"
-fi
-
-if [ -z "$UPSTREAM" ] || [ ! -d "$UPSTREAM/scripts/hooks" ]; then
-    echo "ERROR: Cannot find upstream boll repo."
-    echo "Usage: $0 [--dry-run] [/path/to/boll]"
-    exit 1
-fi
-
-echo "=== bollharness sync-from-upstream ==="
-echo "Upstream: $UPSTREAM"
-echo "Target:   $HARNESS_ROOT"
-echo "Dry run:  $DRY_RUN"
-echo ""
-
-# ─── Files that exist only in boll (not synced) ───
-boll_ONLY=(
-    "find-boll-root.sh"  # boll-specific root finder
-)
-
-# ─── Files that exist only in bollharness (not overwritten) ───
-HARNESS_ONLY=(
-    "find-project-root.sh"  # Generic root finder
-    "sanitize-on-read.ts"   # WP-11 addition
-)
-
-# ─── Step 1: Copy shared hooks ───
-echo "── Step 1: Sync hook scripts ──"
-COPIED=0
-SKIPPED=0
-UNCHANGED=0
-
-for src_file in "$UPSTREAM/scripts/hooks/"*; do
-    [ -f "$src_file" ] || continue  # skip directories (e.g. __pycache__)
-    filename="$(basename "$src_file")"
-
-    # Skip boll-only files
-    skip=false
-    for excl in "${boll_ONLY[@]}"; do
-        if [ "$filename" = "$excl" ]; then
-            skip=true
-            break
-        fi
-    done
-    if $skip; then
-        echo "  SKIP (boll-only): $filename"
-        ((SKIPPED++))
-        continue
-    fi
-
-    # Skip harness-only files (don't overwrite)
-    for excl in "${HARNESS_ONLY[@]}"; do
-        if [ "$filename" = "$excl" ]; then
-            skip=true
-            break
-        fi
-    done
-    if $skip; then
-        echo "  SKIP (harness-only): $filename"
-        ((SKIPPED++))
-        continue
-    fi
-
-    dst_file="$HARNESS_ROOT/scripts/hooks/$filename"
-
-    # Check if content differs
-    if [ -f "$dst_file" ]; then
-        if diff -q "$src_file" "$dst_file" > /dev/null 2>&1; then
-            ((UNCHANGED++))
-            continue
-        fi
-    fi
-
-    if $DRY_RUN; then
-        echo "  WOULD COPY: $filename"
-    else
-        cp "$src_file" "$dst_file"
-        echo "  COPIED: $filename"
-    fi
-    ((COPIED++))
-done
-
-echo ""
-echo "  Results: $COPIED copied, $SKIPPED skipped, $UNCHANGED unchanged"
-
-# ─── Step 2: Replace find-boll-root.sh references ───
-echo ""
-echo "── Step 2: Path references ──"
-PATCHED=0
-
-for hook_file in "$HARNESS_ROOT/scripts/hooks/"*.ts "$HARNESS_ROOT/scripts/hooks/"*.sh; do
-    [ -f "$hook_file" ] || continue
-    filename="$(basename "$hook_file")"
-
-    # Skip harness-only files
-    skip=false
-    for excl in "${HARNESS_ONLY[@]}"; do
-        if [ "$filename" = "$excl" ]; then
-            skip=true
-            break
-        fi
-    done
-    if $skip; then continue; fi
-
-    if grep -q "find-boll-root.sh" "$hook_file" 2>/dev/null; then
-        if $DRY_RUN; then
-            echo "  WOULD PATCH: $filename (find-boll-root.sh → find-project-root.sh)"
-        else
-            # Use perl for reliable in-place replace (macOS sed -i differs from GNU)
-            perl -pi -e 's/find-boll-root\.sh/find-project-root.sh/g' "$hook_file"
-            echo "  PATCHED: $filename"
-        fi
-        ((PATCHED++))
-    fi
-done
-
-if [ "$PATCHED" -eq 0 ]; then
-    echo "  No path references to patch"
-fi
-
-# ─── Step 3: Compare settings.json hook registrations ───
-echo ""
-echo "── Step 3: Hook registration diff ──"
-
-# Extract hook script names from settings.json
-extract_hooks() {
-    npx ts-node -e "
-import json, sys
-const d = JSON.parse(require('fs').readFileSync('$1', 'utf8'));
-const hooks = [];
-for (const [stage, entries] of Object.entries(d.get('hooks', {}))) {
-    for (const entry of entries) {
-        const matcher = entry.get('matcher', '*');
-        for (const h of entry.get('hooks', [])) {
-            const cmd = h.get('command', '');
-            // Extract script name
-            const parts = cmd.split(' ');
-            for (let i = parts.length - 1; i >= 0; i--) {
-                if (parts[i].endsWith('.ts') || parts[i].endsWith('.sh')) {
-                    hooks.push(\`\${stage}|\${matcher}|\${parts[i].split('/').pop()}\`);
-                    break;
-                }
-            }
-        }
-    }
-}
-for (const h of [...new Set(hooks)].sort()) console.log(h);
-" 2>/dev/null
-}
-
-UPSTREAM_HOOKS=$(extract_hooks "$UPSTREAM/.boll/settings.json")
-HARNESS_HOOKS=$(extract_hooks "$HARNESS_ROOT/.boll/settings.json")
-
-# Find hooks only in upstream
-ONLY_UPSTREAM=$(comm -23 <(echo "$UPSTREAM_HOOKS") <(echo "$HARNESS_HOOKS"))
-ONLY_HARNESS=$(comm -13 <(echo "$UPSTREAM_HOOKS") <(echo "$HARNESS_HOOKS"))
-
-if [ -n "$ONLY_UPSTREAM" ]; then
-    echo "  ⚠ Only in boll (missing from bollharness):"
-    echo "$ONLY_UPSTREAM" | while IFS='|' read -r stage matcher script; do
-        echo "    $stage $matcher: $script"
-    done
-fi
-
-if [ -n "$ONLY_HARNESS" ]; then
-    echo "  ℹ Only in bollharness (expected for harness-specific hooks):"
-    echo "$ONLY_HARNESS" | while IFS='|' read -r stage matcher script; do
-        echo "    $stage $matcher: $script"
-    done
-fi
-
-if [ -z "$ONLY_UPSTREAM" ] && [ -z "$ONLY_HARNESS" ]; then
-    echo "  ✓ Hook registrations in sync"
-fi
-
-# ─── Step 4: Check for other synced files ───
-echo ""
-echo "── Step 4: Other shared files ──"
-
-# Scripts in scripts/ root that are shared with boll
-for shared_file in "guard-feedback.ts" "deploy-guard.ts" "context_router.ts" "guard_router.ts"; do
-    src="$UPSTREAM/scripts/$shared_file"
-    dst="$HARNESS_ROOT/scripts/$shared_file"
-    if [ -f "$src" ] && [ -f "$dst" ]; then
-        if ! diff -q "$src" "$dst" > /dev/null 2>&1; then
-            if $DRY_RUN; then
-                echo "  WOULD COPY: scripts/$shared_file"
-            else
-                cp "$src" "$dst"
-                echo "  COPIED: scripts/$shared_file"
-            fi
-        fi
-    elif [ -f "$src" ] && [ ! -f "$dst" ]; then
-        echo "  ⚠ MISSING in harness: scripts/$shared_file"
-    fi
-done
-
-# ─── Step 5: Sync context-fragments/ directory ───
-echo ""
-echo "── Step 5: Context fragments ──"
-FRAG_COPIED=0
-FRAG_UNCHANGED=0
-
-src_frag_dir="$UPSTREAM/scripts/context-fragments"
-dst_frag_dir="$HARNESS_ROOT/scripts/context-fragments"
-
-if [ -d "$src_frag_dir" ]; then
-    if [ ! -d "$dst_frag_dir" ]; then
-        if $DRY_RUN; then
-            echo "  WOULD CREATE: scripts/context-fragments/"
-        else
-            mkdir -p "$dst_frag_dir"
-            echo "  CREATED: scripts/context-fragments/"
-        fi
-    fi
-
-    for src_frag in "$src_frag_dir/"*; do
-        [ -f "$src_frag" ] || continue
-        frag_name="$(basename "$src_frag")"
-        dst_frag="$dst_frag_dir/$frag_name"
-
-        if [ -f "$dst_frag" ]; then
-            if diff -q "$src_frag" "$dst_frag" > /dev/null 2>&1; then
-                ((FRAG_UNCHANGED++))
-                continue
-            fi
-        fi
-
-        if $DRY_RUN; then
-            echo "  WOULD COPY: context-fragments/$frag_name"
-        else
-            cp "$src_frag" "$dst_frag"
-            echo "  COPIED: context-fragments/$frag_name"
-        fi
-        ((FRAG_COPIED++))
-    done
-
-    echo "  Results: $FRAG_COPIED copied, $FRAG_UNCHANGED unchanged"
-else
-    echo "  ⚠ Upstream context-fragments/ not found"
-fi
-
-echo ""
-echo "=== Sync complete ==="

package/src/bollharness/src/index.ts

@@ -1,5 +0,0 @@
-export { Finding, createFinding } from "./scripts/checks/finding";
-export { route, runGuards, writeSessionSignal, readAllSignals, GUARD_MAP, DEFAULT_GUARDS, CATEGORY_TO_SKILLS } from "./scripts/guard_router";
-export { match, loadFragment, FALLBACK_FRAGMENTS, CONTEXT_MAP } from "./scripts/context_router";
-export { main as guardFeedbackMain } from "./scripts/guard-feedback";
-export { main as deployGuardMain } from "./scripts/deploy-guard";

package/src/bollharness/src/scripts/checks/check_adr_plan_numbering.ts

@@ -1,11 +0,0 @@
-import * as fs from "fs";
-import * as path from "path";
-import { Finding } from "./finding";
-
-export function run(repoRoot: string, mode: string = "full"): Finding[] {
-  const findings: Finding[] = [];
-
-  if (mode !== "full" && mode !== "ci") return findings;
-
-  return findings;
-}

package/src/bollharness/src/scripts/checks/check_api_types.ts

@@ -1,52 +0,0 @@
-import * as fs from "fs";
-import * as path from "path";
-import { Finding } from "./finding";
-
-export function run(repoRoot: string, mode: string = "full"): Finding[] {
-  const findings: Finding[] = [];
-
-  const tsFile = path.join(repoRoot, "generated", "api-types.ts");
-  if (!fs.existsSync(tsFile)) {
-    findings.push({
-      severity: "P1",
-      message: "generated/api-types.ts does not exist — run scripts/export_api_types.py",
-      file: "generated/api-types.ts",
-      blocking: false,
-      category: "general",
-      problem_class: "unknown",
-      required_skills: [],
-      required_reads: [],
-    });
-    return findings;
-  }
-
-  const content = fs.readFileSync(tsFile, "utf-8");
-  const interfaceMatch = content.match(/export interface (\w+) \{/g);
-
-  if (!interfaceMatch) {
-    findings.push({
-      severity: "P1",
-      message: "generated/api-types.ts contains no interfaces",
-      file: "generated/api-types.ts",
-      blocking: false,
-      category: "general",
-      problem_class: "unknown",
-      required_skills: [],
-      required_reads: [],
-    });
-    return findings;
-  }
-
-  findings.push({
-    severity: "P2",
-    message: "API type checking requires backend model comparison (Python 3.10+ backend not available in TypeScript check)",
-    file: "generated/api-types.ts",
-    blocking: false,
-    category: "general",
-    problem_class: "unknown",
-    required_skills: [],
-    required_reads: [],
-  });
-
-  return findings;
-}

package/src/bollharness/src/scripts/checks/check_artifact_link.ts

@@ -1,156 +0,0 @@
-import * as fs from "fs";
-import * as path from "path";
-import { execSync } from "child_process";
-import { Finding } from "./finding";
-
-const CODE_EXTENSIONS = new Set([".py", ".ts", ".tsx", ".js", ".jsx"]);
-const CONFIG_EXTENSIONS = new Set([".json", ".yml", ".yaml", ".toml"]);
-const TEST_PREFIXES = ["tests/", "test_"];
-const ARTIFACT_PREFIXES = ["docs/issues/", "docs/decisions/"];
-const BUILD_DIRS = new Set([".open-next", "dist", "build", ".next", "node_modules"]);
-
-function isCodeFile(filePath: string): boolean {
-  const p = path.parse(filePath);
-  if (!CODE_EXTENSIONS.has(p.ext)) return false;
-  const parts = p.dir.split(path.sep);
-  for (const part of parts) {
-    if (part.startsWith("test_") || part === "tests") return false;
-  }
-  for (const part of parts) {
-    if (BUILD_DIRS.has(part)) return false;
-  }
-  return true;
-}
-
-function isArtifactFile(filePath: string): boolean {
-  return ARTIFACT_PREFIXES.some(prefix => filePath.startsWith(prefix)) && filePath.endsWith(".md");
-}
-
-function extractScope(artifactPath: string): string[] {
-  try {
-    const text = fs.readFileSync(artifactPath, "utf-8");
-    if (!text.startsWith("---")) return [];
-
-    const end = text.indexOf("\n---", 3);
-    if (end === -1) return [];
-
-    const frontmatter = text.slice(3, end);
-    const scopes: string[] = [];
-    let inScope = false;
-
-    for (const line of frontmatter.split("\n")) {
-      const stripped = line.trim();
-      if (stripped.startsWith("scope:")) {
-        const value = stripped.slice(6).trim();
-        if (value && !value.startsWith("[")) {
-          scopes.push(value);
-          inScope = false;
-        } else if (value.startsWith("[")) {
-          const inner = value.replace(/[\[\] ]/g, "");
-          scopes.push(...inner.split(",").filter(s => s));
-          inScope = false;
-        } else {
-          inScope = true;
-        }
-        continue;
-      }
-      if (inScope) {
-        if (stripped.startsWith("- ")) {
-          scopes.push(stripped.slice(2).trim().replace(/^["']|["']$/g, ""));
-        } else if (stripped && !stripped.startsWith("#")) {
-          inScope = false;
-        }
-      }
-    }
-
-    return scopes.filter(s => s);
-  } catch {
-    return [];
-  }
-}
-
-function checkScopeBinding(
-  codeFiles: string[],
-  artifactFiles: string[],
-  repoRoot: string
-): Finding[] {
-  const allScopes: string[] = [];
-  for (const af of artifactFiles) {
-    allScopes.push(...extractScope(path.join(repoRoot, af)));
-  }
-
-  if (allScopes.length === 0) return [];
-
-  const uncovered: string[] = [];
-  for (const cf of codeFiles) {
-    if (!allScopes.some(scope => cf.startsWith(scope))) {
-      uncovered.push(cf);
-    }
-  }
-
-  if (uncovered.length === 0) return [];
-
-  return [{
-    severity: "P2",
-    message: `Scope binding gap: ${uncovered.length} code file(s) not covered by any artifact scope. Uncovered: ${uncovered.slice(0, 5).join(", ")}${uncovered.length > 5 ? ` (and ${uncovered.length - 5} more)` : ""}. Add a scope field to the relevant artifact doc.`,
-    file: uncovered[0],
-    blocking: false,
-    category: "scope_binding",
-    problem_class: "unknown",
-    required_skills: ["lead"],
-    required_reads: [],
-  }];
-}
-
-function getChangedFiles(mode: string, repoRoot: string): string[] {
-  if (mode === "staged") {
-    try {
-      const result = execSync("git diff --cached --name-only", { cwd: repoRoot, encoding: "utf-8" });
-      return result.split("\n").map(l => l.trim()).filter(l => l);
-    } catch {
-      return [];
-    }
-  } else if (mode === "ci") {
-    try {
-      const result = execSync("git diff origin/main..HEAD --name-only", { cwd: repoRoot, encoding: "utf-8" });
-      return result.split("\n").map(l => l.trim()).filter(l => l);
-    } catch {
-      return [];
-    }
-  }
-  return [];
-}
-
-export function run(repoRoot: string, mode: string = "full"): Finding[] {
-  if (mode === "full") return [];
-
-  const files = getChangedFiles(mode, repoRoot);
-  if (!files.length) return [];
-
-  const codeFiles = files.filter(f => isCodeFile(f));
-  const artifactFiles = files.filter(f => isArtifactFile(f));
-  const hasCode = codeFiles.length > 0;
-  const hasArtifact = artifactFiles.length > 0;
-
-  const findings: Finding[] = [];
-
-  if (hasCode && !hasArtifact) {
-    findings.push({
-      severity: "P1",
-      message: `Code changes without artifact documentation. ${codeFiles.length} code file(s) changed but no docs/issues/ or docs/decisions/ file included. Add an issue or decision doc.`,
-      file: codeFiles[0],
-      blocking: true,
-      category: "artifact_linkage",
-      problem_class: "unknown",
-      required_skills: ["lead"],
-      required_reads: [],
-    });
-    return findings;
-  }
-
-  if (hasCode && hasArtifact) {
-    findings.push(...checkScopeBinding(codeFiles, artifactFiles, repoRoot));
-  }
-
-  return findings;
-}

package/src/bollharness/src/scripts/checks/check_bridge_deps.ts

@@ -1,11 +0,0 @@
-import * as fs from "fs";
-import * as path from "path";
-import { Finding } from "./finding";
-
-export function run(repoRoot: string, mode: string = "full"): Finding[] {
-  const findings: Finding[] = [];
-
-  if (mode !== "full" && mode !== "ci") return findings;
-
-  return findings;
-}

package/src/bollharness/src/scripts/checks/check_bugfix_binding.ts

@@ -1,11 +0,0 @@
-import * as fs from "fs";
-import * as path from "path";
-import { Finding } from "./finding";
-
-export function run(repoRoot: string, mode: string = "full"): Finding[] {
-  const findings: Finding[] = [];
-
-  if (mode !== "full" && mode !== "ci") return findings;
-
-  return findings;
-}

package/src/bollharness/src/scripts/checks/check_bugfix_binding_ci.ts

@@ -1,11 +0,0 @@
-import * as fs from "fs";
-import * as path from "path";
-import { Finding } from "./finding";
-
-export function run(repoRoot: string, mode: string = "full"): Finding[] {
-  const findings: Finding[] = [];
-
-  if (mode !== "full" && mode !== "ci") return findings;
-
-  return findings;
-}

package/src/bollharness/src/scripts/checks/check_doc_file_references.ts

@@ -1,11 +0,0 @@
-import * as fs from "fs";
-import * as path from "path";
-import { Finding } from "./finding";
-
-export function run(repoRoot: string, mode: string = "full"): Finding[] {
-  const findings: Finding[] = [];
-
-  if (mode !== "full" && mode !== "ci") return findings;
-
-  return findings;
-}