agentic-proofkit 0.1.91

package/docs/document-lifecycle-boundary-design.md

@@ -0,0 +1,62 @@
+# Document Lifecycle Boundary Design
+
+Status: implemented.
+
+Owner: `proofkit`.
+
+## Problem
+
+Design documents and implementation plans are useful while a pull request is
+open, but after merge they stop being durable behavior authority. Current
+repository truth should move to requirement records, specifications, proof
+bindings, routers, work ledgers, or generated lookup surfaces with explicit
+freshness boundaries.
+
+Without a lifecycle boundary, historical prose can keep routing agents as if it
+were current behavior, proof, readiness, or open-work authority.
+
+## Decision
+
+Add `document-lifecycle-boundary`, a deterministic report over caller-provided
+document lifecycle records.
+
+The primitive validates:
+
+- active PR-local design and implementation-plan documents stay temporary
+  reasoning inputs;
+- merged design and implementation-plan documents are historical evidence only;
+- merged implementation plans may be deleted from the active tree when stable
+  design notes, code, tests, and git history preserve the useful evidence;
+- merged temporary documents are not routed as current authority;
+- archived documents do not keep active authority or current routing roles;
+- generated views stay lookup-only and declare source and freshness refs;
+- rendered views stay presentation-only and declare source and freshness refs;
+- generated views are routed only as lookup projections, and rendered views are
+  routed only as presentation views, not owner surfaces;
+- current durable documents declare freshness checks;
+- primary routers use navigation authority;
+- work ledgers use open-work authority;
+- every document declares owner, mutation triggers, forbidden payloads, and
+  non-claims.
+
+## Authority Boundary
+
+Proofkit validates caller-provided lifecycle metadata and emits deterministic
+diagnostics. It does not read Markdown, parse document semantics, infer routes,
+prove generated freshness, archive files, delete files, approve merge, or
+decide product meaning.
+
+## Rejected Alternatives
+
+| Alternative | Rejected Because |
+|---|---|
+| Parse Markdown directly in Proofkit. | Document meaning, prose style, and semantic extraction remain repository-owned. |
+| Fold lifecycle checks into requirement-source admission. | Requirement records and documentation topology have different authority boundaries. |
+| Treat merged plans as current owner surfaces if they contain useful detail. | That preserves stale PR-local reasoning as durable truth. |
+| Track rendered views as canonical source. | Rendered views are presentation surfaces only; source records own durable meaning. |
+
+## Follow-Up
+
+Consumer repositories can feed this report into selective gates or adoption
+checklists. If they need semantic Markdown linting, they should provide
+caller-owned facts to this primitive or implement a separate native witness.

package/docs/json-report-cli-adapter-design.md

@@ -0,0 +1,83 @@
+# JSON Report CLI Adapter Design
+
+Status: implemented reusable primitive.
+
+Owner: `proofkit`.
+
+## Problem
+
+Consumer repositories often maintain small JSON-report command wrappers that
+repeat the same mechanics: parse explicit file flags, support `--output`, read
+JSON or text input, write deterministic JSON output, and wrap direct-main
+errors. Repeating that plumbing creates extra consumer code while providing no
+consumer-specific policy value.
+
+## Decision
+
+Proofkit provides a reusable JSON report CLI adapter:
+
+- `parseProofkitJsonReportCli`
+- `readProofkitJsonReportInput`
+- `readProofkitTextReportInput`
+- `writeProofkitJsonReportOutput`
+- `runProofkitJsonReportCliMain`
+- `formatProofkitCliError`
+
+The adapter owns generic command-wrapper mechanics only. Callers provide the
+flag vocabulary, help text, schema admission, command-specific diagnostics,
+report builder, output path, and any command policy.
+
+Formal boundary:
+
+```text
+Proofkit owns reusable CLI plumbing.
+Consumers own command meaning and proof policy.
+```
+
+## Invariants
+
+1. The parser accepts only explicitly declared flags plus `--output` and
+   `--help`; unknown arguments fail closed.
+2. Required flags are admitted by caller-declared flag metadata.
+3. JSON output is emitted through `proofkitStableJsonString`, so object keys are
+   deterministic and non-JSON values fail closed.
+4. Direct-main execution sets `process.exitCode` and writes a non-secret error
+   message; it does not call `process.exit` for command execution failures.
+5. `--help` exits only through an injectable hook, so command tests can prove
+   help behavior without terminating the test process.
+
+## Non-Claims
+
+The adapter does not own:
+
+- report semantics;
+- schema vocabulary;
+- proof freshness;
+- repository scanning;
+- command selection;
+- native witness execution;
+- credential or network policy;
+- merge or release approval.
+
+## Rejected Alternatives
+
+1. Put the helper in `report-model`.
+   Rejected because `report-model` is a pure report grammar surface, while this
+   adapter reads files and writes process streams.
+2. Add a new `agentic-proofkit` CLI command.
+   Rejected because there is no single command meaning to execute; consumers
+   own their command-specific report builders.
+3. Keep all wrappers in every consumer repository.
+   Rejected because the repeated mechanics are generic, measurable
+   infrastructure code and can be reused without moving consumer policy into
+   proofkit.
+4. Add a command registry or scheduler primitive here.
+   Rejected because registry, scheduling, and freshness policy are separate
+   owner surfaces with their own proof contracts.
+
+## Proof
+
+The primitive is covered by Go command tests and package artifact admission
+through `npm run check` and `npm run package:artifact`. Release evidence must
+still run the tag-only release workflow over the complete root package tarball
+before any registry publication claim.

package/docs/migration-parity-admission-design.md

@@ -0,0 +1,90 @@
+# Migration Parity Admission Design
+
+## Decision
+
+Proofkit provides a deterministic `migration-parity-admission` primitive for
+consumers that migrate local proof infrastructure to Proofkit-owned reusable
+primitives. The primitive validates structured caller-provided parity evidence
+between a declared source proof owner and a declared Proofkit target ref.
+
+## Problem
+
+`migration-plan` can require parity evidence refs before old proof owners are
+retired, but opaque refs do not prove that the evidence has a stable shape,
+declared source/target closure, typed equivalence dimension, digest comparison,
+or fail-closed status vocabulary.
+
+The missing reusable step is admission of parity evidence shape before a
+consumer uses that evidence as an input to migration planning or old-owner
+retirement review.
+
+## Boundary
+
+Proofkit owns:
+
+- exact shape admission for caller-provided migration parity evidence;
+- source-owner and target-ref cross-reference checks;
+- typed parity equivalence kinds;
+- caller-provided digest equality checks for `matched` parity records;
+- fail-closed handling for `mismatched`, `not_comparable`, and `not_run`
+  records;
+- deterministic non-secret diagnostics and stable JSON reports.
+
+The consuming repository owns:
+
+- legacy proof owner content and Proofkit target content;
+- evidence production, receipt production, and producer trust;
+- digest computation and freshness;
+- native witness execution and command result truth;
+- semantic equivalence, proof coverage adequacy, and retirement policy;
+- CI admission, merge approval, release approval, rollout approval, and
+  production decisions.
+
+## Invariant
+
+A migration parity record is admitted only when it references one declared
+source proof owner and one declared target Proofkit ref, declares a supported
+equivalence kind, supplies at least one safe repo-relative evidence ref, and
+uses `status: "matched"` with equal caller-provided `sha256:<64 lowercase hex>`
+legacy and Proofkit digests.
+
+Unknown source or target ids, unsafe evidence paths, malformed digests,
+duplicate evidence ids, empty evidence refs, unequal matched digests, equal
+mismatched digests, or any non-`matched` status must produce deterministic
+failure.
+
+## Non-Claims
+
+Migration parity admission does not claim:
+
+- parity authenticity;
+- native command execution or command result correctness;
+- digest computation, receipt currentness, or proof freshness;
+- semantic correctness of the legacy proof owner or Proofkit target;
+- adequacy of proof coverage;
+- old-owner deletion approval;
+- migration exception approval;
+- merge, release, rollout, or production readiness.
+
+## Rejected Alternatives
+
+| Alternative | Rejection |
+|---|---|
+| Keep parity as opaque evidence paths in `migration-plan` only | Opaque refs are insufficient for deterministic retirement review because they hide source/target closure, equivalence dimensions, and mismatch state. |
+| Let Proofkit compute digests from paths | That would make Proofkit a repository scanner and freshness authority. Consumers own file reads and digest production. |
+| Treat mismatched or not-run parity as advisory while passing | Retirement preconditions must fail closed when parity is incomplete or divergent. |
+| Fold retirement approval into parity admission | Retirement depends on repository policy, rollout risk, and native proof freshness. Parity admission is only a structured evidence precondition. |
+| Use generic receipt-currentness admission for parity | Receipt currentness compares receipt facts to current facts; migration parity needs source-owner to Proofkit-target equivalence metadata and parity-specific states. |
+
+## Proof Obligations
+
+- Unit tests prove matched parity admission, source/target closure failures,
+  malformed digest/path failures, duplicate evidence id failures, empty evidence
+  failures, and non-`matched` status failures.
+- CLI tests prove stable report output, failed report exit status, and JSON
+  pointer/stdin input selection.
+- Package artifact tests prove package binary availability, packed CLI behavior,
+  and published file boundary.
+- Self-hosting requirement bindings keep the primitive tied to
+  `REQ-PROOFKIT-RETIRE-*` coverage without making the generated binding graph a
+  second source of truth.

package/docs/migration-plan-design.md

@@ -0,0 +1,73 @@
+# Migration Plan Design
+
+## Decision
+
+Proofkit provides a deterministic `migration-plan` primitive for consumers that
+replace local proof infrastructure with Proofkit-owned reusable primitives. The
+plan describes a safe caller-owned transition, not an approval to delete old
+proof owners.
+
+## Problem
+
+Consumers can bootstrap new proofkit inputs and scaffold repository profiles,
+but existing repositories also need to retire local proof infrastructure without
+losing parity evidence or creating a hidden proof authority split.
+
+The missing reusable step is a transition plan that keeps old and new proof
+owners explicit until caller-provided parity evidence and post-retirement
+checks exist.
+
+## Boundary
+
+Proofkit owns:
+
+- deterministic validation of caller-provided source owner refs, target
+  proofkit refs, parity evidence refs, retained owners, retired candidates,
+  and follow-up commands;
+- ordered migration phases;
+- blockers that prevent premature retirement recommendations;
+- non-claims that deny deletion, merge, freshness, and rollout authority.
+
+The consuming repository owns:
+
+- old proof owner content and target proofkit content;
+- parity execution and evidence authenticity;
+- native witness execution;
+- file edits and deletion;
+- CI freshness, merge approval, rollout, and final retirement decisions.
+
+## Invariant
+
+A migration plan may list `retire-old-owner` actions only for caller-declared
+retirement candidates that have at least one caller-provided parity evidence
+ref against a declared target proofkit ref, at least one post-retirement
+validation command, and no caller-declared retain policy. Missing parity,
+unknown source or target refs, retained-owner conflicts, or missing
+post-retirement validation must become deterministic blockers. A blocked plan
+must not list `retire-old-owner` actions.
+
+## Phases
+
+The output always uses this phase order:
+
+1. `baseline`
+2. `parallel-proof`
+3. `parity-check`
+4. `retire-old-owner`
+5. `post-retirement-validation`
+
+## Rejected Alternatives
+
+| Alternative | Rejection |
+|---|---|
+| Let Proofkit decide old-owner deletion | Deletion depends on repository-specific risk, CI trust, and rollout policy. |
+| Treat parity as correctness | Parity proves extraction equivalence, not correctness of either implementation. |
+| Reuse bootstrap materialization | Bootstrap materialization creates starter file plans; migration planning owns old/new proof-owner transition semantics. |
+| Emit shell scripts that delete old owners | This would combine planning with mutation and bypass caller-owned review. |
+
+## Proof Obligations
+
+- Unit tests prove phase order, blocker creation, and retirement action
+  admission only with parity evidence plus post-retirement validation commands.
+- CLI tests prove stable JSON and input-shape failures.
+- Package artifact tests prove public API and packed-bin behavior.

package/docs/obligation-decision-agent-envelope-design.md

@@ -0,0 +1,105 @@
+# Obligation Decision Agent Envelope Design
+
+Status: accepted; implemented as an opt-in CLI projection.
+
+Owner: `proofkit`.
+
+## Purpose
+
+Obligation decision reports normalize caller-provided proof facts into one
+decision state per obligation. Agents need a bounded remediation packet that
+routes unsatisfied obligations without loading the full report or inferring
+commands that the decision layer does not own.
+
+Formal goal:
+
+```text
+caller-owned obligation decision report
+  -> bounded agent guidance envelope
+  -> caller-owned proof repair, rerun, policy decision, or receipt refresh
+```
+
+## Authority Boundary
+
+Proofkit owns:
+
+- deterministic envelope construction from an obligation-decision report;
+- bounded requirement and proof-route context refs for actionable decisions;
+- evidence context refs for caller-provided evidence refs;
+- receipt refs for missing receipt classes;
+- clarification questions for unknown scope, unavailable live evidence, and
+  admitted deferrals;
+- blocked preconditions for blocked, unavailable, or unknown-scope decisions;
+- omitted-count records when the decision or receipt-ref set exceeds the
+  envelope limit.
+
+The consuming repository owns:
+
+- requirement meaning;
+- proof route adequacy;
+- native witness execution;
+- producer authentication;
+- receipt freshness;
+- deferral, live availability, scope, merge, release, and rollout policy.
+
+Formal rule:
+
+```text
+The obligation-decision report owns normalized state.
+The obligation-decision envelope owns bounded remediation routing.
+The consuming repository owns the facts and policy behind each state.
+```
+
+## Invariants
+
+- `obligation-decision --agent-envelope` is opt-in; ordinary
+  `obligation-decision` JSON output remains unchanged.
+- The envelope never invents command refs because obligation-decision input does
+  not contain command shape.
+- Actionable decisions are selected from states other than `satisfied` and
+  `not_applicable`.
+- Requirement refs and proof-route refs are emitted as context refs, not as
+  new requirement or proof authority.
+- Missing receipt decisions emit required receipt-class refs.
+- Decisions with caller-provided evidence refs emit evidence context refs, not
+  receipt-artifact refs, because the obligation-decision model does not type
+  evidence refs as receipt artifacts.
+- Unknown-scope, unavailable-live, deferred, and blocked-precondition states
+  route to caller-owned questions or blockers instead of becoming Proofkit
+  policy.
+- Omitted records require the caller to inspect the full decision report or run
+  a wider caller-owned gate.
+
+## Rejected Alternatives
+
+| Alternative | Rejection reason |
+|---|---|
+| Add command refs to obligation-decision envelopes | The report does not own command shape; inventing command refs would create false authority. |
+| Make the envelope the default `obligation-decision` output | Existing callers need the canonical deterministic report unless they opt into agent presentation. |
+| Treat advisory or deferred decisions as hidden pass states | They must stay visible and caller-owned even when they do not block this generic report. |
+| Resolve producer, freshness, live, or scope policy in Proofkit | Those facts depend on consumer CI, credentials, environment, and rollout policy. |
+
+## Proof Obligations
+
+- CLI tests prove ordinary `obligation-decision` output remains unchanged.
+- CLI tests prove `obligation-decision --agent-envelope` emits a bounded packet
+  with no command refs, requirement/proof-route context refs, receipt refs, and
+  route/verify actions.
+- CLI tests prove malformed obligation-decision input in agent-envelope mode
+  returns deterministic invalid-input JSON.
+- Package artifact tests prove the design note is shipped with the public
+  package.
+
+## Non-Claims
+
+Obligation decision agent envelopes do not claim:
+
+- native command execution;
+- receipt freshness;
+- producer authentication;
+- proof adequacy;
+- changed-scope completeness;
+- merge approval;
+- release approval;
+- rollout approval;
+- repository policy ownership.

package/docs/obligation-decision-state-design.md

@@ -0,0 +1,100 @@
+# Obligation Decision State Design
+
+## Decision
+
+Proofkit provides an `obligation-decision` primitive that converts
+caller-provided obligation facts into one closed decision state per obligation.
+
+The primitive owns the deterministic priority lattice and report grammar only.
+It does not authenticate producers, execute commands, compute freshness, infer
+scope, approve merge, or decide repository policy.
+
+## Problem
+
+Proofkit already validates receipt producer admission and selective gate
+evidence. Those reports expose useful diagnostics, but they do not provide one
+generic closed decision vocabulary for a requirement proof obligation.
+
+A raw receipt can have several facts at once: stale, failed, malformed, and
+produced by a non-admitted runner. If each consumer, agent, or gate chooses a
+different label, proof status becomes ambiguous.
+
+The architecture therefore needs a small reusable layer:
+
+```text
+caller-owned obligation facts -> priority lattice -> one obligation decision
+```
+
+## Boundary
+
+Proofkit owns:
+
+- the closed decision state vocabulary;
+- the priority order between candidate states;
+- exact input admission for obligation decision records;
+- deterministic report output, counts, diagnostics, and rule statuses.
+
+The consuming repository owns:
+
+- requirement meaning and proof route adequacy;
+- which facts apply to an obligation;
+- producer admission policy and producer authentication;
+- receipt freshness, scope classification, live availability, and deferral
+  policy;
+- merge, release, rollout, and production readiness decisions.
+
+## State Lattice
+
+When several candidate states apply to the same obligation, the strongest state
+in this priority order wins:
+
+```text
+invalid_producer >
+invalid_receipt >
+stale_receipt >
+failed >
+missing_receipt >
+blocked_missing_precondition >
+unavailable_live >
+unknown_scope >
+deferred_admitted >
+advisory_skipped >
+not_applicable >
+satisfied
+```
+
+This prevents a raw green command from hiding a stronger invalid producer,
+invalid receipt, stale receipt, missing receipt, blocked-precondition, or
+unknown-scope fact.
+
+## Invariant
+
+Every obligation decision report must be total:
+
+- every obligation has at least one candidate state;
+- every obligation emits exactly one selected decision state;
+- candidate state ordering in the input does not affect output;
+- a blocking obligation only satisfies this report when its selected state is
+  `satisfied` or `not_applicable`;
+- advisory or deferred decisions remain visible but do not become hidden merge
+  approval.
+
+## Rejected Alternatives
+
+| Alternative | Rejection |
+|---|---|
+| Add the lattice only inside `selective-gate-evidence` | Too narrow; obligation decisions are generic and may be used by non-selective gates. |
+| Let callers submit a final state with no candidate facts | That would not prove deterministic conflict resolution. |
+| Authenticate CI producers in Proofkit | Producer trust roots and CI identity are consumer-owned. |
+| Treat `deferred_admitted` as equivalent to pass | Deferral may be admissible only under consumer policy and does not satisfy a blocking proof. |
+| Wire all existing reports to the new primitive in the first batch | That risks behavior drift; the first slice must be additive and bounded. |
+
+## Proof Obligations
+
+- Unit tests prove priority ordering, input-order independence, per-state
+  report status mapping, and blocking obligation failure classification.
+- CLI tests prove deterministic JSON output from file and stdin.
+- Package artifact tests prove public export, installed-bin behavior, version,
+  and packaged design note.
+- Full package checks prove the additive primitive does not regress existing
+  reports.

package/docs/package-runtime-dependency-admission-design.md

@@ -0,0 +1,80 @@
+# Package Runtime Dependency Admission Design
+
+Status: implemented.
+
+Owner: `proofkit`.
+
+## Problem
+
+Consumer repositories sometimes need to prove that a runtime dependency seam
+uses an installed external package artifact instead of a sibling workspace
+source checkout. The repeated mechanics are generic: compare caller-observed
+package identity, dependency spec, lockfile-entry presence, and resolution
+locations, then emit deterministic non-secret diagnostics.
+
+If every consumer reimplements those mechanics, each repository keeps bespoke
+path classifiers and report formatting. If Proofkit resolves packages or reads
+manifests itself, it becomes a repository scanner, package-manager authority, or
+consumer policy owner.
+
+## Decision
+
+Add `package-runtime-dependency-admission`, a deterministic report over
+caller-provided runtime dependency facts.
+
+The primitive validates:
+
+- exact input shape and stable report identity;
+- expected package name and exact version against caller-observed resolution
+  facts;
+- expected dependency spec against the observed dependency spec;
+- caller-provided lockfile-entry presence;
+- external, local-workspace, or unadmitted location classification from
+  caller-provided install roots;
+- deterministic non-secret diagnostics and stable report output.
+
+`external_package` is admissible only when the observed package root is the
+expected package root or inside the admitted `node_modules` root, and both the
+real package root and resolved entry point are inside that admitted
+`node_modules` root. Any observed local workspace root participation is
+classified as `local_workspace`; any other shape is `unadmitted_package`.
+
+## Formal Boundary
+
+```text
+consumer package-manager facts
+  -> proofkit package-runtime-dependency-admission
+  -> deterministic report
+  -> consumer-owned wrapper, receipt, and merge decision
+```
+
+Proofkit owns only reusable admission and reporting mechanics. The consuming
+repository owns how facts are collected, which package is expected, which
+dependency spec is correct, which roots are admitted, which lockfile entry is
+fresh, and whether the report satisfies a local gate.
+
+## Rejected Alternatives
+
+| Alternative | Rejected Because |
+|---|---|
+| Keep the classifier only in each consumer. | This preserves duplicate path-mode logic and increases drift risk across repositories. |
+| Let Proofkit resolve packages, read manifests, or inspect lockfiles. | That would add ambient filesystem/package-manager authority and make Proofkit a repository scanner. |
+| Accept a broad multi-dependency policy API in this slice. | The admitted consumer need is one runtime seam; batch policy can be composed by calling the primitive per seam without expanding this public contract prematurely. |
+| Classify from package names alone. | Name matching cannot distinguish external installs from sibling source checkouts. |
+| Echo raw paths or dependency specs in diagnostics. | Paths and specs can expose local topology or credential-shaped material; reports should publish booleans, classes, and stable rule results only. |
+
+## Non-Claims
+
+The report does not resolve packages, read manifests, read lockfiles, fetch or
+authenticate registries, prove package-manager behavior, execute native
+witnesses, prove proof freshness, approve merge, approve release, or choose
+consumer package policy.
+
+## Acceptance
+
+- malformed inputs fail closed with deterministic non-secret diagnostics;
+- external, local workspace, and unadmitted locations are covered by unit tests;
+- CLI supports file, stdin, and JSON Pointer input like other input-based
+  Proofkit commands;
+- the package artifact test proves the public API, CLI, and design note are
+  shipped in the npm package.