@cassiomc1/forgeloop 1.3.0 → 1.6.0

package/docs/diagrams/README.md

@@ -0,0 +1,55 @@
+# Documentation diagrams
+
+The ForgeLoop architecture flow is authored as typed Archify workflow IR in
+[`forgeloop-engineering-flow.workflow.json`](./forgeloop-engineering-flow.workflow.json).
+The checked-in outputs are generated from that source with the pinned Archify
+v2.15.0 toolchain. The animated interactive explorer is the primary experience:
+
+- [animated HTML explorer](../assets/diagrams/forgeloop-engineering-flow.html)
+- [animated, self-contained SVG fallback](../assets/diagrams/forgeloop-engineering-flow.svg)
+- [deterministic generation receipt](../assets/diagrams/forgeloop-engineering-flow.receipt.json)
+
+The canonical source sets `meta.animation` to `trace`, so the explorer and SVG
+trace the workflow edges and nodes. Use the explorer's Present, playback, and
+focus controls for the full animated experience; the SVG remains available for
+repository previews and text-only fallbacks.
+
+[`manifest.json`](./manifest.json) is the governance source for diagram types,
+renderer support, canonical purposes, artifact ownership, and required
+references. The persistent human approval is kept separately in
+[`reviews/forgeloop-engineering-flow.review.json`](./reviews/forgeloop-engineering-flow.review.json).
+
+The JSON IR is the source of truth. Do not edit the generated HTML or SVG by
+hand. Run `npm run docs:diagrams` to regenerate the outputs and
+`npm run docs:diagrams:check` to validate the pinned renderer, source semantics,
+animation markers, artifact fingerprints, persistent review binding, manifest
+ownership, and GitHub-safe SVG constraints.
+
+The HTML view opens in Archify's dark presentation stage so the official flow
+is visible without scrolling; its Present and playback controls expose the
+animated trace, while reduced-motion preferences remain respected. The SVG
+fallback also carries the trace-capable styles and intentionally defaults to the
+dark presentation so it remains legible in repository previews; the adjacent text fallback in
+[`README.md`](../../README.md#architecture-flow) carries the same lifecycle
+semantics for text-only readers.
+
+Archify is vendored at `vendor/archify/v2.15.0/archify` under its MIT license.
+The exact source commit and cryptographic vendor-tree hash are recorded in
+`vendor/archify/v2.15.0/PIN.json`; generated-file hashes are recorded in the
+receipt and the visual approval binds the current source and SVG fingerprints.
+
+`PIN.json` uses ForgeLoop Archify PIN `schemaVersion: 2`. This version describes
+the metadata and integrity-declaration format and is independent of Archify's
+upstream release version. A future PIN format change must increment the schema
+version and update the validator before new files are accepted; it does not
+change the vendored tree digest.
+
+The ForgeLoop Archify wrapper is intentionally documentation-scoped. It reads
+canonical inputs only from `docs/diagrams/` and permits deliver outputs only
+under `docs/assets/diagrams/`.
+
+ForgeLoop governs five documentation-diagram categories: workflow,
+architecture, sequence, dataflow, and lifecycle. The current repository has
+one canonical workflow diagram. Governance support does not imply renderer
+support: a type requires an explicit renderer mapping before it can be added as
+an active diagram.

package/docs/diagrams/forgeloop-engineering-flow.workflow.json

@@ -0,0 +1,122 @@
+{
+  "schema_version": 1,
+  "diagram_type": "workflow",
+  "meta": {
+    "title": "ForgeLoop Evidence-First Engineering Flow",
+    "subtitle": "Typed intent → gated work → validator-backed closure",
+    "animation": "trace",
+    "visual_preset": "signal-flow",
+    "quality_profile": "showcase",
+    "views": [
+      {
+        "id": "contract-to-work",
+        "label": "Contract to work",
+        "focus": ["request", "profile", "contract", "route", "gates", "preflight", "work"],
+        "note": "Follow how a request becomes scoped, routed, and safe to execute."
+      },
+      {
+        "id": "evidence-to-close",
+        "label": "Evidence to close",
+        "focus": ["work", "evidence", "review", "valid"],
+        "note": "See the evidence and review boundary that makes completion trustworthy."
+      },
+      {
+        "id": "recovery-loop",
+        "label": "Recovery loop",
+        "focus": ["evidence", "diagnose", "correct", "preflight", "blocked"],
+        "note": "Failures return to diagnosis and correction before another claim is made."
+      }
+    ],
+    "legend": {
+      "mode": "auto",
+      "entries": {
+        "frontend": { "label": "Human-facing surface" },
+        "backend": { "label": "ForgeLoop state" },
+        "database": { "label": "Durable evidence" },
+        "cloud": { "label": "External boundary" },
+        "security": { "label": "Policy or gate" },
+        "messagebus": { "label": "Recovery signal" },
+        "external": { "label": "Request or result" }
+      }
+    },
+    "viewBox": [720, 900]
+  },
+  "lanes": [
+    { "id": "intent", "label": "Intent + Context" },
+    { "id": "policy", "label": "Policy Boundary" },
+    { "id": "execution", "label": "Resumable Execution" },
+    { "id": "evidence", "label": "Evidence Ledger" },
+    { "id": "recovery", "label": "Recovery + Stops", "variant": "exception" },
+    { "id": "closure", "label": "Review + Closure" }
+  ],
+  "phases": [
+    { "id": "discover", "label": "Discover + scope", "fromCol": 0, "toCol": 2 },
+    { "id": "authorize", "label": "Route + authorize", "fromCol": 3, "toCol": 4, "variant": "emphasis" },
+    { "id": "verify", "label": "Execute + verify", "fromCol": 5, "toCol": 5, "variant": "dashed" }
+  ],
+  "groups": [
+    { "id": "contract_boundary", "label": "Contract boundary", "lane": "policy", "fromCol": 3, "toCol": 5, "variant": "emphasis" },
+    { "id": "evidence_boundary", "label": "Evidence boundary", "lane": "evidence", "fromCol": 4, "toCol": 5, "variant": "dashed" },
+    { "id": "recovery_path", "label": "Reconcile before retry", "lane": "recovery", "fromCol": 0, "toCol": 2, "variant": "security" }
+  ],
+  "mainPath": ["request", "profile", "contract", "route", "gates", "preflight", "work", "evidence", "review", "valid"],
+  "nodes": [
+    { "id": "request", "lane": "intent", "col": 0, "type": "external", "label": "Request", "sublabel": "intent", "width": 50 },
+    { "id": "profile", "lane": "intent", "col": 1, "type": "backend", "label": "Profile", "sublabel": "facts", "width": 50 },
+    { "id": "contract", "lane": "intent", "col": 2, "type": "security", "label": "Contract", "sublabel": "scope", "tag": "saved", "width": 50 },
+    { "id": "route", "lane": "policy", "col": 2, "type": "security", "label": "Route", "sublabel": "guides", "tag": "fail closed", "width": 50 },
+    { "id": "gates", "lane": "policy", "col": 3, "type": "security", "label": "Gates", "sublabel": "policy", "width": 50 },
+    { "id": "preflight", "lane": "policy", "col": 4, "type": "security", "label": "READY", "sublabel": "unlock", "tag": "PREFLIGHT", "width": 50 },
+    { "id": "work", "lane": "execution", "col": 4, "type": "backend", "label": "Work", "sublabel": "checkpoint", "width": 50 },
+    { "id": "evidence", "lane": "evidence", "col": 4, "type": "database", "label": "Evidence", "sublabel": "checks", "tag": "freshness", "width": 50 },
+    { "id": "review", "lane": "closure", "col": 5, "type": "backend", "label": "Review", "sublabel": "drift", "width": 50 },
+    { "id": "valid", "lane": "evidence", "col": 5, "type": "database", "label": "VALID", "sublabel": "validator", "tag": "claim", "width": 50 },
+    { "id": "diagnose", "lane": "recovery", "col": 2, "type": "messagebus", "label": "Diagnose", "sublabel": "failure", "width": 50 },
+    { "id": "correct", "lane": "recovery", "col": 1, "type": "backend", "label": "Correct", "sublabel": "repair", "width": 50 },
+    { "id": "blocked", "lane": "recovery", "col": 0, "type": "security", "label": "Blocked", "sublabel": "stop", "width": 50 }
+  ],
+  "edges": [
+    { "id": "request-profile", "from": "request", "to": "profile", "variant": "emphasis" },
+    { "id": "profile-contract", "from": "profile", "to": "contract", "variant": "default" },
+    { "id": "contract-route", "from": "contract", "to": "route", "variant": "emphasis", "fromSide": "bottom", "toSide": "top", "route": "drop" },
+    { "id": "route-gates", "from": "route", "to": "gates", "variant": "emphasis" },
+    { "id": "gates-preflight", "from": "gates", "to": "preflight", "variant": "security", "fromSide": "bottom", "toSide": "bottom", "route": "bottom-channel", "channelY": 312 },
+    { "id": "preflight-work", "from": "preflight", "to": "work", "variant": "emphasis", "fromSide": "bottom", "toSide": "top", "route": "drop" },
+    { "id": "work-evidence", "from": "work", "to": "evidence", "variant": "dashed", "fromSide": "bottom", "toSide": "top", "route": "drop" },
+    { "id": "evidence-review", "from": "evidence", "to": "review", "variant": "emphasis", "fromSide": "left", "toSide": "left", "route": "return-left", "channelX": 360 },
+    { "id": "review-valid", "from": "review", "to": "valid", "variant": "emphasis", "fromSide": "right", "toSide": "right", "route": "outside-right", "channelX": 760 },
+    { "id": "evidence-diagnose", "from": "evidence", "to": "diagnose", "variant": "security", "role": "error", "fromSide": "left", "toSide": "right", "route": "return-left", "channelX": 360 },
+    { "id": "diagnose-correct", "from": "diagnose", "to": "correct", "variant": "dashed", "role": "branch", "fromSide": "left", "toSide": "right", "route": "return-left" },
+    { "id": "correct-evidence", "from": "correct", "to": "evidence", "variant": "security", "role": "return", "fromSide": "left", "toSide": "left", "route": "return-left", "channelX": 160 },
+    { "id": "correct-blocked", "from": "correct", "to": "blocked", "variant": "dashed", "role": "branch", "fromSide": "left", "toSide": "right", "route": "return-left" }
+  ],
+  "cards": [
+    {
+      "dot": "rose",
+      "title": "Safety boundary",
+      "items": [
+        "Execution starts only after PREFLIGHT_READY",
+        "Failures return to diagnosis before another claim",
+        "Completion is validator-backed, not inferred from a screenshot"
+      ]
+    },
+    {
+      "dot": "cyan",
+      "title": "Evidence contract",
+      "items": [
+        "run-check binds commands to an execution reference",
+        "record-check covers manual observations",
+        "Drift reopens verification instead of being hidden"
+      ]
+    },
+    {
+      "dot": "emerald",
+      "title": "Portable output",
+      "items": [
+        "JSON IR is the source of truth",
+        "HTML stays explorable and SVG stays GitHub-safe",
+        "The text fallback carries the same lifecycle semantics"
+      ]
+    }
+  ]
+}

package/docs/diagrams/manifest.json

@@ -0,0 +1,42 @@
+{
+  "version": 2,
+  "renderer": {
+    "name": "archify",
+    "version": "2.15.0",
+    "commit": "e1ac748f19cf805e44bf74fb93c796662152e273",
+    "source": "https://github.com/tt-a1i/archify/tree/v2.15.0",
+    "license": "MIT"
+  },
+  "policy": {
+    "supportedTypes": [
+      "workflow",
+      "architecture",
+      "sequence",
+      "dataflow",
+      "lifecycle"
+    ],
+    "requireVisualReview": true
+  },
+  "diagrams": [
+    {
+      "id": "forgeloop-engineering-flow",
+      "type": "workflow",
+      "defaultTheme": "dark",
+      "canonicalFor": [
+        "high-level-engineering-flow"
+      ],
+      "source": "docs/diagrams/forgeloop-engineering-flow.workflow.json",
+      "html": "docs/assets/diagrams/forgeloop-engineering-flow.html",
+      "svg": "docs/assets/diagrams/forgeloop-engineering-flow.svg",
+      "receipt": "docs/assets/diagrams/forgeloop-engineering-flow.receipt.json",
+      "review": "docs/diagrams/reviews/forgeloop-engineering-flow.review.json",
+      "fallback": "README.md#architecture-flow",
+      "referencedBy": [
+        "README.md",
+        "DOCS_INDEX.md",
+        "docs/DOCUMENTATION_GUIDE.md",
+        "docs/diagrams/README.md"
+      ]
+    }
+  ]
+}

package/docs/diagrams/reviews/forgeloop-engineering-flow.review.json

@@ -0,0 +1,20 @@
+{
+  "version": 1,
+  "diagramId": "forgeloop-engineering-flow",
+  "status": "approved",
+  "binding": {
+    "sourceSha256": "e4778296d1b9b2129b1ff6c956acaa1e7faba3dbfe68e0e5a6fb47dae3499308",
+    "svgSha256": "f549d1f998c2c84793783b9b6ce7aabe05d9a91edebecb764403c67dfbb4cc52"
+  },
+  "checks": {
+    "darkThemeLegible": true,
+    "noOverlap": true,
+    "labelsReadable": true,
+    "trustBoundariesClear": true,
+    "mobilePreviewAcceptable": true,
+    "textFallbackEquivalent": true,
+    "accessibleMetadataPresent": true
+  },
+  "reviewedBy": "repository-maintainer",
+  "reviewedAt": "2026-08-26"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cassiomc1/forgeloop",
-  "version": "1.3.0",
+  "version": "1.6.0",
   "description": "Portable, verifiable engineering protocol for AI coding environments and developer workflows",
   "repository": {
     "type": "git",
@@ -45,8 +45,8 @@
     ".github/copilot-instructions.md",
     "README.md",
     "DOCS_INDEX.md",
-    "docs/forgeloop-flow.mmd",
-    "docs/assets/forgeloop-flow.svg",
+    "docs/diagrams",
+    "docs/assets/diagrams",
     "docs/GETTING_STARTED.md",
     "docs/CROSS_HARNESS_CONTINUITY.md",
     "docs/CLI_REFERENCE.md",
@@ -54,15 +54,22 @@
     "docs/TROUBLESHOOTING.md",
     "docs/RECIPES.md",
     "docs/DOCUMENTATION_GUIDE.md",
-    "scripts/CI_VALIDATORS.md"
+    "docs/RELEASE_CHECKLIST_1_4.md",
+    "scripts/CI_VALIDATORS.md",
+    "docs/MCP.md",
+    "docs/UNIVERSAL_INTEGRATION.md",
+    "docs/DIAGNOSTIC_MODEL.md",
+    "docs/EXECUTION_TRACE.md",
+    "docs/RELEASE_CHECKLIST_1_5_MCP.md"
   ],
   "scripts": {
     "test": "node scripts/run-tests.js",
     "pack:check": "node --test tests/package.test.js",
     "pack:smoke": "node scripts/package_smoke.mjs",
     "release:identity": "node scripts/verify_release_identity.mjs",
-    "docs:flow": "node scripts/generate-readme-flow.mjs",
-    "docs:diagram:check": "node scripts/check-generated-diagram.mjs",
+    "docs:diagrams": "node scripts/generate-documentation-diagrams.mjs",
+    "docs:diagrams:check": "node scripts/check-documentation-diagrams.mjs",
+    "docs:diagram:inventory": "node scripts/documentation-diagram-inventory.mjs --json",
     "docs:generate": "node scripts/generate_documentation_reference.mjs --write",
     "docs:generated:check": "node scripts/generate_documentation_reference.mjs --check",
     "docs:conformance": "node scripts/validate_documentation_conformance.mjs",
@@ -71,11 +78,17 @@
     "docs:check": "node scripts/run-docs-check.js",
     "lint": "eslint .",
     "coverage": "c8 --all --include=src/**/*.js --reporter=text --reporter=lcov --check-coverage --lines=80 --functions=75 --branches=70 --statements=80 node scripts/run-tests.js",
-    "dependency:policy": "node scripts/check-dependency-policy.mjs"
+    "dependency:policy": "node scripts/check-dependency-policy.mjs",
+    "mcp:test": "node --test integrations/mcp/tests/*.test.js",
+    "mcp:setup": "node scripts/mcp-setup.mjs",
+    "mcp:pack:check": "node scripts/mcp-package-smoke.mjs"
   },
   "devDependencies": {
-    "@mermaid-js/mermaid-cli": "^11.16.0",
     "c8": "^12.0.0",
     "eslint": "^9.39.5"
+  },
+  "exports": {
+    ".": "./src/cli.js",
+    "./integration": "./src/integration.js"
   }
 }

package/schemas/action.schema.json

@@ -0,0 +1,100 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/action.schema.json",
+  "title": "ForgeLoop durable action artifact",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "taskId",
+    "actionId",
+    "actionFingerprint",
+    "effectClass",
+    "capability",
+    "operation",
+    "target",
+    "idempotencyKey",
+    "requiredForCompletion",
+    "requirement",
+    "provenance",
+    "state",
+    "revision",
+    "createdAt",
+    "updatedAt"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "taskId": { "type": "string", "minLength": 1, "maxLength": 256 },
+    "actionId": { "type": "string", "pattern": "^action-[A-Za-z0-9_-]+$" },
+    "actionFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "effectClass": {
+      "enum": [
+        "READ_ONLY",
+        "REVERSIBLE_WRITE",
+        "IRREVERSIBLE_WRITE",
+        "EXTERNAL_PUBLICATION",
+        "DESTRUCTIVE"
+      ]
+    },
+    "capability": {
+      "enum": [
+        "filesystem.read",
+        "filesystem.write",
+        "process.execute",
+        "dependency.install",
+        "network.read",
+        "network.write",
+        "repository.commit",
+        "repository.push",
+        "repository.pull_request",
+        "external.publish",
+        "external.delete",
+        "deployment.execute"
+      ]
+    },
+    "operation": { "type": "string", "minLength": 1, "maxLength": 512 },
+    "target": { "type": "string", "minLength": 1, "maxLength": 512 },
+    "idempotencyKey": { "oneOf": [{ "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "null" }] },
+    "requiredForCompletion": { "type": "boolean" },
+    "requirement": { "oneOf": [{ "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" }] },
+    "provenance": {
+      "enum": [
+        "FORGELOOP_EXECUTED",
+        "HOST_ATTESTED",
+        "CALLER_REPORTED",
+        "HOST_REPORTED",
+        "EXTERNAL_OBSERVED"
+      ]
+    },
+    "state": {
+      "enum": [
+        "PROPOSED",
+        "AUTHORIZED",
+        "STARTED",
+        "COMMITTED",
+        "VERIFIED",
+        "FAILED",
+        "COMMIT_UNKNOWN",
+        "CANCELLED"
+      ]
+    },
+    "revision": { "type": "integer", "minimum": 0 },
+    "createdAt": { "type": "string", "minLength": 1 },
+    "updatedAt": { "type": "string", "minLength": 1 },
+    "lastEvidenceRef": { "oneOf": [{ "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" }] },
+    "lastReconciliationAt": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] },
+    "commitResultCode": {
+      "oneOf": [
+        {
+          "enum": [
+            "IDEMPOTENCY_PROTECTED",
+            "RECONCILED_COMMITTED",
+            "RECONCILED_NOT_COMMITTED",
+            "AMBIGUOUS"
+          ]
+        },
+        { "type": "null" }
+      ]
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/approval.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/approval.schema.json",
+  "title": "ForgeLoop durable action approval artifact",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "taskId",
+    "approvalId",
+    "actionId",
+    "actionFingerprint",
+    "contractFingerprint",
+    "taskRevision",
+    "capability",
+    "status",
+    "requestedAt"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "taskId": { "type": "string", "minLength": 1, "maxLength": 256 },
+    "approvalId": { "type": "string", "pattern": "^approval-[A-Za-z0-9_-]+$" },
+    "actionId": { "type": "string", "pattern": "^action-[A-Za-z0-9_-]+$" },
+    "actionFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "contractFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "taskRevision": { "type": "integer", "minimum": 0 },
+    "capability": {
+      "enum": [
+        "filesystem.read",
+        "filesystem.write",
+        "process.execute",
+        "dependency.install",
+        "network.read",
+        "network.write",
+        "repository.commit",
+        "repository.push",
+        "repository.pull_request",
+        "external.publish",
+        "external.delete",
+        "deployment.execute"
+      ]
+    },
+    "status": { "enum": ["PENDING", "APPROVED", "REJECTED"] },
+    "requestedAt": { "type": "string", "minLength": 1 },
+    "reason": { "oneOf": [{ "type": "string", "maxLength": 512 }, { "type": "null" }] },
+    "decision": { "enum": ["APPROVED", "REJECTED"] },
+    "resolvedAt": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] },
+    "authorityKind": { "enum": ["CALLER_ACKNOWLEDGED", "HOST_ATTESTED"] },
+    "hostGrantRef": { "oneOf": [{ "type": "string", "maxLength": 256 }, { "type": "null" }] }
+  },
+  "additionalProperties": false
+}

package/schemas/capability-policy.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/capability-policy.schema.json",
+  "title": "ForgeLoop project capability policy",
+  "type": "object",
+  "required": ["schemaVersion", "defaultDecision", "rules"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "defaultDecision": { "enum": ["ALLOW", "DENY"] },
+    "rules": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["capability", "decision"],
+        "properties": {
+          "capability": {
+            "enum": [
+              "filesystem.read",
+              "filesystem.write",
+              "process.execute",
+              "dependency.install",
+              "network.read",
+              "network.write",
+              "repository.commit",
+              "repository.push",
+              "repository.pull_request",
+              "external.publish",
+              "external.delete",
+              "deployment.execute"
+            ]
+          },
+          "decision": {
+            "enum": ["ALLOW", "DENY", "REQUIRE_AUTHORITY", "REQUIRE_APPROVAL"]
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/diagnostic-case.schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/diagnostic-case.schema.json",
+  "title": "ForgeLoop structured diagnostic case",
+  "type": "object",
+  "required": ["schemaVersion", "verificationCycle", "diagnosticRevision", "failureClass", "observations", "contributors", "hypotheses", "nextSafeAction", "diagnosticFingerprint"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "verificationCycle": { "type": "integer", "minimum": 1 },
+    "diagnosticRevision": { "type": "integer", "minimum": 1 },
+    "failureClass": { "type": "string", "minLength": 1 },
+    "observations": {
+      "type": "array",
+      "maxItems": 64,
+      "items": {
+        "type": "object",
+        "required": ["id", "kind", "statement"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" },
+          "kind": { "enum": ["CHECK_RESULT", "EXECUTION_RESULT", "REPOSITORY_STATE", "ENVIRONMENT_STATE", "DEPENDENCY_STATE", "MANUAL_OBSERVATION", "PROTOCOL_STATE"] },
+          "evidenceRef": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" },
+          "statement": { "type": "string", "minLength": 1, "maxLength": 4096 },
+          "verificationCycle": { "type": "integer", "minimum": 1 },
+          "provenance": { "enum": ["FORGELOOP_EXECUTED", "ACTOR_REPORTED", "MANUAL_OBSERVATION"] }
+        },
+        "additionalProperties": false
+      }
+    },
+    "contributors": {
+      "type": "array",
+      "maxItems": 64,
+      "items": {
+        "type": "object",
+        "required": ["id", "type", "statement"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" },
+          "type": { "enum": ["CODE", "CONFIGURATION", "ARCHITECTURE", "DEPENDENCY", "ENVIRONMENT", "DATA", "TIMING", "CONCURRENCY", "STATE", "AUTHORITY", "CAPABILITY", "ASSUMPTION", "INTERFACE", "PROCESS", "EXTERNAL_SERVICE", "UNKNOWN"] },
+          "statement": { "type": "string", "minLength": 1, "maxLength": 4096 },
+          "basis": { "type": "array", "maxItems": 32, "items": { "type": "string", "minLength": 1 } },
+          "status": { "enum": ["OBSERVED", "INFERRED", "SUSPECTED", "ELIMINATED", "CONFIRMED_RELEVANT"] }
+        },
+        "additionalProperties": false
+      }
+    },
+    "hypotheses": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 32,
+      "items": {
+        "type": "object",
+        "required": ["id", "statement", "settledBy"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" },
+          "statement": { "type": "string", "minLength": 1, "maxLength": 4096 },
+          "contributorRefs": { "type": "array", "maxItems": 32, "items": { "type": "string", "minLength": 1 } },
+          "evidenceRefs": { "type": "array", "maxItems": 32, "items": { "type": "string", "minLength": 1 } },
+          "settledBy": {
+            "type": "object",
+            "required": ["type"],
+            "properties": {
+              "type": { "enum": ["PREDICATE", "CHECK_STATUS", "FAILURE_SIGNATURE_CHANGE", "REQUIREMENT_STATUS", "MANUAL_OBSERVATION"] },
+              "statement": { "type": "string", "minLength": 1, "maxLength": 4096 },
+              "checkId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" },
+              "expectedStatus": { "type": "string", "minLength": 1 }
+            },
+            "additionalProperties": false
+          },
+          "status": { "const": "OPEN" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "nextSafeAction": {
+      "type": "object",
+      "required": ["statement"],
+      "properties": {
+        "statement": { "type": "string", "minLength": 1, "maxLength": 4096 }
+      },
+      "additionalProperties": false
+    },
+    "diagnosticFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "previousDiagnosticFingerprint": { "oneOf": [{ "type": "null" }, { "type": "string", "pattern": "^[a-f0-9]{64}$" }] }
+  },
+  "additionalProperties": false
+}

package/schemas/execution-receipt.schema.json

@@ -20,6 +20,22 @@
     "selectedGuides": { "type": "array", "items": { "type": "string" } },
     "changedPaths": { "type": "array", "items": { "type": "string" } },
     "checks": { "type": "array", "items": { "type": "object" } },
+    "actions": {
+      "type": "object",
+      "required": ["count", "required", "verified", "failed", "ambiguous", "pending", "actionRefs"],
+      "properties": {
+        "count": { "type": "integer", "minimum": 0 },
+        "required": { "type": "integer", "minimum": 0 },
+        "verified": { "type": "integer", "minimum": 0 },
+        "trustedSatisfied": { "type": "integer", "minimum": 0 },
+        "unresolvedRequired": { "type": "integer", "minimum": 0 },
+        "failed": { "type": "integer", "minimum": 0 },
+        "ambiguous": { "type": "integer", "minimum": 0 },
+        "pending": { "type": "integer", "minimum": 0 },
+        "actionRefs": { "type": "array", "items": { "type": "string", "pattern": "^action-[A-Za-z0-9_-]+$" } }
+      },
+      "additionalProperties": false
+    },
     "evidence": {
       "type": "array",
       "items": {

package/schemas/hypothesis-disposition.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/hypothesis-disposition.schema.json",
+  "title": "ForgeLoop hypothesis disposition record",
+  "type": "object",
+  "required": ["schemaVersion", "verificationCycle", "hypothesisRef", "status", "evidenceRefs", "reason"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "verificationCycle": { "type": "integer", "minimum": 1 },
+    "hypothesisRef": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" },
+    "status": { "enum": ["SUPPORTED", "WEAKENED", "FALSIFIED", "SUPERSEDED", "UNRESOLVED"] },
+    "evidenceRefs": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "type": "string", "minLength": 1 } },
+    "reason": { "type": "string", "minLength": 1, "maxLength": 4096 }
+  },
+  "additionalProperties": false
+}