agentic-proofkit 0.1.91

package/docs/requirement-proof-resolver-projection-design.md

@@ -0,0 +1,97 @@
+# Requirement Proof Resolver Projection Design
+
+Status: active package design.
+
+Owner: `proofkit`.
+
+## Problem
+
+Some consuming repositories already store compact row-array requirement proof
+contracts, but their local resolver outputs need more than the compact
+conformance projection: invariant role, owned invariant, mutation-resistance
+state, witness resolution order, surface/scenario lookup rows, and selector
+matches. Reimplementing that resolver in every repository duplicates generic
+projection mechanics and blocks retirement of consumer-local infrastructure
+code.
+
+## Decision
+
+Proofkit owns a deterministic compact resolver projection:
+
+```text
+caller compact requirement-proof contract
+  + optional caller-owned local environment class list
+  -> proofkit resolver projection
+  -> lookup rows for requirements, surfaces, scenarios, and witness selectors
+```
+
+The CLI exposes
+`projectProofkitCompactRequirementProofResolver`. The CLI exposes the same
+projection through `agentic-proofkit requirement-proof-resolver --input <path>`.
+Repeatable `--local-environment-class <id>` flags are policy input, not
+Proofkit-owned policy. The CLI also accepts `--empty-local-environment-policy`
+to represent the explicit caller decision that no environment class is local.
+Absent policy fails closed because a boolean `preconditioned` value cannot
+represent unknown environment policy without overclaiming.
+
+## Authority Boundary
+
+Proofkit owns:
+
+- compact contract shape admission;
+- deterministic row sorting and selector grouping;
+- preservation of resolver-relevant compact fields;
+- preconditioned projection from caller-supplied local environment classes;
+- surface-level precondition propagation;
+- caller non-claim preservation;
+- lookup-only non-claims.
+
+Consumers own:
+
+- requirement meaning;
+- local environment-class policy;
+- command/environment vocabulary;
+- repository file discovery and source freshness;
+- native witness execution and receipt trust;
+- proof adequacy, merge policy, rollout, and production claims.
+
+Formal rule:
+
+```text
+Proofkit can project explicit contract facts.
+Proofkit cannot decide whether a consumer environment is local unless the
+consumer supplies that policy as input.
+```
+
+## Rejected Alternatives
+
+| Alternative | Rejection reason |
+|---|---|
+| Keep the resolver in each consumer repository | Duplicates generic projection code and makes proof-route retirement harder to prove. |
+| Hardcode local environment classes in Proofkit | Would turn Proofkit into a repository-policy owner and break reuse across stacks. |
+| Infer environment locality from command strings | Shell text is not policy authority and cannot safely classify credentials, network, or live resources. |
+| Replace native witnesses with resolver rows | Resolver rows are lookup metadata; native tests and tools still own executable verification procedures. |
+
+## Proof Obligations
+
+- Unit tests prove full resolver fields, selector grouping, and witness order.
+- Unit tests prove preconditioned state depends on caller-provided local
+  environment classes.
+- Negative tests reject malformed compact witness order.
+- CLI tests prove deterministic projection and flag admission.
+- Package artifact tests prove the public API, CLI, design note, and built
+  dist are included in the published artifact.
+
+## Non-Claims
+
+Requirement proof resolver projections do not claim:
+
+- native witness execution;
+- command success;
+- receipt freshness;
+- producer authentication;
+- local environment policy unless supplied by the caller;
+- proof satisfaction;
+- merge approval;
+- rollout approval;
+- production readiness.

package/docs/requirement-proof-source-set-design.md

@@ -0,0 +1,72 @@
+# Requirement Proof Source Set Design
+
+Status: active package design.
+
+Owner: `proofkit`.
+
+## Problem
+
+Large repositories can split requirement proof bindings into owner fragments.
+Consumers still need one canonical `requirement-proof-bindings/v1` payload for
+projection, impact routing, selective planning, and view rendering. Rewriting
+the source-set resolver in every repository duplicates fail-closed mechanics and
+increases infrastructure code.
+
+## Decision
+
+Proofkit owns a generic source-set normalizer:
+
+```text
+caller source-set payload
+  + caller source text/hash/path facts
+  + caller canonical envelope
+  -> proofkit source-set normalization
+  -> canonical requirement-proof-bindings/v1 payload
+```
+
+The `agentic-proofkit requirement-proof-source-set` CLI exposes
+the same boundary. The CLI is for language-neutral consumers that can provide
+the source-set payload, exact source texts, hashes, paths, and canonical
+envelope explicitly. It does not read repository files or discover sources.
+
+The normalizer admits `requirement-proof-bindings/source-set/v1`, full
+`requirement-proof-bindings/v1` sources, compact `fragment/v1` sources, and
+owner-defaulted `fragment/v2` sources. `fragment/v2` defaults `surface_id` from
+the fragment `source_id`, derives the default `scenario_id` from
+`source_id::owned_invariant`, and lets compact witness rows inherit binding
+environment classes and verify commands only when the row explicitly uses the
+compact witness shape.
+
+## Authority Boundary
+
+Proofkit owns:
+
+- source-set and fragment shape admission;
+- source text SHA-256 comparison against caller-owned source-set rows;
+- nested source-set rejection;
+- role/payload/source-id mismatch rejection;
+- compact fragment inflation into the caller-provided canonical envelope;
+- deterministic source path reporting.
+
+Consumers own:
+
+- repository file discovery and source text reads;
+- canonical envelope text, non-claims, and column authority;
+- requirement meaning;
+- command/environment vocabulary;
+- native witness execution;
+- proof freshness, receipt trust, merge policy, rollout, and production claims.
+
+## Non-Claims
+
+This primitive does not scan repositories, execute commands, authenticate
+receipts, decide proof satisfaction, infer changed scope, approve merges, or
+replace consumer-specific validators. It only converts caller-provided source
+facts into one canonical binding payload or fails closed.
+
+## Proof Invariant
+
+For any accepted source set, downstream consumers must observe the same
+canonical contract shape as if the consumer had stored one monolithic
+`requirement-proof-bindings/v1` contract. Any semantic difference after
+normalization is a defect in the normalizer or the caller-provided envelope.

package/docs/requirement-proof-view-design.md

@@ -0,0 +1,138 @@
+# Requirement Proof View Design
+
+Status: accepted; implemented as on-demand view-model and renderer primitives.
+
+Owner: `proofkit`.
+
+## Purpose
+
+Structured requirement proof records are the machine authority, but humans need
+a readable view that does not require scanning raw JSON. Proofkit should provide
+deterministic presentation machinery while preserving the authority split:
+
+```text
+structured requirement proof input
+  -> lookup-only view model
+  -> on-demand Markdown or self-contained browser-ready HTML rendering
+
+compact requirement proof contract
+  + caller-owned local environment policy
+  -> compact lookup-only view model
+  -> on-demand Markdown or self-contained browser-ready HTML rendering
+```
+
+## Authority Boundary
+
+Proofkit owns:
+
+- deterministic view-model construction from caller-owned requirement proof
+  binding input;
+- deterministic compact view-model construction from caller-owned compact
+  requirement proof contracts and explicit local environment policy;
+- graph or selected-slice presentation scope;
+- Markdown and HTML string rendering from the view model;
+- local browser search, field filters, and ID visibility controls in HTML
+  outputs;
+- HTML escaping for rendered text;
+- fail-closed rejection of invalid requirement proof bindings;
+- explicit lookup-only authority and non-claims.
+
+The consuming repository owns:
+
+- requirement meaning;
+- proof-binding content;
+- source-set and repository file discovery before a compact contract reaches
+  the renderer;
+- local environment-class policy;
+- native witness execution;
+- receipt freshness and producer admission;
+- merge, rollout, and product-readiness decisions;
+- whether any rendered output is tracked with freshness gates.
+
+Formal rule:
+
+```text
+Structured records own machine-admissible proof routing.
+Rendered views explain those records to humans.
+Rendered views never become authority by default.
+```
+
+## Model
+
+The view model includes:
+
+- binding id;
+- scope: `graph` or `slice`;
+- lookup-only authority marker;
+- selected requirements;
+- owner, spec path, claim level, proof state;
+- scenario, command, environment, and witness-path summaries;
+- non-claims.
+
+The compact view model includes:
+
+- compact contract id;
+- lookup-only authority marker;
+- requirement, preconditioned requirement, and command counts;
+- surface id, scenario id, invariant role, owned invariant, proof state,
+  blocking status, required environments, verify commands, witness selectors,
+  positive/falsification witness roles, and mutation-resistance state;
+- caller-provided local environment policy;
+- non-claims.
+
+Markdown and HTML renderers accept only the view model. They do not read files,
+execute commands, or inspect repository state.
+
+HTML renderers emit self-contained browser documents. Browser filters operate
+only on fields already present in the view model. They do not parse rendered
+text as authority, fetch external assets, or persist repository state.
+
+View-model construction fails closed when the underlying requirement proof
+binding report fails. A rendered view must not make malformed or semantically
+invalid proof bindings easier to cite as evidence.
+
+Compact view construction fails closed without explicit local environment
+policy because preconditioned presentation is policy-dependent. Proofkit may
+render explicit compact facts, but it must not infer spec paths, owner routes,
+or whether an environment class is local.
+
+## Rejected Alternatives
+
+| Alternative | Rejection reason |
+|---|---|
+| Commit generated Markdown or HTML views by default | Adds drift-prone generated truth and token load. |
+| Use HTML as the canonical source format | HTML is presentation-heavy and weak for deterministic machine validation. |
+| Render from raw test output | Test output does not own requirement meaning or proof routing. |
+| Add a local web server in this slice | Server lifecycle, browser launch, port auth, and annotation feedback are optional presentation adapters, not proof-view authority. |
+| Keep compact view rendering only in consumers | Duplicates generic presentation mechanics for the current compact proof format and delays consumer infrastructure retirement. |
+| Infer local environment classes from command strings | Command text is not policy authority and cannot safely classify live, credentialed, or local environments. |
+| Collapse positive and falsification witnesses into an unordered selector list | Requirement proof views must not erase witness roles that consumers need for audit and generated lookup routing. |
+
+## Proof Obligations
+
+- Unit tests for graph and slice view models.
+- Unit tests for compact view models built from compact contracts.
+- Negative test proving invalid proof bindings do not render.
+- Negative test proving compact views require explicit local environment
+  policy.
+- Role-preservation test proving positive and falsification witnesses remain
+  distinct in compact views.
+- Renderer tests for Markdown content and HTML escaping.
+- Renderer tests for browser controls and filter metadata.
+- CLI test for `requirement-proof-view` with JSON, Markdown, and HTML output
+  for both structured and compact inputs.
+- Package artifact test proving the package binary and packed contract files.
+
+## Non-Claims
+
+Requirement proof views do not claim:
+
+- canonical requirement meaning;
+- native witness execution;
+- command success;
+- receipt freshness;
+- producer authentication;
+- local environment policy beyond caller-provided inputs;
+- merge approval;
+- rollout approval;
+- generated artifact freshness.

package/docs/requirement-source-admission-design.md

@@ -0,0 +1,66 @@
+# Requirement Source Admission Design
+
+Status: implemented.
+
+Owner: `proofkit`.
+
+## Problem
+
+Spec-first proof architecture needs a machine-admissible source record before
+requirement-to-proof bindings can be trusted. Existing proof-binding validation
+accepts requirement rows as routing input, but it does not validate the
+canonical `requirements.v1.json` source package lifecycle.
+
+Formal gap:
+
+```text
+Human spec owns durable meaning.
+Proof binding owns verification route.
+Therefore the requirement source must be admitted before downstream routes can
+claim stable REQ-* identity.
+```
+
+## Decision
+
+Add `requirement-source-admission`, a deterministic report over
+caller-provided requirement source records.
+
+The primitive validates:
+
+- exact `docs/specs/<capability>/overview.md` and
+  `docs/specs/<capability>/requirements.v1.json` package shape;
+- stable sorted `REQ-*` records;
+- exact requirement source fields;
+- claim level, risk class, owner, invariant text, non-claim refs, and
+  non-claims;
+- lifecycle state, replacement traceability, and removal evidence;
+- non-active lifecycle evidence and active replacement targets;
+- deferral policy for deferred requirements;
+- active blocking requirement proof-binding route refs;
+- update policy for impact declaration and proof-binding review.
+
+## Authority Boundary
+
+Proofkit owns reusable admission grammar and deterministic diagnostics only.
+
+Consumer repositories own:
+
+- requirement sentence meaning;
+- whether a requirement should exist;
+- proof-binding adequacy;
+- native witness behavior;
+- producer admission and receipt freshness;
+- merge, release, rollout, and deferral approval.
+
+## Rejected Alternatives
+
+| Alternative | Rejected Because |
+|---|---|
+| Extend `requirement-bindings` to validate source lifecycle. | It would merge source authority and proof-route authority, making the first layer harder to review and reuse. |
+| Parse Markdown overview files. | Proofkit must not read implicit repository state or infer durable claims from prose. A later consumer-owned linter can enforce overview-to-REQ citation policy. |
+| Make source admission execute proof bindings. | Execution and freshness belong to native witnesses, receipts, and consumer CI policy. |
+
+## Non-Claims
+
+The report does not prove that the overview file has no uncited durable claims,
+that proof bindings are adequate, that tests pass, or that merge is allowed.

package/docs/requirement-source-transition-design.md

@@ -0,0 +1,66 @@
+# Requirement Source Transition Design
+
+Status: implemented.
+
+Owner: `proofkit`.
+
+## Problem
+
+Requirement source admission validates one `requirements.v1.json` snapshot. It
+cannot prove that a pull request changed requirement lifecycle records
+monotonically, because it does not receive the previous source package.
+
+Formal gap:
+
+```text
+Durable REQ-* identity must survive ordinary source edits.
+Single-snapshot admission cannot observe from -> to lifecycle changes.
+Therefore lifecycle transition admission needs caller-provided previous and
+next source records.
+```
+
+## Decision
+
+Add `requirement-source-transition`, a deterministic report over explicit
+previous and next requirement source snapshots.
+
+The primitive validates:
+
+- both snapshots pass requirement-source admission;
+- both snapshots describe the same source package paths;
+- durable previous `REQ-*` records remain present in the next source before
+  deletion;
+- new requirements start as `active`;
+- terminal `removed` and `superseded` states do not change later;
+- terminal `superseded` replacement sets do not expand or shrink later;
+- deprecation, removal, supersession, and reactivation transitions carry a
+  lifecycle evidence ref that was not already present in the previous source;
+- superseded requirements replace only to requirements that are active in the
+  next source;
+- previous lifecycle evidence and replacement refs are not silently dropped.
+
+## Authority Boundary
+
+Proofkit owns reusable transition grammar and deterministic diagnostics only.
+
+Consumer repositories own:
+
+- finding the previous and next source records;
+- requirement sentence meaning;
+- replacement semantic equivalence;
+- proof-binding adequacy;
+- witness execution and receipt freshness;
+- merge, release, rollout, and deletion approval.
+
+## Rejected Alternatives
+
+| Alternative | Rejected Because |
+|---|---|
+| Add previous-state fields to every requirement source record. | It would mix durable source truth with PR-local transition evidence and make stable specs noisier. |
+| Infer the previous source by scanning git history. | Proofkit must stay repository-neutral and must not own VCS access or freshness. |
+| Fold transition checks into proof bindings. | Proof bindings own verification routes, not source lifecycle identity. |
+
+## Non-Claims
+
+The report does not discover diffs, prove replacement equivalence, execute
+native witnesses, compute freshness, approve record deletion, or decide merge.

package/docs/requirement-source-view-design.md

@@ -0,0 +1,51 @@
+# Requirement Source View Design
+
+Status: implemented.
+
+Owner: `proofkit`.
+
+## Problem
+
+`requirements.v1.json` is the machine-admissible source for `REQ-*` identity,
+invariant text, lifecycle, risk, update policy, and non-claims. Humans still
+need a readable view. If repositories solve that by making Markdown or HTML the
+canonical source, presentation and authority become mixed.
+
+## Decision
+
+Add `requirement-source-view`, an on-demand presentation view over admitted
+requirement source records.
+
+The primitive:
+
+- reuses requirement-source admission before rendering;
+- emits a deterministic JSON view model by default;
+- renders Markdown and self-contained browser-ready HTML on demand;
+- marks every output as `presentation_only`;
+- includes counts, owner, invariant, claim level, risk, lifecycle, proof-binding
+  refs, update policy, deferral, and non-claims;
+- gives HTML readers local search, field filters, and an ID visibility toggle
+  over admitted view-model fields;
+- escapes HTML output.
+
+## Authority Boundary
+
+Proofkit owns the generic view model and renderers. It does not read repository
+files, own requirement meaning, lint overview Markdown, validate proof-binding
+adequacy, execute witnesses, compute freshness, or approve merge.
+
+## Rejected Alternatives
+
+| Alternative | Rejected Because |
+|---|---|
+| Use `overview.md` as the only human-readable source. | It would push durable fields back into prose and weaken machine validation. |
+| Track generated rendered files by default. | It adds drift and token load; views should be generated on demand unless a consumer proves review value and freshness. |
+| Fold requirement source rendering into proof-binding views. | Source meaning and proof routes are different authority surfaces. |
+| Render invalid source inputs with warnings. | That would let malformed source records become readable-looking authority. |
+| Add server lifecycle to source view rendering. | Browser launch, ports, auth keys, and process ownership are a separate presentation adapter boundary. |
+
+## Follow-Up
+
+Consumer repositories may wrap this primitive with a local viewer or static page
+only when rendered-artifact freshness proves the generated output is
+presentation-only and current.

package/docs/scaffold-profile-plan-design.md

@@ -0,0 +1,72 @@
+# Scaffold Profile Plan Design
+
+## Decision
+
+Proofkit provides a deterministic `scaffold-profile-plan` primitive that helps a
+consumer author a repository profile without turning Proofkit into a repository
+scanner, file writer, policy owner, or profile authority.
+
+## Problem
+
+`stack-preset` reports describe starter repository shapes, and repo-profile
+admission validates a caller-owned profile against caller-provided facts. The
+missing step is a bounded authoring plan that tells a developer or agent which
+profile fields are already derivable from explicit caller input, which fields
+remain caller-owned gaps, and which follow-up checks should run after review.
+
+Without that bridge, adoption agents either guess repository-profile structure
+or copy repository-specific examples. Both options weaken portability and
+increase token load.
+
+## Boundary
+
+The scaffold plan accepts only explicit caller input:
+
+- repository identity, package name, primary languages, and target profile path;
+- optional stack preset id;
+- caller-owned requirement id pattern;
+- caller-selected policy, router, binding, spec, proof-like, and generated
+  artifact paths;
+- caller-selected environment classes and command matcher hints.
+
+It emits:
+
+- a deterministic draft profile candidate;
+- field provenance for every drafted value;
+- caller-required gaps;
+- follow-up commands for caller-owned validation;
+- non-claims that prevent authority creep.
+
+It does not:
+
+- read repository state;
+- write files or decide overwrite safety;
+- execute native witnesses;
+- infer command policy from shell text;
+- prove profile correctness, proof coverage, freshness, CI readiness, merge
+  readiness, or rollout readiness.
+
+## Invariant
+
+For the same admitted input, the scaffold plan must emit the same stable JSON
+shape and the same ordered caller-required gaps. Every draft value must be
+traceable to either caller input or a named stack preset. Every value that
+cannot be derived without repository-specific judgment must remain a gap.
+
+## Rejected Alternatives
+
+| Alternative | Rejection |
+|---|---|
+| Generate a complete `repo-profile.v1.json` file | Final profile content is repository-owned semantic policy. A complete generated file would hide caller decisions behind Proofkit defaults. |
+| Scan the repository to discover scripts, tracked files, or package topology | Ambient scanning would make Proofkit a repo-state authority and would create non-determinism outside the explicit input contract. |
+| Add a write mode | File writes require conflict, overwrite, and review policy that belongs to the consuming repository. |
+| Fold this into `stack-preset` | Presets are generic starter shapes. Scaffold planning combines a preset with caller decisions and therefore owns a distinct authoring invariant. |
+
+## Proof Obligations
+
+- Unit tests prove deterministic draft shape, provenance, caller-owned gaps,
+  sorted arrays, non-claims, and no mutation of stack preset data.
+- CLI tests prove `scaffold-profile-plan --input <path>` emits stable JSON,
+  supports stdin through the shared CLI path, and rejects unrelated flags.
+- Package artifact tests prove the public API and design note are included while
+  source, tests, maps, and implementation plans remain outside the package.

package/docs/secret-shaped-json-scan-design.md

@@ -0,0 +1,60 @@
+# Secret-Shaped JSON Scan Design
+
+Status: implemented.
+
+Owner: `proofkit`.
+
+## Problem
+
+Consumer repositories often need to reject secret-shaped strings in
+caller-provided evidence artifacts before those artifacts are projected into a
+smaller report model.
+
+If every repository reimplements that recursive scan, diagnostics drift and
+secret redaction becomes inconsistent. If Proofkit scans repositories, files,
+logs, or credentials by itself, it becomes a repository policy owner and
+duplicates dedicated secret-scanning tools.
+
+## Decision
+
+Add `scanProofkitSecretShapedJson`, a reusable API-only primitive over an
+explicit caller-provided JSON value.
+
+The primitive:
+
+- admits only JSON-serializable values;
+- traverses object keys in deterministic order;
+- returns stable JSON-style paths and finding kinds;
+- rejects common secret-shaped strings and URL userinfo in values and object
+  keys;
+- reports secret-shaped object keys by stable sorted key index instead of
+  echoing the key text;
+- never returns the matched value or reads files;
+- accepts an optional stable root path label for embedding findings in a
+  consumer report.
+
+## Authority Boundary
+
+Proofkit owns only deterministic JSON traversal, finding shape, path shape, and
+non-echoing diagnostics for caller-provided values.
+
+The consuming repository owns which files, logs, evidence objects, or operator
+artifacts are read; which values are passed to the scanner; which findings are
+merge-blocking; and whether an additional dedicated secret scanner such as a
+repository-wide credential detector is required.
+
+## Rejected Alternatives
+
+| Alternative | Rejected Because |
+|---|---|
+| Keep raw evidence string scans in every consumer. | This duplicates reusable redaction-sensitive mechanics and creates diagnostic drift. |
+| Add a generic Proofkit secret-scanning CLI. | Repository traversal, ignore policy, baselines, binary handling, and credential policy belong to consumer tools or dedicated scanners. |
+| Return the matched string for debugging. | The result itself would become a secret exposure surface. |
+| Accept arbitrary runtime values. | Non-JSON runtime objects have unstable traversal semantics and should be normalized by the caller first. |
+
+## Follow-Up
+
+Consumers should call this primitive only from owner-specific wrappers that
+already own artifact reading and gate policy. Proofkit command reports may
+reuse the primitive internally when the command already receives explicit JSON
+input from the caller.