agentic-scorecard 0.3.0 → 0.3.1

package/AGENT_PROMPT.md

@@ -4,66 +4,82 @@ These prompts are vendor-neutral. The agent needs terminal access to the reposit
 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: repository baseline
+## Recommended: complete agent-assisted assessment
 
 Copy and paste:
 
 ```text
-Assess this repository's readiness for AI-agent pull-request work.
-
-From the repository root, run:
-npx --yes agentic-scorecard@0.3.0 assess . --profile pr-creation --scope tracked --format markdown --output .agentic/reports/agentic-readiness-v0.3.0.md
-
-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 normative score out of 40 and the repository-detected progress against its offline ceiling;
-2. the highest passed readiness profile and whether pr-creation passes;
-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. Treat UNKNOWN as
-unresolved, not failed. 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.
+Perform the complete ADRB v0.3 assessment of this repository for AI-agent pull-request work.
+
+Do not change product source, tests, configuration, policies, Git history, or the user's current
+checkout. First inspect the repository's commit, tracked-file status, upstream tracking branch, and
+ahead/behind state. If read-only network access is already authorized, fetch the upstream before
+comparing it. Select the commit before creating an assessment worktree. Default to the current HEAD;
+a dirty checkout does not change that selection, so assess HEAD from an isolated clean worktree. Use
+the fetched upstream commit only when I asked for the latest/current upstream state and the branch is
+behind. If the checkout is both dirty and behind, state both facts and preserve HEAD by default unless
+I explicitly asked for upstream or another commit. State the exact commit you selected and why.
+
+Before running the scorecard, choose and state an absolute durable artifact directory outside any
+temporary worktree. Do not delete that directory during worktree cleanup. In the commands below,
+replace `<artifact-dir>` with that path. The npm package version is 0.3.1, while report filenames use
+the immutable ADRB benchmark version 0.3.0.
+
+From that clean target, run the repository-only baseline:
+npx --yes agentic-scorecard@0.3.1 assess . --profile pr-creation --scope tracked --format markdown --output <artifact-dir>/agentic-readiness-v0.3.0-baseline.md
+
+Then prepare unresolved evidence:
+npx --yes agentic-scorecard@0.3.1 init-evidence . --output <artifact-dir>/agent-evidence.yaml --request-output <artifact-dir>/evidence-request.md
+
+Read the baseline, `<artifact-dir>/evidence-request.md`, and the empty target-bound
+`<artifact-dir>/agent-evidence.yaml`. Investigate nuanced repository-scoped requests only from
+tracked files at the selected commit. Before accessing Git hosting settings, CI, dashboards, logs,
+ticketing, or any other connected system, tell me exactly which least-privileged read-only tools,
+accounts, repositories, branches, dashboards, and time ranges you need, and why. Wait for my
+authorization.
+
+After authorization, attempt only eligible requests. For every attempted claim, record its status,
+scope, concise derivation, collection time, 30-day-or-shorter expiry, and durable privacy-safe
+references. Repository claims must use `repo:<path>[#Lx-Ly]`; do not merely restate a keyword match.
+A permission error, stale source, or inconclusive result remains unknown and records the error.
+Never infer a pass, invent an attestation, or treat unavailable evidence as a failure.
+
+Do not place credentials, prompts, source excerpts, raw logs, personal data, customer data, private
+URLs that reveal secrets, or sensitive dashboard contents in generated files.
+
+When authorized evidence collection is complete, run:
+npx --yes agentic-scorecard@0.3.1 assess . --profile pr-creation --scope tracked --agent-evidence <artifact-dir>/agent-evidence.yaml --format markdown --output <artifact-dir>/agentic-readiness-v0.3.0-assisted.md
+
+Tell me the repository-detected progress and normative score, the highest passed profile, whether
+pr-creation passes, every target blocker, and the five highest-value improvements. Compare baseline
+and assisted reports control by control. Keep repository-detected, agent-collected, and
+human-attested evidence separate; treat UNKNOWN as unresolved, not failed; and flag likely false
+positives or negatives. If I decline external access, stop after the baseline and label it clearly as
+a repository-only baseline. Before removing a temporary worktree, verify that every report, evidence
+request, and evidence bundle you cite exists in the durable artifact directory, then tell me that
+directory's absolute path. Leave generated artifacts uncommitted unless I explicitly ask otherwise.
+Do not describe any result as certified, compliant, safe, secure, or independently verified.
 ```
 
-## Agent-assisted unresolved evidence
-
-Use this only after reviewing the repository baseline:
-
-```text
-Investigate the controls that the ADRB v0.3 baseline could not establish.
-
-First ensure tracked files match HEAD and the repository has a commit, then run:
-npx --yes agentic-scorecard@0.3.0 init-evidence .
-
-Read `.agentic/evidence-request.md` and the empty target-bound
-`.agentic/agent-evidence.yaml` bundle. The request includes only unresolved controls that permit
-agent-collected evidence. 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 attempted control,
-record the source-backed status, scope, concise derivation, collection time, 30-day-or-shorter
-expiry, and durable privacy-safe references. For repository-scoped claims, cite only tracked files
-at the bound commit using `repo:<path>[#Lx-Ly]`; do not use a repository claim to restate a keyword
-match. Add only claims you actually investigated. A permission error or inconclusive result must
-remain unknown and include the error; never infer a pass.
+The agent is an evidence investigator. The scorecard remains the scoring authority.
 
-Do not paste credentials, prompts, source excerpts, raw logs, personal data, customer data, or
-sensitive dashboard contents into the bundle.
+## Fast repository-only baseline
 
-Then run:
-npx --yes agentic-scorecard@0.3.0 assess . --profile pr-creation --scope tracked --agent-evidence .agentic/agent-evidence.yaml --format markdown --output .agentic/reports/agentic-readiness-v0.3.0-assisted.md
+Use this when you want an offline first look and accept that platform, organization, and outcome
+controls will remain unresolved:
 
-Summarize every score change and keep agent-collected evidence distinct from deterministic
-repository evidence and human attestations. Do not describe the result as certified, compliant,
-safe, secure, or independently verified.
+```text
+Run a fast repository-only ADRB v0.3 baseline for AI-agent pull-request work. Verify and state the
+selected commit and whether tracked files match HEAD, then run:
+npx --yes agentic-scorecard@0.3.1 assess . --profile pr-creation --scope tracked --format markdown --output .agentic/reports/agentic-readiness-v0.3.0-baseline.md
+
+Do not change repository files or invent evidence. Summarize repository-detected progress before
+the normative score, target-profile blockers, and the five highest-value repository improvements.
+Separate true repository gaps from platform, organization, and outcome evidence that this offline
+scan cannot establish. Treat UNKNOWN as unresolved, not failed, and call the result a repository-only
+baseline rather than a complete assessment. Leave generated artifacts uncommitted.
 ```
 
-The agent is an evidence investigator. The scorecard remains the scoring authority.
-
 ## Choose a different authority level
 
 Replace `pr-creation` with one of:
@@ -90,7 +106,7 @@ authorize.
 ## Reassessment
 
 ```text
-Re-run the pinned ADRB v0.3.0 benchmark for the same profile and tracked scope. Compare reports
+Re-run the pinned ADRB v0.3.0 benchmark with agentic-scorecard@0.3.1 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. Compare normative and
 repository-detected progress separately. Write a new dated report; do not overwrite the previous

package/README.md

@@ -22,20 +22,27 @@ historical reproduction; scores from different benchmark versions are not direct
 
 ## Ask your coding agent
 
-You do not need to install or learn the CLI yourself. Paste this prompt into Codex, Claude Code,
+You do not need to install or learn the CLI yourself. Paste this instruction into Codex, Claude Code,
 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.3.0 assess . --profile pr-creation --scope tracked --format markdown --output .agentic/reports/agentic-readiness-v0.3.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. 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).
+> Perform the complete ADRB v0.3 assessment of this repository for AI-agent pull-request work using
+> `agentic-scorecard@0.3.1`. First select and state the commit without modifying my checkout; preserve
+> HEAD when the checkout is dirty, and use upstream only if I requested the latest upstream state.
+> Assess it from a clean worktree and keep all generated artifacts in a durable directory outside any
+> temporary worktree. Run the tracked repository baseline, then run `init-evidence`, read its evidence
+> request, and tell me which least-privileged read-only connected systems you need. Wait for my
+> authorization before accessing them. After authorized collection, rerun the assessment and compare
+> the baseline and assisted reports control by control. Keep repository-detected, agent-collected, and
+> human-attested evidence separate; never invent evidence; treat UNKNOWN as unresolved; and leave
+> generated artifacts uncommitted.
+
+The complete copy-and-paste prompt, including privacy limits and exact commands, is in
+[AGENT_PROMPT.md](AGENT_PROMPT.md). It makes the evidence-assisted workflow the recommendation. A
+fast filesystem scan remains available, but it is explicitly a **repository-only baseline** and
+cannot establish platform, organization, or outcome controls by itself.
+
+The reference CLI/package is version 0.3.1. Generated report names use benchmark version 0.3.0
+because the patch release changed workflow guidance, not the immutable scoring benchmark.
 
 ## Feedback and community
 
@@ -70,7 +77,7 @@ 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.3.0 assess /path/to/repository \
+npx agentic-scorecard@0.3.1 assess /path/to/repository \
   --profile pr-creation \
   --scope tracked \
   --format markdown \
@@ -80,7 +87,7 @@ npx agentic-scorecard@0.3.0 assess /path/to/repository \
 To record controls that repository inspection cannot prove:
 
 ```bash
-npx agentic-scorecard@0.3.0 init /path/to/repository
+npx agentic-scorecard@0.3.1 init /path/to/repository
 ```
 
 Complete `.agentic/attestations.yaml` with owners and durable evidence links, then assess again.
@@ -91,7 +98,7 @@ external systems, first generate a target-bound template. The repository must be
 with at least one commit so the bundle can bind to the exact assessed state:
 
 ```bash
-npx agentic-scorecard@0.3.0 init-evidence /path/to/repository
+npx agentic-scorecard@0.3.1 init-evidence /path/to/repository
 ```
 
 Ask the agent to review `.agentic/evidence-request.md`, obtain approval before using

package/dist/cli.js

@@ -537,6 +537,10 @@ function toMarkdown(report) {
     (control) => ["platform", "organization"].includes(controlScope(control))
   );
   const outcomeControls = unresolved.filter((control) => controlScope(control) === "outcome");
+  const repositoryOnlyBaseline = !report.controls.some(
+    ({ agent_evidence: agentEvidence, attestation }) => agentEvidence !== null || attestation !== null
+  );
+  const resolvedEvidence = report.evidence_summary.resolved !== void 0 && report.evidence_summary.total !== void 0 ? `; ${report.evidence_summary.resolved}/${report.evidence_summary.total} controls resolved` : "";
   const lines = [
     "# Agentic Development Readiness Assessment",
     "",
@@ -546,13 +550,16 @@ function toMarkdown(report) {
     `- Git commit: ${report.target.git_head ? `\`${report.target.git_head}\`` : "unavailable"}`,
     `- Working tree dirty: ${report.target.working_tree_dirty === null ? "unknown" : String(report.target.working_tree_dirty)}`,
     `- Assessed: ${report.assessed_at}`,
-    `- Score: **${report.score.total}/${report.score.maximum} (${report.score.percentage}%)**`,
+    ...repositoryOnlyBaseline ? [
+      "- Assessment mode: **repository-only baseline** \u2014 platform, organization, and outcome evidence has not been established"
+    ] : ["- Assessment mode: **evidence-assisted assessment**"],
     ...report.score.repository ? [
       `- Repository-detected progress: **${report.score.repository.achieved}/${report.score.repository.ceiling} (${report.score.repository.percentage}%)** of the maturity levels the offline repository collector can establish`
     ] : [],
+    `- Normative readiness score: **${report.score.total}/${report.score.maximum} (${report.score.percentage}%)**`,
     `- Highest readiness profile: **${report.readiness.highest_profile ?? "none"}**`,
     `- Target \`${report.target.profile}\`: **${report.readiness.target_passed ? `PASS${targetProvenance}` : "FAIL"}**`,
-    `- Evidence: ${report.evidence_summary.repository_detected} repository-detected, ${report.evidence_summary.agent_collected} agent-collected, ${report.evidence_summary.attested} human-attested, ${report.evidence_summary.unmet} unmet, ${report.evidence_summary.unknown} unknown${report.evidence_summary.resolved !== void 0 && report.evidence_summary.total !== void 0 ? `; ${report.evidence_summary.resolved}/${report.evidence_summary.total} controls resolved` : ""}`,
+    `- Established evidence: ${report.evidence_summary.repository_detected} repository-detected, ${report.evidence_summary.agent_collected} agent-collected, ${report.evidence_summary.attested} human-attested; ${report.evidence_summary.unmet} unmet, ${report.evidence_summary.unknown} unknown${resolvedEvidence}`,
     ...report.warnings && report.warnings.length > 0 ? [`- Warnings: **${report.warnings.length} \u2014 review before using this assessment**`] : [],
     "",
     ...report.warnings && report.warnings.length > 0 ? [
@@ -1130,6 +1137,27 @@ async function assess(repo, benchmark, catalog, profileId, options = {}) {
       )
     )
   );
+  const warnings = [...options.warnings ?? []];
+  if (benchmark.version === "0.3.0") {
+    if (scope === "tracked" && context.metadata.tracked_tree_dirty) {
+      warnings.push(
+        "Tracked assessment includes uncommitted tracked-file contents, so the result is not reproducible from git_head alone. Use a clean worktree before comparing scores or collecting agent evidence."
+      );
+    }
+    const hasActiveSupplementalEvidence = controls.some(
+      ({ agent_evidence: agentEvidence, attestation }) => agentEvidence !== null || attestation !== null
+    );
+    const unresolvedExternalOrOutcome = controls.some(
+      ({ evidence, status }) => (status === "unknown" || status === "not_met") && evidence.some(
+        ({ scope: evidenceScope }) => ["platform", "organization", "outcome"].includes(evidenceScope)
+      )
+    );
+    if (!hasActiveSupplementalEvidence && unresolvedExternalOrOutcome) {
+      warnings.push(
+        "Repository-only baseline: no active agent-collected or human-attested evidence was supplied. Platform, organization, and outcome evidence remains unresolved until authorized evidence is collected with init-evidence or supplied by accountable owners."
+      );
+    }
+  }
   const dimensions = benchmark.dimensions.map(({ id, title }) => {
     const dimensionControls = controls.filter((control) => control.dimension === id);
     return {
@@ -1157,7 +1185,7 @@ async function assess(repo, benchmark, catalog, profileId, options = {}) {
       working_tree_dirty: context.metadata.working_tree_dirty
     },
     assessed_at: now.toISOString(),
-    ...benchmark.version === "0.3.0" ? { warnings: options.warnings ?? [] } : {},
+    ...benchmark.version === "0.3.0" ? { warnings } : {},
     score: {
       total,
       maximum: 40,
@@ -1295,7 +1323,7 @@ function countLines(contents) {
 
 // src/cli.ts
 var program = new Command();
-program.name("agentic-scorecard").description("Evidence-backed readiness assessment for agentic software development harnesses").version("0.3.0");
+program.name("agentic-scorecard").description("Evidence-backed readiness assessment for agentic software development harnesses").version("0.3.1");
 program.command("validate").description("Validate the bundled benchmark catalog").action(async () => {
   const { benchmark, controls } = await loadBenchmark();
   process.stdout.write(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-scorecard",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Vendor-neutral, evidence-backed readiness benchmark for agentic software development harnesses.",
   "author": "Planet B2B Inc. <benchmark@planetb2b.com>",
   "homepage": "https://github.com/Planet-B2B/agentic-readiness#readme",