agentic-proofkit 0.1.91

package/docs/bootstrap-agent-envelope-design.md

@@ -0,0 +1,97 @@
+# Bootstrap Agent Envelope Design
+
+Status: accepted; implemented as an opt-in CLI projection.
+
+Owner: `proofkit`.
+
+## Purpose
+
+Gradual adoption bootstrap reports include starter payloads. Those payloads are
+useful for materialization, but they are too large for the first agent routing
+step. Agents need the smaller actionable packet: which caller-owned files are
+planned, which observe-mode commands should be run, and which promotion steps
+remain caller-owned.
+
+Formal goal:
+
+```text
+caller-owned bootstrap report
+  -> bounded bootstrap agent envelope
+  -> caller-owned file materialization and observe-mode verification
+```
+
+## Authority Boundary
+
+Proofkit owns:
+
+- deterministic envelope construction from the bootstrap result;
+- bounded planned-file refs with context roles;
+- command refs for emitted observe-mode bootstrap commands;
+- route questions and action-plan projection;
+- invalid-input envelope reporting for parsed bootstrap failures.
+
+The consuming repository owns:
+
+- whether to create or update the planned files;
+- final specification and proof-binding content;
+- native witness execution;
+- receipt production and producer admission;
+- CI freshness, merge approval, enforcement promotion, and rollout decisions.
+
+Formal rule:
+
+```text
+The bootstrap envelope routes first adoption work.
+The bootstrap report owns starter payload planning.
+The consuming repository owns materialization and verification.
+```
+
+## Model
+
+The projection emits:
+
+- context refs for planned module spec, profile, adoption, guidance, proof
+  binding, and witness-plan files;
+- command refs for emitted observe-mode proofkit commands;
+- bind, verify, and promote action items;
+- route questions for what changed, what proves it, and who owns it;
+- no payload body copies;
+- no receipt refs because the bootstrap step has not executed witnesses.
+
+The envelope is intentionally not a starter-file transport. Consumers that need
+the actual starter JSON payloads must inspect the full bootstrap report.
+
+## Rejected Alternatives
+
+| Alternative | Rejection reason |
+|---|---|
+| Emit the full bootstrap report as the agent packet | It repeats starter payloads and defeats the purpose of bounded guidance. |
+| Make the bootstrap command write planned files | It would turn proofkit into a repository mutator and policy owner. |
+| Treat planned commands as passed evidence | Bootstrap commands are instructions for caller-owned execution, not receipts. |
+| Add a generic envelope for every report shape | Report families need separate mapping proofs to avoid misleading actions. |
+
+## Proof Obligations
+
+- CLI test for `gradual-adoption-bootstrap --agent-envelope`;
+- invalid-input envelope test for bootstrap parsing failures;
+- unsupported command test proving unrelated report families still reject
+  `--agent-envelope`;
+- package artifact test proving the design note ships with the public CLI
+  contract;
+- full package check proving ordinary bootstrap output is unchanged without
+  `--agent-envelope`.
+
+## Non-Claims
+
+Bootstrap agent envelopes do not claim:
+
+- file writes;
+- starter payload completeness inside the envelope;
+- native witness execution;
+- command pass evidence;
+- receipt freshness;
+- producer admission;
+- merge approval;
+- enforcement promotion approval;
+- rollout approval;
+- repository policy ownership.

package/docs/bootstrap-materialization-manifest-design.md

@@ -0,0 +1,100 @@
+# Bootstrap Materialization Manifest Design
+
+Status: accepted; implemented as an opt-in dry-run projection.
+
+Owner: `proofkit`.
+
+## Purpose
+
+Gradual adoption bootstrap reports produce starter payloads, but a consuming
+repository still needs a deterministic review surface before an agent writes
+files. The materialization manifest turns the bootstrap result into an explicit
+dry-run file list with payload content hashes, caller-owned content gaps, and
+non-claims.
+
+Formal goal:
+
+```text
+caller-owned bootstrap input
+  -> bootstrap report
+  -> dry-run materialization manifest
+  -> caller-owned review and file writes
+```
+
+## Authority Boundary
+
+Proofkit owns:
+
+- deterministic manifest construction from an admitted bootstrap report;
+- mapping bootstrap payload keys to repository-relative file paths;
+- stable JSON payload text and `sha256:` content refs for generated starter
+  payloads;
+- explicit caller-content-required entries for files proofkit cannot own.
+
+The consuming repository owns:
+
+- whether to write, overwrite, merge, or ignore each file;
+- final specification text and repository profile content;
+- existing-file conflict resolution;
+- native witness execution;
+- receipt production, CI freshness, merge approval, enforcement promotion, and
+  rollout decisions.
+
+Formal rule:
+
+```text
+The manifest describes candidate files.
+It does not write candidate files.
+The consuming repository owns all materialization decisions.
+```
+
+## Model
+
+The projection emits:
+
+- `manifestKind = proofkit.gradual-adoption-bootstrap-materialization-manifest`;
+- a source bootstrap report ref with a stable hash;
+- one file entry per planned bootstrap file;
+- `payload_available` entries with stable JSON content and `contentSha256`;
+- `caller_content_required` entries with no content for module specs and
+  repository profiles;
+- next commands that should be run after caller-owned materialization review;
+- non-claims denying file writes, file existence, witness execution, merge,
+  enforcement, rollout, and product-readiness approval.
+
+## Rejected Alternatives
+
+| Alternative | Rejection reason |
+|---|---|
+| Let `gradual-adoption-bootstrap` write files | This would make proofkit a repository mutator and create hidden policy authority. |
+| Put file content into the agent envelope | Agent envelopes are bounded routing packets; payload bodies would defeat token efficiency. |
+| Emit only hashes without content | That would not help first-time adoption because the consumer would still need to recover the starter payloads elsewhere. |
+| Treat module specs and profiles as generated content | Those files carry repository-specific meaning and must remain caller-owned. |
+
+## Proof Obligations
+
+- API test proving deterministic file entries, content hashes, and caller-owned
+  gaps;
+- CLI test for `gradual-adoption-bootstrap --materialization-manifest`;
+- CLI test proving `--materialization-manifest` is bootstrap-only and mutually
+  exclusive with `--agent-envelope`;
+- package artifact test proving the design note ships with the public CLI
+  contract;
+- full package check proving ordinary bootstrap and envelope outputs are
+  unchanged.
+
+## Non-Claims
+
+Bootstrap materialization manifests do not claim:
+
+- file writes;
+- file existence;
+- overwrite safety;
+- final specification or repository profile content;
+- native witness execution;
+- command pass evidence;
+- receipt freshness;
+- merge approval;
+- enforcement promotion approval;
+- rollout approval;
+- repository policy ownership.

package/docs/branch-authority-report-design.md

@@ -0,0 +1,121 @@
+# Branch Authority Report Design
+
+## Decision
+
+Proofkit provides a `branch-authority` report that compares caller-provided
+branch authority facts against caller-provided expected branches.
+
+## Problem
+
+Repository automation often depends on several branch references:
+
+- repository default branch;
+- pull request base branch;
+- CI push trigger branch;
+- package or release source branch;
+- tag-only release workflow guard branch.
+
+If those references drift, review, package, and publish authority can point at
+different source lines. A consumer needs a compact report that exposes that
+drift without requiring Proofkit to query GitHub, parse workflows, or decide
+which branch name is correct.
+
+Formal risk:
+
+```text
+observed branch ref != expected branch ref
+  -> review, CI, or publish authority may evaluate a stale source line
+  -> proof and release evidence may no longer describe the same code line
+```
+
+## Boundary
+
+Proofkit owns:
+
+- exact validation of caller-provided branch authority records;
+- deterministic comparison of `observedBranch` to `expectedBranch`;
+- required versus advisory drift classification;
+- stable report output and non-claims.
+
+The consuming repository owns:
+
+- repository default branch discovery;
+- workflow parsing;
+- branch protection and repository settings;
+- which branch refs are required;
+- whether an expected branch is correct;
+- remediation, merge, publish, release, and rollout decisions.
+
+Formal rule:
+
+```text
+The branch authority report compares caller-provided facts.
+It does not discover branch facts, mutate settings, or approve release.
+```
+
+## Model
+
+The input declares:
+
+- `reportId`;
+- branch refs;
+- preexisting caller failures;
+- non-claims.
+
+Each branch ref declares:
+
+- `refId`;
+- `refKind`;
+- `observedBranch`;
+- `expectedBranch`;
+- `required`;
+- `evidenceRef`;
+- non-claims.
+
+The report fails when a required branch ref drifts or the caller supplies
+preexisting failures. Optional branch drift is visible as advisory diagnostics,
+but it does not fail the report.
+
+`expectedBranch` is caller policy, not Proofkit policy. This lets consumers use
+`main`, `master`, release branches, protected maintenance branches, or separate
+publish-source branches without Proofkit hard-coding a repository convention.
+
+Evidence refs are opaque caller-owned references. They may name files, artifact
+ids, setting snapshots, workflow excerpts, URLs, or hashes according to
+consumer policy. Proofkit does not parse or dereference them.
+
+## Rejected Alternatives
+
+| Alternative | Rejection reason |
+|---|---|
+| Query GitHub repository settings | Credentialed discovery and API trust roots are consumer-owned. |
+| Parse workflow YAML in Proofkit | Workflow semantics and parser policy are repository-owned and provider-specific. |
+| Hard-code `main` as the expected branch | That would make Proofkit a repository policy owner. |
+| Treat optional drift as failure | Consumers need advisory visibility for fixtures, migration leftovers, and non-blocking refs. |
+
+## Proof Obligations
+
+- Unit tests prove required drift failure, optional drift visibility,
+  preexisting-failure propagation, deterministic ordering, and malformed input
+  rejection.
+- CLI tests prove stable JSON output, stdin parity, failed-report exit codes,
+  and unsupported flag rejection.
+- Package artifact tests prove package binary, installed CLI smoke, and shipped
+  design-note coverage.
+- Full package check proves existing proofkit behavior remains unchanged.
+
+## Non-Claims
+
+Branch authority reports do not claim:
+
+- repository settings discovery;
+- workflow parsing;
+- GitHub API access;
+- branch mutation;
+- branch protection proof;
+- CI execution;
+- publish execution;
+- package publication;
+- release approval;
+- rollout approval;
+- consumer policy authority.

package/docs/changed-path-set-agent-envelope-design.md

@@ -0,0 +1,70 @@
+# Changed Path Set Agent Envelope Design
+
+Status: accepted.
+
+Owner: `proofkit`.
+
+## Problem
+
+`changed-path-set` is the earliest reusable input to selective proof planning.
+The canonical report is correct for machines, but a coding agent should not
+need to load the full path payload before deciding the next route. A bounded
+agent packet is useful only if it preserves the trust boundary:
+
+```text
+caller-supplied changed paths -> admitted set report -> bounded route packet
+```
+
+The packet must not become git discovery, command selection, freshness proof,
+or merge approval.
+
+## Decision
+
+`buildProofkitChangedPathSetAgentEnvelope(report)` projects an existing
+`ProofkitChangedPathSetReport` into an opt-in `ProofkitAgentGuidanceEnvelope`.
+The CLI exposes the same projection via:
+
+```bash
+agentic-proofkit changed-path-set --input proofkit/changed-path-set.json --agent-envelope
+```
+
+The projection is intentionally narrow:
+
+- `sourceReport.reportKind`, `reportId`, and `state` come from the report.
+- `sourceReport.stableHash` is `changedPathSetHash` for caller-owned
+  correlation only.
+- `contextRefs` are JSON pointers into the source report.
+- `commands`, `receiptRefs`, and action `commandIds` are empty.
+- path values and diagnostics stay in the source report and are represented by
+  exact omission counts.
+- failed source reports produce failed envelopes and a blocked precondition.
+- empty admitted sets produce a non-blocking caller-owned policy question.
+
+## Rejected Alternatives
+
+| Alternative | Rejection reason |
+|---|---|
+| Include every changed path directly in the envelope | It breaks the bounded-envelope contract and increases agent token load. |
+| Infer package commands from paths | Command selection belongs to consumer-owned selective/workspace policy, not changed-path admission. |
+| Read git diff or filesystem state inside proofkit | Proofkit must remain explicit-input infrastructure and must not own repository-state discovery. |
+| Treat an empty changed set as no-op approval | Empty source semantics are repository policy; proofkit cannot prove freshness or completeness. |
+
+## Invariants
+
+1. Ordinary `changed-path-set` output remains the canonical report.
+2. `--agent-envelope` changes only the output projection.
+3. The envelope never executes native witnesses.
+4. The envelope never infers command ids, proof routes, fallback policy,
+   receipt freshness, merge approval, release approval, or rollout approval.
+5. Failed changed-path admission remains failed in the envelope.
+6. The set hash is an identity correlation field, not source freshness or
+   completeness evidence.
+
+## Proofs
+
+- Unit tests prove passed, failed, and empty-set envelope projections.
+- CLI tests prove ordinary report output remains stable and
+  `changed-path-set --agent-envelope` is opt-in.
+- Package artifact tests prove the packed CLI exposes the projection.
+- Package boundary tests prove the design document and package binary are shipped.
+

package/docs/completion-criteria-report-design.md

@@ -0,0 +1,132 @@
+# Completion Criteria Report Design
+
+## Decision
+
+Proofkit provides a `completion-criteria` report that validates and classifies
+caller-provided completion criteria in the falsifiable table form:
+
+```text
+Criterion | Validator or proof | Fails when
+```
+
+The primitive owns deterministic shape admission and state reporting only. It
+does not execute validators, authenticate evidence, compute freshness, own
+requirement meaning, or approve merge.
+
+## Problem
+
+The spec-first machine-proof architecture is complete only when each completion
+criterion has a falsifiable validator or proof and a failure predicate. A plain
+checklist can say that something is done, but it does not prove that the item is
+testable, owner-scoped, or blocked for a precise reason.
+
+Without a generic report, each consuming repository must invent its own
+completion table grammar. That repeats infrastructure code and lets informal
+review notes masquerade as completion evidence.
+
+## Boundary
+
+Proofkit owns:
+
+- exact schema admission for caller-provided completion criteria;
+- criterion class and status vocabularies;
+- the rule that a criterion must declare at least one validator or proof ref;
+- the rule that `satisfied`, `not_applicable`, and `deferred_admitted` states
+  require evidence refs;
+- blocking-unsatisfied classification;
+- deterministic report output and non-claims.
+
+The consuming repository owns:
+
+- which criteria exist and which are blocking;
+- requirement meaning and proof adequacy;
+- validator, proof, evidence, and owner ref content;
+- evidence authenticity and receipt freshness;
+- native command execution;
+- merge, release, rollout, and production-readiness decisions.
+
+Formal rule:
+
+```text
+Completion criteria reports prove falsifiable completion shape.
+They do not prove that the referenced validators or proofs actually passed.
+```
+
+## Model
+
+Input records have:
+
+- `criterionId`;
+- `criterionClass = blocking | advisory | deferred`;
+- human-readable criterion text;
+- owner;
+- validator refs;
+- proof refs;
+- structured decision refs for human review, checklist, or code-review
+  validators;
+- sorted `failsWhen` conditions;
+- status;
+- evidence refs;
+- optional blocker text;
+- non-claims.
+
+Statuses:
+
+| Status | Required shape | Blocking meaning |
+|---|---|---|
+| `satisfied` | Evidence refs required, blocker forbidden | Satisfies this report |
+| `not_applicable` | Evidence refs required, blocker forbidden | Satisfies this report for scoped-out criteria |
+| `missing_evidence` | Blocker forbidden | Fails when blocking |
+| `failed` | Blocker forbidden | Fails when blocking |
+| `blocked_missing_precondition` | Blocker required | Fails when blocking |
+| `deferred_admitted` | Deferred class and evidence refs required | Visible but non-blocking |
+| `advisory_skipped` | Advisory class required | Visible but non-blocking |
+
+The report passes only when every blocking criterion is `satisfied` or
+`not_applicable`. Advisory and deferred criteria remain visible, but Proofkit
+does not decide whether a consumer should promote them to blocking.
+
+`failsWhen` is a sorted, non-empty array because a falsifiable completion
+criterion must name concrete failure conditions instead of one opaque paragraph.
+`structuredDecisionRefs` are opaque caller-owned refs. A consuming repository
+must use them when a validator or proof route is a human review, checklist, or
+code-review decision; Proofkit validates ref shape but does not infer that need
+from repository-specific wording.
+
+## Rejected Alternatives
+
+| Alternative | Rejection reason |
+|---|---|
+| Extend `adoption-checklist` | Adoption checklist owns adoption state, not the generic falsifiable completion table required by the architecture. |
+| Use `obligation-decision` directly | Obligation decisions classify proof obligations; completion criteria describe architecture/readiness criteria and their validators. |
+| Accept free-form checklist text | It would not machine-check the validator/proof and failure predicate fields. |
+| Infer human-review routes from ref wording | That would encode consumer-specific semantics and make Proofkit a policy owner. |
+| Execute validators from the report | Native command execution, credentials, locks, and freshness are consumer-owned. |
+
+## Proof Obligations
+
+- Unit tests prove pass/fail classification, evidence requirements,
+  class/status restrictions, duplicate rejection, and deterministic output.
+- CLI tests prove JSON output, stdin parity, JSON pointer selection, and
+  unsupported-mode rejection.
+- Package artifact tests prove the public export, installed CLI path, and
+  packed design note.
+- Full package check proves the additive primitive does not regress existing
+  reports.
+
+## Non-Claims
+
+Completion criteria reports do not claim:
+
+- validator execution;
+- native proof execution;
+- evidence authenticity;
+- receipt freshness;
+- requirement meaning;
+- proof adequacy;
+- structured-review completeness;
+- consumer policy authority;
+- merge approval;
+- release approval;
+- rollout approval;
+- production readiness.

package/docs/custom-rule-boundary-design.md

@@ -0,0 +1,56 @@
+# Custom Rule Boundary Design
+
+Status: implemented.
+
+Owner: `proofkit`.
+
+## Problem
+
+Consumer repositories sometimes need local diagnostic rules before a generic
+Proofkit primitive exists for that exact repository invariant. Those rules are
+useful only if they cannot suppress generic failures, mutate generic decision
+state, read undeclared inputs, use credentials, access network resources, or
+become a permanent second proof engine.
+
+Without a generic boundary validator, custom rules can silently turn local
+adoption glue into hidden proof authority.
+
+## Decision
+
+Add `custom-rule-boundary`, a deterministic report over caller-provided custom
+rule declarations.
+
+The primitive validates that every custom rule is:
+
+- namespaced under the consuming repository or profile, not under Proofkit;
+- explicitly `local_diagnostics_only`;
+- append-only for findings;
+- unable to downgrade or satisfy generic decision state;
+- network-free and credential-free;
+- deterministic, stably ordered, and secret-redacted;
+- bounded by affected path globs and a use limit;
+- paired with remediation metadata;
+- paired with a concrete removal condition and owner.
+
+## Authority Boundary
+
+Proofkit validates custom-rule metadata and emits deterministic diagnostics. It
+does not execute custom rules, inspect repository state, authenticate evidence,
+admit receipts, compute freshness, approve merge, or promote a local invariant
+into generic Proofkit behavior.
+
+## Rejected Alternatives
+
+| Alternative | Rejected Because |
+|---|---|
+| Put custom-rule admission into repo-profile structural admission. | Repository profiles describe topology. Custom-rule monotonicity is a separate proof-infrastructure boundary. |
+| Let custom rules suppress or downgrade generic findings with explicit flags. | That would make local rules a bypass for generic Proofkit failures. |
+| Allow `proofkit.*` namespaces for consumer rules. | That would confuse repository-local diagnostics with generic Proofkit-owned contracts. |
+| Execute custom rules from this primitive. | Execution, filesystem access, credentials, and receipts are consumer-owned native proof surfaces. |
+
+## Follow-Up
+
+Consumer repositories can reference this report from adoption or selective gate
+inputs when they admit repository-local custom diagnostics. Promotion from a
+custom rule to a generic Proofkit primitive requires a separate design and
+review path.

package/docs/deployment-evidence-admission-design.md

@@ -0,0 +1,80 @@
+# Deployment Evidence Admission Design
+
+Status: implemented.
+
+Owner: `proofkit`.
+
+## Problem
+
+Deployment evidence across repositories often repeats the same reusable
+admission mechanics: stable envelope shape, required evidence coverage declared
+by the caller, non-local evidence refs, digest-pinned image refs, source commit
+shape, safe endpoint URLs, temporary endpoint metadata, and secret-shaped value
+rejection.
+
+If every consumer reimplements those mechanics, local deployment verifiers grow
+large and drift-prone. If Proofkit defines the deployment topology, it becomes a
+consumer product, environment, rollout, or production-readiness policy owner.
+If raw operator artifacts are checked only after projection into normalized
+facts, unprojected notes can still carry secret-shaped material.
+
+## Decision
+
+Add `deployment-evidence-admission`, a deterministic report over
+caller-provided deployment evidence facts and caller-provided policy facts.
+
+The primitive validates:
+
+- exact evidence envelope and fact shape;
+- expected schema, proof scope, and deployment claim supplied by the caller;
+- caller-required non-claims;
+- caller-required fact ids and fact kinds;
+- non-local refs using caller-provided local-ref indicators;
+- caller-forbidden value indicators;
+- digest-pinned image refs when required by caller policy;
+- lowercase 40-character source commits when required by caller policy;
+- endpoint HTTPS, URL credential rejection, local host rejection, stable versus
+  temporary endpoint classification, temporary endpoint approval metadata, and
+  RFC3339 UTC expiry shape;
+- recursive secret-shaped value rejection without echoing secret values.
+
+The evidence uses generic `facts[]`; consumers choose the fact ids, kinds,
+refs, URLs, image refs, source commits, and metadata that represent their own
+deployment topology.
+
+Consumers may additionally provide `rawOperatorEvidence[]` records. Those
+records are not topology authority and do not satisfy required fact coverage;
+they are admitted as JSON and scanned with the reusable
+`scanProofkitSecretShapedJson` primitive before the report is considered safe.
+
+## Authority Boundary
+
+Proofkit validates only reusable admission mechanics. It does not read files,
+query deployment systems, authenticate evidence refs, choose fact vocabulary,
+choose environment names, choose endpoint policy, execute deployment, execute
+rollback, prove publication, approve rollout, approve production readiness, or
+decide merge policy.
+
+The consuming repository owns the deployment schema name, proof-scope
+vocabulary, claim vocabulary, required fact ids and kinds, required non-claims,
+local-ref indicators, forbidden value indicators, temporary endpoint suffixes,
+which raw operator artifacts are read and passed to `rawOperatorEvidence`,
+native witness commands, receipt producer policy, CI admission, and rollout
+decision.
+
+## Rejected Alternatives
+
+| Alternative | Rejected Because |
+|---|---|
+| Keep every deployment evidence check in each consumer. | This duplicates reusable admission mechanics and increases drift risk. |
+| Add a Proofkit production-deployment verifier with fixed topology fields. | That would move consumer product and rollout policy into Proofkit. |
+| Read evidence files directly from the Proofkit primitive. | File paths, environment variables, and operator artifact locations are consumer-owned. |
+| Let raw operator evidence satisfy required fact coverage. | Raw artifacts are safety-scanned only; normalized facts remain the proof-shape contract. |
+| Treat local or credentialed evidence as production readiness. | Evidence admission only validates artifact shape and safety; readiness remains outside Proofkit. |
+
+## Follow-Up
+
+Consumers can wrap this primitive with local file reading and policy constants,
+then keep their native selftests as product witnesses. A consumer can retire
+local helper code only after the exact Proofkit version is published, pinned,
+and proved through its own registry-consumer and wrapper selftests.