planr 1.8.0 → 1.10.0-alpha.1

package/docs/contracts/fixtures/evidence/v1/examples/coverage-verdict.json

@@ -0,0 +1,66 @@
+{
+  "id": "cverdict-api-health-v1",
+  "schema_version": "evidence.contract.v1",
+  "scope": {
+    "kind": "criterion",
+    "id": "criterion-api-health",
+    "plan_id": "pln-example",
+    "item_id": "item-example"
+  },
+  "evaluated_at": "2026-07-28T12:00:08Z",
+  "status": "satisfied",
+  "observation_coverage": [
+    {
+      "requirement_id": "obs-http-200",
+      "status": "covered",
+      "covering_receipt_ids": ["erec-planr-api-health-v1"],
+      "covered_observation_ids": ["obs-http-200"]
+    }
+  ],
+  "validation_details": {
+    "trust": {
+      "status": "passed",
+      "checked_at": "2026-07-28T12:00:08Z",
+      "receipt_ids": ["erec-planr-api-health-v1"],
+      "gap_reasons": []
+    },
+    "freshness": {
+      "status": "passed",
+      "checked_at": "2026-07-28T12:00:08Z",
+      "receipt_ids": ["erec-planr-api-health-v1"],
+      "gap_reasons": []
+    },
+    "target": {
+      "status": "passed",
+      "checked_at": "2026-07-28T12:00:08Z",
+      "receipt_ids": ["erec-planr-api-health-v1"],
+      "gap_reasons": []
+    },
+    "schema": {
+      "status": "passed",
+      "checked_at": "2026-07-28T12:00:08Z",
+      "receipt_ids": ["erec-planr-api-health-v1"],
+      "gap_reasons": []
+    },
+    "provenance": {
+      "status": "passed",
+      "checked_at": "2026-07-28T12:00:08Z",
+      "receipt_ids": ["erec-planr-api-health-v1"],
+      "gap_reasons": []
+    },
+    "fixture": {
+      "status": "passed",
+      "checked_at": "2026-07-28T12:00:08Z",
+      "receipt_ids": ["erec-planr-api-health-v1"],
+      "gap_reasons": []
+    },
+    "completion": {
+      "status": "passed",
+      "checked_at": "2026-07-28T12:00:08Z",
+      "receipt_ids": ["erec-planr-api-health-v1"],
+      "gap_reasons": []
+    }
+  },
+  "suggested_next_action": "none",
+  "actionable_now": false
+}

package/docs/contracts/fixtures/evidence/v1/examples/evidence-attempt.json

@@ -0,0 +1,39 @@
+{
+  "id": "eatt-planr-api-health-v1",
+  "schema_version": "evidence.contract.v1",
+  "criterion_id": "criterion-api-health",
+  "obligation_id": "pob-planr-api-health-v1",
+  "capability_instance_id": "vcinst-planr-http-process-v1",
+  "started_at": "2026-07-28T12:00:05Z",
+  "ended_at": "2026-07-28T12:00:06Z",
+  "status": "passed",
+  "resolved_command": {
+    "kind": "command",
+    "command": ["curl", "-fsS", "http://127.0.0.1:4173/health"],
+    "cwd": "$PLANR_REPOSITORY_ROOT"
+  },
+  "exit": {
+    "exit_code": 0,
+    "signal": null,
+    "error": null
+  },
+  "retry_lineage": {
+    "attempt_number": 1,
+    "max_attempts": 1,
+    "previous_attempt_ids": []
+  },
+  "stdout_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "stderr_digest": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+  "raw_result": {
+    "kind": "artifact",
+    "artifact_id": "artifact-http-response",
+    "digest": "sha256:8888888888888888888888888888888888888888888888888888888888888888"
+  },
+  "artifacts": [],
+  "output_bounds": {
+    "stdout_bytes": 16,
+    "stderr_bytes": 0,
+    "stdout_truncated": false,
+    "stderr_truncated": false
+  }
+}

package/docs/contracts/fixtures/evidence/v1/examples/evidence-policy.json

@@ -0,0 +1,117 @@
+{
+  "id": "epolicy-default-v1",
+  "schema_version": "evidence.contract.v1",
+  "policy_digest": "sha256:c1a2a26ece3ee7a3cf3166cd849664d723fe2fffda2dc0773b2c92dc8d1ae8c1",
+  "defaults": {
+    "preset_id": "preset-http-health",
+    "binding": true,
+    "assurance_level": "standard"
+  },
+  "named_presets": [
+    {
+      "id": "preset-http-health",
+      "schema_version": "evidence.contract.v1",
+      "namespace": "planr.api",
+      "observations": [
+        {
+          "id": "obs-http-200",
+          "type": "planr.api.http.response",
+          "subject": "GET /health",
+          "expected": {
+            "status": 200
+          },
+          "target": {
+            "kind": "local_service",
+            "uri": "http://127.0.0.1:4173/health"
+          },
+          "environment": {
+            "kind": "local",
+            "id": "dev-shell",
+            "digest": "sha256:5555555555555555555555555555555555555555555555555555555555555555"
+          },
+          "runtime_target": {
+            "kind": "process",
+            "id": "planr-doc-fixture"
+          }
+        }
+      ]
+    }
+  ],
+  "observation_schema_registrations": [
+    {
+      "type": "planr.api.http.response",
+      "schema_ref": "planr.api.http.response@v1",
+      "schema_digest": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
+      "owning_namespace": "planr.api"
+    }
+  ],
+  "adapter_registrations": [
+    {
+      "manifest_id": "vcap-planr-http-process-v1",
+      "manifest_path": "docs/contracts/fixtures/evidence/v1/examples/verification-capability-manifest.json",
+      "manifest_digest": "sha256:6666666666666666666666666666666666666666666666666666666666666666",
+      "observation_types": ["planr.api.http.response"],
+      "payload_schemas": [
+        {
+          "type": "planr.api.http.response",
+          "schema_ref": "planr.api.http.response@v1",
+          "schema_digest": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
+        }
+      ],
+      "provenance_path": "planr_observed_execution",
+      "execution_contract": {
+        "kind": "process",
+        "executable": "curl",
+        "args": ["--fail", "--silent", "http://127.0.0.1:4173/health"],
+        "working_directory": ".",
+        "timeout_ms": 10000,
+        "stdout_limit_bytes": 1048576,
+        "stderr_limit_bytes": 1048576,
+        "payload_schema": {
+          "type": "planr.api.http.response",
+          "schema_ref": "planr.api.http.response@v1",
+          "schema_digest": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
+        }
+      }
+    }
+  ],
+  "extension_namespaces": ["planr.api"],
+  "trust_policy": {
+    "accepted_provenance": ["planr_observed_execution"],
+    "min_receipt_status": "trusted",
+    "allow_user_attestation": false
+  },
+  "freshness_policy": {
+    "max_age_seconds": 3600,
+    "invalidate_on": [
+      "source_change",
+      "target_change",
+      "policy_change",
+      "adapter_schema_change",
+      "configuration_change"
+    ]
+  },
+  "fixture_policy": {
+    "fixtures_allowed": false,
+    "mocks_allowed": false,
+    "disclosure_required": true
+  },
+  "completion_policy": {
+    "require_satisfied_or_waived": true,
+    "allow_inconclusive_completion": false,
+    "require_review_evidence": true
+  },
+  "layering_policy": {
+    "mode": "monotonic_strengthening",
+    "weakening_requires_waiver": true,
+    "layers": [
+      {
+        "scope": {
+          "kind": "plan",
+          "id": "pln-example"
+        },
+        "policy_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+      }
+    ]
+  }
+}

package/docs/contracts/fixtures/evidence/v1/examples/evidence-receipt.json

@@ -0,0 +1,93 @@
+{
+  "id": "erec-planr-api-health-v1",
+  "schema_version": "evidence.contract.v1",
+  "criterion_id": "criterion-api-health",
+  "obligation_id": "pob-planr-api-health-v1",
+  "receipt_status": "trusted",
+  "source": {
+    "revision": "0123456789abcdef0123456789abcdef01234567",
+    "tree_digest": "sha256:3333333333333333333333333333333333333333333333333333333333333333",
+    "dirty": false
+  },
+  "target": {
+    "kind": "local_service",
+    "uri": "http://127.0.0.1:4173/health",
+    "digest": "sha256:4444444444444444444444444444444444444444444444444444444444444444"
+  },
+  "environment": {
+    "kind": "local",
+    "id": "dev-shell",
+    "digest": "sha256:5555555555555555555555555555555555555555555555555555555555555555"
+  },
+  "vantage_point": {
+    "kind": "localhost",
+    "identity": "127.0.0.1"
+  },
+  "capability": {
+    "manifest_id": "vcap-planr-http-process-v1",
+    "manifest_digest": "sha256:6666666666666666666666666666666666666666666666666666666666666666",
+    "instance_id": "vcinst-planr-http-process-v1",
+    "instance_digest": "sha256:7777777777777777777777777777777777777777777777777777777777777777"
+  },
+  "provenance": {
+    "source": "planr_observed_execution",
+    "assigned_by": "planr",
+    "execution_id": "exec-20260728-api-health",
+    "tool_call_id": null
+  },
+  "observations": [
+    {
+      "requirement_id": "obs-http-200",
+      "type": "planr.api.http.response",
+      "outcome": "passed",
+      "predicate": {
+        "status": 200,
+        "json_path": "$.status",
+        "equals": "ok"
+      },
+      "actual": {
+        "status": 200,
+        "json": {
+          "status": "ok"
+        }
+      }
+    }
+  ],
+  "attempt_ids": [
+    "eatt-planr-api-health-v1"
+  ],
+  "retry_history": [],
+  "artifacts": [
+    {
+      "id": "artifact-http-response",
+      "kind": "stdout",
+      "digest": "sha256:8888888888888888888888888888888888888888888888888888888888888888"
+    }
+  ],
+  "raw_result": {
+    "kind": "artifact",
+    "artifact_id": "artifact-http-response",
+    "digest": "sha256:8888888888888888888888888888888888888888888888888888888888888888"
+  },
+  "config_digest": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
+  "fixture_disclosure": {
+    "fixtures_used": false,
+    "mocks_used": false
+  },
+  "permissions": {
+    "network": "localhost_only",
+    "filesystem": "read_workspace"
+  },
+  "sandbox": {
+    "mode": "bounded_process",
+    "limits": {
+      "timeout_ms": 10000,
+      "stdout_bytes": 1048576,
+      "stderr_bytes": 1048576
+    }
+  },
+  "proof_gaps": [],
+  "started_at": "2026-07-28T12:00:05Z",
+  "ended_at": "2026-07-28T12:00:06Z",
+  "receipt_digest": "sha256:6ea111943fdafe268a5bbe85b0fecaab75890dbcb9b2e2dfb966f3c6916e348f"
+}

package/docs/contracts/fixtures/evidence/v1/examples/evidence-waiver.json

@@ -0,0 +1,31 @@
+{
+  "id": "ewaiver-api-health-expiry",
+  "schema_version": "evidence.contract.v1",
+  "scope": {
+    "kind": "item",
+    "id": "item-example",
+    "plan_id": "pln-example"
+  },
+  "observation_ids": ["obs-http-200"],
+  "source": {
+    "revision": "0123456789abcdef0123456789abcdef01234567",
+    "tree_digest": "sha256:3333333333333333333333333333333333333333333333333333333333333333",
+    "dirty": false
+  },
+  "target": {
+    "kind": "local_service",
+    "uri": "http://127.0.0.1:4173/health",
+    "digest": "sha256:4444444444444444444444444444444444444444444444444444444444444444"
+  },
+  "reason": "temporary approved exception for local fixture downtime",
+  "created_by": "user@example.com",
+  "created_at": "2026-07-28T12:00:00Z",
+  "expires_at": "2026-07-29T12:00:00Z",
+  "approval_ref": "approval-123",
+  "audit_trail": [
+    {
+      "event": "created",
+      "at": "2026-07-28T12:00:00Z"
+    }
+  ]
+}

package/docs/contracts/fixtures/evidence/v1/examples/proof-obligation.json

@@ -0,0 +1,67 @@
+{
+  "id": "pob-planr-api-health-v1",
+  "schema_version": "evidence.contract.v1",
+  "criterion_id": "criterion-api-health",
+  "plan_id": "pln-example",
+  "item_id": "item-example",
+  "title": "API health endpoint returns OK from the target service",
+  "binding": true,
+  "observations": [
+    {
+      "id": "obs-http-200",
+      "type": "planr.api.http.response",
+      "subject": "GET /health",
+      "expected": {
+        "status": 200,
+        "json_path": "$.status",
+        "equals": "ok"
+      },
+      "target": {
+        "kind": "local_service",
+        "uri": "http://127.0.0.1:4173/health"
+      },
+      "environment": {
+        "kind": "local",
+        "id": "dev-shell",
+        "digest": "sha256:5555555555555555555555555555555555555555555555555555555555555555"
+      },
+      "runtime_target": {
+        "kind": "process",
+        "id": "planr-doc-fixture"
+      },
+      "payload_schema": {
+        "schema_ref": "planr.api.http.response@v1"
+      },
+      "freshness_policy": {
+        "source": "source_tree",
+        "max_age_seconds": 3600
+      },
+      "assurance_policy": {
+        "min_provenance": "planr_observed_execution",
+        "independent_methods": 1
+      }
+    }
+  ],
+  "fixture_policy": {
+    "fixtures_allowed": false,
+    "mocks_allowed": false,
+    "disclosure_required": true
+  },
+  "freshness_policy": {
+    "invalidate_on": [
+      "source_change",
+      "target_change",
+      "policy_change",
+      "adapter_schema_change",
+      "configuration_change"
+    ]
+  },
+  "assurance_policy": {
+    "min_receipt_status": "trusted",
+    "allow_user_attestation": false
+  },
+  "policy_digest": "sha256:c1a2a26ece3ee7a3cf3166cd849664d723fe2fffda2dc0773b2c92dc8d1ae8c1",
+  "config_digest": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
+  "created_at": "2026-07-28T12:00:00Z",
+  "supersedes": null
+}

package/docs/contracts/fixtures/evidence/v1/examples/proof-preset.json

@@ -0,0 +1,28 @@
+{
+  "id": "preset-http-health",
+  "schema_version": "evidence.contract.v1",
+  "namespace": "planr.api",
+  "observations": [
+    {
+      "id": "obs-http-200",
+      "type": "planr.api.http.response",
+      "subject": "GET /health",
+      "expected": {
+        "status": 200
+      },
+      "target": {
+        "kind": "local_service",
+        "uri": "http://127.0.0.1:4173/health"
+      },
+      "environment": {
+        "kind": "local",
+        "id": "dev-shell",
+        "digest": "sha256:5555555555555555555555555555555555555555555555555555555555555555"
+      },
+      "runtime_target": {
+        "kind": "process",
+        "id": "planr-doc-fixture"
+      }
+    }
+  ]
+}

package/docs/contracts/fixtures/evidence/v1/examples/untrusted-evidence-proposal.json

@@ -0,0 +1,20 @@
+{
+  "id": "uep-agent-health-claim-v1",
+  "schema_version": "evidence.contract.v1",
+  "source_kind": "agent",
+  "submitted_at": "2026-07-28T12:00:07Z",
+  "claims": {
+    "criterion_id": "criterion-api-health",
+    "summary": "agent reported the health endpoint returned ok"
+  },
+  "artifact_refs": [
+    {
+      "id": "artifact-agent-note",
+      "kind": "agent-note",
+      "digest": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+    }
+  ],
+  "producer_metadata": {
+    "client": "codex"
+  }
+}

package/docs/contracts/fixtures/evidence/v1/examples/verification-capability-instance.json

@@ -0,0 +1,39 @@
+{
+  "id": "vcinst-planr-http-process-v1",
+  "schema_version": "evidence.contract.v1",
+  "manifest_id": "vcap-planr-http-process-v1",
+  "manifest_digest": "sha256:6666666666666666666666666666666666666666666666666666666666666666",
+  "host": "codex",
+  "surface": "local-process",
+  "host_version": "1.0.0",
+  "adapter_version": "1.0.0",
+  "environment": {
+    "kind": "local",
+    "id": "dev-shell",
+    "digest": "sha256:5555555555555555555555555555555555555555555555555555555555555555"
+  },
+  "permissions": {
+    "network": "localhost_only",
+    "filesystem": "read_workspace"
+  },
+  "availability": {
+    "status": "available"
+  },
+  "probe_result": {
+    "probe_execution_id": "probe-20260728-curl",
+    "outcome": "passed",
+    "observed_at": "2026-07-28T12:00:04Z",
+    "checks": [
+      {
+        "name": "curl-present",
+        "outcome": "passed"
+      }
+    ]
+  },
+  "observed_payload_contract": {
+    "schema_ref": "planr.api.http.response@v1",
+    "observation_types": ["planr.api.http.response"]
+  },
+  "limitations": ["localhost target must be running"],
+  "captured_at": "2026-07-28T12:00:04Z"
+}

package/docs/contracts/fixtures/evidence/v1/examples/verification-capability-manifest.json

@@ -0,0 +1,52 @@
+{
+  "id": "vcap-planr-http-process-v1",
+  "schema_version": "evidence.contract.v1",
+  "version": "1.0.0",
+  "adapter_kind": "process",
+  "adapter_digest": "sha256:6666666666666666666666666666666666666666666666666666666666666666",
+  "supported_surfaces": ["local-process"],
+  "supported_observations": [
+    {
+      "type": "planr.api.http.response",
+      "schema_ref": "planr.api.http.response@v1",
+      "schema_digest": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
+    }
+  ],
+  "supported_interactions": ["http-get"],
+  "supported_artifacts": ["stdout"],
+  "runtime_targets": [
+    {
+      "kind": "process",
+      "id": "planr-doc-fixture"
+    }
+  ],
+  "provenance_path": "planr_observed_execution",
+  "permissions": {
+    "network": "localhost_only",
+    "filesystem": "read_workspace"
+  },
+  "costs": {
+    "network": "local"
+  },
+  "determinism": "deterministic for static health endpoint",
+  "repeatability": "replayable from source tree and target URI",
+  "independence": "adapter observes process output independently of agent text",
+  "blind_spots": ["external network failures outside localhost are not covered"],
+  "availability_probe": {
+    "kind": "process",
+    "execution": {
+      "kind": "process",
+      "executable": "curl",
+      "args": ["--version"],
+      "working_directory": ".",
+      "timeout_ms": 5000,
+      "stdout_limit_bytes": 65536,
+      "stderr_limit_bytes": 65536,
+      "payload_schema": {
+        "type": "planr.api.http.response",
+        "schema_ref": "planr.api.http.response@v1",
+        "schema_digest": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
+      }
+    }
+  }
+}

package/docs/contracts/fixtures/evidence/v1/negative/aborted-zero-exit-attempt.json

@@ -0,0 +1,39 @@
+{
+  "id": "eatt-aborted-zero-exit",
+  "schema_version": "evidence.contract.v1",
+  "criterion_id": "criterion-api-health",
+  "obligation_id": "pob-planr-api-health-v1",
+  "capability_instance_id": "vcinst-planr-http-process-v1",
+  "started_at": "2026-07-28T12:00:05Z",
+  "ended_at": "2026-07-28T12:00:06Z",
+  "status": "aborted",
+  "resolved_command": {
+    "kind": "command",
+    "command": ["curl", "-fsS", "http://127.0.0.1:4173/health"],
+    "cwd": "$PLANR_REPOSITORY_ROOT"
+  },
+  "exit": {
+    "exit_code": 0,
+    "signal": null,
+    "error": null
+  },
+  "retry_lineage": {
+    "attempt_number": 1,
+    "max_attempts": 1,
+    "previous_attempt_ids": []
+  },
+  "stdout_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "stderr_digest": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+  "raw_result": {
+    "kind": "artifact",
+    "artifact_id": "artifact-http-response",
+    "digest": "sha256:8888888888888888888888888888888888888888888888888888888888888888"
+  },
+  "artifacts": [],
+  "output_bounds": {
+    "stdout_bytes": 2,
+    "stderr_bytes": 0,
+    "stdout_truncated": false,
+    "stderr_truncated": false
+  }
+}