@backbencher/brain 0.0.0-stage → 0.1.1

package/docs/data/m10-baseline.json

@@ -0,0 +1,602 @@
+{
+  "schemaVersion": 1,
+  "milestone": "M10",
+  "issue": 116,
+  "packageVersion": "0.1.0",
+  "runtimeMcp": {
+    "toolNames": [
+      "bb_search",
+      "bb_ask",
+      "bb_health",
+      "bb_patterns",
+      "bb_security",
+      "bb_visualize",
+      "bb_migrate",
+      "bb_analyze",
+      "bb_doc",
+      "bb_edit",
+      "bb_index",
+      "bb_graph",
+      "bb_impact",
+      "bb_cross_language",
+      "bb_annotate",
+      "bb_annotations"
+    ],
+    "descriptors": {
+      "bb_search": {
+        "mutability": "read",
+        "requiresIndex": true,
+        "modes": [
+          "symbols",
+          "content",
+          "symbol",
+          "file"
+        ],
+        "required": [],
+        "properties": [
+          "mode",
+          "query",
+          "symbolName",
+          "filePath",
+          "limit",
+          "language",
+          "symbolKind",
+          "includeContent",
+          "exact",
+          "caseSensitive",
+          "regex",
+          "offset",
+          "refresh"
+        ],
+        "defaults": {
+          "mode": "symbols",
+          "limit": 15,
+          "includeContent": false,
+          "exact": false,
+          "caseSensitive": false,
+          "regex": false,
+          "offset": 0
+        }
+      },
+      "bb_ask": {
+        "mutability": "read",
+        "requiresIndex": true,
+        "modes": [
+          "answer"
+        ],
+        "required": [
+          "query"
+        ],
+        "properties": [
+          "query",
+          "limit"
+        ],
+        "defaults": {
+          "limit": 5
+        }
+      },
+      "bb_health": {
+        "mutability": "read",
+        "requiresIndex": false,
+        "modes": [
+          "status",
+          "refresh"
+        ],
+        "required": [],
+        "properties": [
+          "verbose",
+          "history",
+          "limit",
+          "refresh",
+          "force",
+          "wait",
+          "freshness",
+          "sampleSize",
+          "integrity",
+          "includeAnalysisRuns",
+          "paths",
+          "checkUnindexed"
+        ],
+        "defaults": {
+          "verbose": false,
+          "history": false,
+          "limit": 20,
+          "refresh": false,
+          "force": false,
+          "wait": true,
+          "freshness": "sampled",
+          "sampleSize": 200,
+          "integrity": false,
+          "includeAnalysisRuns": false
+        }
+      },
+      "bb_patterns": {
+        "mutability": "read",
+        "requiresIndex": true,
+        "modes": [
+          "orphaned",
+          "all"
+        ],
+        "required": [],
+        "properties": [
+          "scope",
+          "limit",
+          "includeOrphaned",
+          "includeFramework",
+          "includeAntiPatterns",
+          "confidenceThreshold",
+          "history",
+          "recordRun"
+        ],
+        "defaults": {
+          "scope": "all",
+          "limit": 20,
+          "includeOrphaned": true,
+          "includeFramework": true,
+          "includeAntiPatterns": true,
+          "confidenceThreshold": 0,
+          "history": false,
+          "recordRun": false
+        }
+      },
+      "bb_security": {
+        "mutability": "read",
+        "requiresIndex": true,
+        "modes": [
+          "findings"
+        ],
+        "required": [],
+        "properties": [
+          "history",
+          "recordRun",
+          "limit"
+        ],
+        "defaults": {
+          "history": false,
+          "recordRun": false,
+          "limit": 20
+        }
+      },
+      "bb_visualize": {
+        "mutability": "read",
+        "requiresIndex": true,
+        "modes": [
+          "project",
+          "file",
+          "module",
+          "symbol",
+          "feature"
+        ],
+        "required": [],
+        "properties": [
+          "scope",
+          "target",
+          "maxNodes",
+          "maxLinks",
+          "offset",
+          "relationshipTypes",
+          "symbolKinds",
+          "languages",
+          "excludePatterns",
+          "includeTests",
+          "view",
+          "layout",
+          "format"
+        ],
+        "defaults": {
+          "scope": "project",
+          "maxNodes": 200,
+          "maxLinks": 5000,
+          "offset": 0,
+          "format": "text"
+        }
+      },
+      "bb_migrate": {
+        "mutability": "read",
+        "requiresIndex": true,
+        "modes": [
+          "plan"
+        ],
+        "required": [
+          "targetLanguage"
+        ],
+        "properties": [
+          "symbolName",
+          "symbolNames",
+          "paths",
+          "symbolIds",
+          "targetLanguage",
+          "format"
+        ],
+        "defaults": {
+          "format": "text"
+        }
+      },
+      "bb_analyze": {
+        "mutability": "read",
+        "requiresIndex": true,
+        "modes": [
+          "callers",
+          "callees",
+          "trace",
+          "dependencies",
+          "stats",
+          "complexity",
+          "impact",
+          "test_mapping",
+          "test_gaps",
+          "test_impact",
+          "test_quality"
+        ],
+        "required": [
+          "mode"
+        ],
+        "properties": [
+          "mode",
+          "target",
+          "filePath",
+          "limit"
+        ],
+        "defaults": {
+          "limit": "25 edges per direction (callers/callees/trace); 20 files (dependencies); 50 entries (test_mapping/test_gaps); 50 files (test_quality)",
+          "target": "required for callers, callees, trace, impact, test_impact; optional file path or directory prefix for complexity",
+          "filePath": "optional path prefix (or an exact file) for dependencies, test_mapping, test_gaps, test_quality"
+        }
+      },
+      "bb_doc": {
+        "mutability": "read",
+        "requiresIndex": true,
+        "modes": [
+          "symbol",
+          "file",
+          "module",
+          "feature",
+          "api",
+          "project",
+          "coverage"
+        ],
+        "required": [
+          "mode"
+        ],
+        "properties": [
+          "mode",
+          "target",
+          "format",
+          "audience",
+          "detail",
+          "includeExamples",
+          "includeDiagrams",
+          "includeTests",
+          "limit",
+          "maxTokens",
+          "refresh"
+        ],
+        "defaults": {
+          "format": "markdown",
+          "audience": "developer",
+          "detail": "standard",
+          "includeExamples": false,
+          "includeDiagrams": false,
+          "includeTests": false,
+          "limit": 20,
+          "maxTokens": 8000
+        }
+      },
+      "bb_edit": {
+        "mutability": "write",
+        "requiresIndex": true,
+        "modes": [
+          "write",
+          "update",
+          "insert",
+          "delete",
+          "refactor",
+          "batch"
+        ],
+        "required": [
+          "mode"
+        ],
+        "properties": [
+          "mode",
+          "dryRun",
+          "filePath",
+          "symbolName",
+          "lineStart",
+          "content",
+          "newContent",
+          "targetSymbolName",
+          "position",
+          "newName",
+          "force",
+          "format",
+          "overwrite",
+          "edits",
+          "files"
+        ],
+        "defaults": {
+          "dryRun": false,
+          "format": true,
+          "force": false
+        }
+      },
+      "bb_index": {
+        "mutability": "write",
+        "requiresIndex": false,
+        "modes": [
+          "auto",
+          "file",
+          "dir",
+          "post"
+        ],
+        "required": [
+          "path"
+        ],
+        "properties": [
+          "path",
+          "mode"
+        ],
+        "defaults": {
+          "mode": "auto"
+        }
+      },
+      "bb_graph": {
+        "mutability": "read",
+        "requiresIndex": true,
+        "modes": [
+          "graph"
+        ],
+        "required": [
+          "symbol"
+        ],
+        "properties": [
+          "symbol",
+          "maxDepth",
+          "direction",
+          "relationshipTypes",
+          "includeCrossLanguage",
+          "timeBudgetMs",
+          "maxEdges",
+          "edgeLimit"
+        ],
+        "defaults": {
+          "maxDepth": 5,
+          "direction": "both"
+        }
+      },
+      "bb_impact": {
+        "mutability": "read",
+        "requiresIndex": true,
+        "modes": [
+          "impact"
+        ],
+        "required": [
+          "symbol"
+        ],
+        "properties": [
+          "symbol",
+          "relationshipTypes",
+          "file",
+          "refresh"
+        ],
+        "defaults": {}
+      },
+      "bb_cross_language": {
+        "mutability": "read",
+        "requiresIndex": true,
+        "modes": [
+          "cross-language"
+        ],
+        "required": [
+          "symbol"
+        ],
+        "properties": [
+          "symbol",
+          "limit"
+        ],
+        "defaults": {
+          "limit": 200
+        }
+      },
+      "bb_annotate": {
+        "mutability": "write",
+        "requiresIndex": false,
+        "modes": [
+          "annotate"
+        ],
+        "required": [
+          "symbol",
+          "body"
+        ],
+        "properties": [
+          "symbol",
+          "body",
+          "path",
+          "toolIdentity"
+        ],
+        "defaults": {}
+      },
+      "bb_annotations": {
+        "mutability": "read",
+        "requiresIndex": false,
+        "modes": [
+          "annotate"
+        ],
+        "required": [],
+        "properties": [
+          "symbol",
+          "path",
+          "limit",
+          "includeNameLevel"
+        ],
+        "defaults": {
+          "limit": 50
+        }
+      }
+    },
+    "postBaselineRepairs": {
+      "bb_index": "added M22 (8b71297) — was missing from this frozen baseline until repaired under M35.E1",
+      "bb_visualize.modes": "scope-only since M13.44 (859c0b0) — baseline had stale pre-M13.44 modes until repaired under M35.E1",
+      "aliases": "bb_reindex alias removed under M35.E1 (zero references, zero-alias policy)",
+      "M50.A5 re-freeze (#768)": "re-froze toolNames/descriptors/commands from the live registry so verify-contract-diff + verify-m10-baseline compare against the real surface (M28 graph/impact/cross-language/annotate tools and the M43 bb_search `refresh` option were missing)",
+      "M71 audit re-freeze": "re-cut every descriptor's properties/defaults/modes from the live registry. Growth since the M50.A5 cut: bb_health paths+checkUnindexed (788647abc, M64), bb_visualize symbolKinds/excludePatterns/includeTests+view+layout (M48/M13.44/codemap+class+regions), bb_migrate paths+symbolIds (16d789d78), bb_doc refresh, bb_impact refresh+relationshipTypes, bb_graph relationshipTypes/edgeLimit/maxEdges/timeBudgetMs (7aec61416)/direction/includeCrossLanguage plus the `direction` default, bb_cross_language limit plus its default, bb_annotations includeNameLevel+path (fb2c4b715), bb_patterns' confidenceThreshold default 0.6 -> 0, and bb_edit's overwrite/edits/files plus the `batch` mode (M13.E13/M71.D9). The CLI `search` contract is a human decision and stays hand-maintained: `[query]` is optional now (--symbol-name/--file-path may stand in) and the action refuses a search that supplies neither, so its frozen `required` is empty and that refusal is asserted behaviorally in script/m40/verify-a7-cli-parity.ts."
+    }
+  },
+  "cli": {
+    "commands": [
+      "help",
+      "tool",
+      "index",
+      "setup",
+      "show",
+      "doctor",
+      "upgrade",
+      "stats",
+      "status",
+      "projects",
+      "search",
+      "health",
+      "onboard",
+      "mcp",
+      "version",
+      "--version"
+    ],
+    "contracts": {
+      "index": {
+        "required": [
+          "dir"
+        ],
+        "options": [
+          "force"
+        ]
+      },
+      "search": {
+        "required": [],
+        "requiredNote": "`[query]` is OPTIONAL since the M43/M71 read path: `--symbol-name` and `--file-path` may stand in for it (the help's own `bb search --mode symbol --symbol-name handleRequest` example passes no positional at all, and with a required argument it exited 1). The action refuses a search that supplies none of the three, so the guarantee is preserved as BEHAVIOR — asserted by script/m40/verify-a7-cli-parity.ts — rather than by commander's required-argument check.",
+        "options": [
+          "dir",
+          "limit",
+          "language"
+        ]
+      },
+      "health": {
+        "required": [],
+        "options": [
+          "dir",
+          "refresh",
+          "force",
+          "no-wait",
+          "complete",
+          "integrity",
+          "sample-size"
+        ]
+      },
+      "mcp": {
+        "required": [],
+        "options": [
+          "dir"
+        ]
+      },
+      "tool": {
+        "required": [
+          "name"
+        ],
+        "options": [
+          "dir",
+          "args"
+        ]
+      },
+      "--version": {
+        "required": [],
+        "options": []
+      }
+    }
+  },
+  "libraryExports": [
+    "BrainDatabase",
+    "BrainSchema",
+    "ProjectSchema",
+    "ProjectID",
+    "CoreStorage",
+    "ASTEngine",
+    "indexProjectParallel",
+    "BrainTools",
+    "SemanticEngine",
+    "checkFileFreshness",
+    "checkResultsFreshness",
+    "hashFileContent",
+    "getProjectId",
+    "BACKBENCHER_BRAIN_VERSION",
+    "TOOL_DESCRIPTORS",
+    "serializeToolMetadata",
+    "toMcpToolList",
+    "validateToolDescriptors",
+    "ToolDescriptor",
+    "ToolDocumentation",
+    "ToolInputSchema"
+  ],
+  "legacyInventory": {
+    "sentinelCommands": [
+      "status",
+      "patrol",
+      "report",
+      "verify",
+      "hotspots",
+      "traps",
+      "trap_summary",
+      "validate_api",
+      "coverage_summary",
+      "coverage_gaps",
+      "taint_scan",
+      "auth_gate_scan",
+      "pii_report",
+      "cve_report"
+    ],
+    "sentinelSymbols": [
+      "sentinel",
+      "sentinelStatus",
+      "sentinelPatrol",
+      "sentinelReport",
+      "sentinelVerify",
+      "sentinelHotspots",
+      "sentinelTraps",
+      "sentinelTrapSummary",
+      "sentinelValidateApi",
+      "sentinelCoverageSummary",
+      "sentinelCoverageGaps",
+      "sentinelTaintScan",
+      "sentinelAuthGateScan",
+      "sentinelPiiReport",
+      "sentinelCveReport"
+    ],
+    "legacyFacades": [
+      "TestIntelligenceBrainTools",
+      "revolutionaryArchitectureIntelligence",
+      "BrainTools.quickAnswer",
+      "PatternBrainTools.detectPatterns",
+      "CrossLanguageSecurityAnalysis",
+      "CrossLanguageMigrationAssistant"
+    ],
+    "obsoletePersistenceMarkers": [
+      "sentinel_runs",
+      "sentinel_findings",
+      "FROM symbols",
+      "FROM files",
+      "symbol_relationships"
+    ],
+    "claimsToReview": [
+      "WORLD’S FIRST",
+      "revolutionary",
+      "No other tool in the world"
+    ]
+  },
+  "verification": {
+    "requiredCommands": [
+      "npm run typecheck",
+      "npm run build",
+      "npm run docs:verify",
+      "npm run verify"
+    ],
+    "fixture": "script/fixtures/contract-fixture.ts",
+    "requiredVerifier": "script/verify-m10-baseline.ts"
+  }
+}

package/docs/data/m10-benchmark-baseline.json

@@ -0,0 +1,57 @@
+{
+  "schemaVersion": 1,
+  "milestone": "M10",
+  "issue": 114,
+  "packageVersion": "0.1.0",
+  "declaredAt": "2026-08-10",
+  "budgetBasis": {
+    "fixtureHint": "contract-fixture (~6 source files, 1 test)",
+    "hardwareClass": "commodity development machine",
+    "runtime": "bun 1.3+",
+    "embeddingModelCompatibility": "compare same model name only"
+  },
+  "verificationExpectations": {
+    "tools": 10,
+    "verify-chain-stages": 36,
+    "equivalenceUnderParity": true
+  },
+  "perfBudgetsMs": {
+    "bb_search_symbol": 400,
+    "bb_ask_stat": 300,
+    "bb_ask_semantic": 2500,
+    "bb_search_content": 500,
+    "bb_analyze_graph": 400,
+    "bb_patterns_orphaned": 600,
+    "bb_patterns_all": 1500,
+    "bb_security_taint": 1200,
+    "bb_health_status": 800,
+    "bb_health_refresh": 60000,
+    "bb_visualize_project": 1000,
+    "bb_migrate_plan": 2000,
+    "bb_doc_symbol": 2500,
+    "bb_edit_write": 300,
+    "index_cold": 8000,
+    "index_warm_reindex": 1500
+  },
+  "correctnessExpectations": {
+    "tools.exactly": 10,
+    "tools.modeMatrix": "b10-baseline.json runtimeMcp.descriptors",
+    "library.exportsInclude": [
+      "BrainDatabase", "BrainSchema", "ProjectSchema", "ProjectID", "CoreStorage",
+      "ASTEngine", "indexProjectParallel", "BrainTools", "SemanticEngine",
+      "checkFileFreshness", "checkResultsFreshness", "hashFileContent", "getProjectId",
+      "BACKBENCHER_BRAIN_VERSION", "TOOL_DESCRIPTORS", "serializeToolMetadata",
+      "toMcpToolList", "validateToolDescriptors", "ToolDescriptor",
+      "ToolDocumentation", "ToolInputSchema"
+    ],
+    "semantic.classification": "semantic_candidate",
+    "orphans.classification": "static_finding",
+    "security.classification": "static_finding",
+    "testIntel.classification": "inferred",
+    "testIntel.runtimeCoveragePolicy": "available-false",
+    "patterns.findingMinFields": [
+      "rule", "engine", "severity", "confidence", "location", "linesOfCode",
+      "description", "remediation", "evidence", "limitations"
+    ]
+  }
+}