agentic-proofkit 0.1.91

package/NON_CLAIMS.md

@@ -0,0 +1,197 @@
+# Non-Claims
+
+`proofkit` owns reusable proof infrastructure primitives
+only.
+
+It does not own:
+
+- product requirements or product readiness;
+- consuming repository requirement meaning, final proof-binding content,
+  command registry content, environment policy, native witness selection, or
+  merge admission decisions;
+- consuming repository topology, work ledgers, or rollout policy;
+- native witness execution or command pass evidence;
+- GitHub App behavior, issue or pull-request automation, deployment, queues,
+  databases, LLM harnesses, or credentialed runtime behavior;
+- organization rollout approval, consumer migration approval, consumer fallback
+  deletion, or consumer CI policy;
+- packed-tarball pilot adoption as a registry release, organization rollout
+  approval, proof freshness decision, or native witness pass claim.
+- package artifact verification as runtime execution proof for every non-native
+  embedded platform binary unless the CI matrix supplies that native OS and CPU
+  tuple.
+- release-authority reports as package publication, registry credential
+  authority, package access-control proof, or consumer fallback-deletion
+  approval.
+- GitHub Release tarballs, checksum files, or release manifests as the primary
+  dependency authority for package-manager consumers; public npm registry
+  identity remains the install authority.
+- OCI, Homebrew, Go module, or GitHub Packages publication as completed release
+  channels unless their own release workflow and artifact identity are present.
+- workspace package graph primitives as consuming repository script policy,
+  namespace policy, lockfile freshness proof, or CI admission authority.
+- workspace changed-package and shard-partition CLI reports as git diff
+  discovery, repository scanning, CI scheduling policy, command execution,
+  dependency graph freshness, merge approval, rollout approval, or consumer
+  policy authority.
+- repo-profile structural admission and command admission as repository-state
+  discovery, consuming repository command execution, shell-command authoring,
+  environment vocabulary authority, native witness pass evidence, or
+  replacement for caller-owned profile review.
+- repo-profile scaffold plans as repository-state discovery, file writes,
+  overwrite safety, final repository profile content, profile admission,
+  command policy authority, native witness execution, proof freshness, merge
+  approval, rollout approval, or replacement for caller-owned profile review.
+- project-structure scaffold reports or materialization manifests as
+  repository-state discovery, file writes, file existence proof, overwrite
+  safety, final module specification content, final repository profile content,
+  native witness execution, command pass evidence, receipt authenticity, proof
+  freshness, merge approval, enforcement promotion approval, release approval,
+  rollout approval, or consumer policy authority.
+- project-structure scaffold agent envelopes as starter payload transport,
+  repository-state discovery, file writes, file existence proof, overwrite
+  safety, final specification or profile content, native witness execution,
+  command pass evidence, receipt authenticity, proof freshness, merge approval,
+  enforcement promotion approval, release approval, rollout approval, or
+  consumer policy authority.
+- adoption-workflow-plan reports as repository-state discovery, file writes,
+  native witness execution, command pass evidence, receipt authenticity,
+  receipt freshness, CI freshness, merge approval, enforcement promotion
+  approval, rollout approval, scenario appropriateness, or consumer policy
+  authority.
+- adoption-workflow-plan contract envelopes as primitive input payload
+  transport, scenario inference, repository-state discovery, file writes,
+  native witness execution, receipt authenticity, freshness, merge approval,
+  release approval, rollout approval, or consumer policy authority.
+- adoption-workflow-plan agent envelopes as primitive input payload transport,
+  repository-state discovery, file writes, native witness execution, command
+  pass evidence, receipt authenticity, receipt freshness, CI freshness,
+  scenario selection, merge approval, enforcement promotion approval, release
+  approval, rollout approval, or consumer policy authority.
+- adoption-checklist reports as repository-state discovery, native witness
+  execution, command pass evidence, evidence authentication, receipt freshness,
+  requiredness policy, merge approval, release approval, rollout approval,
+  production readiness, or consumer policy authority.
+- completion-criteria reports as validator execution, native proof execution,
+  command pass evidence, evidence authentication, receipt freshness,
+  requirement meaning, proof adequacy, merge approval, release approval,
+  rollout approval, production readiness, or consumer policy authority.
+- registry-consumer reports as package fetching, registry credential access,
+  native install execution, rollback execution proof, package access-control
+  proof, consumer migration approval, or proof freshness.
+- package-runtime-dependency admission reports as package resolution, manifest
+  reads, lockfile reads, package-manager semantic proof, registry
+  authentication, dependency freshness, command execution, merge approval, or
+  consumer package policy authority.
+- gradual-adoption-guidance reports as native witness execution, proof
+  freshness, autofix safety proof, waiver, readiness, rollout approval, or
+  consumer policy authority.
+- agent guidance envelopes as native witness execution, proof freshness,
+  source report authenticity, edit approval, rollout approval, consumer policy
+  authority, LLM invocation, repository-state discovery, or replacement for
+  caller-owned review.
+- rendered HTML, rendered Markdown, lookup graphs, slices, envelopes, or
+  validation reports as canonical repository source unless a consuming repository
+  explicitly admits a small tracked artifact with freshness checks.
+- branch-authority reports as repository settings discovery, workflow parsing,
+  GitHub API access, branch mutation, branch protection proof, CI execution,
+  publish execution, package publication, release approval, rollout approval,
+  or consumer branch policy authority.
+- gradual-adoption-bootstrap reports as file writes, native witness execution,
+  implicit repository-state scans, proof truth, rollout approval, or consumer CI
+  policy authority.
+- gradual-adoption-bootstrap agent envelopes as file writes, starter payload
+  transport, native witness execution, command pass evidence, receipt
+  freshness, enforcement promotion approval, rollout approval, or consumer
+  policy authority.
+- gradual-adoption-bootstrap materialization manifests as file writes, file
+  existence proof, overwrite safety, final specification or profile content,
+  native witness execution, command pass evidence, merge approval, enforcement
+  promotion approval, rollout approval, or consumer policy authority.
+- migration plans as file edits, old proof-owner deletion, parity evidence
+  authentication, native witness execution, command pass evidence, proof
+  freshness, merge approval, rollout approval, retirement approval, or consumer
+  policy authority.
+- bootstrap proof binding payloads as native witness execution, proof coverage,
+  proof freshness, caller repository approval, or a replacement for
+  caller-owned proof binding review.
+- stack preset reports as consuming repository topology, mandatory CI policy,
+  proof coverage, native witness execution, rollout approval, or replacement
+  for caller-owned repository profiles.
+- requirement-binding reports, evidence graphs, or proof slices as product
+  requirement meaning, native witness execution, command pass evidence, proof
+  freshness, waiver authority, rollout approval, or replacement for
+  caller-owned proof binding review.
+- requirement-source admission reports as product requirement meaning, overview
+  Markdown citation linting, proof-binding adequacy, native witness execution,
+  receipt freshness, merge approval, rollout approval, or replacement for
+  caller-owned source review.
+- requirement-source transition reports as diff discovery, product requirement
+  meaning, replacement semantic equivalence, native witness execution, receipt
+  freshness, deletion approval, merge approval, rollout approval, or
+  replacement for caller-owned source review.
+- spec-overview claim boundary reports as Markdown reading, extractor
+  completeness, product requirement meaning, semantic adequacy of a cited
+  `REQ-*`, requirement source validation, merge approval, rollout approval, or
+  replacement for caller-owned overview review.
+- requirement-source views as canonical source authority, requirement meaning,
+  overview Markdown linting, proof-binding adequacy, native witness execution,
+  receipt freshness, merge approval, rollout approval, or generated artifact
+  freshness.
+- requirement-proof view models, Markdown rendering, or HTML rendering as
+  product requirement meaning, native witness execution, command pass evidence,
+  receipt freshness, producer authentication, generated artifact freshness,
+  merge approval, rollout approval, or canonical repository source.
+- witness-scheduler-plan reports as native witness execution, filesystem
+  inspection, network inspection, lock-state inspection, cache-state
+  inspection, producer authentication, proof freshness, CI runner allocation,
+  merge approval, rollout approval, or proof-result cache authority.
+- custom-rule-boundary reports as custom-rule execution, repository-state
+  discovery, generic Proofkit failure suppression, generic decision-state
+  downgrade, product requirement meaning, proof freshness, merge approval,
+  rollout approval, or promotion of a local rule into generic Proofkit
+  behavior.
+- document-lifecycle-boundary reports as Markdown parsing, document content
+  review, product semantics, generated artifact freshness, route inference,
+  file archive or deletion approval, merge approval, rollout approval, or
+  replacement for caller-owned documentation review.
+- rendered-artifact-freshness reports as source-file reads, rendered artifact
+  reads, renderer execution, requirement meaning, proof-route ownership, native
+  witness execution, publication approval, merge approval, rollout approval, or
+  replacement for caller-owned digest-producing witnesses.
+- `agentActionPlan` entries as native witness execution, edit approval,
+  rollout approval, proof truth, consumer policy authority, or a replacement for
+  caller-owned review.
+- selective-gate-plan reports as git state discovery, changed-path completeness
+  proof, native command execution, command pass evidence, generated artifact
+  freshness proof, proof coverage approval, secret-scan pass evidence, consumer
+  CI policy authority, or permission to skip caller-owned gates.
+- selective-gate-evidence reports as native command execution, CI log
+  authority, receipt authenticity proof, receipt freshness proof, proof
+  coverage approval, consumer CI policy authority, or permission to skip
+  caller-owned gates. When optional producer admission is supplied, the report
+  validates metadata consistency only; it still does not authenticate
+  producers, prove freshness, or approve merge.
+- receipt-producer-admission reports as producer authentication, CI trust-root
+  ownership, receipt freshness proof, command execution proof, command result
+  correctness, merge approval, rollout approval, or consumer policy authority.
+- spec-proof-bundle admission reports as native witness execution, producer
+  authentication, receipt freshness, semantic proof adequacy, command result
+  correctness, merge approval, release approval, rollout approval, or
+  production readiness.
+- readiness-closeout reports as product row-id authority, product phrase
+  authority, work-ledger ownership, readiness policy, native witness execution,
+  proof freshness, rollout approval, or production readiness.
+
+Consuming repositories must keep their own specifications, proof bindings,
+native witnesses, CI gates, and rollback policy.
+
+Reference infrastructure boundary:
+
+```text
+Proofkit owns reusable grammar, algorithms, reports, rendering/view-model
+machinery, selective planning, impact routing, receipt validation, and agent
+guidance when those capabilities are generic.
+Consuming repositories provide the requirement sentences, policies, witnesses,
+receipts, and rollout decisions.
+```

package/README.md

@@ -0,0 +1,265 @@
+# agentic-proofkit
+
+Reusable CLI and JSON proof infrastructure for spec-to-proof workflows in
+software repositories.
+
+`agentic-proofkit` helps repositories build deterministic proof reports, validate
+structured proof inputs, plan witness commands, model proof graphs, and report
+changed-requirement impact without copying verifier logic between projects.
+
+## Reference Infrastructure Role
+
+Proofkit is the reference implementation boundary for the reusable
+infrastructure side of spec-first machine-proof architecture. It is the package
+where generic grammar, algorithms, deterministic reports, rendering/view-model
+machinery, selective-planning primitives, receipt validation, and agent guidance
+primitives belong when they do not encode consumer-specific truth. The
+capabilities below list the currently implemented slices that consuming
+repositories can use through one CLI dependency.
+
+The package does not own the consuming repository's product semantics. A
+consumer keeps its own specifications, requirement records, proof bindings,
+command registry, environment policy, native witnesses, CI policy, and rollout
+decisions. Proofkit validates, normalizes, renders, and plans from caller-owned
+inputs.
+
+Formal boundary:
+
+```text
+Proofkit owns generic grammar, algorithms, reports, and rendering machinery.
+The repository provides the sentences, policies, witnesses, and decisions.
+```
+
+## Capability Routing
+
+Proofkit capabilities are grouped into reusable primitive families. The package
+README intentionally names the major groups only; the maintained routing table
+for CLI commands, caller-owned inputs, Proofkit-owned mechanics, consumer-owned
+policy, output authority, and non-claims is
+[`docs/proofkit-contract-map.md`](docs/proofkit-contract-map.md).
+
+Current groups:
+
+- deterministic report grammar, schema admission, stable JSON, JSON report CLI
+  adapter mechanics, and redacted diagnostics;
+- reusable profile, path, JSON, and secret-shaped JSON safety primitives;
+- structured witness commands, scheduler metadata, and cache/concurrency safety
+  reports;
+- requirement-source, spec-overview, requirement-proof, proof-graph, proof-slice,
+  compact-proof, and rendered-view primitives;
+- changed-path, impact, selective planning, selective evidence, and obligation
+  decision projections;
+- receipt admission, receipt producer admission, receipt currentness/scope,
+  receipt trust-class, producer-policy self-proof reports, and spec-proof
+  bundle admission;
+- document lifecycle, rendered artifact freshness, custom-rule boundary,
+  deployment evidence admission, completion criteria, branch authority, release
+  authority, registry consumer, and external consumer reports;
+- adoption workflow, adoption checklist, gradual adoption, stack presets,
+  profile scaffolding, project-structure scaffolding, migration planning,
+  migration parity admission, and agent guidance envelopes;
+- workspace package graph, workspace registry, TypeScript package public API
+  surface, package dist manifest, shard partition, and repo-profile admission
+  helpers.
+
+Every group follows the same boundary: Proofkit normalizes caller-owned inputs
+and emits deterministic reports or views; it does not infer repository policy,
+execute native witnesses, authenticate producers, compute proof freshness,
+decide merge admission, or own consumer policy. Helpers whose names read, list,
+or resolve files operate only on explicit caller-provided roots and paths; they
+extract repository facts for consumer-owned scripts instead of owning freshness,
+coverage, or gate policy.
+
+## Primary Contract
+
+The primary cross-language contract is the `agentic-proofkit` CLI plus
+structured JSON inputs, deterministic JSON outputs, exit codes, and shipped
+contract records. This is the contract Python, Go, Rust, Java, shell,
+JavaScript, TypeScript, and CI consumers should target.
+
+There is no package-root language SDK in the Go-only package model. Consumers
+that want language-native ergonomics should wrap the CLI/JSON contract without
+creating independent behavior, schema, freshness, or policy authority.
+
+## CLI
+
+The `agentic-proofkit` CLI reads caller-provided JSON. Report and planner commands emit
+deterministic JSON; presentation commands emit Markdown or HTML only when an
+explicit presentation format is requested:
+
+The machine-readable CLI contract is `proofkit/cli-contract.v1.json`. It is the
+compact command inventory for command ids, admitted flags, input modes, and
+output modes; the examples below are human routing help, not the contract owner.
+There is no second SDK-to-CLI parity owner.
+
+```bash
+# Inspect the complete machine contract when routing an agent or CI wrapper.
+agentic-proofkit --help
+
+# Start or migrate a repository into the spec/proof model.
+agentic-proofkit adoption-workflow-plan --input proofkit/adoption-workflow-plan.json
+agentic-proofkit adoption-workflow-plan --input proofkit/adoption-workflow-plan.json --agent-envelope
+agentic-proofkit gradual-adoption-bootstrap --input proofkit/bootstrap.json
+agentic-proofkit gradual-adoption-guidance --input proofkit/adoption-guidance.json
+agentic-proofkit migration-parity-admission --input proofkit/migration-parity-admission.json
+agentic-proofkit migration-plan --input proofkit/migration-plan.json
+
+# Bind stable requirements to proof routes and selective gates.
+agentic-proofkit obligation-decision --input proofkit/obligation-decision.json
+agentic-proofkit requirement-bindings --input proofkit/requirement-bindings.json
+agentic-proofkit requirement-proof-resolver --input proofkit/compact-requirement-bindings.json --local-environment-class local-go
+agentic-proofkit selective-gate-plan --input proofkit/selective-gate-plan.json --agent-envelope
+agentic-proofkit selective-gate-evidence --input proofkit/selective-gate-evidence.json
+
+# Render source/proof views without making generated views authoritative.
+agentic-proofkit requirement-browser-server --input proofkit/requirements.v1.json --view source --serve
+agentic-proofkit requirement-browser-server --input proofkit/requirement-bindings.json --view proof --scope graph --serve --open
+agentic-proofkit requirement-source-view --input proofkit/requirements.v1.json --format markdown
+agentic-proofkit requirement-source-view --input proofkit/requirements.v1.json --format html > /tmp/proofkit-requirements.html
+
+# Validate release, package, and evidence boundaries from caller-owned facts.
+agentic-proofkit proof-receipt-admission --input proofkit/proof-receipts.json
+agentic-proofkit producer-policy-self-proof --input proofkit/producer-policy-self-proof.json
+agentic-proofkit release-authority --input proofkit/release-authority.json
+agentic-proofkit registry-consumer --input proofkit/registry-consumer.json
+agentic-proofkit receipt-trust-class --input proofkit/receipt-trust-class.json
+
+# Author repository profiles without hardcoding a stack into Proofkit.
+agentic-proofkit repo-profile-admission --input proofkit/repo-profile-admission.json
+agentic-proofkit scaffold-profile-plan --input proofkit/scaffold-profile-plan.json
+agentic-proofkit scaffold-project-structure --input proofkit/project-structure-scaffold.json
+agentic-proofkit stack-preset --preset typescript_workspace
+```
+
+Use `--input -` to read the same JSON contract from stdin when a consumer
+already has the input in memory and does not need a temporary file.
+
+Use `--input-pointer <pointer>` to run a command against a JSON Pointer inside
+the input document when the caller owns a larger envelope.
+
+Supported mode flags:
+
+- `--contract-envelope` is supported by `adoption-workflow-plan`,
+  `gradual-adoption`, `gradual-adoption-bootstrap`,
+  `gradual-adoption-guidance`, and `pilot-admission`.
+- `pilot-admission` supports `--stack-diverse` and
+  `--pilot <first|stack-diverse|all>`; `--pilot all` requires
+  `--contract-envelope`.
+- `gradual-adoption-guidance --contract-envelope` may narrow caller-owned
+  guidance with `--guidance-mode`, `--checked-scope`, and
+  `--touched-rule-id`.
+- `conformance-profile` requires exactly one of `--verify`, `--list`, or
+  `--profile <id>` and supports `--format markdown` for selected profiles.
+- `requirement-proof-resolver` and compact `requirement-proof-view` require
+  explicit local environment policy:
+  repeatable `--local-environment-class` flags or
+  `--empty-local-environment-policy`. Those flags are caller-owned policy used
+  only to project which requirements are preconditioned; Proofkit does not
+  decide environment policy.
+
+`requirement-source-view --format html` and `requirement-proof-view --format
+html` emit self-contained browser documents with hierarchy sections, local
+search, field filters, card/table presentation modes, ID and detail visibility
+toggles, and scenario/witness detail disclosure when proof inputs include those
+facts. These HTML documents are rendered projections over structured source
+records; they are not canonical source, do not execute witnesses, and should be
+generated on demand unless a consumer repository adds its own rendered-artifact
+freshness gate.
+
+`requirement-browser-server` serves the same HTML views on a loopback-only local
+HTTP endpoint. It is for review ergonomics: the server accepts explicit input,
+rejects non-loopback hosts, exposes `/healthz`, and does not scan repositories,
+execute witnesses, persist annotations, or decide freshness. Use it when a
+developer wants to inspect requirement hierarchy, owner grouping, table/card
+views, and linked proof scenarios in a browser without committing generated
+HTML.
+
+The CLI never executes native witnesses or caller-provided commands, reads
+implicit repository state, publishes artifacts, or decides proof freshness.
+Contract-envelope flags project caller-owned repository contracts into the
+smallest Proofkit input accepted by that command. `registry-consumer` is
+different: its CLI consumes a full registry-consumer report input because the
+report also requires caller-collected proof evidence. Consumers that need a
+repo-specific projection into registry-consumer input should keep that
+projection in their own repository and feed the resulting JSON to the CLI.
+Use `selective-gate-obligation-decision-input` as a pure translation step, then
+pipe it into the existing obligation decision owner when a report or agent
+envelope is needed:
+
+```bash
+agentic-proofkit selective-gate-obligation-decision-input --input proofkit/selective-gate-obligation-decision.json \
+  | agentic-proofkit obligation-decision --input -
+
+agentic-proofkit selective-gate-obligation-decision-input --input proofkit/selective-gate-obligation-decision.json \
+  | agentic-proofkit obligation-decision --input - --agent-envelope
+```
+`--agent-envelope` is an opt-in output projection for supported reports. It
+changes the shape of the emitted JSON into an agent-facing work packet, but it
+does not change command execution, proof freshness, edit approval, rollout
+approval, or repository policy authority. Agent envelopes include a cost
+contract with emitted ref counts, omitted-edge accounting, stop reason,
+sufficiency basis, and escalation route so bounded guidance cannot silently
+become a broad proof-graph prompt.
+
+## Package Boundary
+
+The public npm release is one root CLI package. The `agentic-proofkit` package
+contains the POSIX launcher, embedded statically linked Go binaries for each
+supported OS/CPU tuple, package metadata, `README.md`, `ADOPTION.md`,
+`NON_CLAIMS.md`, proofkit contract records, the proofkit contract map, specs,
+and stable design notes for shipped primitives. Consumers declare only the root
+`agentic-proofkit` dependency.
+
+Package verification smokes the installed launcher on the current runner
+platform and verifies the root tarball contains every embedded platform binary;
+it does not execute every cross-compiled architecture binary unless CI supplies
+that native tuple. Source files, tests, generated JavaScript, type declaration
+artifacts, source maps, implementation planning records, and build-cache files
+are not package artifacts.
+
+This repository targets public npm as the primary dependency channel and
+GitHub Releases as the immutable archive/provenance channel. `npm pack`, the
+package artifact test, publish dry-run evidence, post-publish registry capture,
+checksums, and the release manifest together prove tarball shape,
+external-consumer behavior, declared artifact identity, and channel boundaries.
+A consumer may treat a versioned registry package as the default dependency
+only after an actual package publication, exact install proof, parity proof,
+and rollback path are recorded by that consumer.
+
+Registry releases must distinguish local or dry-run artifact identity from the
+artifact identity served by the package registry after publish. The publish
+workflow captures post-publish package metadata with the package name, version,
+filename, shasum, and integrity. Registry-consumer evidence should reference
+that published registry identity, because it describes the artifact the
+registry serves. Consumer repositories still own whether and how exact registry
+identity becomes merge policy.
+
+Formal rule:
+
+```text
+Dry-run artifacts prove package shape before publish.
+Published registry artifacts prove the bytes consumers install.
+GitHub Release assets prove archive/provenance lookup, not dependency install authority.
+Registry-consumer evidence references published registry identity.
+```
+
+See [ADOPTION.md](ADOPTION.md) for registry and tarball channel obligations.
+See [Proofkit Contract Map](docs/proofkit-contract-map.md) for primitive
+routing and [Agent Guidance Envelope Design](docs/agent-guidance-envelope-design.md)
+for the reusable agent-facing guidance layer.
+
+## Gates
+
+```bash
+npm run check
+git diff --check
+```
+
+`npm run check` includes Go tests/static analysis, package artifact creation,
+package artifact verification, outside-consumer binary smoke proof, and
+self-hosting receipt generation. Publish dry-run evidence is owned by the
+tag-only `release` workflow because it must run over the complete release
+tarball.
+
+See [NON_CLAIMS.md](NON_CLAIMS.md) for boundaries that remain owned by
+consuming repositories.

package/dist/agentic-proofkit

@@ -0,0 +1,35 @@
+#!/usr/bin/env sh
+set -eu
+
+case "$(uname -s)" in
+  Darwin) os="darwin" ;;
+  Linux) os="linux" ;;
+  *) echo "agentic-proofkit: unsupported operating system: $(uname -s)" >&2; exit 1 ;;
+esac
+
+case "$(uname -m)" in
+  x86_64|amd64) arch="x64" ;;
+  arm64|aarch64) arch="arm64" ;;
+  *) echo "agentic-proofkit: unsupported architecture: $(uname -m)" >&2; exit 1 ;;
+esac
+
+script="$0"
+while [ -L "$script" ]; do
+  link=$(readlink "$script")
+  case "$link" in
+    /*) script="$link" ;;
+    *) script=$(CDPATH= cd -- "$(dirname -- "$script")" && pwd)/"$link" ;;
+  esac
+done
+
+dir=$(CDPATH= cd -- "$(dirname -- "$script")" && pwd)
+package_dir=$(CDPATH= cd -- "$dir/.." && pwd)
+binary="$package_dir/dist/platform/$os-$arch/agentic-proofkit"
+
+if [ ! -x "$binary" ]; then
+  echo "agentic-proofkit: missing embedded platform binary for $os-$arch" >&2
+  echo "agentic-proofkit: reinstall agentic-proofkit from the published package artifact" >&2
+  exit 1
+fi
+
+exec "$binary" "$@"

package/docs/adoption-checklist-report-design.md

@@ -0,0 +1,138 @@
+# Adoption Checklist Report Design
+
+## Decision
+
+Proofkit provides an `adoption-checklist` report that classifies
+caller-provided adoption evidence into satisfied, missing, blocked, and
+not-applicable checklist items for a selected adoption scenario.
+
+## Problem
+
+Proofkit now offers workflow plans, scaffolds, materialization manifests,
+agent envelopes, selective plans, receipt producer checks, release authority,
+and consumer checks. A consuming repository still needs a compact way to answer:
+
+```text
+Which proofkit adoption obligations are already evidenced?
+Which required obligations are still missing or blocked?
+Which commands or evidence refs should an agent inspect next?
+```
+
+Without that report, agents must infer adoption state from README prose or
+multiple primitive outputs. That repeats context loading and risks treating
+optional or advisory evidence as merge-satisfying proof.
+
+## Boundary
+
+Proofkit owns:
+
+- deterministic validation of caller-provided checklist item records;
+- required-item coverage and state classification;
+- sorted evidence refs, command refs, and blocker diagnostics;
+- stable report output and non-claims.
+
+The consuming repository owns:
+
+- repository state discovery;
+- whether an adoption item is required for its policy;
+- evidence authenticity, freshness, and producer admission;
+- native command execution and receipts;
+- merge, enforcement, release, rollout, and production-readiness decisions.
+
+Formal rule:
+
+```text
+The checklist report classifies caller-provided evidence.
+It does not discover, execute, authenticate, or approve that evidence.
+```
+
+Required item ids are caller-policy input. Proofkit validates that every
+required id references a declared item and then applies the generic state table
+below; it does not decide which items a repository must require.
+
+## Model
+
+The input declares:
+
+- `scenario`;
+- sorted checklist items;
+- sorted required item ids;
+- optional follow-up command refs;
+- explicit non-claims.
+
+Each item has:
+
+- `itemId`;
+- `status = satisfied | missing | blocked | not_applicable`;
+- owner;
+- evidence refs;
+- command refs;
+- optional blocker text;
+- non-claims.
+
+Evidence refs are opaque caller-owned references. They may name files,
+artifacts, receipt ids, URLs, or hashes according to consumer policy, but
+proofkit does not parse or dereference them as paths. A consumer that needs
+path-only evidence must enforce that in its repository policy or a separate
+profile command.
+
+State table:
+
+| Status | Required evidence | Blocker | Merge meaning |
+|---|---|---|---|
+| `satisfied` | Must have at least one evidence ref | Must be absent | May satisfy a required checklist item if caller policy made it required |
+| `missing` | May be empty | Must be absent | Fails when required; advisory when optional |
+| `blocked` | May be empty | Must be present | Fails when required; visible when optional |
+| `not_applicable` | May be empty | Must be absent | Fails when required; advisory when optional |
+
+Command refs are routing metadata only. They never count as evidence refs and
+never prove native command execution or command pass evidence.
+
+The report passes only when every required item is `satisfied`. Missing,
+blocked, and not-applicable required items are failures. Optional items may be
+missing or not-applicable without failing the report, but they remain visible in
+the summary and diagnostics.
+
+The `scenario` field reuses `ProofkitAdoptionWorkflowScenario` from adoption
+workflow planning. The checklist report does not own a second scenario
+vocabulary or scenario-routing policy.
+
+## Rejected Alternatives
+
+| Alternative | Rejection reason |
+|---|---|
+| Scan repository files to infer checklist state | Repository topology and file existence are consumer-owned facts. |
+| Reuse adoption workflow plans | Workflow plans route commands; they do not classify already-collected evidence. |
+| Reuse gradual adoption guidance | Guidance is module-scoped and source-report-scoped; adoption checklist state can span packaging, profile, bindings, witnesses, receipts, and release channel. |
+| Treat checklist output as an agent work packet | Agent envelopes already own bounded work packets; checklist reports own compact state classification only. |
+| Treat optional missing items as failures | Consumers need gradual adoption without pretending optional evidence is merge-blocking. |
+
+## Proof Obligations
+
+- Unit tests prove pass/fail classification, required-item coverage,
+  deterministic sorting, optional item non-failures, and malformed input
+  rejection.
+- CLI tests prove stable JSON output, stdin parity, JSON pointer selection,
+  failed-checklist exit codes, and unsupported flag rejection.
+- Package artifact tests prove the package binary, CLI smoke path, and design note
+  are shipped to outside consumers.
+- Full package check proves existing adoption workflow, scaffold, and guidance
+  behavior remains unchanged.
+
+## Non-Claims
+
+Adoption checklist reports do not claim:
+
+- repository-state discovery;
+- file existence;
+- evidence authenticity;
+- evidence freshness;
+- producer admission;
+- native command execution;
+- command pass evidence;
+- merge approval;
+- enforcement promotion approval;
+- release approval;
+- rollout approval;
+- production readiness;
+- consumer policy authority.