@research-engineering/agentic-proofkit 0.1.152 → 0.1.153

package/README.md

@@ -38,6 +38,10 @@ registry identity, `dist.integrity`, `dist.shasum`, `npm pack`, and root-only
 registry install evidence. Bun is a supported consumer/developer package
 manager path, not a replacement for npm release evidence.
 
+Python consumers use the Python package as a runner wrapper over the same Go
+CLI, not as a Python SDK. Python projects should still treat CLI/JSON records,
+exit codes, and package metadata as the public contract.
+
 ## Project Boundary
 
 `agentic-proofkit` is intended to provide reusable proof-workflow mechanics for
@@ -139,6 +143,45 @@ make generated invariants authoritative by itself.
 
 ## Start Here
 
+Use the CLI help route before reading source:
+
+```bash
+agentic-proofkit help
+agentic-proofkit init
+agentic-proofkit help repo-profile-admission
+agentic-proofkit repo-profile-admission --help
+```
+
+Command-specific help is derived from the private command descriptor table and
+does not read stdin. The full machine-readable command inventory remains
+`proofkit/cli-contract.v1.json`; the human route map is
+`docs/proofkit-contract-map.md`.
+
+| Repository state | Minimal first route | Stop condition |
+|---|---|---|
+| Unknown starting point | `init` | Stop before reading repository files, writing files, or treating route guidance as proof |
+| Fresh repository with no specs and no extracted observations | `init --preset fresh`, then `scaffold-project-structure` or `gradual-adoption-bootstrap` | Stop before writing files or inventing requirement meaning |
+| Current code is trusted as the initial contract | `capability-map-admission` with `trustMode: "code_baseline"` | Stop before treating generated seeds as admitted requirements |
+| Current code must be audited before it becomes a contract | `capability-map-admission` with `trustMode: "audit_from_code"` | Stop at owner questions and candidate-only records |
+| Legacy repository has local proof infrastructure | `migration-parity-admission`, then `migration-plan` | Stop before deleting local proof owners without parity evidence |
+| A change set needs bounded checks | `changed-path-set`, optional `impact`, then `selective-gate-plan` and `selective-gate-evidence` | Stop on unknown scope, missing routes, or stale receipts |
+
+Use `secret-scan` only when the caller provides an explicit file inventory with
+content. It is a dedicated secret-like text detector for admitted inventory
+records; it does not traverse the repository, validate credential liveness, or
+replace provider secret scanning.
+
+For TypeScript consumers that want a small wrapper instead of hand-written
+child-process code:
+
+```bash
+agentic-proofkit json-report-cli-adapter-source --language typescript --format json
+```
+
+The generated adapter remains caller-owned after materialization. It must be
+reviewed, pinned to the installed package, and kept behind the same CLI/JSON
+contract; it does not become a separate public SDK or proof authority.
+
 | Need | Owner |
 |---|---|
 | Human orientation | This README |

package/docs/proofkit-contract-map.md

@@ -33,15 +33,15 @@ No command may infer ambient repository truth from the current directory.
 
 | Family | Main commands | Caller provides | Proofkit owns | Consumer owns | Output authority |
 |---|---|---|---|---|---|
-| Adoption and scaffolding | `adoption-contract-envelope`, `adoption-workflow-plan`, `adoption-checklist`, `adoption-doctor`, `gradual-adoption`, `gradual-adoption-bootstrap`, `gradual-adoption-guidance`, `capability-map-admission`, `pilot-admission`, `scaffold-profile-plan`, `scaffold-project-structure`, `stack-preset` | adoption intent, aggregate adoption contract envelope, checklist facts, target paths, owner routes, caller-extracted stale authority vocabulary facts, explicit pre-spec capability observations, pilot records, stack preset id | aggregate contract-envelope admission, deterministic starter plans, checklist/report admission, bounded guidance envelopes, dry-run manifests, pre-spec trust-mode admission, adoption gap and stale-authority classification, pilot shape admission | final files, final requirements, rollout policy, text extraction from files, code observation extraction, pilot truth | selected child output, plan, report, seed packet, or agent envelope |
+| Adoption and scaffolding | `init`, `adoption-contract-envelope`, `adoption-workflow-plan`, `adoption-checklist`, `adoption-doctor`, `gradual-adoption`, `gradual-adoption-bootstrap`, `gradual-adoption-guidance`, `capability-map-admission`, `pilot-admission`, `scaffold-profile-plan`, `scaffold-project-structure`, `stack-preset` | adoption intent, aggregate adoption contract envelope, checklist facts, target paths, owner routes, caller-extracted stale authority vocabulary facts, explicit pre-spec capability observations, pilot records, stack preset id, optional init preset id | dry-run route selection, aggregate contract-envelope admission, deterministic starter plans, checklist/report admission, bounded guidance envelopes, dry-run manifests, pre-spec trust-mode admission, adoption gap and stale-authority classification, pilot shape admission | final files, final requirements, rollout policy, text extraction from files, code observation extraction, pilot truth | selected child output, plan, report, seed packet, or agent envelope |
 | Requirement source | `capability-map-admission`, `requirement-authoring-plan`, `requirement-source-admission`, `requirement-source-transition`, `spec-overview-claims`, `requirement-spec-tree`, `requirement-spec-tree-view`, `requirement-source-view`, `requirement-browser-server` | `requirements.v1.json`, caller-owned capability maps, caller-owned authoring facts, overview claim extraction, explicit spec hierarchy, view options | candidate seed admission, candidate-only authoring packets, source-shape admission, lifecycle checks, explicit tree topology/source-ref admission, shared safe renderer fragments, presentation-only views | requirement meaning, extraction completeness, Markdown extraction completeness, hierarchy ownership, proof adequacy, file materialization | capability map report, authoring packet, source report, spec-tree report, rendered view, or browser presentation |
 | Requirement proof binding | `requirement-bindings`, `binding-partition`, `proof-slice`, `evidence-graph`, `requirement-proof-resolver`, `requirement-proof-source-set`, `requirement-proof-view`, `spec-proof-bundle-admission` | requirement records, bindings, witness commands, source-set facts, receipt reports, partition policy | graph validation, binding partition projection, compact slices, typed compact proof contract projections, resolver projections, bundle linkage checks | test semantics, witness execution, proof freshness, merge policy | proof report, partition report, slice, lookup graph, or view |
 | Test inventory and coverage | `test-evidence-inventory`, `test-evidence-inventory --projection discovery-draft`, `test-evidence-inventory --normalized-inventory`, `requirement-coverage-input-compose`, `requirement-coverage-view`, `requirement-browser-server --view coverage` | caller-owned direct or source-set test inventory, caller-owned explicit test discovery facts, declared quality findings, requirement source, proof binding or compact proof contract, coverage universe, optional owner-invariant registry, aggregate coverage compose input | strict inventory/source-set admission, candidate-only discovery draft projection, fail-closed normalized inventory projection, deterministic coverage-view input composition from explicit facts, weak-oracle and declared-quality classification, bounded agent action guidance, requirement/test/command/owner-invariant joins, nonsemantic command-evidence classification, stable coverage failure/warning classifications, presentation-only coverage view | inventory completeness, weak-test truth, test discovery extraction, native test execution, receipt freshness, producer trust, merge policy | candidate inventory guidance, inventory report, normalized inventory data product, coverage-view input, coverage view, or browser presentation |
-| Selective planning | `changed-path-set`, `requirement-impact-input-compose`, `impact`, `selective-gate-plan`, `selective-gate-evidence`, `selective-gate-obligation-decision-input`, `proof-obligation-algebra`, `obligation-decision` | changed paths, base/current requirement sources, base/current single-binding-per-requirement proof contracts, generated-artifact policy, local environment policy, proof-like path policy, planned receipts, obligation routes, obligation algebra records | fail-closed impact input composition, fail-closed planning, receipt comparison, obligation algebra admission, bounded agent packets | git diff truth, repository scanning, command execution, producer trust, final admission | composed impact input, plan, evidence report, obligation algebra report, or obligation input |
+| Selective planning | `changed-path-set`, `requirement-impact-input-compose`, `impact`, `selective-gate-plan`, `selective-gate-evidence`, `selective-gate-obligation-decision-input`, `proof-obligation-algebra`, `obligation-decision` | changed paths, base/current requirement sources, base/current single-binding-per-requirement proof contracts, generated-artifact policy, local environment policy, proof-like path policy, scan obligation ownership, planned receipts, obligation routes, obligation algebra records | fail-closed impact input composition, fail-closed planning, receipt comparison, obligation algebra admission, bounded agent packets | git diff truth, repository scanning, command execution, producer trust, final admission | composed impact input, plan, evidence report, obligation algebra report, or obligation input |
 | Receipts and producers | `proof-receipt-admission`, `receipt-producer-admission`, `receipt-currentness-scope`, `receipt-trust-class`, `producer-policy-self-proof` | receipt sets, producer policy, scope/currentness facts, trust classes | receipt shape, producer/receipt compatibility, self-proof diagnostics | producer authentication, freshness policy, CI trust roots | receipt/provenance report |
 | Release and deployment | `release-authority`, `external-consumer`, `registry-consumer-proof-input-compose`, `registry-consumer`, `deployment-evidence-admission`, `completion-criteria`, `branch-authority`, `readiness-closeout` | package facts, tarball/registry facts, explicit primitive registry/install/smoke facts, deployment evidence, criteria, branch facts | artifact/channel boundary checks, registry-consumer input composition, release diagnostics, falsifiable criteria shape | package publication, registry fetch, package-manager execution, deployment, rollback, approval | composed input, release/deployment/readiness report |
 | Supply-chain and quality | `self-check`, release workflow, `npm run release:sbom`, `npm run self:coverage`, `npm run go:actionlint`, `npm run go:bench` | release artifacts, source workflows, specs, bindings, witness plans, explicit benchmark invocation | deterministic self-check report shape, SBOM candidate evidence, coverage metrics, workflow lint routing, benchmark entrypoints | public-source provenance, vulnerability triage, license approval, CI run admission, release approval | self-check report, SBOM, metrics report, CI signal, or benchmark output |
-| Repository structure | `repo-profile-admission`, `workspace-manifest-facts`, `workspace-registry`, `workspace-changed-package-plan`, `workspace-shard-partition`, `typescript-public-api-surfaces`, `text-policy`, `package-runtime-dependency-admission` | explicit repo/profile facts, caller-owned manifest records, caller-owned roots, and caller-owned text file inventories | structural admission, manifest-to-workspace fact projection, workspace graph projections, TypeScript package public API checks, text policy admission, shard plans | repository freshness, git/file discovery, command policy, package manager truth | structural, fact, policy, or planning report |
+| Repository structure | `repo-profile-admission`, `workspace-manifest-facts`, `workspace-registry`, `workspace-changed-package-plan`, `workspace-shard-partition`, `typescript-public-api-surfaces`, `text-policy`, `secret-scan`, `package-runtime-dependency-admission` | explicit repo/profile facts, caller-owned manifest records, caller-owned roots, caller-owned text file inventories, optional `environmentClassPolicies` tuples | structural admission, manifest-to-workspace fact projection, workspace graph projections, TypeScript package public API checks, text policy admission, explicit-inventory secret-like text detection, shard plans | repository freshness, git/file discovery, command policy, package manager truth, provider secret scanning | structural, fact, policy, or planning report |
 | Custom and generated artifacts | `custom-rule-boundary`, `document-lifecycle-boundary`, `rendered-artifact-freshness`, `conformance-profile`, `json-report-cli-adapter-source`, `witness-plan`, `witness-scheduler-plan` | custom rule metadata, document lifecycle records, artifact digests, profile manifests, command metadata, adapter language | boundary checks, generated-view freshness shape, deterministic adapter source generation, scheduler metadata checks | rule execution, document meaning, cache contents, CI scheduling, committed generated-source freshness | boundary report, generated source artifact, or scheduler report |
 | CLI metadata | `help` | optional command name or help flag | built-in command catalog and help text routing | command selection, semantic proof, freshness, merge policy | text help only |
 
@@ -76,6 +76,7 @@ Route ambiguous modernization work through the smallest matching family:
 | Does a `REQ-*` have a route to execution? | `requirement-bindings` or `proof-slice` | Proof bindings own route closure, while tests own executable behavior. |
 | Tests were discovered from an existing repository but are not yet admitted proof evidence. | `test-evidence-inventory --projection discovery-draft` | It accepts explicit caller-owned discovery facts and emits candidate-only inventory guidance with a non-strict candidate authority. Stop before treating candidates as semantic coverage; the consumer must materialize strict test inventory rows. |
 | Which checks should run for a change? | `selective-gate-plan` then `selective-gate-evidence` | Planning and receipt comparison stay separate from command execution. |
+| Does the selective plan need a text or secret scan? | Prefer `scanObligation` with `commandOwnership: "proofkit_text_policy"` for `text-policy`, `commandOwnership: "proofkit_secret_scan"` for `secret-scan`, or `commandOwnership: "caller_owned_external"` for an external scanner; legacy `secretScan` is a compatibility alias only. | Stop before treating any inventory command as repository-wide discovery. Proofkit admits scan obligations but does not execute scanner commands or prove repository-wide credential absence. |
 
 ## Agent Decision Procedure
 
@@ -102,6 +103,7 @@ Decision tree:
 
 | State or goal | Next Proofkit route | Stop or escalation condition |
 |---|---|---|
+| The agent does not know where to start. | `init` or `init --preset fresh|code-baseline|code-audit|legacy|change-set` | Treat output as dry-run route guidance only. Stop before scanning, writing files, or making requirements authoritative. |
 | No admitted spec/profile exists and the caller has explicit capability observations. | `capability-map-admission`; use `trustMode: "code_baseline"` only when maintainers intentionally freeze current code, otherwise use `trustMode: "audit_from_code"`. | Stop before treating seeds as stable requirements. The consumer owns observation extraction, materialization, requirement meaning, and proof adequacy. |
 | No admitted spec/profile exists and no capability observations exist. | `scaffold-project-structure`, `adoption-workflow-plan`, or `stack-preset` | Stop before writing files; the consumer owns materialization, overwrite policy, and final requirement text. |
 | Candidate boundary is uncertain. | `adoption-doctor` or `gradual-adoption-guidance --agent-envelope` | Escalate to owner review when the boundary is advisory, ambiguous, or missing native witnesses. |
@@ -111,12 +113,14 @@ Decision tree:
 | Overview prose may contain durable claims. | `spec-overview-claims` | Escalate when normative claims are not tied to `REQ-*` records. |
 | Requirements have no verified proof route. | `requirement-bindings`, `witness-plan` from either an explicit `witness_command_catalog` or a complete `binding_witness_plan_input`, `proof-slice`, or `requirement-proof-resolver` | Stop before claiming proof adequacy; native witness semantics stay with the consumer. A binding-derived witness plan still needs caller-owned vocabulary and conservative command policy. |
 | Tests or proof evidence need inventory. | `test-evidence-inventory`; use `--projection discovery-draft` only for explicit discovered-test facts, then `requirement-coverage-input-compose` when an aggregate `coverage_compose_input` exists, then `requirement-coverage-view` when a `coverage_view_input` exists | Compose only from explicit caller-owned facts. Discovery drafts are candidate-only and cannot close coverage. Use `failureClassifications[]`, `warningClassifications[]`, and `agentActionPlan[]` for machine routing. Escalate when tests are route-only, weak-oracle, unbound, or outside the caller-owned coverage universe. |
-| A change set is known. | `changed-path-set`, optionally `requirement-impact-input-compose`, `impact`, then `selective-gate-plan --agent-envelope` | Raw `knownChangedPaths` in `agent-route` are diagnostic only. Materialize a caller-owned `changed_path_set`, compose a caller-owned `impact_input` before `impact`, and compose a caller-owned `selective_gate_plan_input` before `selective-gate-plan`. Fail closed on unknown scope, dynamic edges, missing owner routes, unbound proof-like paths, or full-gate escalation. |
+| A change set is known. | `changed-path-set`, optionally `requirement-impact-input-compose`, `impact`, then `selective-gate-plan --agent-envelope` | Raw `knownChangedPaths` in `agent-route` are diagnostic only. Materialize a caller-owned `changed_path_set`, compose a caller-owned `impact_input` before `impact`, and compose a caller-owned `selective_gate_plan_input` before `selective-gate-plan`. Use `scanObligation` to name whether a `text-policy`, `secret-scan`, or caller-owned external scanner is required. Fail closed on unknown scope, dynamic edges, missing owner routes, unbound proof-like paths, or full-gate escalation. |
+| Caller-owned file contents need secret-like text detection. | `secret-scan` | Provide explicit sorted file inventory with content. Stop before claiming repository-wide discovery, credential validity, provider ingestion, merge readiness, or replacement of GitHub secret scanning. |
 | Does a TypeScript package public API match a caller-owned manifest? | `agent-route` with `goal: "verify_typescript_public_api"` and explicit `typescript_public_api_manifest` plus `typescript_public_api_repo_root`, then `typescript-public-api-surfaces --repo-root <caller-selected-root>` | This is an explicit filesystem scanner. Stop before guessing `repo-root`, claiming checkout freshness, package-manager truth, or merge readiness. |
 | Receipts are available for planned checks. | `selective-gate-evidence --agent-envelope`; then materialize a caller-owned `obligation_decision_input` from the evidence output plus command routes, currentness, and trust facts; then run `selective-gate-obligation-decision-input`; then materialize the resulting `obligation_decision` input and run `obligation-decision --agent-envelope` | Escalate on missing, stale, invalid, untrusted, blocked, unavailable, or unknown-scope evidence. |
 | Human inspection is needed. | `requirement-source-view`, `requirement-proof-view`, `requirement-coverage-view`, `requirement-spec-tree-view`, or `requirement-browser-server` | `agent-route` emits browser commands as plan-only by default. Use `browserMode: "serve_local_view"` for `--serve` and `openBrowser: true` for `--open`. Rendered HTML and Markdown are presentation only unless the consumer admits a tracked artifact freshness gate. |
 | Temporary external document lifecycle facts, generated views, or rendered views need authority classification. | `document-lifecycle-boundary` | Treat lifecycle records as caller-owned metadata. Temporary design docs and implementation plans are not retained repository authority unless rewritten into deterministic specs, proof bindings, tests, package-public docs, or backlog rows. |
-| A JavaScript/TypeScript consumer needs less wrapper code. | `json-report-cli-adapter-source --language typescript` | Generated adapter source is caller-owned after materialization. The consumer still owns package pin, binary path, repo paths, local policy, and freshness proof. |
+| A JavaScript/TypeScript consumer needs less wrapper code. | `json-report-cli-adapter-source --language typescript --format json` | Generated adapter source is caller-owned after materialization. The consumer still owns package pin, binary path, repo paths, local policy, and freshness proof. It is a CLI runner adapter, not a separate SDK authority. |
+| A Python consumer needs Proofkit from Python tooling. | Install the Python package when available and invoke the same CLI/JSON contract. | The Python package is a runner wrapper over the Go CLI, not a Python SDK or alternate schema owner. |
 | Local proof infrastructure may be retired. | `migration-parity-admission`, then `migration-plan` | Stop before deleting local owners unless parity and post-retirement validation are caller-approved. |
 | Release, package, or deploy evidence is in scope. | `release-authority`, `registry-consumer-proof-input-compose`, `registry-consumer`, `external-consumer`, `deployment-evidence-admission`, or `readiness-closeout` | Compose registry-consumer input from explicit primitive facts first when needed; final registry-consumer validation remains separate. Treat registry, release, CI, deployment, and readiness evidence as separate classes. |
 | The agent does not know which route applies. | `agent-route` with a known goal, or this map when no route input exists yet. | Escalate to the consumer owner instead of guessing, scanning ambient state, or executing commands. |

package/docs/release-process.md

@@ -200,6 +200,15 @@ The evidence must distinguish:
 
 These evidence classes are not interchangeable.
 
+Historical GitHub Releases are immutable provider state. If an older release
+metadata record names an asset that is absent from the provider release and the
+provider rejects exact backfill, the repository records that as a historical
+archive-evidence exception instead of mutating the release model around it.
+Future releases must prevent recurrence by verifying the expected public asset
+set, byte-for-byte Release asset content, `release-notes.md` presence, release
+manifest and metadata checksum closure, and retained workflow evidence checksum
+closure before reporting GitHub Release archive evidence as passed.
+
 ## Rollback
 
 Published npm versions are immutable. Rollback means pinning consumers back to

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@research-engineering/agentic-proofkit",
   "description": "Reusable proof profile, report, graph, and witness-planning primitives.",
-  "version": "0.1.152",
+  "version": "0.1.153",
   "type": "module",
   "license": "MIT",
   "sideEffects": false,

package/proofkit/cli-contract.v1.json

@@ -103,10 +103,10 @@
             "item": {
               "kind": {
                 "enum": [
-              "adoption_workflow",
-              "authoring_plan",
-              "binding_witness_plan_input",
-              "capability_map",
+                  "adoption_workflow",
+                  "authoring_plan",
+                  "binding_witness_plan_input",
+                  "capability_map",
                   "changed_path_set",
                   "coverage_compose_input",
                   "coverage_view_input",
@@ -485,6 +485,43 @@
         "--input-pointer"
       ]
     },
+    {
+      "command": "init",
+      "input": "none",
+      "stdin": false,
+      "inputPointer": false,
+      "scopeClass": "built_in_package_catalog",
+      "outputModes": [
+        "json"
+      ],
+      "allowedFlags": [
+        "--preset"
+      ],
+      "outputContract": {
+        "contractId": "proofkit.init.output.v1",
+        "schemaVersion": 1,
+        "authority": "dry-run adoption route guidance",
+        "presets": [
+          "all",
+          "change-set",
+          "code-audit",
+          "code-baseline",
+          "fresh",
+          "legacy"
+        ],
+        "requiredReportFields": [
+          "diagnostics",
+          "nonClaims",
+          "reportId",
+          "reportKind",
+          "ruleResults",
+          "schemaVersion",
+          "state",
+          "summary"
+        ],
+        "nonClaim": "Init does not read repository files, discover tests, write files, create requirements, or approve merge/release/rollout."
+      }
+    },
     {
       "command": "json-report-cli-adapter-source",
       "input": "none",
@@ -776,7 +813,29 @@
       "allowedFlags": [
         "--input",
         "--input-pointer"
-      ]
+      ],
+      "inputContract": {
+        "contractId": "proofkit.repo-profile-admission.input.v1",
+        "schemaVersion": 1,
+        "authority": "repo profile input admission",
+        "compatibility": {
+          "schemaVersion": "optional transitional top-level field; if present it must be 1",
+          "profile.schema": "required proofkit.repo-profile.v1"
+        },
+        "environmentPolicy": {
+          "legacyFields": [
+            "liveGithubRequiredClasses",
+            "localSecretRequiredClasses"
+          ],
+          "preferredField": "environmentClassPolicies",
+          "tupleFields": [
+            "environmentClass",
+            "networkPolicy",
+            "credentialClass"
+          ],
+          "nonClaim": "Repo-profile admission checks explicit caller-owned command policy facts and does not execute commands or discover repository files."
+        }
+      }
     },
     {
       "command": "requirement-authoring-plan",
@@ -1244,6 +1303,62 @@
         "--input-pointer"
       ]
     },
+    {
+      "command": "secret-scan",
+      "input": "required",
+      "stdin": true,
+      "inputPointer": true,
+      "scopeClass": "explicit_caller_input",
+      "outputModes": [
+        "json"
+      ],
+      "allowedFlags": [
+        "--input",
+        "--input-pointer"
+      ],
+      "inputContract": {
+        "contractId": "proofkit.secret-scan.input.v1",
+        "schemaVersion": 1,
+        "authority": "caller-owned explicit file inventory",
+        "requiredFields": [
+          "files",
+          "nonClaims",
+          "reportId",
+          "schemaVersion"
+        ],
+        "fileRecord": {
+          "requiredFields": [
+            "path",
+            "state"
+          ],
+          "optionalFields": [
+            "contentBase64"
+          ],
+          "state": [
+            "missing",
+            "present"
+          ],
+          "rules": [
+            "paths must be sorted unique repository-relative POSIX paths",
+            "present files must include contentBase64",
+            "missing files must not include contentBase64"
+          ]
+        },
+        "nonClaim": "Secret scan does not discover repository files or replace provider secret scanning."
+      },
+      "outputContract": {
+        "contractId": "proofkit.secret-scan.output.v1",
+        "schemaVersion": 1,
+        "authority": "secret-like text pattern findings over admitted explicit inventory",
+        "findingFields": [
+          "findingClass",
+          "line",
+          "path"
+        ],
+        "redactionRule": "matched secret-like values are never emitted to stdout reports",
+        "nonClaim": "Findings are pattern detections, not credential validity proof."
+      }
+    },
     {
       "command": "selective-gate-evidence",
       "input": "required",
@@ -1288,7 +1403,35 @@
         "--agent-envelope",
         "--input",
         "--input-pointer"
-      ]
+      ],
+      "inputContract": {
+        "contractId": "proofkit.selective-gate-plan.input.v1",
+        "schemaVersion": 1,
+        "authority": "selective gate plan input admission",
+        "scanObligation": {
+          "preferred": true,
+          "fields": [
+            "command",
+            "commandId",
+            "commandOwnership",
+            "mode",
+            "reason",
+            "required"
+          ],
+          "commandOwnership": [
+            "proofkit_secret_scan",
+            "proofkit_text_policy",
+            "caller_owned_external"
+          ],
+          "reason": [
+            "secret_scan",
+            "text_policy",
+            "external_secret_scan"
+          ],
+          "legacyAlias": "secretScan",
+          "nonClaim": "Selective gate planning admits scan obligations but does not execute scanner commands or prove repository-wide credential absence."
+        }
+      }
     },
     {
       "command": "self-check",
@@ -1575,6 +1718,10 @@
               "commands",
               "vocabulary"
             ],
+            "optional": [
+              "schemaVersion"
+            ],
+            "schemaVersionRule": "If present, schemaVersion must be 1.",
             "nonClaim": "Explicit command catalogs are caller-owned; Proofkit admits command safety shape but does not execute commands."
           },
           "requirement-bindings": {