agentic-scorecard 0.3.1 → 0.4.0

package/benchmark/v0.4/controls/security.yaml

@@ -0,0 +1,143 @@
+dimension: security
+controls:
+  - id: ADRB-SEC-001
+    level: 1
+    title: Agent secret and sensitive-data boundaries are documented
+    outcome: Contributors can find agent-specific rules for credentials, secrets, and sensitive data.
+    risk: Agents expose credentials or sensitive data while planning, changing, or reporting work.
+    allow_agent_evidence: true
+    agent_evidence_scopes: [repository]
+    evidence:
+      - type: content_terms
+        scope: repository
+        files:
+          [
+            SECURITY.md,
+            AGENTS.md,
+            Agents.md,
+            agents.md,
+            .ai/AGENTS.md,
+            .ai/Agents.md,
+            .ai/constitution.md,
+            .ai/instructions/**/*.md,
+            .ai/rules/**/*.md,
+            .ai/skills/**/*.md,
+            .agents/**/*.md,
+            docs/security/**,
+            docs/agentic/**,
+          ]
+        terms: [secret, secrets, credential, credentials, sensitive data, personal data, PII]
+        min_terms: 2
+        max_span_lines: 80
+        max_files_per_pattern: 50
+    remediation: Document agent-specific rules for secrets, credentials, sensitive data, logs, prompts, and generated artifacts.
+  - id: ADRB-SEC-002
+    level: 2
+    title: Agent data and autonomy boundaries are explicit
+    outcome: Agent preflight guidance binds permitted data, tools, mutations, approvals, and stop conditions.
+    risk: Operators grant more data or authority than the task requires.
+    allow_agent_evidence: true
+    agent_evidence_scopes: [repository]
+    evidence:
+      - type: content_terms
+        scope: repository
+        files:
+          [
+            SECURITY.md,
+            AGENTS.md,
+            Agents.md,
+            agents.md,
+            .ai/AGENTS.md,
+            .ai/Agents.md,
+            .ai/constitution.md,
+            .ai/instructions/**/*.md,
+            .ai/rules/**/*.md,
+            .ai/skills/**/*.md,
+            .agents/**/*.md,
+            docs/security/**,
+            docs/agentic/**,
+            templates/**,
+          ]
+        terms:
+          [
+            data classification,
+            allowed tools,
+            mutation,
+            budget,
+            human approval,
+            autonomy,
+            stop condition,
+          ]
+        min_terms: 3
+        max_span_lines: 120
+        max_files_per_pattern: 50
+    remediation: Add a task preflight that binds data, tools, write scope, budget, approvals, and stop conditions.
+  - id: ADRB-SEC-006
+    level: 2
+    title: Security reporting and response are documented
+    outcome: Contributors can find a vulnerability-reporting or security-escalation path.
+    risk: Security concerns discovered during agent work lack an accountable response path.
+    allow_agent_evidence: true
+    agent_evidence_scopes: [repository]
+    evidence:
+      - type: content_terms
+        scope: repository
+        files: [SECURITY.md, docs/security/**, docs/contributing/**]
+        terms: [report, vulnerability, security contact, escalation, incident]
+        min_terms: 2
+        max_span_lines: 80
+    remediation: Publish a vulnerability-reporting and security-escalation path with response ownership.
+  - id: ADRB-SEC-003
+    level: 3
+    title: Automated secret-leakage safeguards are enforced
+    outcome: Repository or platform automation scans relevant changes for secrets before integration.
+    risk: Credentials can enter version history because secret safeguards are absent or merely documented.
+    allow_attestation: true
+    allow_agent_evidence: true
+    agent_evidence_scopes: [repository, platform]
+    evidence_mode: any
+    evidence:
+      - type: ci_command
+        scope: repository
+        min_tools: 1
+      - type: manual
+        scope: platform
+        prompt: Show that host-native secret scanning or push protection covers the assessed repository and relevant branches, including current status and controlled exceptions.
+    remediation: Run a secret-leakage safeguard in applicable CI or enable equivalent protected platform scanning with reviewable evidence.
+  - id: ADRB-SEC-007
+    level: 3
+    title: Untrusted agent-input safeguards are enforced
+    outcome: The harness bounds untrusted content and prompt-borne instructions with enforced isolation, validation, or tested handling.
+    risk: Repository, issue, tool, or retrieved content can redirect an agent beyond the authorized task and authority.
+    allow_attestation: true
+    allow_agent_evidence: true
+    agent_evidence_scopes: [repository, platform, organization]
+    evidence:
+      - type: manual
+        scope: organization
+        prompt: Show the untrusted-input boundaries and recent mechanical tests or enforcement evidence for prompt injection, sandbox escape, or unauthorized tool instructions.
+    remediation: Define untrusted-input boundaries and enforce them with sandboxing, validation, allowlists, or adversarial tests appropriate to the harness.
+  - id: ADRB-SEC-005
+    level: 3
+    title: High-impact agent actions are technically gated
+    outcome: External authority controls prevent unapproved high-impact actions and record controlled exceptions.
+    risk: Repository instructions alone cannot prevent credential misuse or irreversible external actions.
+    allow_attestation: true
+    allow_agent_evidence: true
+    evidence:
+      - type: manual
+        scope: platform
+        prompt: Show authorization gates, scoped credentials, approval enforcement, audit records, and controlled bypasses for high-impact agent actions.
+    remediation: Enforce least-privileged credentials, approval gates, auditability, and restricted exception handling.
+  - id: ADRB-SEC-004
+    level: 4
+    title: Agent security outcomes drive improvement
+    outcome: Denials, near misses, incidents, exceptions, and adversarial exercises are trended and improve controls.
+    risk: Controls appear complete while effectiveness against real failure modes remains unknown.
+    allow_attestation: true
+    allow_agent_evidence: true
+    evidence:
+      - type: manual
+        scope: outcome
+        prompt: Provide agent-security outcome trends or exercise results and a recent control change driven by them.
+    remediation: Run adversarial exercises, trend security outcomes, and update boundaries from the results.

package/benchmark/v0.4/controls/specification.yaml

@@ -0,0 +1,65 @@
+dimension: specification
+controls:
+  - id: ADRB-SPC-001
+    level: 1
+    title: Work has a durable objective
+    outcome: Engineering work starts from a tracked issue, request, or specification artifact.
+    risk: Agents optimize an inferred problem and completion cannot be judged consistently.
+    evidence:
+      - type: path_any
+        scope: repository
+        patterns: [docs/requirements/**, docs/spec*.md, docs/specs/**, specs/**, .ai/specs/**]
+    remediation: Adopt a tracked work-request or specification template with objective, owner, and outcome.
+  - id: ADRB-SPC-002
+    level: 2
+    title: Acceptance criteria and constraints are documented
+    outcome: Work artifacts state testable acceptance criteria plus material constraints or exclusions.
+    risk: An implementation can appear plausible without satisfying a shared definition of done.
+    allow_agent_evidence: true
+    agent_evidence_scopes: [repository]
+    evidence:
+      - type: content_terms
+        scope: repository
+        files: [docs/requirements/**, docs/spec*.md, docs/specs/**, specs/**, .ai/specs/**]
+        terms: [acceptance criteria, requirements, constraints, non-goals, verification]
+        min_terms: 2
+        max_span_lines: 160
+    remediation: Add testable outcomes, constraints, exclusions, and verification expectations to work artifacts.
+  - id: ADRB-SPC-003
+    level: 3
+    title: Specification traceability is mechanically checked
+    outcome: Automation checks that applicable changes and verification trace to an approved work artifact.
+    risk: Specifications become optional prose disconnected from implementation and tests.
+    allow_agent_evidence: true
+    agent_evidence_scopes: [repository]
+    evidence:
+      - type: ci_command
+        scope: repository
+        providers: []
+        tools: []
+        min_tools: 1
+    remediation: Add a deterministic traceability check from change to work artifact and verification record.
+  - id: ADRB-SPC-005
+    level: 3
+    title: Specification traceability is required before merge
+    outcome: Repository merge policy requires the applicable traceability check or equivalent review evidence.
+    risk: A configured check can be skipped or bypassed when delivery pressure rises.
+    allow_attestation: true
+    allow_agent_evidence: true
+    evidence:
+      - type: manual
+        scope: platform
+        prompt: Show that the traceability check or equivalent review requirement is an enforced merge gate with controlled exceptions.
+    remediation: Require the traceability check in merge policy and restrict, record, and review bypasses.
+  - id: ADRB-SPC-004
+    level: 4
+    title: Specification effectiveness drives improvement
+    outcome: Rework and escaped ambiguity attributable to specifications are trended and improve the process.
+    risk: Specification ceremony grows without reducing misunderstanding or rework.
+    allow_attestation: true
+    allow_agent_evidence: true
+    evidence:
+      - type: manual
+        scope: outcome
+        prompt: Provide specification-related rework or ambiguity trends and a recent process change driven by them.
+    remediation: Classify rework causes and evolve specification practices using outcome evidence.

package/benchmark/v0.4/controls/testing.yaml

@@ -0,0 +1,82 @@
+dimension: testing
+controls:
+  - id: ADRB-TST-001
+    level: 1
+    title: Automated tests exist
+    outcome: The tracked repository contains executable tests for at least one important behavior.
+    risk: Agent changes rely on plausibility or manual inspection alone.
+    evidence:
+      - type: path_any
+        scope: repository
+        patterns: ['**/*.test.*', '**/*.spec.*', tests/**, test/**]
+    remediation: Add a fast automated test for a critical behavior and document how to run it.
+  - id: ADRB-TST-002
+    level: 2
+    title: Verification layers and canonical commands are documented
+    outcome: Contributors can identify applicable test layers and the canonical verification path.
+    risk: Agents run a convenient subset and overstate confidence in the result.
+    allow_agent_evidence: true
+    agent_evidence_scopes: [repository]
+    evidence:
+      - type: content_terms
+        scope: repository
+        files:
+          [
+            README.md,
+            CONTRIBUTING.md,
+            AGENTS.md,
+            Agents.md,
+            agents.md,
+            .ai/AGENTS.md,
+            .ai/Agents.md,
+            .ai/constitution.md,
+            .ai/instructions/**/*.md,
+            .ai/rules/**/*.md,
+            .ai/skills/**/*.md,
+            .agents/**/*.md,
+            docs/testing/**,
+            package.json,
+            Makefile,
+          ]
+        terms: [unit test, integration test, end-to-end, e2e, typecheck, lint, test]
+        min_terms: 2
+        required_any_terms: [verify, verification, test, check, CI]
+        max_span_lines: 120
+        max_files_per_pattern: 50
+    remediation: Define the test taxonomy and one canonical command that matches CI.
+  - id: ADRB-TST-003
+    level: 3
+    title: CI executes the required verification layers
+    outcome: Repository automation runs appropriate tests and static checks from a clean state.
+    risk: Documented verification can be omitted from automation or run in an unrepresentative environment.
+    allow_agent_evidence: true
+    agent_evidence_scopes: [repository]
+    evidence:
+      - type: ci_command
+        scope: repository
+        min_tools: 2
+    remediation: Configure CI to run the applicable verification layers from a clean environment.
+  - id: ADRB-TST-005
+    level: 3
+    title: Verification is enforced before merge
+    outcome: Merge policy requires the applicable CI checks and restricts bypasses.
+    risk: Healthy CI configuration remains optional under delivery pressure.
+    allow_attestation: true
+    allow_agent_evidence: true
+    evidence:
+      - type: manual
+        scope: platform
+        prompt: Show required status checks or equivalent merge gates, covered branches, bypass actors, and exception controls.
+    remediation: Make appropriate CI checks required merge gates and restrict, record, and review bypasses.
+  - id: ADRB-TST-004
+    level: 4
+    title: Verification effectiveness drives improvement
+    outcome: Escaped defects, flakiness, and other signal-quality outcomes are trended and improve testing.
+    risk: Test count and coverage rise while meaningful defects still escape.
+    allow_attestation: true
+    allow_agent_evidence: true
+    evidence:
+      - type: manual
+        scope: outcome
+        prompt: Provide verification outcome trends by task class and a recent test-strategy improvement driven by them.
+    remediation: Trend escaped defects and signal quality, then invest in the weakest verification layers.

package/benchmark/v0.4/controls/tooling.yaml

@@ -0,0 +1,69 @@
+dimension: tooling
+controls:
+  - id: ADRB-TOL-001
+    level: 1
+    title: Supported agent tools are declared
+    outcome: The tracked repository identifies supported agent interfaces or tool configuration.
+    risk: Agents discover tools opportunistically and use unsupported or unsafe paths.
+    allow_agent_evidence: true
+    agent_evidence_scopes: [repository]
+    evidence:
+      - type: path_any
+        scope: repository
+        patterns: [.ai/agentic.config.*, .ai/skills/**, .agents/**, mcp.json, .mcp.json]
+    remediation: Commit a non-empty declaration of supported agent surfaces and their intended use.
+  - id: ADRB-TOL-002
+    level: 2
+    title: Tool scope and failure behavior are documented
+    outcome: Tool guidance defines authority, validation, success signals, failure handling, and approved fallback.
+    risk: Agents bypass failures, widen scope, or mistake partial results for success.
+    allow_agent_evidence: true
+    agent_evidence_scopes: [repository]
+    evidence:
+      - type: content_terms
+        scope: repository
+        files:
+          [
+            AGENTS.md,
+            Agents.md,
+            agents.md,
+            .ai/AGENTS.md,
+            .ai/Agents.md,
+            .ai/agentic*.md,
+            .ai/instructions/**/*.md,
+            .ai/rules/**/*.md,
+            .ai/skills/**/*.md,
+            .agents/**/*.md,
+            docs/agentic/**,
+            docs/tools/**,
+          ]
+        terms: [authority, permission, read-only, validation, failure, fallback, approval]
+        min_terms: 3
+        required_any_terms: [tool, MCP, connector, skill, command, agent]
+        max_span_lines: 120
+        max_files_per_pattern: 50
+    remediation: Document each high-impact tool's authority, inputs, validation, failure mode, and fallback.
+  - id: ADRB-TOL-003
+    level: 3
+    title: High-impact tool authority is technically bounded and audited
+    outcome: High-impact tools enforce least privilege, authorization, structured validation, and audit records.
+    risk: Prompt instructions become the only barrier between an agent and an irreversible action.
+    allow_attestation: true
+    allow_agent_evidence: true
+    evidence:
+      - type: manual
+        scope: platform
+        prompt: Show technical least-privilege enforcement, authorization tests, validation, audit records, and fail-closed behavior for high-impact tools.
+    remediation: Enforce scoped credentials, authorization, schema validation, audit logging, and deny-by-default behavior.
+  - id: ADRB-TOL-004
+    level: 4
+    title: Tool reliability drives improvement
+    outcome: Tool success, partial failure, denial, latency, and unsafe-fallback attempts are trended and improved.
+    risk: Tooling quality and risky workarounds remain anecdotal until an incident occurs.
+    allow_attestation: true
+    allow_agent_evidence: true
+    evidence:
+      - type: manual
+        scope: outcome
+        prompt: Provide tool reliability trends and a recent tool or fallback improvement driven by them.
+    remediation: Trend tool outcomes by task and risk class and improve weak or bypassed interfaces.

package/benchmark/v0.4/report-schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentic-readiness.dev/schema/v0.4/report.json",
+  "title": "ADRB v0.4 assessment report",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "benchmark",
+    "target",
+    "assessed_at",
+    "warnings",
+    "score",
+    "evidence_summary",
+    "dimensions",
+    "controls",
+    "profiles",
+    "readiness",
+    "limitations"
+  ],
+  "properties": {
+    "schema_version": { "const": "0.4.0" },
+    "benchmark": {
+      "type": "object",
+      "required": ["id", "version"],
+      "properties": { "version": { "const": "0.4.0" } }
+    },
+    "target": {
+      "type": "object",
+      "required": [
+        "repository",
+        "profile",
+        "scope",
+        "git_head",
+        "git_remote",
+        "working_tree_dirty"
+      ],
+      "properties": { "scope": { "enum": ["tracked", "workspace"] } }
+    },
+    "assessed_at": { "type": "string", "format": "date-time" },
+    "warnings": { "type": "array", "items": { "type": "string" } },
+    "score": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["total", "maximum", "percentage", "repository"],
+      "properties": {
+        "total": { "type": "integer", "minimum": 0, "maximum": 40 },
+        "maximum": { "const": 40 },
+        "percentage": { "type": "integer", "minimum": 0, "maximum": 100 },
+        "repository": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["achieved", "ceiling", "percentage"],
+          "properties": {
+            "achieved": { "type": "integer", "minimum": 0, "maximum": 40 },
+            "ceiling": { "type": "integer", "minimum": 0, "maximum": 40 },
+            "percentage": { "type": "integer", "minimum": 0, "maximum": 100 }
+          }
+        }
+      }
+    },
+    "evidence_summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "repository_detected",
+        "agent_collected",
+        "attested",
+        "unmet",
+        "unknown",
+        "resolved",
+        "total"
+      ],
+      "properties": {
+        "repository_detected": { "type": "integer", "minimum": 0 },
+        "agent_collected": { "type": "integer", "minimum": 0 },
+        "attested": { "type": "integer", "minimum": 0 },
+        "unmet": { "type": "integer", "minimum": 0 },
+        "unknown": { "type": "integer", "minimum": 0 },
+        "resolved": { "type": "integer", "minimum": 0 },
+        "total": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "dimensions": { "type": "array", "minItems": 10, "maxItems": 10 },
+    "controls": { "type": "array" },
+    "profiles": { "type": "array" },
+    "readiness": { "type": "object" },
+    "limitations": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/benchmark/v0.4/scoring-policy.md

@@ -0,0 +1,175 @@
+# v0.4 scoring policy
+
+This document is normative for benchmark version 0.4.0.
+
+## Unit and assessment scope
+
+The unit is one repository plus explicitly supplied repository-semantic, external, and
+organizational evidence bound to that repository. The default `tracked` mode considers only
+Git-tracked paths, using their current working-tree contents. Reports record the commit, remote, and
+dirty state. `workspace` mode is available for provisional assessment and is not directly
+comparable with tracked-mode reports.
+
+Generated reports, attestations, evidence requests, and imported evidence bundles never qualify as
+repository evidence. An assessment must be idempotent: adding its own generated artifacts cannot
+change its score.
+
+## Dimension scores
+
+Each dimension earns level `n` only when every applicable control at that level and every lower
+level is met. More than one control may exist at a level when separate observable outcomes are
+required. Controls met above the first gap are reported but do not increase the dimension score.
+
+The normative score is the sum of ten dimension scores, with a maximum of 40. Its percentage is
+display-only and does not determine readiness.
+
+### Repository-detected progress
+
+v0.4 also reports an explanatory repository score and ceiling. For each dimension, the ceiling is
+the highest consecutive level for which every control has a deterministic, non-manual repository
+collector. The achieved value is the highest consecutive level established only with
+`repository-detected` evidence. The two values are summed across dimensions.
+
+Agent-collected and human-attested evidence never increases repository-detected progress. The
+repository percentage is `achieved / ceiling`; it does not replace the normative score, remove
+UNKNOWN controls, or affect readiness-profile decisions.
+
+## Readiness decisions
+
+Each autonomy profile defines a floor for every dimension. A profile passes only if every floor is
+met. Strength in one dimension cannot compensate for a security, testing, governance, or recovery
+gap elsewhere. No profile grants deployment or production authority.
+
+When a passed target profile depends on agent-collected or human-attested controls, the report's
+target-profile headline discloses the number of required controls from each provenance class.
+
+## Evidence scopes and provenance
+
+- `repository-detected`: a deterministic collector found qualifying evidence in the selected path
+  scope. It proves the reported artifact match, not consistent human behavior or external
+  enforcement.
+- `agent-collected`: an authorized agent supplied a structured, source-backed repository-semantic
+  or external claim. It may satisfy only explicitly eligible controls and is never independently
+  verified.
+- `attested`: an accountable person supplied a dated, expiring claim and durable reference.
+- `unknown`: evidence is unavailable, expired, mismatched, unauthorized, or inconclusive.
+
+Repository controls use non-empty files, control-specific term thresholds, semantic component
+groups, structurally identifiable non-placeholder ownership mappings, enabled integration-triggered
+CI invocations with adapter-declared full action identities plus explicit refs or executable plus
+required argument-group signatures and prohibited non-blocking modes, executable step/job structure,
+auto-loaded provider entry points, supported complete conditions and inheritance, no unparsed path
+or exclusion gates, and blocking foreground exit-status
+propagation, bounded line windows, and per-pattern candidate limits. Partial evidence remains
+visible but does not pass a control. An ownership artifact, explicit accountable-human approval
+authority, and explicit accountable-human merge authority are independently required for
+`ADRB-GOV-002`; a generic owner/reviewer mention or declared agent authority cannot establish either
+human authority. Directly negated authority statements do not count as positive evidence whether
+negation appears before or after the matched phrase, including a colon-delimited policy label, and
+explicit mappings require a recognized repository-wide target or path/component target rather than
+arbitrary or punctuation-only syntax.
+Typed ownership-table scope columns may use substantive component names, while conventional
+plain-text former-owner sections remain inactive. Restrictive phrases such as `must not exceed`
+establish an upper bound and are not treated as absence of the control.
+`ADRB-RES-002` requires resource budgets and retry bounds as independent co-located components;
+neither substitutes for the other.
+Mechanical Level 3 context, environment, specification, testing, and learning controls require
+structurally recognized CI commands; comments, documentation, and command-name keywords do not
+establish execution. `ADRB-ENV-003` requires a locked installation plus independent test and
+static-analysis command classes in the same CI execution group; commands split across jobs or
+workflow files do not prove that one clean environment performs canonical verification. GitHub
+event conditions are part of that identity, so commands restricted to mutually exclusive
+`pull_request` and `merge_group` executions do not combine.
+`ADRB-TST-003`
+requires independent test and static-analysis command classes aggregated across the assessed CI
+entry points. Root package-manager tasks must
+resolve to tracked script definitions whose command bodies establish the applicable command class,
+including when supported wrappers or global package-manager options precede the invocation.
+Context-changing package/workspace options require resolution of the selected manifest or fail
+closed; nested package-exec tools may qualify only at a supported executable position.
+Custom guidance validators additionally require adapter-declared validation structures in the
+executed tracked source after language comments are excluded; file presence or comment text alone
+does not establish behavior. Specification-traceability and knowledge-curation checks use the same
+source-bound standard. A recognized specification validator binds an approved work-item reference
+to both implementation and verification artifacts; checking only for a heading is insufficient.
+Constant-false branches and validation functions without a top-level reachable call path fail closed.
+Required structural groups cannot combine across unreachable function bodies. JavaScript/TypeScript
+class methods, object shorthand methods, and object arrow methods fail closed when the conservative
+collector cannot prove their invocation.
+Tool-specific discovery or listing modes do not count as execution. In a supported fail-fast shell,
+each multiline command may contribute because any failure gates the step; without fail-fast
+semantics, only the final effective foreground command may establish execution.
+Catalog pattern order is significant when a candidate limit is present: authoritative entry points
+precede large run, skill, or documentation corpora. External platform, organization, and outcome
+controls cannot be inferred from repository keywords.
+
+Human attestations and agent evidence may satisfy only controls explicitly eligible for those
+classes. A v0.4 control may permit an `agent-collected` repository claim when a legitimate tracked
+artifact uses an unrecognized convention. This is a semantic alternative, not a deterministic
+pass: it remains separately labelled and does not increase repository-detected progress. Human
+attestations cannot override repository-artifact controls. `ADRB-SEC-003` permits a dated, expiring
+human attestation only for its platform alternative, such as host-native secret scanning or push
+protection; it cannot attest the repository CI alternative. Malformed or unknown v0.4 attestation
+control IDs are rejected rather than silently ignored. Every v0.4 attestation file is bound to the
+assessed repository's normalized, sanitized origin URL, or its canonical root when no origin exists,
+and rejects unknown file or claim fields. An optional remote `.git` suffix does not change target
+identity. Human attestations are repository-bound and expiring but not
+commit-bound: they establish accountable platform, organization, or outcome facts whose review
+period may span repository commits. `agentic-scorecard init` derives the target; a file for another
+repository fails closed. A non-`unknown` attestation with a generated `TODO` owner or evidence value
+fails closed, as does any attestation whose review date is later than the assessment time.
+
+Controls require every evidence check by default. A v0.4 control may explicitly declare
+`evidence_mode: any` only when the checks are alternative ways to establish the same outcome. A
+repository-only run remains `unknown` when the repository alternative is absent and an external
+alternative has not been collected; it does not infer either a platform pass or a platform failure.
+Supplemental evidence resolves only alternatives with the same scope. A negative claim makes the
+control `not_met` only when every alternative is established negatively; any uncollected alternative
+keeps the control `unknown`.
+The report shows every alternative and its provenance. Control confidence comes from the
+alternative that establishes the decisive pass or complete negative result; supplemental input on a
+different alternative does not relabel the result or its evidence-summary/profile dependency.
+An unresolved control always serializes control confidence as `none`; the supplemental input remains
+visible in its separately labelled claim fields.
+Established-control tables display the scope of the evidence that resolved the control rather than
+an unresolved alternative scope.
+
+Level 4 requires time-series or outcome evidence and an improvement decision influenced by it. The
+existence of a dashboard is insufficient.
+
+## Agent evidence bundles
+
+An agent evidence bundle is version-bound and target-bound. Claims record scope, status, collector,
+collection and expiry times, a privacy-safe derivation summary, and durable references. The core
+scanner makes no network calls; the agent obtains explicit authorization and uses read-only tools to
+create the bundle. An error is distinct from a negative result and cannot pass a control.
+
+Agent evidence can satisfy only controls with `allow_agent_evidence: true` and an allowed scope.
+Deterministic passes take precedence. Repository-scoped claims additionally require tracked files
+to match HEAD and references of the form `repo:<tracked-path>[#Lx-Ly]`; every referenced path must
+exist in the tracked assessment scope at the exact bound commit. Untracked generated artifacts do
+not affect tracked-scope evidence. An agent may use such a claim only to
+establish the control outcome from a nonstandard artifact the deterministic catalog did not
+recognize.
+
+`ADRB-SEC-007` deliberately accepts source-backed agent claims at repository, platform, or
+organization scope because enforced untrusted-input safeguards may be implemented as tracked
+adversarial harness tests, platform sandbox or tool policy, or organization-wide controls. The
+claim's scope must identify where enforcement actually resides. Repository-scoped claims remain
+commit-bound and line-referenced; no scope may pass from prose alone, and deterministic repository
+keyword scanning is not an evidence path for this non-compensating security floor.
+
+## Changes and comparability
+
+v0.1, v0.2, and v0.3 remain immutable. Scores from v0.1, v0.2, v0.3, and v0.4 are not directly
+comparable because evidence and control semantics changed. Reports are comparable only when
+benchmark version, target profile, repository scope, evidence policy, and assessment mode match.
+
+## Claims
+
+Allowed: “We self-assessed repository X against ADRB v0.4.0 on DATE; N controls were
+repository-detected, M agent-collected, and P human-attested. Repository-detected progress was A of
+an offline ceiling C.”
+
+Not allowed: “Certified,” “compliant,” “safe,” “secure,” or “independently verified” based only on
+this self-assessment.