@bolloon/bolloon-agent 0.1.0

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

@@ -0,0 +1,156 @@
+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

@@ -0,0 +1,11 @@
+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

@@ -0,0 +1,11 @@
+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

@@ -0,0 +1,11 @@
+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

@@ -0,0 +1,11 @@
+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_freshness.ts

@@ -0,0 +1,141 @@
+import * as fs from "fs";
+import * as path from "path";
+import { execSync } from "child_process";
+import { Finding } from "./finding";
+
+function countRouteDecorators(repoRoot: string): number {
+  const routesDir = path.join(repoRoot, "backend", "product", "routes");
+  if (!fs.existsSync(routesDir)) return 0;
+
+  let count = 0;
+  try {
+    const files = fs.readdirSync(routesDir).filter(f => f.endsWith(".py"));
+    for (const file of files) {
+      const content = fs.readFileSync(path.join(routesDir, file), "utf-8");
+      const matches = content.match(/@router\.(get|post|put|patch|delete|websocket)\(/g);
+      if (matches) count += matches.length;
+    }
+  } catch {}
+  return count;
+}
+
+function countScenes(repoRoot: string): number {
+  const scenesDir = path.join(repoRoot, "scenes");
+  if (!fs.existsSync(scenesDir)) return 0;
+  try {
+    return fs.readdirSync(scenesDir).filter(f => {
+      const fullPath = path.join(scenesDir, f);
+      return fs.statSync(fullPath).isDirectory() && !f.startsWith(".");
+    }).length;
+  } catch {
+    return 0;
+  }
+}
+
+function countADRs(repoRoot: string): number {
+  const decisions = path.join(repoRoot, "docs", "decisions");
+  if (!fs.existsSync(decisions)) return 0;
+  try {
+    return fs.readdirSync(decisions).filter(f => f.startsWith("ADR-") && f.endsWith(".md")).length;
+  } catch {
+    return 0;
+  }
+}
+
+function countPlans(repoRoot: string): number {
+  const decisions = path.join(repoRoot, "docs", "decisions");
+  if (!fs.existsSync(decisions)) return 0;
+  try {
+    return fs.readdirSync(decisions).filter(f => f.startsWith("PLAN-") && f.endsWith(".md")).length;
+  } catch {
+    return 0;
+  }
+}
+
+function extractRoadmapNumbers(repoRoot: string): Record<string, string> {
+  const roadmap = path.join(repoRoot, "docs", "ROADMAP.md");
+  if (!fs.existsSync(roadmap)) return {};
+
+  const content = fs.readFileSync(roadmap, "utf-8");
+  const numbers: Record<string, string> = {};
+  const regex = /\|\s*(\S[^|]+?)\s*\|\s*(\S[^|]+?)\s*\|/g;
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    const key = match[1].trim();
+    const val = match[2].trim();
+    if (key !== "指标" && key !== "---") {
+      numbers[key] = val;
+    }
+  }
+  return numbers;
+}
+
+export function run(repoRoot: string, mode: string = "full"): Finding[] {
+  const findings: Finding[] = [];
+
+  const actualRoutes = countRouteDecorators(repoRoot);
+  const routesDoc = path.join(repoRoot, ".boll", "rules", "backend-routes.md");
+  const claudeMd = path.join(repoRoot, "CLAUDE.md");
+
+  if (fs.existsSync(routesDoc)) {
+    const routesContent = fs.readFileSync(routesDoc, "utf-8");
+    const routeClaims = routesContent.match(/-\s+`(?:GET|POST|PUT|PATCH|DELETE|WS)\s+/g) || [];
+    const docRoutes = routeClaims.length;
+    if (actualRoutes - docRoutes > 5) {
+      findings.push({
+        severity: "P1",
+        message: `.boll/rules/backend-routes.md documents ${docRoutes} routes but code has ${actualRoutes} decorators (gap: ${actualRoutes - docRoutes})`,
+        file: ".boll/rules/backend-routes.md",
+        blocking: false,
+        category: "doc_integrity",
+        problem_class: "unknown",
+        required_skills: [],
+        required_reads: [],
+      });
+    }
+  }
+
+  const actualADRs = countADRs(repoRoot);
+  const actualPlans = countPlans(repoRoot);
+  const roadmapNums = extractRoadmapNumbers(repoRoot);
+
+  if ("ADR" in roadmapNums) {
+    const match = roadmapNums["ADR"].match(/\d+/);
+    if (match) {
+      const claimed = parseInt(match[0], 10);
+      if (actualADRs - claimed > 2) {
+        findings.push({
+          severity: "P2",
+          message: `ROADMAP claims ${claimed} ADRs but ${actualADRs} exist`,
+          file: "docs/ROADMAP.md",
+          blocking: false,
+          category: "doc_integrity",
+          problem_class: "unknown",
+          required_skills: [],
+          required_reads: [],
+        });
+      }
+    }
+  }
+
+  if ("PLAN" in roadmapNums) {
+    const match = roadmapNums["PLAN"].match(/\d+/);
+    if (match) {
+      const claimed = parseInt(match[0], 10);
+      if (actualPlans - claimed > 3) {
+        findings.push({
+          severity: "P2",
+          message: `ROADMAP claims ${claimed} PLANs but ${actualPlans} exist`,
+          file: "docs/ROADMAP.md",
+          blocking: false,
+          category: "doc_integrity",
+          problem_class: "unknown",
+          required_skills: [],
+          required_reads: [],
+        });
+      }
+    }
+  }
+
+  return findings;
+}

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

@@ -0,0 +1,36 @@
+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 docFiles = ["CLAUDE.md", "docs/ROADMAP.md", "README.md"];
+  const maxAgeDays = 7;
+
+  for (const docFile of docFiles) {
+    const fullPath = path.join(repoRoot, docFile);
+    if (!fs.existsSync(fullPath)) continue;
+
+    try {
+      const stats = fs.statSync(fullPath);
+      const ageMs = Date.now() - stats.mtimeMs;
+      const ageDays = Math.floor(ageMs / (1000 * 60 * 60 * 24));
+
+      if (ageDays > maxAgeDays) {
+        findings.push({
+          severity: "P2",
+          message: `${docFile} has not been updated in ${ageDays} days (threshold: ${maxAgeDays})`,
+          file: docFile,
+          blocking: false,
+          category: "doc_freshness",
+          problem_class: "unknown",
+          required_skills: [],
+          required_reads: [],
+        });
+      }
+    } catch {}
+  }
+
+  return findings;
+}

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

@@ -0,0 +1,11 @@
+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 !== "staged") return findings;
+
+  return findings;
+}

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

@@ -0,0 +1,40 @@
+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 fragmentDir = path.join(repoRoot, "scripts", "context-fragments");
+  const routerFile = path.join(repoRoot, "src", "scripts", "context_router.ts");
+
+  if (!fs.existsSync(routerFile)) {
+    findings.push({
+      severity: "P1",
+      message: "context_router.ts not found",
+      file: "src/scripts/context_router.ts",
+      blocking: false,
+      category: "governance_bootstrap",
+      problem_class: "unknown",
+      required_skills: [],
+      required_reads: [],
+    });
+    return findings;
+  }
+
+  if (!fs.existsSync(fragmentDir)) {
+    findings.push({
+      severity: "P2",
+      message: "context-fragments directory not found",
+      file: "scripts/context-fragments/",
+      blocking: false,
+      category: "governance_bootstrap",
+      problem_class: "unknown",
+      required_skills: [],
+      required_reads: [],
+    });
+    return findings;
+  }
+
+  return findings;
+}

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

@@ -0,0 +1,70 @@
+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 hookFiles = [
+    "src/scripts/hooks/loop-detection.ts",
+    "src/scripts/hooks/risk-tracker.ts",
+    "src/scripts/hooks/stop-evaluator.ts",
+    "src/scripts/hooks/guard-feedback.ts",
+    "src/scripts/hooks/deploy-guard.ts",
+  ];
+
+  const settingsFile = path.join(repoRoot, ".boll", "settings.json");
+
+  if (!fs.existsSync(settingsFile)) {
+    findings.push({
+      severity: "P1",
+      message: ".boll/settings.json does not exist",
+      file: ".boll/settings.json",
+      blocking: false,
+      category: "general",
+      problem_class: "unknown",
+      required_skills: [],
+      required_reads: [],
+    });
+    return findings;
+  }
+
+  try {
+    const settings = JSON.parse(fs.readFileSync(settingsFile, "utf-8"));
+    const registeredHooks = settings.hooks || {};
+
+    for (const [stage, hooks] of Object.entries(registeredHooks)) {
+      const hookList = hooks as Array<{ hooks?: Array<{ command?: string }> }>;
+      for (const hookGroup of hookList) {
+        for (const hook of hookGroup.hooks || []) {
+          const cmd = hook.command || "";
+          if (cmd.includes("python3") && cmd.includes(".py")) {
+            findings.push({
+              severity: "P1",
+              message: `Hook in ${stage} still references Python script: ${cmd}`,
+              file: ".boll/settings.json",
+              blocking: false,
+              category: "governance_bootstrap",
+              problem_class: "unknown",
+              required_skills: [],
+              required_reads: [],
+            });
+          }
+        }
+      }
+    }
+  } catch (exc) {
+    findings.push({
+      severity: "P1",
+      message: `Failed to parse settings.json: ${exc}`,
+      file: ".boll/settings.json",
+      blocking: false,
+      category: "governance_bootstrap",
+      problem_class: "unknown",
+      required_skills: [],
+      required_reads: [],
+    });
+  }
+
+  return findings;
+}

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

@@ -0,0 +1,51 @@
+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 docsIssuesDir = path.join(repoRoot, "docs", "issues");
+
+  if (!fs.existsSync(docsIssuesDir)) {
+    return findings;
+  }
+
+  const issueFiles = fs.readdirSync(docsIssuesDir).filter(f => f.endsWith(".md"));
+
+  for (const issueFile of issueFiles) {
+    const issuePath = path.join(docsIssuesDir, issueFile);
+    const content = fs.readFileSync(issuePath, "utf-8");
+
+    const hasStatus = /^(status|State):\s*/im.test(content);
+    const hasResolution = /^(resolution|Closed):\s*/im.test(content);
+
+    if (!hasStatus) {
+      findings.push({
+        severity: "P2",
+        message: `Issue ${issueFile} missing status field`,
+        file: `docs/issues/${issueFile}`,
+        blocking: false,
+        category: "doc_integrity",
+        problem_class: "unknown",
+        required_skills: [],
+        required_reads: [],
+      });
+    }
+
+    if (!hasResolution) {
+      findings.push({
+        severity: "P2",
+        message: `Issue ${issueFile} missing resolution/closed field`,
+        file: `docs/issues/${issueFile}`,
+        blocking: false,
+        category: "doc_integrity",
+        problem_class: "unknown",
+        required_skills: [],
+        required_reads: [],
+      });
+    }
+  }
+
+  return findings;
+}

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

@@ -0,0 +1,11 @@
+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_security.ts

@@ -0,0 +1,54 @@
+import * as fs from "fs";
+import * as path from "path";
+import { Finding } from "./finding";
+
+const SENSITIVE_PATTERNS = [
+  { pattern: /api[_-]?key["\s:=]+["'][a-zA-Z0-9]{20,}["']/gi, severity: "P0" as const },
+  { pattern: /password["\s:=]+["'][^"']{8,}["']/gi, severity: "P0" as const },
+  { pattern: /secret["\s:=]+["'][a-zA-Z0-9]{16,}["']/gi, severity: "P0" as const },
+  { pattern: /token["\s:=]+["'][a-zA-Z0-9]{20,}["']/gi, severity: "P1" as const },
+  { pattern: /bearer\s+[a-zA-Z0-9]{20,}/gi, severity: "P1" as const },
+];
+
+export function run(repoRoot: string, mode: string = "full"): Finding[] {
+  const findings: Finding[] = [];
+
+  if (mode !== "full" && mode !== "ci") return findings;
+
+  const extensions = [".ts", ".tsx", ".js", ".jsx", ".py", ".json", ".yaml", ".yml"];
+
+  function scanDir(dir: string): void {
+    if (!fs.existsSync(dir)) return;
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!entry.name.startsWith(".") && entry.name !== "node_modules") {
+          scanDir(fullPath);
+        }
+      } else if (extensions.includes(path.extname(entry.name))) {
+        const content = fs.readFileSync(fullPath, "utf-8");
+        for (const { pattern, severity } of SENSITIVE_PATTERNS) {
+          const matches = content.match(pattern);
+          if (matches) {
+            findings.push({
+              severity,
+              message: `Potential secret detected: ${matches[0].slice(0, 30)}...`,
+              file: path.relative(repoRoot, fullPath),
+              blocking: severity === "P0",
+              category: "security",
+              problem_class: "secret_exposure",
+              required_skills: [],
+              required_reads: [],
+            });
+          }
+        }
+      }
+    }
+  }
+
+  scanDir(repoRoot);
+
+  return findings;
+}

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

@@ -0,0 +1,11 @@
+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_versions.ts

@@ -0,0 +1,11 @@
+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/finding.ts

@@ -0,0 +1,35 @@
+export interface Finding {
+  severity: "P0" | "P1" | "P2";
+  message: string;
+  file: string;
+  line?: number;
+  blocking: boolean;
+  category: string;
+  problem_class: string;
+  required_skills: string[];
+  required_reads: string[];
+}
+
+export function createFinding(params: {
+  severity: "P0" | "P1" | "P2";
+  message: string;
+  file: string;
+  line?: number;
+  blocking?: boolean;
+  category?: string;
+  problem_class?: string;
+  required_skills?: string[];
+  required_reads?: string[];
+}): Finding {
+  return {
+    severity: params.severity,
+    message: params.message,
+    file: params.file,
+    line: params.line,
+    blocking: params.blocking ?? false,
+    category: params.category ?? "general",
+    problem_class: params.problem_class ?? "unknown",
+    required_skills: params.required_skills ?? [],
+    required_reads: params.required_reads ?? [],
+  };
+}