Close proof, contract, release, and onboarding audit gaps

.github/workflows/ci.yml

@@ -81,6 +81,9 @@ jobs:
       - name: Verify Go formatting
         run: npm run go:fmt
 
+      - name: Verify generated command contracts
+        run: npm run command-contract:check
+
       - name: Verify generated command family catalog
         run: npm run command-family:check
 
@@ -188,6 +191,17 @@ jobs:
       - name: Run browser proof
         run: npm run browser:check
 
+      - name: Upload browser failure diagnostics
+        if: ${{ failure() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: browser-runtime-diagnostics-${{ github.sha }}-${{ github.run_attempt }}
+          path: |
+            artifacts/browser-run-*/playwright-report.json
+            artifacts/browser-run-*/test-results
+          if-no-files-found: error
+          retention-days: 14
+
       - name: Upload browser proof
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:

.github/workflows/release.yml

@@ -976,23 +976,13 @@ jobs:
               --notes-file artifacts/release/release-notes.md
             existing_dir="$(mktemp -d)"
             gh release view "$GITHUB_REF_NAME" --json assets --jq '.assets[].name' | sort > /tmp/proofkit-existing-release-assets.txt
-            mapfile -t existing_asset_names < /tmp/proofkit-existing-release-assets.txt
-            comm -13 \
-              <(printf '%s\n' "${expected_asset_names[@]}") \
-              <(printf '%s\n' "${existing_asset_names[@]}") \
-              >/tmp/proofkit-extra-release-assets.txt
-            if [ -s /tmp/proofkit-extra-release-assets.txt ]; then
-              cat /tmp/proofkit-extra-release-assets.txt >&2
-              echo "release $GITHUB_REF_NAME contains unexpected assets" >&2
+            if ! cmp -s /tmp/proofkit-expected-release-assets.txt /tmp/proofkit-existing-release-assets.txt; then
+              diff -u /tmp/proofkit-expected-release-assets.txt /tmp/proofkit-existing-release-assets.txt >&2 || true
+              echo "release $GITHUB_REF_NAME asset set differs from the candidate asset set" >&2
               exit 1
             fi
-            missing_assets=()
             for asset in "${expected_assets[@]}"; do
               asset_name="$(basename "$asset")"
-              if ! grep -Fxq "$asset_name" /tmp/proofkit-existing-release-assets.txt; then
-                missing_assets+=("$asset")
-                continue
-              fi
               gh release download "$GITHUB_REF_NAME" --pattern "$asset_name" --dir "$existing_dir"
               existing_asset="$existing_dir/$asset_name"
               if ! cmp -s "$asset" "$existing_asset"; then
@@ -1001,9 +991,6 @@ jobs:
                 exit 1
               fi
             done
-            if [ "${#missing_assets[@]}" -gt 0 ]; then
-              gh release upload "$GITHUB_REF_NAME" "${missing_assets[@]}"
-            fi
             gh release view "$GITHUB_REF_NAME" --json tagName,name,body,isDraft,isPrerelease,assets >/tmp/proofkit-release-view.json
             go run ./internal/tools/releasepreflight github-release \
               --release-file /tmp/proofkit-release-view.json \
@@ -1012,17 +999,6 @@ jobs:
               --asset-names-file /tmp/proofkit-expected-release-assets.txt
             cp /tmp/proofkit-release-view.json artifacts/release/github-release.json
             go run ./internal/tools/releasepreflight retained-evidence --artifact-root artifacts
-            final_dir="$(mktemp -d)"
-            for asset in "${expected_assets[@]}"; do
-              asset_name="$(basename "$asset")"
-              gh release download "$GITHUB_REF_NAME" --pattern "$asset_name" --dir "$final_dir"
-              final_asset="$final_dir/$asset_name"
-              if ! cmp -s "$asset" "$final_asset"; then
-                echo "release $GITHUB_REF_NAME final asset $asset_name differs from the candidate artifact" >&2
-                sha256sum "$asset" "$final_asset" >&2 || true
-                exit 1
-              fi
-            done
             echo "release $GITHUB_REF_NAME already exists and matches the candidate artifacts" >&2
             exit 0
           fi

ADOPTION.md

@@ -30,18 +30,19 @@ Publisher and post-publish registry identity are admitted. GitHub Release
 assets are archive and provenance lookup, not package-manager dependency
 authority.
 
-Consumers may choose npm or Bun for installation. Both consume the same npm
-registry package identity:
+Consumers install the exact npm registry package identity:
 
 ```bash
-npm install -D @research-engineering/agentic-proofkit
-bun add -d @research-engineering/agentic-proofkit
+npm install --save-dev --save-exact @research-engineering/agentic-proofkit
+npm exec --offline -- agentic-proofkit help
 ```
 
 Release evidence still uses npm as the registry-authority CLI because Proofkit
 records npm-specific package identity, `dist.integrity`, `dist.shasum`, `npm
-pack`, and root-only registry install proof. Bun is not used as a substitute
-for those release-authority facts.
+pack`, and root-only registry install proof. A bare `agentic-proofkit` command
+is valid only when an installed package binary is already on `PATH`.
+Equivalent exact-tarball Bun execution has not been admitted, so Bun execution
+remains a non-claim.
 
 Stable authority channel ids:
 

README.md

@@ -24,25 +24,55 @@ packets without copying verifier logic between projects.
 The canonical registry identity is npm:
 
 ```bash
-npm install -D @research-engineering/agentic-proofkit
+npm install --save-dev --save-exact @research-engineering/agentic-proofkit
 ```
 
-Bun consumers may install the same npm registry package with Bun:
+Pre-1.0 releases may contain owner-declared breaking changes, so npm consumers
+must retain the exact saved version instead of replacing it with a version
+range.
+
+The canonical local invocation resolves only the already-installed dependency:
 
 ```bash
-bun add -d @research-engineering/agentic-proofkit
+npm exec --offline -- agentic-proofkit help
 ```
 
 npm remains the release-authority toolchain because release proof records npm
 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.
+registry install evidence. A bare `agentic-proofkit` command is valid when the
+package manager, script runner, or activated environment has already placed the
+installed binary on `PATH`; it is not the canonical copy-and-paste route.
+Equivalent exact-tarball Bun execution has not been admitted, so this README
+does not claim a Bun execution route.
 
 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.
 
-Published Darwin binary distributions require macOS 12.0 or later.
+<!-- proofkit:platform-python:start -->
+Supported binary targets are macOS 12 or later on arm64 or x64.
+Linux manylinux 2.17 or later is supported on arm64 or x64. Windows is unsupported. The Python
+runner requires Python 3.9 or later and wraps the same Go CLI; it is not a
+Python SDK.
+
+After an exact Python package version is available from an admitted channel,
+use one complete package-manager chain:
+
+```bash
+python -m pip install agentic-proofkit==<version>
+python -m agentic_proofkit help
+```
+
+or:
+
+```bash
+uv add --dev agentic-proofkit==<version>
+uv run agentic-proofkit help
+```
+
+These conditional commands do not claim that any current version is available
+on PyPI.
+<!-- proofkit:platform-python:end -->
 
 ## Project Boundary
 
@@ -148,10 +178,10 @@ make generated invariants authoritative by itself.
 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
+npm exec --offline -- agentic-proofkit help
+npm exec --offline -- agentic-proofkit init
+npm exec --offline -- agentic-proofkit help repo-profile-admission
+npm exec --offline -- agentic-proofkit repo-profile-admission --help
 ```
 
 Command-specific help is derived from the private command descriptor table and
@@ -175,8 +205,60 @@ value with lower transport overhead by placing the process option before the
 command:
 
 ```bash
-agentic-proofkit --json-layout compact requirement-context-slice --input slice-input.json
+npm exec --offline -- agentic-proofkit --json-layout compact requirement-context-slice --input slice-input.json
+```
+
+### First Valid Input
+
+The following marker-bounded record is a complete minimal requirement-source
+input. Its example IDs, paths, owner, invariant, and non-claims are
+caller-replaceable examples, not Proofkit-owned product meaning.
+
+<!-- proofkit:first-valid-input:start -->
+```bash
+npm exec --offline -- agentic-proofkit requirement-source-admission --input -
+```
+
+```json
+{
+  "schemaVersion": 1,
+  "sourceId": "example.requirements",
+  "specPackagePath": "docs/specs/example",
+  "overviewPath": "docs/specs/example/overview.md",
+  "requirementsPath": "docs/specs/example/requirements.v1.json",
+  "nonClaims": [
+    "This example does not approve merge or release."
+  ],
+  "requirements": [
+    {
+      "requirementId": "REQ-EXAMPLE-001",
+      "ownerId": "example.owner",
+      "invariant": "The example owner must replace this sentence with an admitted product invariant.",
+      "claimLevel": "blocking",
+      "riskClass": "medium",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [],
+      "nonClaims": [
+        "This example does not execute or authenticate a native witness."
+      ],
+      "lifecycle": {
+        "state": "active",
+        "replacementRequirementIds": [],
+        "evidenceRefs": []
+      },
+      "deferral": null,
+      "updatePolicy": {
+        "reviewOwnerId": "example.owner",
+        "requiresImpactDeclaration": true,
+        "requiresProofBindingReview": true
+      }
+    }
+  ]
+}
 ```
+<!-- proofkit:first-valid-input:end -->
 
 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
@@ -187,7 +269,7 @@ 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
+npm exec --offline -- agentic-proofkit json-report-cli-adapter-source --language typescript --format json
 ```
 
 The generated adapter remains caller-owned after materialization. It must be
@@ -197,10 +279,7 @@ contract; it does not become a separate public SDK or proof authority.
 | Need | Owner |
 |---|---|
 | Human orientation | This README |
-| Coding-agent startup | `AGENTS.md` |
 | Adoption and release-channel model | `ADOPTION.md` |
-| Active work ledger | `BACKLOG.md` |
-| Contribution rules | `CONTRIBUTING.md` |
 | Vulnerability reporting boundary | `SECURITY.md` |
 | Explicit boundary denials | `NON_CLAIMS.md` |
 | `LICENSE` | MIT license |

cmd/agentic-proofkit/main.go

@@ -2,11 +2,21 @@ package main
 
 import (
 	"context"
+	"fmt"
 	"os"
 
 	"github.com/research-engineering/agentic-proofkit/internal/app"
+	"github.com/research-engineering/agentic-proofkit/internal/kernel/cliexec"
 )
 
 func main() {
-	os.Exit(app.Run(context.Background(), os.Args[1:], os.Stdin, os.Stdout, os.Stderr))
+	renderer, err := cliexec.AdmitLauncherProfile(
+		os.Getenv(cliexec.LauncherProfileEnvironment),
+		os.Getenv(cliexec.PythonExecutableEnvironment),
+	)
+	if err != nil {
+		_, _ = fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	os.Exit(app.RunWithRenderer(context.Background(), os.Args[1:], os.Stdin, os.Stdout, os.Stderr, renderer))
 }