agentic-proofkit 0.1.91

package/docs/specs/proofkit-spec-proof-core/requirements.v1.json

@@ -0,0 +1,148 @@
+{
+  "schemaVersion": 1,
+  "sourceId": "proofkit.spec-proof-core.requirements",
+  "specPackagePath": "docs/specs/proofkit-spec-proof-core",
+  "overviewPath": "docs/specs/proofkit-spec-proof-core/overview.md",
+  "requirementsPath": "docs/specs/proofkit-spec-proof-core/requirements.v1.json",
+  "requirements": [
+    {
+      "requirementId": "REQ-PROOFKIT-SPEC-001",
+      "ownerId": "proofkit.spec-proof-core",
+      "invariant": "Requirement source admission validates structured REQ-* records and source-package shape without owning requirement meaning or scanning overview prose as authority.",
+      "claimLevel": "blocking",
+      "riskClass": "high",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [
+        "NC-PROOFKIT-SPEC-001"
+      ],
+      "nonClaims": [
+        "This requirement does not claim product requirement meaning, proof freshness, native witness execution, or overview prose authority."
+      ],
+      "lifecycle": {
+        "state": "active",
+        "replacementRequirementIds": [],
+        "evidenceRefs": []
+      },
+      "deferral": null,
+      "updatePolicy": {
+        "reviewOwnerId": "proofkit.spec-proof-core",
+        "requiresImpactDeclaration": true,
+        "requiresProofBindingReview": true
+      }
+    },
+    {
+      "requirementId": "REQ-PROOFKIT-SPEC-002",
+      "ownerId": "proofkit.spec-proof-core",
+      "invariant": "Requirement proof binding reports validate caller-owned requirement-to-witness mappings and emit deterministic lookup projections without executing witnesses or deciding proof freshness.",
+      "claimLevel": "blocking",
+      "riskClass": "high",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [
+        "NC-PROOFKIT-SPEC-002"
+      ],
+      "nonClaims": [
+        "This requirement does not claim native witness pass evidence, proof freshness, receipt authenticity, or merge approval."
+      ],
+      "lifecycle": {
+        "state": "active",
+        "replacementRequirementIds": [],
+        "evidenceRefs": []
+      },
+      "deferral": null,
+      "updatePolicy": {
+        "reviewOwnerId": "proofkit.spec-proof-core",
+        "requiresImpactDeclaration": true,
+        "requiresProofBindingReview": true
+      }
+    },
+    {
+      "requirementId": "REQ-PROOFKIT-SPEC-003",
+      "ownerId": "proofkit.spec-proof-core",
+      "invariant": "Witness planning accepts caller-owned structured command metadata, scheduler constraints, and environment classes without executing commands or selecting repository policy.",
+      "claimLevel": "blocking",
+      "riskClass": "high",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [
+        "NC-PROOFKIT-SPEC-003"
+      ],
+      "nonClaims": [
+        "This requirement does not claim command execution, CI scheduling authority, credential approval, or repository-specific command policy."
+      ],
+      "lifecycle": {
+        "state": "active",
+        "replacementRequirementIds": [],
+        "evidenceRefs": []
+      },
+      "deferral": null,
+      "updatePolicy": {
+        "reviewOwnerId": "proofkit.spec-proof-core",
+        "requiresImpactDeclaration": true,
+        "requiresProofBindingReview": true
+      }
+    },
+    {
+      "requirementId": "REQ-PROOFKIT-SPEC-004",
+      "ownerId": "proofkit.spec-proof-core",
+      "invariant": "Selective planning and selective evidence reports keep changed-path facts, planned commands, receipts, and obligation candidates explicit and fail closed for unknown or unmatched proof inputs.",
+      "claimLevel": "blocking",
+      "riskClass": "high",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [
+        "NC-PROOFKIT-SPEC-004"
+      ],
+      "nonClaims": [
+        "This requirement does not claim changed-path completeness, command success, receipt authenticity, proof freshness, or approval to skip caller-owned gates."
+      ],
+      "lifecycle": {
+        "state": "active",
+        "replacementRequirementIds": [],
+        "evidenceRefs": []
+      },
+      "deferral": null,
+      "updatePolicy": {
+        "reviewOwnerId": "proofkit.spec-proof-core",
+        "requiresImpactDeclaration": true,
+        "requiresProofBindingReview": true
+      }
+    },
+    {
+      "requirementId": "REQ-PROOFKIT-SPEC-005",
+      "ownerId": "proofkit.spec-proof-core",
+      "invariant": "Rendered proof views and agent envelopes remain bounded, derived presentations over structured source and never become canonical proof or requirement authority.",
+      "claimLevel": "blocking",
+      "riskClass": "medium",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [
+        "NC-PROOFKIT-SPEC-005"
+      ],
+      "nonClaims": [
+        "This requirement does not claim generated view authority, full graph context emission, proof freshness, or agent edit approval."
+      ],
+      "lifecycle": {
+        "state": "active",
+        "replacementRequirementIds": [],
+        "evidenceRefs": []
+      },
+      "deferral": null,
+      "updatePolicy": {
+        "reviewOwnerId": "proofkit.spec-proof-core",
+        "requiresImpactDeclaration": true,
+        "requiresProofBindingReview": true
+      }
+    }
+  ],
+  "nonClaims": [
+    "Consumers still own requirement meaning, command policy, native witness execution, receipts, CI admission, and rollout decisions.",
+    "Proofkit spec-proof core requirements describe reusable infrastructure primitives only."
+  ]
+}

package/docs/witness-scheduler-plan-design.md

@@ -0,0 +1,57 @@
+# Witness Scheduler Plan Design
+
+Status: implemented.
+
+Owner: `proofkit`.
+
+## Problem
+
+`witness-command` admits command shape, but scheduler and cache safety need
+additional caller-owned metadata: input selectors, output selectors, resource
+reads, resource writes, exclusive locks, side-effect class, retry policy,
+cancellation policy, timeout policy, and cache-admission refs.
+
+Without this layer, selective checking can know which command exists but not
+whether it is safe to parallelize or cache.
+
+## Decision
+
+Add `witness-scheduler-plan`, an additive deterministic report over admitted
+witness commands and caller-provided scheduler policies.
+
+The primitive validates:
+
+- every command has exactly one scheduler policy;
+- no policy references an unknown command;
+- cacheable commands declare deterministic output, no network, no credentials,
+  input selectors, cache-admission refs, and required artifact output selectors;
+- networked commands are not declared side-effect free or deterministic;
+- side-effect-free commands do not declare writes or exclusive locks;
+- local-write commands declare resource writes;
+- shared-resource and destructive commands declare resource reads or writes;
+- shared-resource and destructive commands declare exclusive locks;
+- destructive commands do not retry automatically and support cooperative
+  cancellation;
+- parallel groups have no exclusive-lock, write/write, write/read, read/write,
+  or destructive-concurrency collisions;
+- timeout policy matches the admitted witness command timeout.
+
+## Authority Boundary
+
+Proofkit validates caller-provided scheduler metadata and emits deterministic
+diagnostics. It does not execute commands, inspect filesystem or lock state,
+read caches, authenticate producers, compute receipt freshness, allocate CI
+runners, or approve merge.
+
+## Rejected Alternatives
+
+| Alternative | Rejected Because |
+|---|---|
+| Add resource and scheduler fields directly to `witness-command`. | That would break existing consumers of command v1 and merge command-shape admission with scheduling policy. |
+| Treat missing cache dimensions as advisory. | Cache reuse is proof-adjacent; missing dimensions must fail closed for commands that opt into cache. |
+| Infer resource conflicts from command strings or paths. | Proofkit must not infer repository semantics from shell text or implicit state. |
+
+## Follow-Up
+
+Consumer repositories can compose this report with selective proof planning and
+receipt admission, but the scheduler plan itself remains pre-execution metadata.

package/docs/workspace-planning-agent-envelope-design.md

@@ -0,0 +1,101 @@
+# Workspace Planning Agent Envelope Design
+
+Status: accepted; implemented as opt-in CLI projections.
+
+Owner: `proofkit`.
+
+## Purpose
+
+Workspace changed-package and shard-partition reports are useful machine
+planning outputs, but coding agents need a bounded work packet that says which
+caller-owned proof scope to inspect without loading full changed-path,
+package-root, or shard payloads.
+
+Formal goal:
+
+```text
+caller-owned workspace planning facts
+  -> deterministic workspace plan report
+  -> bounded agent guidance envelope
+  -> caller-owned command registry, CI schedule, receipts, and merge decision
+```
+
+## Boundary
+
+Proofkit owns:
+
+- deterministic envelope construction from workspace planning outputs;
+- JSON-pointer context refs for selected package roots, escalation reasons,
+  shard rows, shard failures, and source changed paths;
+- bounded action routing for package-scope, full-workspace, or failed-shard
+  outcomes;
+- omitted-count records that keep large plan payloads in the source report;
+- fail-closed blocked-precondition projection for invalid shard partitions.
+
+The consuming repository owns:
+
+- changed-path discovery;
+- package graph freshness;
+- package ownership policy;
+- command registry and witness command ids;
+- CI runner scheduling and retry policy;
+- receipt creation, producer admission, and freshness;
+- merge, release, and rollout decisions.
+
+Formal rule:
+
+```text
+Workspace reports own deterministic planning facts.
+Workspace planning envelopes own bounded agent routing.
+Consumer repositories own execution, receipts, and policy.
+```
+
+## Invariants
+
+- `workspace-changed-package-plan --agent-envelope` and
+  `workspace-shard-partition --agent-envelope` are opt-in; ordinary JSON output
+  is unchanged.
+- Envelopes never emit command refs because workspace planning does not own a
+  caller command registry.
+- Envelopes reference source report JSON pointers instead of copying large
+  changed-path, package, or shard arrays.
+- Full-workspace escalation remains visible and routes to caller-owned full
+  gates instead of being narrowed by package selection.
+- Empty changed-package plans ask a caller-owned policy question instead of
+  becoming hidden pass states.
+- Failed shard partitions produce a failed source state and a blocked
+  precondition before any caller treats matrix rows as usable.
+
+## Rejected Alternatives
+
+| Alternative | Rejection reason |
+|---|---|
+| Add command refs to workspace planning envelopes | Package selection and shard rows do not define caller command ids or witness semantics. |
+| Copy full changed-path and shard payloads into envelopes | That increases token load and creates a second lookup surface. |
+| Make agent envelopes the default workspace CLI output | Existing consumers need stable machine JSON unless they opt into agent presentation. |
+| Treat failed shard partitions as advisory only | Invalid partition coverage can hide omitted or duplicate package execution. |
+
+## Proof Obligations
+
+- Unit tests prove changed-package envelopes include bounded context, no command
+  refs, explicit full-gate routing, and no hidden pass for empty package
+  selection.
+- Unit tests prove shard partition envelopes include no scheduling authority,
+  produce failed source state for invalid partitions, and emit blocked
+  preconditions.
+- CLI tests prove opt-in envelope output for both workspace commands and keep
+  non-workspace modes fail-closed.
+- Package artifact tests prove the packed CLI supports the new projections.
+
+## Non-Claims
+
+Workspace planning agent envelopes do not claim:
+
+- git diff freshness;
+- package graph freshness;
+- command execution;
+- CI scheduling;
+- receipt authenticity or freshness;
+- merge approval;
+- release approval;
+- rollout approval.

package/docs/workspace-registry-admission-design.md

@@ -0,0 +1,57 @@
+# Workspace Registry Admission Design
+
+## Purpose
+
+Workspace registry admission gives consumers one deterministic report for
+caller-provided package registry facts: root scripts, package scripts,
+workspace dependency refs, and optional lockfile text.
+
+The design goal is reuse without policy capture. Proofkit owns generic
+cross-reference mechanics. The consuming repository owns which scripts are
+required, which commands are exact, which package prefixes are internal, which
+lockfile snippets matter, and which native witnesses make the report fresh.
+
+## Formal Boundary
+
+```text
+consumer facts + consumer policy
+  -> proofkit workspace-registry admission
+  -> deterministic report
+  -> consumer-owned gate/receipt/merge decision
+```
+
+Proofkit must not infer repository policy from package names, package-manager
+choice, CI workflows, registry credentials, or historical consumer usage.
+
+## Owned Mechanics
+
+- root script membership and exact-command comparison against caller policy;
+- package required-script comparison against caller policy;
+- script target existence and self-target checks against caller package facts;
+- internal dependency refs checked against caller prefixes and workspace
+  version;
+- optional lockfile text snippet and workspace entry checks;
+- deterministic report shape, rule ids, diagnostics, and non-claims.
+
+## Consumer-Owned Inputs
+
+- package facts and known package names;
+- root and package script policy;
+- internal namespace prefixes and workspace dependency version;
+- optional lockfile text and expected snippets;
+- repository freshness, command execution, receipt producer admission, CI
+  scheduling, merge policy, release policy, and rollout policy.
+
+## Non-Claims
+
+The report does not execute scripts, generate lockfiles, prove lockfile
+freshness, authenticate registry credentials, read implicit repository state,
+approve merge, or prove package-manager behavior.
+
+## Acceptance
+
+- malformed or contradictory caller facts fail closed;
+- no consumer package names or script names are embedded in Proofkit;
+- CLI output is deterministic JSON and supports file, stdin, and JSON Pointer
+  input like other input-based Proofkit commands;
+- package artifact tests prove the public API, CLI, and design note are shipped.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "agentic-proofkit",
+  "description": "Reusable proof profile, report, graph, and witness-planning primitives.",
+  "version": "0.1.91",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "packageManager": "npm@11.16.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "bin": {
+    "agentic-proofkit": "dist/agentic-proofkit"
+  },
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/W25X80/agentic-proofkit.git"
+  },
+  "files": [
+    "ADOPTION.md",
+    "LICENSE",
+    "NON_CLAIMS.md",
+    "README.md",
+    "dist/**",
+    "docs/*.md",
+    "docs/specs/**/*",
+    "proofkit/*.json"
+  ],
+  "scripts": {
+    "build": "go run ./internal/tools/packagebuild",
+    "check": "npm run npm:version && npm run go:check && npm run package:artifact && npm run self:receipt",
+    "go:check": "npm run go:fmt && npm run go:test && npm run go:vet && npm run go:staticcheck && npm run go:vulncheck",
+    "go:fmt": "test -z \"$(gofmt -l cmd internal scripts)\"",
+    "go:test": "go test ./...",
+    "go:vet": "go vet ./...",
+    "npm:version": "node -e \"const {execFileSync}=require('node:child_process'); const expected=require('./package.json').packageManager.split('@').at(-1); const actual=execFileSync('npm',['--version'],{encoding:'utf8'}).trim(); if(actual!==expected){throw new Error('expected npm '+expected+', got '+actual)}\"",
+    "package:artifact": "npm run build && go run ./internal/tools/packagepack && go run ./internal/tools/packageverify",
+    "self:receipt": "go run ./scripts/validate-self-hosting-receipts.go",
+    "go:staticcheck": "go tool staticcheck ./...",
+    "go:vulncheck": "go tool govulncheck ./..."
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "arm64",
+    "x64"
+  ]
+}