agentic-proofkit 0.1.91

package/docs/adoption-workflow-agent-envelope-design.md

@@ -0,0 +1,67 @@
+# Adoption Workflow Agent Envelope Design
+
+## Decision
+
+Proofkit supports `adoption-workflow-plan --agent-envelope` as an opt-in
+projection from a deterministic workflow plan to a bounded agent work packet.
+The projection keeps structured `argv` command refs so agents do not have to
+recover command boundaries from shell text.
+
+## Problem
+
+`adoption-workflow-plan` gives consumers a scenario-level route over existing
+Proofkit primitives. Agents still need a compact work packet that says which
+inputs to inspect, which commands are planned, which blockers remain, and which
+ownership questions must be answered.
+
+Returning the full plan is machine-correct, but it is not the most
+token-efficient agent input. Converting it into a generic agent guidance
+envelope avoids another bespoke agent protocol, but the envelope must not
+degrade structured workflow command refs into shell-only strings.
+
+## Boundary
+
+Proofkit owns:
+
+- projection from an admitted workflow plan to an agent guidance envelope;
+- context refs for declared workflow inputs;
+- action items grouped by existing workflow phases;
+- command refs that preserve `argv` arrays;
+- blockers mapped to caller-owned preconditions;
+- non-claims that deny execution, file writes, proof freshness, scenario
+  selection, and policy authority.
+
+The consuming repository owns:
+
+- scenario appropriateness;
+- input file content;
+- command execution and receipts;
+- CI producer admission and freshness;
+- file materialization, merge, enforcement, release, and rollout decisions.
+
+## Invariant
+
+For the same admitted workflow plan, the envelope must emit the same bounded
+context refs, command refs, action plan, blockers, and non-claims. The envelope
+must not include payload bodies or execute commands. Every emitted command ref
+must preserve the structured `argv` from the workflow plan.
+
+## Rejected Alternatives
+
+| Alternative | Rejection |
+|---|---|
+| Return only the raw workflow plan to agents | Correct but less token-efficient; agents must infer context roles and blockers from a route graph. |
+| Add a second bespoke workflow-agent schema | This duplicates the existing reusable agent guidance envelope contract. |
+| Convert commands to shell strings only | This loses argument boundaries and weakens deterministic command routing. |
+| Make `--agent-envelope` the default output | Existing CLI users expect the canonical plan JSON unless they opt into agent presentation. |
+
+## Proof Obligations
+
+- Unit tests prove workflow envelopes preserve `argv`, context refs, actions,
+  blockers, and non-claims.
+- CLI tests prove ordinary workflow output is unchanged without
+  `--agent-envelope`, and `--agent-envelope` is deterministic for file and
+  stdin inputs.
+- Agent-envelope tests prove optional `argv` command refs remain backward
+  compatible with existing command-string envelopes.
+- Package artifact tests prove the shipped public API and design note.

package/docs/adoption-workflow-authority-routes-design.md

@@ -0,0 +1,76 @@
+# Adoption Workflow Authority Routes Design
+
+## Decision
+
+Extend `adoption-workflow-plan` so caller-provided workflow inputs may route to
+the existing `adoption-checklist` and `branch-authority` primitives.
+
+The extension is optional and routing-only. It does not make either primitive a
+new global adoption prerequisite, and it does not change the authority of those
+primitive reports.
+
+## Problem
+
+Proofkit now provides focused primitives for adoption state summaries and
+branch authority drift checks. A consumer using the scenario-level adoption
+workflow still has to remember to run those primitives outside the workflow.
+
+That creates unnecessary glue:
+
+- the workflow can route proof bindings, witness plans, selective gates,
+  receipts, migration plans, and release-channel checks;
+- the workflow cannot yet route adoption checklist or branch authority refs;
+- agents must load extra examples or infer where the commands belong.
+
+The missing route is an integration gap, not a reason to add another
+orchestrator.
+
+## Boundary
+
+Proofkit owns:
+
+- admitting `adoption_checklist` and `branch_authority` as workflow input kinds;
+- deterministic command refs for `adoption-checklist` and `branch-authority`;
+- stable phase placement for those optional routes;
+- agent-envelope context roles and command refs derived from the same plan.
+
+The consuming repository owns:
+
+- whether either route is relevant to the scenario;
+- the checklist content, branch facts, expected branch policy, and evidence
+  refs;
+- command execution, receipts, freshness, merge approval, release approval,
+  rollout approval, and repository policy.
+
+## Invariant
+
+If an admitted workflow input declares `adoption_checklist` or
+`branch_authority`, the plan must emit the corresponding command ref exactly
+once. If the input omits either ref, the plan must not invent a path, scan the
+repository, or create a blocker solely because the optional ref is absent.
+
+`branch_authority` routes in the `profile` phase because branch identity is a
+repository authority fact that can affect adoption and release routing.
+
+`adoption_checklist` routes in the `collect-evidence` phase because it
+summarizes caller-owned adoption evidence after scenario selection.
+
+## Rejected Alternatives
+
+| Alternative | Rejection |
+|---|---|
+| Make both refs required for every scenario | This would introduce hidden policy and break valid minimal consumers. |
+| Add a new closeout/orchestration primitive | The existing workflow already owns scenario routing; another layer would duplicate authority. |
+| Infer checklist or branch paths from conventions | Ambient discovery would turn Proofkit into a repository scanner. |
+| Inline checklist or branch report semantics in the workflow | That would duplicate primitive schemas and create drift. |
+
+## Proof Obligations
+
+- Unit tests prove optional refs produce the expected command refs and are not
+  missing-input blockers.
+- Agent-envelope tests prove the routes remain structured argv refs and bounded
+  context refs.
+- CLI tests prove workflow output remains deterministic for stdin and file
+  inputs.
+- Package artifact tests prove the design note is shipped with the public
+  artifact.

package/docs/adoption-workflow-contract-envelope-design.md

@@ -0,0 +1,87 @@
+# Adoption Workflow Contract Envelope Design
+
+## Decision
+
+Proofkit admits an optional contract-envelope projection for
+`adoption-workflow-plan`. The envelope gives consumers one stable adoption
+entrypoint while preserving the existing workflow planner as the owner of
+scenario routing.
+
+## Problem
+
+`adoption-workflow-plan` is the highest-level adoption route. It currently
+accepts its native input directly, while older adoption surfaces can be invoked
+from a caller-owned contract envelope. That mismatch forces consumer agents to
+remember which entrypoints support envelope projection and makes gradual
+adoption less uniform.
+
+The missing invariant is:
+
+```text
+caller-owned adoption workflow envelope
+  -> admitted workflow planner input
+  -> deterministic workflow plan or agent envelope
+```
+
+## Boundary
+
+Proofkit owns:
+
+- the envelope schema id;
+- exact extraction of the `workflow` object;
+- fail-closed schema and field drift diagnostics;
+- CLI routing for `adoption-workflow-plan --contract-envelope`;
+- compatibility with `--agent-envelope`.
+
+The consuming repository owns:
+
+- the workflow object content;
+- scenario choice;
+- referenced input files;
+- file materialization;
+- native witness execution;
+- receipts, producer admission, freshness, merge, release, and rollout.
+
+## Chosen Shape
+
+The v1 envelope is intentionally small:
+
+```json
+{
+  "schema": "proofkit.adoption-workflow.v1",
+  "workflow": {
+    "schemaVersion": 1,
+    "workflowId": "consumer-owned-id",
+    "scenario": "existing_gradual_adoption",
+    "presetId": "typescript_workspace",
+    "inputRefs": [],
+    "nonClaims": []
+  }
+}
+```
+
+The envelope does not embed primitive payload bodies. It only carries the
+caller-owned workflow routing record. Referenced primitive inputs remain
+separate caller-owned files because they have separate owners, review cycles,
+and proof obligations.
+
+## Rejected Alternatives
+
+| Alternative | Rejection |
+|---|---|
+| Make `workflow` optional and infer it from other fields | That would turn Proofkit into a scenario selector. |
+| Embed every primitive input payload in the envelope | That creates a token-heavy mega-object and duplicates primitive schemas. |
+| Use a generic `input` field | Existing contract envelopes already use command-specific fields; `workflow` is clearer and avoids confusing it with lower-level primitive inputs. |
+| Support ambient repository discovery | Contract envelopes are explicit caller records, not repo scans. |
+
+## Proof Obligations
+
+- Contract-envelope unit tests prove extraction, schema drift, and missing
+  `workflow` fail closed.
+- CLI tests prove `adoption-workflow-plan --contract-envelope` works both with
+  normal plan output and `--agent-envelope`.
+- CLI tests prove unsupported contract-envelope commands remain fail-closed.
+- Package artifact tests prove the new public projection and design note are
+  exported.
+- Full package check proves existing adoption, agent-envelope, and contract
+  envelope behavior remains compatible.

package/docs/adoption-workflow-plan-design.md

@@ -0,0 +1,97 @@
+# Adoption Workflow Plan Design
+
+## Decision
+
+Proofkit provides a deterministic `adoption-workflow-plan` primitive that
+routes common consumer adoption scenarios to existing Proofkit primitives. The
+plan is an ordered caller-reviewed workflow, not an orchestrator.
+
+## Problem
+
+Proofkit already exposes focused primitives for stack presets, repository
+profile scaffolding, gradual adoption bootstrap, proof migration, selective
+gates, receipts, and release-channel authority. A new consumer still needs a
+small deterministic entrypoint that answers:
+
+- which Proofkit command should run first for this scenario;
+- which caller-owned input files are required;
+- which steps are blocked because their input refs are absent;
+- which commands are follow-up checks rather than proof evidence.
+
+Without that entrypoint, adoption agents must load broad README material or
+guess command order from examples. That increases token load and makes
+cross-repository onboarding less reproducible.
+
+## Boundary
+
+Proofkit owns:
+
+- scenario vocabulary;
+- deterministic mapping from scenario and caller-provided input refs to ordered
+  workflow phases;
+- optional command routes for adoption checklist and branch authority refs
+  declared by the caller;
+- fail-closed blockers for missing required input refs;
+- structured CLI command refs that do not rely on shell parsing;
+- non-claims denying repository scanning, native witness execution, file
+  writes, proof freshness, merge approval, rollout approval, and policy
+  ownership.
+
+The consuming repository owns:
+
+- whether a scenario is appropriate;
+- all input files referenced by the workflow;
+- file materialization, overwrite, and deletion decisions;
+- native witness execution and command receipts;
+- CI producer admission and freshness;
+- merge, enforcement, release, and rollout decisions.
+
+Scenario selection is caller-owned. The plan only validates that the selected
+scenario has the declared input refs needed to route to existing Proofkit
+primitives.
+
+Adoption checklist and branch authority refs are optional workflow routes. They
+are included when the caller declares them, but their absence is not a
+missing-input blocker. Checklist requiredness and branch policy remain
+consumer-owned.
+
+## Invariant
+
+For the same admitted caller input, the workflow plan must emit the same ordered
+phases, command refs, blockers, and non-claims. A step that requires a missing
+input ref must be represented as a blocker, not silently omitted or invented
+from repository state.
+
+The plan may reference existing Proofkit commands, but it must not inline or
+reimplement the semantics of those commands. Each step points at the command
+that owns the next proof-infrastructure operation.
+
+## Scenarios
+
+The initial scenario vocabulary is intentionally small:
+
+| Scenario | Purpose |
+|---|---|
+| `new_repository` | Start a repository with a profile plan, bootstrap payloads, and first non-blocking proof route. |
+| `existing_gradual_adoption` | Add Proofkit to an existing repository one bounded module at a time. |
+| `legacy_proof_migration` | Run old and new proof owners side by side until caller-owned parity evidence allows retirement review. |
+| `release_channel` | Prove package artifact or registry consumption boundaries before consumer rollout. |
+
+## Rejected Alternatives
+
+| Alternative | Rejection |
+|---|---|
+| Build a full orchestrator | Execution, retries, receipts, credentials, and CI freshness are repository or CI authority. |
+| Duplicate command-specific inputs in the workflow | That would create a second schema for each primitive and drift from the owning command. |
+| Infer missing input paths from repository layout | Ambient discovery would turn Proofkit into a repository scanner and weaken reproducibility. |
+| Emit shell command strings | Structured argv refs avoid shell parsing ambiguity and are easier for agents and CI adapters to validate. |
+
+## Proof Obligations
+
+- Unit tests prove scenario-to-phase order, missing-input blockers, structured
+  argv command refs, and non-claims.
+- CLI tests prove `adoption-workflow-plan --input <path>` emits stable JSON and
+  fails invalid input shapes.
+- Package artifact tests prove the public API and design note are exported.
+- Full package check proves the workflow plan does not change existing
+  primitive behavior.