agentic-scorecard 0.1.0 → 0.2.0

package/AGENT_PROMPT.md

@@ -1,10 +1,10 @@
-# Ask an AI coding agent to run the benchmark
+# Ask an AI coding agent to run ADRB v0.2
 
-These prompts are deliberately vendor-neutral. The agent needs terminal access to the repository and
-permission to download the published npm package. The benchmark itself runs locally, invokes no
-model, uploads no source, and makes no network calls after package installation.
+These prompts are vendor-neutral. The agent needs terminal access to the repository and permission
+to download the published npm package. The default benchmark runs locally, reads only tracked paths,
+invokes no model, uploads no source, and makes no network calls after installation.
 
-## Recommended: first assessment
+## Recommended: repository baseline
 
 Copy and paste:
 
@@ -12,25 +12,57 @@ Copy and paste:
 Assess this repository's readiness for AI-agent pull-request work.
 
 From the repository root, run:
-npx --yes agentic-scorecard@0.1.0 assess . --profile pr-creation --format markdown --output .agentic/reports/agentic-readiness-v0.1.0.md
+npx --yes agentic-scorecard@0.2.0 assess . --profile pr-creation --scope tracked --format markdown --output .agentic/reports/agentic-readiness-v0.2.0.md
 
-Do not change product source code, configuration, policies, or tests. Do not create or mark manual
-attestations as met. Read the generated report and tell me:
+Do not change product source, configuration, policies, or tests. Do not invent evidence or mark an
+attestation as met. Read the report and tell me:
 1. the score and highest passed readiness profile;
 2. whether the pr-creation target passes;
-3. each target-profile blocker and the evidence that was or was not found;
-4. the five highest-value improvements in dependency order; and
-5. any likely false positive, false negative, or organizational control that repository inspection
-   cannot prove.
-
-Keep tool-verified and self-attested evidence clearly separated. Leave the generated report
-uncommitted unless I explicitly ask you to commit it. If the command cannot run, explain the exact
-blocker without changing the repository to work around it.
+3. each target-profile blocker and its evidence scope;
+4. the five highest-value improvements in dependency order;
+5. which findings are repository gaps versus external or outcome evidence not yet established; and
+6. any likely false positive or false negative.
+
+Keep repository-detected, agent-collected, and human-attested evidence separate. Leave generated
+artifacts uncommitted unless I explicitly ask otherwise. If the command cannot run, explain the
+exact blocker without modifying the repository to work around it.
 ```
 
+## Agent-assisted external evidence
+
+Use this only after reviewing the repository baseline:
+
+```text
+Collect the external evidence that ADRB v0.2 could not establish from tracked repository files.
+
+First run:
+npx --yes agentic-scorecard@0.2.0 init-evidence .
+
+Read `.agentic/evidence-request.md` and the empty target-bound
+`.agentic/agent-evidence.yaml` bundle. Before accessing any connected system, tell me which
+read-only tools, accounts, repositories, branches, dashboards, and time ranges you need. Wait for
+my authorization.
+
+After authorization, use only least-privileged read-only operations. For each eligible control,
+record the source-backed status, scope, concise derivation, collection time, 30-day-or-shorter
+expiry, and durable privacy-safe references. Add only claims you actually attempted. Do not paste
+credentials, prompts, source excerpts, raw logs, personal data, or sensitive dashboard contents. A
+permission error or inconclusive result must remain unknown and include the error; never infer a
+pass.
+
+Then run:
+npx --yes agentic-scorecard@0.2.0 assess . --profile pr-creation --scope tracked --agent-evidence .agentic/agent-evidence.yaml --format markdown --output .agentic/reports/agentic-readiness-v0.2.0-assisted.md
+
+Summarize every score change and keep agent-collected evidence distinct from repository evidence and
+human attestations. Do not describe the result as certified, compliant, safe, secure, or
+independently verified.
+```
+
+The agent is an evidence investigator. The scorecard remains the scoring authority.
+
 ## Choose a different authority level
 
-Replace `pr-creation` with exactly one of:
+Replace `pr-creation` with one of:
 
 - `read-only-analysis` — inspect approved source and return advice;
 - `planning` — draft plans and specifications;
@@ -42,23 +74,20 @@ No benchmark profile grants production deployment authority.
 
 ## Guided remediation
 
-Use this only after reviewing the first report:
-
 ```text
-Read .agentic/reports/agentic-readiness-v0.1.0.md and create a remediation proposal for the failed
-target-profile controls. Do not implement changes yet. Group recommendations into quick wins,
-foundational engineering, and organizational evidence. For each recommendation include the ADRB
-control ID, risk reduced, files or systems likely affected, accountable role, verification method,
-dependencies, and an effort estimate. Identify claims requiring a human owner or access to external
-systems; never invent an attestation. End by asking which recommendations I authorize you to
-implement.
+Read the latest ADRB v0.2 report and create a remediation proposal for the failed target-profile
+controls. Do not implement changes yet. Group recommendations into repository changes, platform or
+organizational controls, and outcome measurement. For each include the control ID, risk reduced,
+systems affected, accountable role, verification method, dependencies, and effort estimate. Never
+invent an attestation or convert unavailable evidence into a failure. End by asking which changes I
+authorize.
 ```
 
-## Reassessment after approved improvements
+## Reassessment
 
 ```text
-Re-run the pinned Agentic Development Readiness Benchmark v0.1.0 for the same readiness profile.
-Compare the new report to the previous report control by control. Explain score changes using evidence,
-not assumptions, and identify any regression or expired attestation. Do not overwrite the previous
-report; add the current date to the new report filename.
+Re-run the pinned ADRB v0.2.0 benchmark for the same profile and tracked scope. Compare reports
+control by control. Explain changes using evidence and identify changed commit state, expired claims,
+scope differences, regressions, or newly established controls. Write a new dated report; do not
+overwrite the previous one.
 ```

package/FEEDBACK.md

@@ -0,0 +1,53 @@
+# Feedback guide
+
+Feedback from real assessments is essential to improving the Agentic Development Readiness
+Benchmark without weakening its evidence standards or vendor neutrality.
+
+## Choose the right channel
+
+| Feedback                                                                                  | Channel                                                                                                                  |
+| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| False positive, false negative, unclear result, usability problem, or adoption experience | [Assessment feedback issue](https://github.com/Planet-B2B/agentic-readiness/issues/new?template=assessment-feedback.yml) |
+| Proposed control, scoring, evidence, or readiness-profile change                          | [Benchmark change issue](https://github.com/Planet-B2B/agentic-readiness/issues/new?template=benchmark-change.yml)       |
+| Private adoption question or feedback that cannot be public                               | [benchmark@planetb2b.com](mailto:benchmark@planetb2b.com)                                                                |
+| Suspected security vulnerability                                                          | Follow [SECURITY.md](SECURITY.md); do not open a public issue or email the benchmark contact                             |
+
+Public issues are preferred when the information can be safely shared because they let other users
+compare experiences and participate in the design review.
+
+## What useful feedback includes
+
+- benchmark and package version;
+- requested readiness profile and assessment scope;
+- relevant control IDs;
+- the observed result and the expected result;
+- whether the concern is scanner behavior, control wording, evidence semantics, scoring policy, or
+  documentation;
+- a minimal sanitized reproduction or description; and
+- the material impact on adoption or decision-making.
+
+Do not attach complete private reports. Never include credentials, proprietary source, private
+URLs, personal data, customer data, or confidential dashboard content. A path name or summarized
+evidence characteristic is usually enough to begin triage.
+
+## Ask a coding agent to prepare feedback
+
+Paste this prompt into an agent that can read your assessment report:
+
+> Review my Agentic Development Readiness report and draft feedback for the
+> `Planet-B2B/agentic-readiness` repository. Include the benchmark version, target profile,
+> assessment scope, relevant control IDs, observed result, expected result, and a minimal sanitized
+> explanation. Classify the feedback as a likely scanner defect, documentation problem, adoption
+> experience, or proposed normative benchmark change. Do not include credentials, proprietary
+> source, private URLs, personal data, customer data, or full report contents. Show me the complete
+> draft and ask for my approval before opening a GitHub issue. If I approve and you have GitHub
+> access, use the assessment feedback issue form; otherwise give me the final text to submit.
+
+Agents must treat opening an issue as an external write and obtain accountable human approval first.
+Security concerns must follow `SECURITY.md` rather than this workflow.
+
+## Help others discover the benchmark
+
+If this project helps your team, [star the repository](https://github.com/Planet-B2B/agentic-readiness).
+Stars make the public benchmark easier for other engineering teams to discover; substantive feedback
+and reproducible examples are even more valuable.

package/README.md

@@ -1,3 +1,9 @@
+![Agentic Development Readiness](assets/brand/banner.png)
+
+<p align="center">
+  <img src="assets/brand/avatar.png" width="96" height="96" alt="Agentic Development Readiness project mark">
+</p>
+
 # Agentic Development Readiness Benchmark
 
 A vendor-neutral, evidence-backed benchmark for the engineering harness around AI coding agents.
@@ -10,8 +16,9 @@ The benchmark measures the harness, not the model brand. It assesses ten dimensi
 maturity levels and applies non-compensating floors to five autonomy profiles. A high total score
 cannot hide a critical security, testing, governance, or recovery gap.
 
-This repository is an early **v0.1 reference implementation** intended for public review and
-piloting. It is not a certification standard.
+This repository is a **v0.2 reference implementation** intended for public review and piloting. It
+is not a certification standard. The immutable v0.1 benchmark remains available for historical
+reproduction; v0.1 and v0.2 scores are not directly comparable.
 
 ## Ask your coding agent
 
@@ -19,17 +26,42 @@ You do not need to install or learn the CLI yourself. Paste this prompt into Cod
 GitHub Copilot, Cursor, or another coding agent that has terminal access to your repository:
 
 > Assess this repository's readiness for AI-agent pull-request work. From the repository root, run
-> `npx --yes agentic-scorecard@0.1.0 assess . --profile pr-creation --format markdown --output .agentic/reports/agentic-readiness-v0.1.0.md`.
+> `npx --yes agentic-scorecard@0.2.0 assess . --profile pr-creation --scope tracked --format markdown --output .agentic/reports/agentic-readiness-v0.2.0.md`.
 > Do not change product source code or invent attestations. Read the resulting report and summarize
 > the score, highest passed profile, whether `pr-creation` passes, target-profile blockers, and the
-> five highest-value improvements. Clearly separate tool-verified evidence from self-attested
-> evidence and flag likely false positives or missing organizational evidence. Leave the report
-> uncommitted unless I ask you to commit it.
+> five highest-value improvements. Separate repository gaps from external and outcome evidence, and
+> keep repository-detected, agent-collected, and human-attested evidence distinct. Flag likely false
+> positives or negatives. Leave generated artifacts uncommitted unless I ask you to commit them.
 
 That is the recommended first assessment. The agent downloads the pinned benchmark package, runs the
 read-only local collector, and explains the results. For alternate authority levels or a guided
 remediation session, use the prompts in [AGENT_PROMPT.md](AGENT_PROMPT.md).
 
+## Feedback and community
+
+Real-world assessment feedback helps make the benchmark more accurate and useful across different
+engineering organizations and agent harnesses.
+
+- Share false positives, false negatives, unclear controls, and adoption experience through the
+  [assessment feedback form](https://github.com/Planet-B2B/agentic-readiness/issues/new?template=assessment-feedback.yml).
+- Propose scoring, control, evidence, or readiness-profile changes through the
+  [benchmark change form](https://github.com/Planet-B2B/agentic-readiness/issues/new?template=benchmark-change.yml).
+- Send private adoption questions or feedback that cannot be shared publicly to
+  [benchmark@planetb2b.com](mailto:benchmark@planetb2b.com). Do not email vulnerability reports;
+  follow [SECURITY.md](SECURITY.md) instead.
+
+Ask a coding agent to prepare privacy-safe feedback with this prompt:
+
+> Review my Agentic Development Readiness report and draft feedback for the
+> `Planet-B2B/agentic-readiness` repository. Include the benchmark version, target profile, relevant
+> control IDs, observed result, expected result, and a minimal sanitized explanation. Distinguish a
+> likely scanner defect from a proposed benchmark-policy change. Do not include credentials,
+> proprietary source, private URLs, personal data, customer data, or full report contents. Show me
+> the draft and ask for my approval before opening a GitHub issue.
+
+See [FEEDBACK.md](FEEDBACK.md) for the full feedback guide. If the project is useful to you, please
+[star the repository](https://github.com/Planet-B2B/agentic-readiness) so others can discover it.
+
 ## Quick start
 
 ### Installation and prerequisites
@@ -38,8 +70,9 @@ A supported Node.js LTS release (20.19+, 22.13+, or 24+) is required. Assessment
 read-only, and offline by default.
 
 ```bash
-npx agentic-scorecard@0.1.0 assess /path/to/repository \
+npx agentic-scorecard@0.2.0 assess /path/to/repository \
   --profile pr-creation \
+  --scope tracked \
   --format markdown \
   --output agentic-readiness.md
 ```
@@ -47,11 +80,31 @@ npx agentic-scorecard@0.1.0 assess /path/to/repository \
 To record controls that repository inspection cannot prove:
 
 ```bash
-npx agentic-scorecard@0.1.0 init /path/to/repository
+npx agentic-scorecard@0.2.0 init /path/to/repository
 ```
 
-Complete `.agentic/attestations.yaml` with owners and links to durable evidence, then assess again.
-Attested evidence remains visibly distinct from tool-verified evidence in every report.
+Complete `.agentic/attestations.yaml` with owners and durable evidence links, then assess again.
+Human-attested evidence remains visibly distinct in every report.
+
+To let an authorized coding agent collect evidence from Git hosting, CI, dashboards, or other
+external systems, first generate a target-bound template. The repository must be a Git worktree
+with at least one commit so the bundle can bind to the exact assessed state:
+
+```bash
+npx agentic-scorecard@0.2.0 init-evidence /path/to/repository
+```
+
+Ask the agent to review `.agentic/evidence-request.md`, obtain approval before using
+least-privileged read-only connectors, add attempted claims to `.agentic/agent-evidence.yaml`, and
+rerun with `--agent-evidence`. The default bundle path is loaded automatically. See
+[AGENT_PROMPT.md](AGENT_PROMPT.md) for the complete copy-and-paste workflow.
+
+### Migrating from v0.1
+
+Run a new tracked-scope baseline and retain the old report as historical evidence. Do not present the
+score change as improvement or regression because v0.2 changes evidence semantics. Re-review v0.1
+attestations before recreating them for v0.2; v0.2 repository-artifact controls cannot be overridden
+by declaration, and every human or agent-collected external claim must expire.
 
 For development from this checkout:
 
@@ -104,30 +157,32 @@ No profile grants production deployment authority. Organizations should evaluate
 through a separate, system-specific safety case.
 
 The exact floors live in
-[`benchmark/v0.1/benchmark.yaml`](benchmark/v0.1/benchmark.yaml) and their rationale in
-[`benchmark/v0.1/scoring-policy.md`](benchmark/v0.1/scoring-policy.md).
+[`benchmark/v0.2/benchmark.yaml`](benchmark/v0.2/benchmark.yaml) and their rationale in
+[`benchmark/v0.2/scoring-policy.md`](benchmark/v0.2/scoring-policy.md).
 
-## Evidence and trust labels
+## Evidence scopes and trust labels
 
-- **Verified:** a deterministic local collector found the configured repository evidence.
-- **Attested:** an accountable owner supplied an evidence link or explanation. This may satisfy a
-  control, but it never becomes verified evidence.
-- **Unmet/unknown:** evidence is absent, expired, contradictory, or still requires review.
-- **Independently reviewed:** reserved for a future external review protocol; the CLI does not issue
-  this label.
+- **Repository-detected:** the local collector found qualifying evidence in the selected path scope.
+  This proves an artifact match, not consistent practice or external enforcement.
+- **Agent-collected:** an authorized agent supplied a target-bound, expiring, source-backed external
+  claim. It is not independently verified.
+- **Human-attested:** an accountable owner supplied a dated evidence link or explanation.
+- **Unknown:** evidence is unavailable, expired, unauthorized, mismatched, or inconclusive.
 
-Repository heuristics are intentionally explainable and conservative. They prove that an artifact
-or term exists—not that a team consistently follows it. Manual claims make organizational controls
-portable across GitHub, GitLab, Azure DevOps, internal systems, and different agent harnesses while
-preserving provenance.
+Controls also identify whether their evidence belongs in the repository, hosting platform,
+organization, or outcome systems. This prevents expected external unknowns from masquerading as
+missing files. Future independently conformant adapters require a separate protocol; v0.2 does not
+issue certification or independent-verification claims.
 
 ## Reports and CI
 
 The CLI emits Markdown for people and stable JSON for automation:
 
 ```bash
-agentic-scorecard assess . --format json --output .agentic/report.json
+agentic-scorecard assess . --scope tracked --format json --output .agentic/report.json
+agentic-scorecard assess . --profile pr-creation --agent-evidence .agentic/agent-evidence.yaml
 agentic-scorecard assess . --profile pr-creation --enforce
+agentic-scorecard init-evidence .
 agentic-scorecard explain ADRB-SEC-003
 agentic-scorecard validate
 ```
@@ -142,11 +197,12 @@ funded the remediation plan. See
 The default collector:
 
 - makes no network calls and invokes no model;
-- reads only the target checkout;
-- ignores `.git`, dependency, build, and coverage directories;
+- reads only Git-tracked paths and records commit and dirty-worktree metadata;
+- ignores `.git`, dependencies, build output, coverage, generated reports, attestations, and imported
+  evidence bundles;
 - caps content-scanned files at 512 KB;
 - reports file paths and match counts, never matching source snippets;
-- writes nothing unless `--output` or `init` is explicitly requested.
+- writes nothing unless `--output`, `init`, or `init-evidence` is explicitly requested.
 
 Do not place credentials, private prompts, source excerpts, or personal data in attestations. Link to
 access-controlled evidence instead. Report suspected vulnerabilities through [SECURITY.md](SECURITY.md).
@@ -154,7 +210,8 @@ access-controlled evidence instead. Report suspected vulnerabilities through [SE
 ## Repository structure
 
 ```text
-benchmark/v0.1/       immutable benchmark definition and controls
+benchmark/v0.1/       immutable historical v0.1 definition
+benchmark/v0.2/       current normative benchmark, schemas, and controls
 benchmark/mappings/   informative mappings to external frameworks
 src/                  reference CLI and local evidence collectors
 templates/            adoption, preflight, attestation, and remediation templates
@@ -171,21 +228,23 @@ OIDC-provenance release process.
 
 1. Run a local baseline for the least-authoritative profile you actually need.
 2. Review every result with security, platform, and representative delivery teams.
-3. Supply owned attestations for controls that cannot be mechanically verified.
-4. Publish the report internally with explicit limitations and benchmark version.
-5. Fund the smallest improvements that close target-profile blockers.
-6. Reassess on material harness changes and at least quarterly.
-7. Add a non-blocking CI report; enforce only the agreed target profile after a pilot.
+3. Use an authorized agent to collect source-backed external evidence where appropriate.
+4. Supply owned human attestations only where deterministic collection is unavailable.
+5. Publish the report internally with explicit limitations, scope, commit, and benchmark version.
+6. Fund the smallest improvements that close target-profile blockers.
+7. Reassess on material harness changes and at least quarterly.
+8. Add a non-blocking CI report; enforce only the agreed target profile after a pilot.
 
 Never optimize to the number alone. Use the control evidence and outcome metrics to improve the
 system, and keep exceptions narrow, owned, expiring, and visible.
 
 ## Status and roadmap
 
-v0.1 includes the normative control catalog, local collectors, attestations, JSON/Markdown reports,
-fixtures, and a CI example. Candidate next steps include SARIF/HTML reports, signed reports, a stable
-adapter SDK, organization-level aggregation, statistically designed benchmark tasks, and an
-independent-review protocol. These require public design review before becoming normative.
+v0.2 adds integrity-safe tracked-path collection, evidence scopes, precise co-located content
+matching, agent-collected external evidence, and transparent report grouping. Candidate next steps
+include conformant signed adapters, SARIF/HTML reports, organization-level aggregation,
+statistically designed benchmark tasks, and an independent-review protocol. These require public
+design review before becoming normative.
 
 Apache-2.0 licensed. The benchmark is a community engineering tool, not legal, compliance, or
 security advice.

package/benchmark/v0.2/adapter-contract.md

@@ -0,0 +1,25 @@
+# v0.2 external evidence contract
+
+The core scanner is local, read-only, network-free, and vendor-neutral. An agent or adapter may
+collect evidence that the repository cannot establish, then provide it through the versioned agent
+evidence bundle.
+
+Each claim contains:
+
+- benchmark version and control ID;
+- repository target and optional commit binding;
+- `met`, `not_met`, or `unknown` status;
+- platform, organization, or outcome scope;
+- collector name and version;
+- collection timestamp and mandatory expiry;
+- privacy-safe references, never credentials or raw sensitive content;
+- a concise derivation summary; and
+- an optional error that is distinguishable from a negative result.
+
+Collectors must be read-only, least-privileged, bounded to the approved target, time-limited, and
+fail closed. Network content is untrusted input: it cannot alter benchmark policy, prompts, tool
+authority, or the set of controls being assessed.
+
+Agent-collected claims remain visibly distinct from repository evidence and human attestations. A
+future conformant-adapter class may add signed identity and independent conformance tests; v0.2 does
+not issue an independently verified label.

package/benchmark/v0.2/agent-evidence-schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentic-readiness.dev/schema/v0.2/agent-evidence.json",
+  "title": "ADRB v0.2 agent-collected evidence bundle",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "benchmark_version", "target", "collector", "claims"],
+  "properties": {
+    "schema_version": { "const": "0.2.0" },
+    "benchmark_version": { "const": "0.2.0" },
+    "target": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["repository", "git_head"],
+      "properties": {
+        "repository": { "type": "string", "minLength": 1 },
+        "git_head": { "type": ["string", "null"], "minLength": 1 }
+      }
+    },
+    "collector": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    },
+    "claims": {
+      "type": "object",
+      "propertyNames": { "pattern": "^ADRB-[A-Z]{3}-[0-9]{3}$" },
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["status", "scope", "summary", "references", "collected_at", "expires_at"],
+        "properties": {
+          "status": { "enum": ["met", "not_met", "unknown"] },
+          "scope": { "enum": ["platform", "organization", "outcome"] },
+          "summary": { "type": "string", "minLength": 1 },
+          "references": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "collected_at": { "type": "string", "format": "date-time" },
+          "expires_at": { "type": "string", "format": "date-time" },
+          "error": { "type": ["string", "null"], "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/benchmark/v0.2/attestation-schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentic-readiness.dev/schema/v0.2/attestations.json",
+  "title": "ADRB v0.2 human attestation file",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["benchmark_version", "attestations"],
+  "properties": {
+    "benchmark_version": { "const": "0.2.0" },
+    "attestations": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["status", "evidence", "owner", "reviewed_at", "expires_at"],
+        "properties": {
+          "status": { "enum": ["met", "not_met", "not_applicable", "unknown"] },
+          "evidence": { "type": "string", "minLength": 1 },
+          "owner": { "type": "string", "minLength": 1 },
+          "reviewed_at": { "type": "string", "format": "date" },
+          "expires_at": { "type": "string", "format": "date" }
+        }
+      }
+    }
+  }
+}

package/benchmark/v0.2/benchmark.yaml

@@ -0,0 +1,127 @@
+id: agentic-development-readiness
+version: 0.2.0
+title: Agentic Development Readiness Benchmark
+description: >-
+  A vendor-neutral, evidence-backed assessment of the engineering harness that surrounds AI agents.
+  It measures whether a repository and its operating controls can safely support increasing levels
+  of delegated software work.
+
+maturity_levels:
+  0: Absent
+  1: Ad hoc
+  2: Documented
+  3: Enforced
+  4: Measured and improving
+
+dimensions:
+  - id: context
+    title: Context and knowledge
+    description: Agents can discover authoritative, scoped, current instructions without guesswork.
+  - id: environment
+    title: Reproducible environment
+    description: Agents can establish and verify a faithful development environment.
+  - id: specification
+    title: Specification and planning
+    description: Work starts from testable outcomes, constraints, and explicit acceptance criteria.
+  - id: tooling
+    title: Tooling and interfaces
+    description: Agent tools are discoverable, least-privileged, observable, and fail safely.
+  - id: security
+    title: Security and data governance
+    description: Credentials, data, autonomy, and untrusted content have explicit boundaries.
+  - id: testing
+    title: Verification and testing
+    description: Changes are checked at the right layers with trustworthy, reproducible signals.
+  - id: governance
+    title: Review and change governance
+    description: Human accountability, change scope, and merge authority remain explicit.
+  - id: learning
+    title: Learning and knowledge maintenance
+    description: Corrections compound into maintained instructions instead of being rediscovered.
+  - id: observability
+    title: Outcome observability
+    description: Runs and outcomes can be evaluated by task class, risk, cost, and quality.
+  - id: resilience
+    title: Failure containment and recovery
+    description: Agent failures are bounded, reversible, diagnosed, and rehearsed.
+
+readiness_profiles:
+  - id: read-only-analysis
+    title: Read-only analysis
+    description: Agent may inspect approved repository content and return advice, without mutations.
+    floors:
+      context: 1
+      environment: 0
+      specification: 0
+      tooling: 0
+      security: 1
+      testing: 0
+      governance: 0
+      learning: 0
+      observability: 0
+      resilience: 0
+  - id: planning
+    title: Planning and specification
+    description: Agent may draft plans, specifications, and proposed changes for human review.
+    floors:
+      context: 2
+      environment: 0
+      specification: 1
+      tooling: 1
+      security: 1
+      testing: 0
+      governance: 1
+      learning: 0
+      observability: 0
+      resilience: 0
+  - id: local-implementation
+    title: Local implementation
+    description: Agent may edit an isolated checkout and run approved local verification.
+    floors:
+      context: 2
+      environment: 2
+      specification: 2
+      tooling: 2
+      security: 2
+      testing: 2
+      governance: 1
+      learning: 1
+      observability: 1
+      resilience: 1
+  - id: pr-creation
+    title: Pull request creation
+    description: Agent may create a branch and propose a pull request; a human retains merge authority.
+    floors:
+      context: 2
+      environment: 2
+      specification: 2
+      tooling: 2
+      security: 2
+      testing: 2
+      governance: 2
+      learning: 1
+      observability: 1
+      resilience: 2
+  - id: limited-autonomous-maintenance
+    title: Limited autonomous maintenance
+    description: >-
+      Agent may complete pre-approved, low-risk maintenance within strict scope, budget, and stop
+      conditions. This profile never grants production deployment authority.
+    floors:
+      context: 3
+      environment: 3
+      specification: 3
+      tooling: 3
+      security: 3
+      testing: 3
+      governance: 3
+      learning: 3
+      observability: 3
+      resilience: 3
+
+scoring:
+  dimension_method: consecutive-levels
+  overall_method: sum
+  maximum_score: 40
+  readiness_method: non-compensating-floors
+  attestation_counts_as_verified: false