Tool · Go · Experimental dynamic analysis

BRAG: evidence-backed repository analysis

README.md

BRAG produces evidence-backed summaries of bounded Git history and static repository measurements. It keeps selected-contributor activity distinct from repository-wide evidence and does not rank contributors or infer individual impact. Default analysis is read-only and offline; opt-in dynamic tests execute repository code and are not sandboxed. Requires Go 1.22 or newer. From the repository root, go install ./cmd/brag installs brag to GOBIN or GOPATH/bin; alternatively, go build -trimpath -o ./brag ./cmd/brag builds a local executable to run as ./brag. The root brag binary is Git-ignored and is not a release artifact. BRAG is licensed under Apache-2.0; see LICENSE.

sh
1brag --base origin/main                 # branch contribution history
2brag --selected 'Ada Lovelace=ada@x'    # selected contributor override
3brag all                                # all commits reachable from HEAD

Runs from any repository subdirectory, but evaluates configuration and Git state from repository top-level. Branch scope uses only configured upstream metadata, or requires explicit --base REF; it resolves and records the ref commit and merge-base. Merge-base is not necessarily the original branch creation point. all includes HEAD and only commits reachable from HEAD; it has no fabricated net-change baseline. history.included_commit_ids is the exact set measured.

Identity config

--selected NAME=EMAIL overrides current identity from local Git user.name/user.email. If neither source yields both values, selected contributor identity and metrics are unavailable; the CLI never chooses a contributor by ranking. Optional .brag.json (or --config FILE) format:

json
1{"version":1,"identities":[{"name":"Ada Lovelace","email":"ada@x","available":true}],"aliases":{"ada-old@x":"ada@x"}}

--identity NAME=EMAIL and --alias EMAIL=CANONICAL_EMAIL are repeatable overrides. Matching uses case-insensitive email. Commit authorship and Co-authored-by trailers are separate counts. A contributor may appear in both, so coauthor counts can overlap author counts and do not sum to commit count.

Metric interpretation

Per-commit numstat is cumulative churn (changed lines summed over commits), not net snapshot change. Binary files are omitted. Merge commits use git diff-tree combined-diff default and can have no counted changes. Source churn is the subset of recognized source extensions, not a measure of quality or unique/current lines. Author-commit ratio numerator is that identity’s authored commits and denominator is all included commits; value is null for zero denominator. The working tree overlay compares the final tracked index+worktree state to HEAD exactly once, including staged and unstaged edits, tracked additions/deletions/renames; it is not attributed. Untracked files are checked for presence only; contents are not read. Overlay is a snapshot difference, distinct from cumulative history churn.

Schema: schema/brag-v2.schema.json, version 2. Schema v1 remains Phase 1 compatible; adding required engineering_evidence is a breaking output-contract change, so Phase 2 reports use schema version 2. working_tree_state_identity is SHA-256 over git diff --raw -z --no-ext-diff --no-renames HEAD --: relative tracked-path diff metadata only, excluding untracked files and contents. selected_identity is separate. Branch scope reports source snapshot net change against the pinned merge-base; all marks it unavailable because it has no selected snapshot baseline. This net measure is not attributed to any contributor. Commit churn belongs to the commit author; coauthor counts are separate and may overlap author counts. Repository ratio denominator is all included commits. Unmeasured categories have explicit unavailable status/reason: pull_requests, code_reviews, test_coverage, test_effectiveness, reliability, maintainability, and duplication. Security has static indicators in engineering_evidence; its vulnerability scanner is separately marked unavailable/not run. Complexity, test inventory, and documentation/source-doc evidence are reported in engineering_evidence; historical ratios may be partial when merges or limits prevent complete attribution. Output includes no timestamps, absolute repository paths, random identifiers, or scores.

Phase 2 evidence (accepted with documented limitations)

Schema v2 adds required engineering_evidence while preserving Phase 1 fields. The static Go evidence was accepted after controlled fixture, schema-instance, reproducibility, and bounded performance checks; see the roadmap for category decisions and evidence. complexity uses custom brag-go-ast-v2 Go AST rules (not a standard score): cyclomatic starts at 1 and adds if, loops, switch/select statements and each case/communication clause, plus each &&/||; cognitive adds each control statement plus nesting depth and each else; clauses add no nesting; function literals are excluded from enclosing metrics and are not independently keyed. Physical lines include declaration start/end. Distributions use lower-middle median, nearest-rank p95, max, top-decile share; thresholds are cyclomatic >10, cognitive >15, nesting >4, lines >100. Branch snapshots are pinned merge-base, HEAD and current tracked worktree; all has HEAD/current only. Function identity is package/file/receiver/name. No complexity change is attributed to a person. Recognized non-Go source extensions are listed with per-snapshot counts as unsupported across Go-only measurements. Git tree blobs use ls-tree/cat-file and blob size is checked before reading; current sources use tracked regular files only and do not follow symlinks. Limits are 2,000 Go files, 1 MiB/file, 20 MiB/snapshot, 100 changed-function details, and 50 parse-failure paths per snapshot.

test_inventory inventories top-level conventional test functions only in _test.go: TestX/BenchmarkX require exact *testing.T/*testing.B, no receiver/type parameters/results; TestMain(*testing.M) is separate; examples are named/signature inventory only and may not be runnable without output declarations. Test-to-production ratio is executable TestX functions / non-test named function declarations. calls to the test function’s *testing.T parameter .Run count call sites, not runtime subtests; table-driven sites heuristically require a range, composite literal and t.Run in one test function. Definitions are compared by file/kind/name and full-declaration hash; moves/renames are ambiguous. Snapshot inventory is separate from historical attribution: bounded first-parent comparisons of changed _test.go blobs count only new valid TestX definition keys (full declaration hashes distinguish modifications from additions). Root commits compare with an empty parent; merges are excluded and mark the result partial. Commit author and Co-authored-by identities use the existing alias resolution; coauthor credits may overlap author credits. selected_tests_added_ratio is selected-credited introduced TestX functions / all newly introduced TestX functions; all_tests_added_ratio is TestX functions introduced / analyzed included commits; when history limits stop the scan early, the report marks the ratio partial and discloses analyzed and omitted commits. Both carry explicit integer denominators and units. History caps are 500 commits, 100 changed test files/commit, 5,000 files and 20 MiB of blobs; parse-failure paths cap at 50; limit/read/parse/author failures mark results partial. Current tracked overlay remains separate and unattributed. Test snapshot analysis uses the 2,000 Go-file, 1 MiB/file, 20 MiB total-byte limits; details cap at 500 definitions/snapshot.

documentation counts parsed Go packages with package comments, exported declaration-symbol doc presence, and exported interface-method doc presence. Each exported function/method/type/const/var name counts once; grouped declaration comments attach to each contained name. Ratios include numerator/denominator and units. This records comment presence only, not quality. Tracked .md, .markdown, .rst, .adoc, .txt, .html, and .htm files compare by blob/content identity. Canonical Code generated ... DO NOT EDIT. comments classify generated outputs; other generation provenance is unknown. //go:generate source files/directives and recognized template/config patterns (templates/, codegen/, .tmpl, .template, .gotmpl, buf.gen.yaml, stringer.conf) are counted without running generators. Documentation/generation evidence is repository-wide and not attributed to authors. Per-snapshot Go/doc file and byte limits are disclosed; detail arrays cap at 100 changes, doc inventory at 500 files, and parse-failure paths at 50 per snapshot.

architecture reports tracked Go packages and direct internal/external imports, test-only imports, fan-in/out, transitive-only internal reachability (excluding direct imports), cycles, and snapshot comparisons. Module-path classification comes from tracked root go.mod; build tags, replace directives, unresolved paths, parse/resource limits may make a snapshot partial. This is static import coupling, not runtime coupling or dependency resolution. security inventories direct go.mod requirements and source locations for selected crypto, HTTP/handler, process-execution, syscall/privilege, unsafe, and lexical auth-related indicators. These indicators do not establish vulnerability, reachability, or exploitability. The vulnerability scanner is explicitly unavailable/not run because no advisory data/scanner is integrated. Architecture/security are repository-wide, not person-attributed. duplication is explicitly unavailable/unmeasured; no simplistic text metric is used. Analysis does not execute code from the repository being measured, invoke generators/scanners, resolve or download its modules, or use the network; BRAG itself is built and run to produce the report. See roadmap.

Identity/config and scope options are shown above; brag --help shows CLI usage. Default .brag.json is read only when tracked in Git; --config FILE is an explicit opt-in to read that file. The full roadmap and acceptance criteria are in docs/ROADMAP.md.

Harness-agnostic Agent Skill

BRAG includes a portable Agent Skills companion embedded in the executable, so brag skill install works from a source build or go install. By default it installs to the shared user location $HOME/.agents/skills/brag; use --project for the current Git root’s .agents/skills/brag. The project-level .agents/skills path is documented by Codex and supported by Gemini CLI, Cursor, and VS Code/Copilot in documented versions. The user-level .agents path is documented for Codex and Gemini; other hosts use native user paths.

Use repeatable --agent options for native host paths, for example brag skill install --agent pi --agent claude. --agent all selects one documented path per common harness group. Existing identical files are left unchanged; a different SKILL.md is preserved unless --force is supplied. Installation only copies the skill and does not run BRAG or contact a model provider.

TargetProject pathUser pathNotes
agents / codex.agents/skills/brag~/.agents/skills/bragShared project path for several hosts; user-level path is documented for Codex/Gemini.
claude.claude/skills/brag~/.claude/skills/bragClaude Code; OpenCode also discovers project .claude/skills.
pi.pi/skills/brag~/.pi/agent/skills/bragPi native path.
gemini.gemini/skills/brag~/.gemini/skills/bragGemini CLI native path; project .agents is also supported.
opencode.opencode/skills/brag~/.config/opencode/skills/bragOpenCode native path.
cursor.cursor/skills/brag~/.cursor/skills/bragCursor native path; project .agents is also supported.
copilot.github/skills/brag~/.copilot/skills/bragGitHub Copilot/VS Code native path; project .agents is also supported.

For project --agent all, BRAG installs to .agents (Codex/Gemini/Cursor/Copilot), .claude (Claude/OpenCode), and .pi (Pi). For user --agent all, it installs to .agents (Codex/Gemini), plus the native Claude, Pi, OpenCode, Cursor, and Copilot paths. Discovery paths and support vary by harness/version; no single directory is universal. Use brag skill install --help for details.

Pi static integration (Phase 4A)

The minimal extension in .pi/extensions/brag.js registers /brag and /brag all. For arbitrary analyzed repositories, copy the trusted extension and its sibling schema to Pi’s global extension directory (for example, ~/.pi/agent/extensions/brag.js and ~/.pi/agent/extensions/brag-v2.schema.json); do not load extension code from the analyzed repository. When BRAG_BIN or BRAG_GIT is unset, the extension resolves brag or git from absolute entries in the Pi process’s PATH; empty and relative PATH entries are ignored. Explicit overrides must be absolute executable paths. Use a trusted Pi PATH; the extension canonicalizes the selected executables and restricts the child process’s PATH to the selected Git directory. Optionally set BRAG_SELECTED=NAME=EMAIL there to pass the CLI’s existing --selected override to either command. This value must be non-empty, bounded, and free of control characters. If unset, the CLI may use configured local Git user.name/user.email; neither the extension nor CLI infers a person from commit history. A tracked .brag.json can continue to resolve canonical identities and aliases. If the CLI has no available identity, the report is explicitly repository-only; an identity with no matching commits receives zero history counts, not inferred attribution. /brag requires the repository’s configured upstream unless the operator explicitly sets BRAG_BASE to a non-empty Git ref (passed as --base REF); empty, option-like, whitespace/control-containing values are rejected. /brag all invokes all, optionally with the selected identity, and ignores BRAG_BASE. Any other command arguments are rejected without spawning a process. The extension adds no base or scope fallback. It resolves executable realpaths, refuses a BRAG binary within the analyzed repository, invokes argv-only with a 30-second/8 MiB bound, scrubs inherited Git overrides, and sets PATH to the configured Git executable directory. The timeout bounds the BRAG child; it does not guarantee process-group cleanup of Git descendants if the limit fires.

Only schema-v2 output is accepted and validated against the bundled copy of schema/brag-v2.schema.json; unknown top-level fields are rejected. The extension reads no sidecars or source files directly, though the CLI report may already contain bounded source-line evidence. A bounded projection of validated status, provenance, denominators, snapshots, working-tree state, and static engineering evidence is sent to Pi’s configured model provider for an evidence-linked response. The complete CLI report retains the ordered history IDs; the projection keeps the history boundary, count, and first/last IDs instead of forwarding the full list. It can include contributor names/emails, commit IDs, repository paths/package names, and static source-line excerpts; follow the provider’s data-handling policy. The response is a compact Markdown evidence dashboard: an at-a-glance band followed by exactly six cards (Contributions, Complexity, Testing, Documentation, Security, and Engineering usability), with concise labels and source references rather than narrative paragraphs. It separates developer-attributable measurements from repository-wide measurements. For a selected identity, it is instructed to show the author-commit numerator/denominator and percentage from the same author_commit_ratio. Complexity, test inventory/test additions, architecture, and Go-source security indicators are Go-only; non-Go source is disclosed as unsupported for those categories. Documentation evidence covers tracked document files plus Go comments. It must preserve denominators and unavailable states; PRs/reviews, dynamic coverage and defect sensitivity are unavailable in the default schema-v2 path, tests are inventoried but not run, static indicators are not vulnerability findings, and complexity is not developer-specific maintainability. If no selected identity is available, it labels the output repository-only and does not infer a developer from authors. During the BRAG-triggered agent run, it empties the active tool list and blocks every Pi tool_call event, including codemode/deferred calls, until Pi settles; any queued messages in that run share this restriction. It then restores the prior tool list. Optional BRAG_DIAGNOSTICS=1 writes bounded stage and digest metadata, HTTP status when exposed, assistant stop/outcome, and usage metadata to Pi’s stderr without report, prompt, response, header, or error-message content. Independent side effects from other extensions outside Pi’s tool-call path are not controlled. Configure executable paths only from a trusted environment; report strings are untrusted data, not instructions. Phase 4A creates no separate agent report schema, and later Phase 4 work remains unimplemented.

Opt-in dynamic Go tests (experimental Phase 3A, accepted with limits)

Dynamic tests are never run by default. Dynamic and mutation execution require --expected-root PATH, which must identify the canonical Git repository root; this is an accidental-target guard, not an OS sandbox. Dynamic test code remains unsandboxed and can access host APIs. brag --base REF --dynamic-tests --expected-root PATH (or brag all --dynamic-tests --expected-root PATH) opts into executing go test -json -count=1 -shuffle=off ./... in disposable tracked-file snapshots; --dynamic-repeat 1..3, --dynamic-timeout (maximum 10m), and --dynamic-total-timeout (maximum 30m) bound execution; timeout values must be positive whole milliseconds and are recorded exactly in milliseconds. --dynamic-artifacts DIR is required for durable logs and coverage; it must be outside the analyzed repository and have private permissions (existing caller-owned directories are never chmodded). Go toolchain selection and module access are locally constrained (GOTOOLCHAIN=local, GOPROXY=off, GOSUMDB=off, GOWORK=off, read-only module mode) using a sanitized child environment. Test stdout/stderr are each capped at 1 MiB, snapshots at 5,000 files / 16 MiB per file / 128 MiB total, coverage profiles at 8 MiB each, and artifacts at 96 MiB per invocation. all executes only current tracked working-tree state; branch scope selects baseline, HEAD, and current tracked state. Dynamic reports use schema v3; ordinary reports remain v2. Caller SIGINT/SIGTERM cancellation emits the static report with dynamic status cancelled, then exits 130. The report summarizes test/package counts and aggregate coverage; per-test/per-package results, coverable-unit identities, and per-package comparison details are stored in bounded structured JSON artifacts referenced by the report. Coverage comparisons identify run order and require exact coverable-unit identity sets; empty denominators are not comparable. Package profile attribution is reported unavailable unless profile paths exactly map to package events. Results/durations are execution evidence and must not be treated as deterministic static measurements. Repeated differing outcomes are only observed instability, not proof of flakiness.

On Darwin/Linux subprocesses run in a process group which is terminated on cancellation; other operating systems report dynamic execution unavailable rather than running without that cleanup mechanism. Safety: this is not a sandbox. A Go test can execute arbitrary code with the current user’s host privileges and access host APIs; do not run untrusted repositories. Go network/module lookup is disabled, but this does not prevent arbitrary test code from attempting network access.

Opt-in Go mutation testing (Phase 3B.1) and test contributions (Phase 3B.2)

--test-contributions is accepted only alongside --mutation-tests; branch scope emits schema v5 with exactly one mutation snapshot, while all scope uses the schema-v7 current-author comparison described below. It verifies/reuses the selected Phase 3B.1 manifest and source/test identities, inventories bounded top-level tests by package/file/name/full-declaration hash, and executes anchored escaped package-scoped selectors on fresh copies for controls and selected test/mutation pairs. A passing isolated control and complete attributable selected-test failure are required for detected; a complete pass is not_detected; event, setup, package, skip, timeout, output, artifact and control failures are inconclusive. Repeats 1..3 that differ are unstable. The report provides bounded pair counts, detector/overlap evidence, confirmed unique mutations only when every eligible selected test outcome is valid, set-derived marginal evidence (not remove-test reruns), suite/isolated disagreements, and a bounded private matrix artifact with SHA-256. Schema v5 describes the matrix and requires artifact paths to pair with lowercase SHA-256 digests. Every executed selector control and pair has a private output evidence artifact path and SHA-256 in that matrix; logs may contain repository test output and remain in the explicitly configured private artifact directory. Evidence and matrix writes share Phase 3B.1’s aggregate artifact budget, so persistence failure makes affected outcomes inconclusive. Package initialization and TestMain still run. In branch scope, merge-base _test.go blobs are overlaid byte-for-byte on the selected source snapshot and evaluated against the same mutation IDs. Definition changes use package/file/kind/name plus full declaration hash; included first-parent commits attribute exact introduced/modified versions to commit authors and Co-authored-by identities via configured aliases. Current tracked test versions differing from HEAD are counted as uncommitted/unattributed. Group deltas require complete valid outcomes for the same mutations and report incomplete denominators. Branch-scope schema-v5 reports compare against the merge-base test set; brag all uses the separate schema-v7 current-author comparison described below. Contribution mode limits tests to 200/population, matrix pairs to 1,000 across populations, repeats to 1..3, per evaluation to 5m maximum, and total contribution evaluation to 30m maximum (defaults: 1 repeat, 1m, 10m); output/event and matrix artifacts reuse the dynamic output/artifact limits. Contribution attribution scans the supplied ordered commit history in 500-commit Git-diff chunks rather than truncating to an oldest-500 prefix. Changed test files outside the current candidate paths are not parsed. Bounds are 8 MiB changed-path output/chunk, 32 MiB total path output, 100 relevant changed test files/commit, 5,000 relevant changed-file revisions, 20 MiB total changed-test blobs, 50,000 definition events, and 32 MiB historical module metadata. Any bound or unreadable/malformed history marks attribution partial and withholds current cohorts; merge commits and Git-detected test-file renames are explicitly uncertain; copies at new paths use distinct path identities. Current provenance comes from the latest establishing event for the definition key, including its author and coauthors, and only credits an exact current committed definition hash; recurring hashes do not recover older credits. The separate static test_inventory TestX-additions analysis remains capped at 500 commits. A candidate test path whose historical package belongs to a nested module is marked partial rather than credited to the root module; unrelated nested-module test paths outside the candidate set are ignored. Historical module identities are cached once per revision. Acceptance review: Phase 3B.2 is accepted with documented limitations (see the roadmap decision). This accepts bounded experimental evidence only; it does not establish causal defect-detection contribution or developer impact. Schema v4 behavior is unchanged without the option.

With brag all --mutation-tests --test-contributions, the opt-in CLI emits schema v7 and adds a current-snapshot selected-author-only versus other-author-only test comparison. Membership uses only the selected/configured identity and first-parent definition-change history resolved through configured aliases and Co-authored-by; tests credited to both sides and tests lacking resolvable history are disclosed separately and never treated as peers. If identity is unavailable or history is partial, shared_tests and unattributed_tests are null, and indeterminate_tests counts the full current test population; cohorts are withheld. The two cohorts use the identical tracked-worktree source identity and mutation ID list. Deterministic package/cohort-stratified test selection is bounded to 200 tests total across both cohorts, and pair evaluation is bounded to 1,000 total (up to 500 per cohort); each cohort discloses eligible, selected, and omitted test counts. Pair omissions use selected tests × selected mutation IDs; omitted mutation IDs are reported separately. detected_mutations counts mutation IDs (not test/mutation pairs) with a complete outcome denominator across every selected test and passing control, as disclosed by complete_mutation_denominator_unit. Bounded control/pair output artifacts and a matrix with source/test/mutation provenance are persisted under the existing private artifact budget and referenced by SHA-256; persistence failures make affected outcomes inconclusive and aggregates partial. Existing per-cohort detected counts and denominators retain their meaning: each uses that cohort’s own complete outcomes and is not directly comparable when the complete mutation sets differ. The v7 paired_comparison derives a shared denominator from the intersection of mutation IDs with valid passing controls and terminal outcomes for every selected test in both cohorts. It lists paired and omitted mutation IDs with omission reasons, and partitions paired IDs into selected-only detected, other-only detected, both detected, and neither detected. Its denominator is null when either cohort or the mutation population is unavailable; an empty cohort keeps its existing per-cohort denominator at zero with status unavailable, not as a measured zero detection rate. The paired denominator is zero when both cohorts have selected tests but no mutation has complete outcomes in both. Missing, failing, unstable, timed-out, unexecuted, or artifact-incomplete outcomes are omitted, never counted as survivors. Selector controls and mutation/test evaluations run sequentially in deterministic interleaved rounds; the round’s first cohort receives at most half the remaining time, the starting cohort alternates, and budget-truncated work remains incomplete. No extrapolation is performed. Package relevance is not matched. Test selection is deterministic and package/cohort-stratified, while mutation selection takes the lowest stable IDs without package/operator stratification; neither sample is representative or an equal measure of responsibility or difficulty. This is experimental CLI evidence only—not a quality score, causal claim, or Pi/default-schema-v2 integration. Schema v6 remains unchanged; v7 adds the required paired report, and existing schema v5 branch behavior is unchanged.

brag --base REF --mutation-tests --dynamic-artifacts DIR (or brag all --mutation-tests) opts into schema v4 mutation evidence. This cannot be combined with --dynamic-tests; static commands run neither test workflow. Branch defaults to HEAD, all scope to current tracked worktree. Repeat --mutation-snapshot baseline|HEAD|current_tracked_worktree to choose available branch snapshots. --mutation-limit selects at most 20 stable-ID mutants per snapshot (maximum 50); --mutation-package and --mutation-path are repeatable filters (union within a filter, intersection across filters). Tests always run against ./..., regardless of source filter. Stable selection is lexicographically lowest deterministic mutant IDs; the bounded scan is 10,000 candidates/snapshot.

Operator brag-go-mutation-v1 changes one token: </<=, >/>=, ==/!=, &&/||, and true/false. Boolean swaps are emitted only when Go object resolution confirms the identifier is an unshadowed predeclared constant; declarations, shadowed uses, and selector names are excluded and disclosed. Generated source, vendor, test files, nested-module source, Go-command-ignored hidden/underscore/testdata directories, platform-suffixed Go files, and any Go file with build constraints are excluded and reported as skipped. The report records host GOOS/GOARCH, per-run/total timeout values, and the fixed test command/configuration. Package filters are Go import-path prefixes and require a tracked root go.mod module path; paths must be safe repo-relative paths. The root summary separates killed, survived, invalid, inconclusive and not-executed counts; score is killed/(killed+survived), null when denominator is zero. A killed result requires a passing control followed by a valid test failure. Compile-invalid candidates and setup/dependency/infrastructure/output/timeout/cancellation/artifact problems are not counted killed. The deterministic manifest is separate from execution outcomes and records operator version, filters, selected sites with exact source expression/token and line/column, and source/test snapshot identities. The control and each mutant run in a fresh disposable copy; structured outcome evidence records control/test results and per-mutant failing test identities. Bounded manifest/outcome/log artifacts are referenced by the report with SHA-256 identities. Known eligible/unselected counts are distinct from an incomplete/unknown population. No individual-test or developer contribution is inferred.

Per-run/total timeouts and artifact/output bounds reuse Phase 3A limits (2m/10m defaults, 10m/30m maxima, 1 MiB per output stream, 96 MiB aggregate artifacts). This remains experimental: tests run with host-user privileges and can access host APIs/network; module lookup constraints do not sandbox test code. Candidate detection is AST-based; only source in the go test ./... package population is considered. Generated/test/vendor, nested-module, Go-ignored, platform-suffixed and build-constrained files are excluded; boolean identifiers are emitted only when predeclared-object resolution is certain. Parse failures or scan caps can leave populations incomplete. Schema v4 is separate; v1-v3 contracts remain unchanged. Example: 4 killed, 8 survived, 1 invalid, 2 inconclusive yields score 4/12 = 0.333; invalid/inconclusive/not-executed are excluded from the denominator.

Development tests

Run BRAG’s own tests offline from the source root:

sh
1GOTOOLCHAIN=local GOPROXY=off GOSUMDB=off go test -short -count=1 ./... # fast loop
2GOTOOLCHAIN=local GOPROXY=off GOSUMDB=off go test -count=1 ./...        # full suite

Short mode skips slow fixture test-suite execution/compilation integrations, signal/descendant-process integration, and the 10,000-commit scale fixture. It retains parsing, schemas, calculations, static attribution, execution-root/artifact safety checks, and branch/all static non-execution markers. Full mode runs all integration and scale tests, including unsandboxed test execution in synthetic local fixtures; short mode is not a substitute for that coverage. Both modes build a temporary CLI and use local Git fixtures. Run test invocations sequentially: TestMain currently shares a temporary CLI path across invocations.

Author evidence (initial metadata slice)

sh
1brag author-evidence --selected 'Name=email' --all
2brag author-evidence --selected 'Name=email' --base REF

Without either scope override, this new command reads Git config brag.base; if absent it asks through an actionable error, never guessing main/master or a branch upstream. --all and --base are mutually exclusive. A base compares pinned merge-base(ref, HEAD)..HEAD, not a proven creation point; a configured HEAD boundary may yield zero commits. Use --all for historical author scope. Identity must be explicit; tracked .brag.json and existing identity/alias flags apply. Authored and Co-authored-by matches are distinguished and counted once. Target is HEAD; overlay and execution flags are unsupported.

The new brag-author-evidence-v1 / brag-author-metadata-v1 output streams scoped commit metadata with bounded resources, not a commit-count prefix. It retains bounded recent selected messages separately from analyzed totals, preserves raw/canonical identities, parents and hashes/encodings, and reports partial/unknown populations honestly. Overall author-test evidence remains partial: source/test changes, current lineage, helper context, authority and model analysis are explicitly unavailable/not_collected. No analyzed code or provider executes. Legacy commands/default schemas are unchanged. See the contract and limits.