@open-agent-toolkit/cli 0.2.5 → 0.2.7

package/assets/skills/explainer-kit/references/extension-contract.md

@@ -0,0 +1,71 @@
+# Wrapper extension contract
+
+V1 freezes one destination-neutral extension seam:
+
+1. **Pre-resolution:** the caller resolves presets, private source systems,
+   accounts, and destination topology without exposing them as public config.
+2. **`ExplainerRunRequestV1`:** the caller translates only the inputs required
+   by `explainer-kit.run-request/v1`.
+3. **Core run:** the caller invokes `runExplainer(request, options)` once. The
+   core owns validation, fact-base processing, content, theme, render, QA, and
+   run records.
+4. **Manifest consumption:** the caller accepts only
+   `explainer-kit.manifest/v1`, verifies its run, recipe, and slug identity, and
+   reads built artifact paths from the manifest.
+5. **Post-run linking:** the caller may create companion notes, synchronize
+   external documents, or maintain private links from manifest and optional
+   publish-receipt data.
+
+Private wrappers may retain presets, vault conventions, Google Docs behavior,
+and personal destinations around this seam. Those values are wrapper-owned;
+they are not OAT config keys and must not be discovered by the core.
+
+## Frozen v1 boundary
+
+The versioned request, artifact package, manifest, build record, durability
+request, publish request, and publish receipt are the public boundary. V1 has
+no plugin registry and no mid-pipeline callback API for private destinations.
+Provider-neutral callbacks already documented by the core remain explicit run
+options; they do not transfer stage ownership to a wrapper.
+
+V1 readers reject unsupported contract majors and identity mismatches rather
+than guessing. Wrappers should preserve unknown future versions for diagnosis,
+stop before post-processing, and migrate deliberately.
+
+The compatibility smoke fixture at
+`tools/smoke/explainer-kit/wrapper-compatibility.test.mjs` proves this sequence
+with the actual core. It uses sanitized private-wrapper inputs and is not a
+substitute for the operator-owned release-candidate gate.
+
+Release-candidate execution requires the retained tarball directory explicitly:
+
+```bash
+# Pre: resolve private inputs and write the external run request.
+node tools/release/run-explainer-rc.mjs \
+  --rc-manifest /path/to/acceptance/rc.json \
+  --artifacts-dir /path/to/retained/explainer-kit-rc \
+  --entry scripts/run.mjs \
+  --record /path/to/acceptance/private-wrapper-execution.json \
+  -- --request /path/to/private/request.json
+```
+
+The packaged CLI stdout contract is exactly one complete JSON result document.
+The document may be pretty-printed across lines; progress text and
+line-delimited JSON are not part of this machine framing. The RC runner parses
+the complete document, then binds the request, child-reported manifest, and core
+run ID. It binds a receipt only when the packaged child itself reports that
+output. The sanitized record does not store paths, argument values, credentials,
+or private content.
+
+After the core command returns, the wrapper performs its post-run publication
+and linking work. It retains the immutable core manifest as
+`private-wrapper-manifest.json`, the complete `PublishReceiptV1` as
+`private-wrapper-publish-receipt.json`, and its sanitized wrapper result as
+`private-wrapper-result.json`. The wrapper result repeats canonical hashes for
+the request, manifest, and post-run receipt.
+
+The wrapper acceptance stage reads those post-run files separately. It
+validates the closed receipt contract, every manifest artifact/hash and
+destination, the run-unique sentinel, the manifest hash, and the core run ID
+against `private-wrapper-execution.json`. Repeating a matching hash cannot make
+a foreign or stale receipt attributable to the packaged run.

package/assets/skills/explainer-kit/references/fact-base-contract.md

@@ -0,0 +1,119 @@
+# Fact-base processing contract
+
+`processFactBase(binding, options)` produces one
+`explainer-kit.fact-base/v1` record plus processing diagnostics. It has no
+provider-specific dispatch logic and reads no ambient configuration.
+
+## Result
+
+The function resolves to:
+
+```js
+{
+  factBase, // valid explainer-kit.fact-base/v1
+  checks,   // consistency/freshness diagnostics
+  critic,   // critic invocation and provenance metadata
+}
+```
+
+All claims are cited. Claims that cannot be reconciled remain in
+`unresolvedClaims` with one of the contract's closed reason values.
+
+## Supplied mode
+
+Use:
+
+```js
+await processFactBase({
+  mode: 'supplied',
+  freshnessPolicy: 'live-wins',
+  factBase,
+});
+```
+
+The processor validates the supplied v1 record, verifies unique source and
+claim IDs, verifies that every citation names a declared source, verifies that
+every override names a confirmed claim, and compares `generatedAt` plus each
+available source `observedAt` with the freshness window. Staleness produces a
+warning; structural or citation inconsistency rejects the input.
+
+Supplied mode never invokes the adversarial critic. Its `critic` result is
+`{ invoked: false, reason: 'supplied-mode-lightweight-check-only' }`.
+
+## Federated mode
+
+Each source document contains a schema-compatible source and extracted claims:
+
+```js
+{
+  mode: 'federated',
+  freshnessPolicy: 'live-wins',
+  sourceDocuments: [{
+    source: {
+      id,
+      kind,
+      locator,
+      revision,
+      hash,
+      observedAt,
+      authoritativeFor,
+    },
+    claims: [{ id, text, locator }],
+  }],
+  overrides: [{ claimId, decision, confirmedAt }],
+}
+```
+
+For conflicting text under one claim ID, an `authoritativeFor` declaration
+wins first. Otherwise the newest `observedAt` wins. A tie remains
+`contradictory`. Operator overrides take final precedence, produce an
+`overridden` claim, remain explicit in `overrides`, and suppress critic
+findings for that claim.
+
+Federated processing requires `options.critic`, an asynchronous,
+provider-neutral callback. The callback receives only data:
+
+```js
+async function critic({ freshnessPolicy, sources, claims, overrides }) {
+  return {
+    criticId: 'stable-callback-id',
+    executedAt: new Date().toISOString(),
+    findings: [
+      {
+        claimId: 'status',
+        classification: 'contradictory',
+        text: 'The status sources disagree.',
+        sourceIds: ['snapshot', 'live'],
+      },
+    ],
+  };
+}
+```
+
+The seam deliberately contains no provider, model, command, or dispatch
+field. The caller owns critic execution; the core only invokes the callback
+and integrates its returned data.
+
+## Critic provenance
+
+Every federated invocation adds one source:
+
+```js
+{
+  id: `critic:${criticId}`,
+  kind: 'other',
+  locator: `critic-callback:${criticId}`,
+  hash: canonicalHash(criticResult),
+  observedAt: executedAt,
+}
+```
+
+The result's `critic` metadata repeats the stable critic ID, execution time,
+source ID, and canonical result hash. Integrated findings cite both this
+synthetic critic source and every declared source named by the finding. This
+makes the critic's contribution auditable without exposing or depending on a
+provider-specific implementation.
+
+Critic classifications map directly to unresolved-claim reasons. A finding
+removes a previously confirmed claim and creates an unresolved claim, or
+updates an already unresolved claim while preserving its existing citations.

package/assets/skills/explainer-kit/schemas/build-record.schema.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "explainer-kit.build-record/v1",
+  "title": "BuildRecordV1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "runId",
+    "renderStrategy",
+    "startedAt",
+    "stages",
+    "outcome"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "explainer-kit.build-record/v1" },
+    "runId": { "type": "string", "minLength": 1 },
+    "renderStrategy": { "enum": ["default-only", "user-switchable"] },
+    "startedAt": { "type": "string", "format": "date-time" },
+    "completedAt": { "type": "string", "format": "date-time" },
+    "stages": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/stage" },
+      "minItems": 1
+    },
+    "outcome": {
+      "enum": ["built-durable", "built-not-durable", "failed", "incomplete"]
+    }
+  },
+  "$defs": {
+    "safeRelativePath": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+$"
+    },
+    "error": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "message", "recovery"],
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 },
+        "recovery": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "minItems": 1
+        }
+      }
+    },
+    "stage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "status", "outputPaths", "warnings"],
+      "properties": {
+        "id": {
+          "enum": [
+            "validate",
+            "fact-base",
+            "content",
+            "theme",
+            "render",
+            "qa",
+            "durability",
+            "publish"
+          ]
+        },
+        "status": {
+          "enum": [
+            "pending",
+            "running",
+            "passed",
+            "warned",
+            "failed",
+            "skipped"
+          ]
+        },
+        "startedAt": { "type": "string", "format": "date-time" },
+        "completedAt": { "type": "string", "format": "date-time" },
+        "outputPaths": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/safeRelativePath" },
+          "uniqueItems": true
+        },
+        "warnings": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "error": { "$ref": "#/$defs/error" }
+      }
+    }
+  }
+}

package/assets/skills/explainer-kit/schemas/durability-evidence.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "explainer-kit.durability-evidence/v1",
+  "title": "DurabilityEvidenceRequestV1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "manifestPath", "evidence"],
+  "properties": {
+    "schemaVersion": {
+      "const": "explainer-kit.durability-evidence/v1"
+    },
+    "manifestPath": { "type": "string", "minLength": 1 },
+    "evidence": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "repoRoot", "commit", "paths"],
+          "properties": {
+            "kind": { "const": "commit" },
+            "repoRoot": { "type": "string", "minLength": 1 },
+            "commit": {
+              "type": "string",
+              "pattern": "^[a-f0-9]{7,64}$"
+            },
+            "paths": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/safeRelativePath" },
+              "minItems": 1,
+              "uniqueItems": true
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "receiptPath"],
+          "properties": {
+            "kind": { "const": "publish" },
+            "receiptPath": { "type": "string", "minLength": 1 }
+          }
+        }
+      ]
+    }
+  },
+  "$defs": {
+    "safeRelativePath": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+$"
+    }
+  }
+}

package/assets/skills/explainer-kit/schemas/fact-base.schema.json

@@ -0,0 +1,129 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "explainer-kit.fact-base/v1",
+  "title": "FactBaseV1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "generatedAt",
+    "mode",
+    "freshnessPolicy",
+    "sources",
+    "claims",
+    "unresolvedClaims",
+    "overrides"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "explainer-kit.fact-base/v1" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "mode": { "enum": ["supplied", "federated"] },
+    "freshnessPolicy": { "const": "live-wins" },
+    "sources": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/source" },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "claims": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/claim" },
+      "uniqueItems": true
+    },
+    "unresolvedClaims": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/unresolvedClaim" },
+      "uniqueItems": true
+    },
+    "overrides": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/override" },
+      "uniqueItems": true
+    }
+  },
+  "$defs": {
+    "hash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "locator", "hash"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "kind": {
+          "enum": ["file", "directory", "git", "github", "session", "other"]
+        },
+        "locator": { "type": "string", "minLength": 1 },
+        "role": { "type": "string", "minLength": 1 },
+        "sourceSetId": { "type": "string", "minLength": 1 },
+        "revision": { "type": "string", "minLength": 1 },
+        "hash": { "$ref": "#/$defs/hash" },
+        "observedAt": { "type": "string", "format": "date-time" },
+        "authoritativeFor": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        }
+      }
+    },
+    "citation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sourceId", "locator"],
+      "properties": {
+        "sourceId": { "type": "string", "minLength": 1 },
+        "locator": { "type": "string", "minLength": 1 }
+      }
+    },
+    "claim": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "text", "status", "citations"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "text": { "type": "string", "minLength": 1 },
+        "status": { "enum": ["confirmed", "overridden"] },
+        "citations": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/citation" },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      }
+    },
+    "unresolvedClaim": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "text", "reason", "citations"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "text": { "type": "string", "minLength": 1 },
+        "reason": {
+          "enum": [
+            "contradictory",
+            "stale",
+            "missing-evidence",
+            "needs-confirmation"
+          ]
+        },
+        "citations": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/citation" },
+          "uniqueItems": true
+        }
+      }
+    },
+    "override": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["claimId", "decision", "confirmedAt"],
+      "properties": {
+        "claimId": { "type": "string", "minLength": 1 },
+        "decision": { "type": "string", "minLength": 1 },
+        "confirmedAt": { "type": "string", "format": "date-time" }
+      }
+    }
+  }
+}

package/assets/skills/explainer-kit/schemas/manifest.schema.json

@@ -0,0 +1,193 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "explainer-kit.manifest/v1",
+  "title": "ArtifactManifestV1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "runId",
+    "slug",
+    "recipe",
+    "createdAt",
+    "source",
+    "theme",
+    "artifacts",
+    "immutableHashes",
+    "outcome",
+    "buildRecord",
+    "warnings"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "explainer-kit.manifest/v1" },
+    "runId": { "type": "string", "minLength": 1 },
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "recipe": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "version"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["factBasePath", "factBaseHash", "inputHashes"],
+      "properties": {
+        "factBasePath": { "$ref": "#/$defs/safeRelativePath" },
+        "factBaseHash": { "$ref": "#/$defs/hash" },
+        "sourceRevision": { "type": "string", "minLength": 1 },
+        "inputHashes": { "$ref": "#/$defs/hashMap" }
+      }
+    },
+    "theme": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "hash", "derived"],
+      "properties": {
+        "path": { "const": "theme.resolved.json" },
+        "hash": { "$ref": "#/$defs/hash" },
+        "derived": { "type": "boolean" }
+      }
+    },
+    "artifacts": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/artifactEntry" },
+      "uniqueItems": true
+    },
+    "immutableHashes": { "$ref": "#/$defs/hashMap" },
+    "outcome": {
+      "enum": ["built-durable", "built-not-durable", "failed", "incomplete"]
+    },
+    "buildRecord": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "hash"],
+      "properties": {
+        "path": { "const": "build-record.json" },
+        "hash": { "$ref": "#/$defs/hash" }
+      }
+    },
+    "publishReceipt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "hash"],
+      "properties": {
+        "path": { "const": "publish-receipt.json" },
+        "hash": { "$ref": "#/$defs/hash" }
+      }
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    }
+  },
+  "$defs": {
+    "hash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "safeRelativePath": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+$"
+    },
+    "hashMap": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/safeRelativePath" },
+      "additionalProperties": { "$ref": "#/$defs/hash" }
+    },
+    "failure": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "message", "recovery"],
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 },
+        "recovery": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "minItems": 1
+        }
+      }
+    },
+    "durableEvidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "ref", "paths", "attestedAt"],
+      "properties": {
+        "kind": { "enum": ["commit", "publish"] },
+        "ref": { "type": "string", "minLength": 1 },
+        "paths": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/safeRelativePath" },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "attestedAt": { "type": "string", "format": "date-time" },
+        "supersedes": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["ref", "paths"],
+          "properties": {
+            "ref": { "type": "string", "minLength": 1 },
+            "paths": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/safeRelativePath" },
+              "minItems": 1,
+              "uniqueItems": true
+            }
+          }
+        }
+      }
+    },
+    "rebuild": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["argv", "cwd", "inputHashes"],
+      "properties": {
+        "argv": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1
+        },
+        "cwd": { "type": "string", "minLength": 1 },
+        "inputHashes": { "$ref": "#/$defs/hashMap" }
+      }
+    },
+    "artifactEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "type", "contentPath", "status", "rebuildable"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "type": { "enum": ["hub", "diagram", "explainer", "deck", "catalog"] },
+        "contentPath": { "$ref": "#/$defs/safeRelativePath" },
+        "renderedPath": {
+          "allOf": [
+            { "$ref": "#/$defs/safeRelativePath" },
+            { "pattern": "^site/" }
+          ],
+          "pattern": "^site/"
+        },
+        "mediaType": { "type": "string", "minLength": 1 },
+        "status": { "enum": ["built", "failed", "skipped"] },
+        "hash": { "$ref": "#/$defs/hash" },
+        "rebuildable": { "type": "boolean" },
+        "rebuild": { "$ref": "#/$defs/rebuild" },
+        "durableEvidence": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/durableEvidence" },
+          "uniqueItems": true
+        },
+        "failure": { "$ref": "#/$defs/failure" }
+      }
+    }
+  }
+}