@open-agent-toolkit/cli 0.2.73 → 0.2.74

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

@@ -1,124 +1,99 @@
-# Fact-base processing contract
+# Fact-base 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.
+`bundle.mjs` writes the authoring inputs under `<run-root>/source/`. The
+machine contract is `fact-base.json`; `fact-base.md` is its readable rendering;
+`ledger.json` is the bounded verification index.
 
-## Result
+## Fact-base record
 
-The function resolves to:
+`source/fact-base.json` is an `explainer-kit.fact-base/v1` object with exactly
+these eight required keys:
 
-```js
-{
-  factBase, // valid explainer-kit.fact-base/v1
-  checks,   // consistency/freshness diagnostics
-  critic,   // critic invocation and provenance metadata
-}
-```
+| Key                | Flow value or meaning                                                        |
+| ------------------ | ---------------------------------------------------------------------------- |
+| `schemaVersion`    | `explainer-kit.fact-base/v1`                                                 |
+| `generatedAt`      | ISO date-time for this bundle                                                |
+| `mode`             | `supplied`; the agent-authored flow assembles the fact base before authoring |
+| `freshnessPolicy`  | `live-wins`                                                                  |
+| `sources`          | Hash-bound allowlisted input files                                           |
+| `claims`           | Confirmed source-backed claims                                               |
+| `unresolvedClaims` | Inputs or claims that cannot be stated as confirmed                          |
+| `overrides`        | Explicit claim decisions; normally empty                                     |
 
-All claims are cited. Claims that cannot be reconciled remain in
-`unresolvedClaims` with one of the contract's closed reason values.
+The record is canonical JSON and must pass
+`validateContract('fact-base', value)` before authoring starts. It carries no
+claims index or browser evidence.
 
-## Supplied mode
+## Sources and citations
 
-Use:
+Each selected input is represented by a source:
 
-```js
-await processFactBase({
-  mode: 'supplied',
-  freshnessPolicy: 'live-wins',
-  factBase,
-});
+```json
+{
+  "id": "source-1",
+  "kind": "file",
+  "locator": "plan.md",
+  "hash": "sha256:…"
+}
 ```
 
-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' }`.
+The flow may add the `role: "bundle-input"` marker used when the manifest
+copies input hashes. Every claim citation has exactly the source identity and
+the source-relative location:
 
-## Federated mode
+```json
+{ "sourceId": "source-1", "locator": "plan.md:40-44" }
+```
 
-Each source document contains a schema-compatible source and extracted claims:
+Do not add `path`, `lineRange`, repository, or URL backlink fields to
+agent-authored-flow citations. Every citation must name a declared source.
 
-```js
-{
-  mode: 'federated',
-  freshnessPolicy: 'live-wins',
-  sourceDocuments: [{
-    source: {
-      id,
-      kind,
-      locator,
-      revision,
-      hash,
-      observedAt,
-      authoritativeFor,
-    },
-    claims: [{ id, text, locator, sections }],
-  }],
-  overrides: [{ claimId, decision, confirmedAt }],
-}
-```
+## Claims
 
-Optional `sections` entries are recipe `requiredNarrative` IDs. Tagged claims
-are routed only to those sections; untagged claims remain shared context for
-every required section. Federated reconciliation preserves shared scope when
-any agreeing selected observation is untagged.
-
-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'],
-      },
-    ],
-  };
-}
-```
+Confirmed claims have `{ id, text, status: "confirmed", citations }`.
+Unresolved claims retain their text and citations with one schema-defined
+reason: `contradictory`, `stale`, `missing-evidence`, or
+`needs-confirmation`. Inputs that cannot be parsed are represented here rather
+than silently omitted.
 
-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.
+The author may summarize confirmed claims but must not invent a connective
+fact. An unresolved claim remains visibly uncertain in the artifact.
 
-## Critic provenance
+## Anchor ledger
 
-Every federated invocation adds one source:
+`source/ledger.json` is derived from the same claims and has four keys:
 
-```js
+```json
 {
-  id: `critic:${criticId}`,
-  kind: 'other',
-  locator: `critic-callback:${criticId}`,
-  hash: canonicalHash(criticResult),
-  observedAt: executedAt,
+  "terminology": [{ "term": "agent-authored-recap" }],
+  "numbers": [{ "subject": "p02", "value": "4" }],
+  "statuses": [{ "subject": "p02", "value": "in_progress" }],
+  "claims": [
+    {
+      "subject": "p02",
+      "value": "4",
+      "kind": "number",
+      "claimId": "claim-1"
+    }
+  ]
 }
 ```
 
-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.
+`terminology`, `numbers`, and `statuses` are the bounded anchor groups used by
+the ledger-to-page cohesion check. Each group contains at most 12 entries; an
+individual group may be empty, but all three may not be empty together.
+
+`claims` is the page-to-ledger index for numeric, date, and closed-vocabulary
+status tokens. Its subject comes from the source table row, sentence
+identifier, or heading. The authored page keeps each token with that subject
+so `verify.mjs` can match the exact `(subject, value, kind)` tuple.
+
+## Consumers
 
-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.
+- The host agent reads `fact-base.json`, `fact-base.md`, and `ledger.json`
+  while authoring.
+- `verify.mjs` checks ledger anchors against the page and machine-readable page
+  claims against `ledger.claims`.
+- `record.mjs` carries the fact-base hash and source input hashes into
+  `manifest.json`.
+- A human uses source locators and claim IDs to diagnose verification findings.

package/assets/skills/explainer-kit/references/recap-authoring.md

@@ -0,0 +1,99 @@
+# Agent-authored recap mechanics
+
+Use this reference with the recipe's bundled author brief. The brief defines
+the audience, voice, and narrative intent; this reference defines how to turn a
+prepared run into one verifiable HTML artifact.
+
+## Read the run inputs
+
+Read these files before authoring:
+
+- `source/fact-base.json` for confirmed and unresolved claims and their source
+  locators;
+- `source/fact-base.md` for a readable rendering of the same fact base;
+- `source/ledger.json` for the bounded terminology, number, date, and status
+  anchors verification expects;
+- `theme.resolved.json` for the resolved palette and typography; and
+- the selected recipe's `floor[0]`, including `template`,
+  `requiredNarrative`, and `briefRef`.
+
+Read the bundled file named by `briefRef` verbatim. Do not replace its
+audience or editorial instructions with generic recap prose.
+
+## Preserve recipe anchors
+
+Write each `requiredNarrative` value as a non-empty `<section id="…">`:
+
+| Recipe              | Required section IDs                                                                                                          |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `project-recap`     | `original-request`, `key-agent-decisions`, `as-built-architecture`, `implementation-record`, `validation-evidence`, `outcome` |
+| `program-recap`     | `program-overview`, `wave-map`, `per-wave-outcomes`, `convention-evolution`, `aggregate-numbers`, `follow-up-ledger`          |
+| `project-explainer` | `planned-architecture`, `decisions`, `risks`, `phases`, `validation-approach`                                                 |
+| `engineer-tour`     | `orientation`, `architecture`, `execution-flow`, `key-code`, `validation`                                                     |
+
+Navigation should link to these IDs with descriptive labels. Keep every
+section useful without JavaScript.
+
+## Build from the recipe shell
+
+Copy `templates/<floor[0].template>.html` to `site/index.html`, then replace its
+tokens:
+
+- `THEME_CSS`: CSS derived from `theme.resolved.json`;
+- `TITLE`, `DESCRIPTION`, and `EYEBROW`: concise framing grounded in the fact
+  base;
+- `NAVIGATION`: links to every required section;
+- `CONTENT`: the authored sections and their source-grounded visuals; and
+- `FOOTER`: provenance or reading guidance that does not dump source text.
+
+The `engineer-tour` shell also has a `DIAGRAM` token. Fill it only with
+source-grounded inline SVG markup. Preserve every bundled script byte-for-byte;
+do not add scripts or event-handler attributes.
+
+## Keep the artifact self-contained
+
+Produce one `site/index.html` with inline CSS and inline, shell-approved
+scripts only. Do not load fonts, images, styles, scripts, or other resources
+from external URLs. Do not paste source documents or the fact base into the
+page. Summarize and structure the evidence for the reader.
+
+## Trace every machine-checkable claim
+
+Spell terms, identifiers, numbers, dates, and closed-vocabulary statuses
+exactly as the fact base spells them. Keep each number, date, or status in the
+same sentence, list item, or table row as its subject so verification can match
+the `(subject, value)` pair in `source/ledger.json`.
+For cards, definition lists, and other non-paragraph elements, verification
+uses the nearest bold or definition label or preceding heading as the subject,
+with the enclosing section ID as fallback.
+
+Treat `unresolvedClaims` as unresolved. Label uncertainty as
+`needs confirmation`; do not turn it into a confirmed narrative bridge.
+Citations remain in the fact base and should inform the prose without becoming
+a source dump.
+
+## Review visual composition
+
+Follow `references/visual-authoring.md` for hierarchy, responsive navigation,
+tables, diagrams, and the final composition check. The page itself must not
+overflow horizontally. Put intrinsically wide content inside a bounded,
+scrollable container.
+
+## Submit host-rung evidence
+
+When the host has browser capability:
+
+1. Open `file://<run-root>/site/index.html`.
+2. Capture the page at widths 320, 768, and 1440 into
+   `<run-root>/qa/320.png`, `768.png`, and `1440.png`.
+3. Inspect all three screenshots. Confirm no horizontal page overflow, every
+   required section is visible, headings remain readable at 320 pixels, and no
+   text overlaps.
+4. Compute the SHA-256 of the exact `site/index.html` bytes captured.
+5. Run `verify.mjs` with `--rung host`, `--screenshots <run-root>/qa`,
+   `--artifact-sha256 <sha256:hex>`, `--visual-verdict pass|findings`, and
+   concise `--visual-notes`.
+
+A screenshot capture without inspection is not verification. If the artifact
+hash or any PNG binding is invalid, verification records the browser rung as
+`none`.

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

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "explainer-kit.manifest/v1",
-  "title": "ArtifactManifestV1",
+  "$id": "explainer-kit.manifest/v2",
+  "title": "ArtifactManifestV2",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -10,16 +10,16 @@
     "slug",
     "recipe",
     "createdAt",
+    "mode",
     "source",
     "theme",
     "artifacts",
     "immutableHashes",
     "outcome",
-    "buildRecord",
     "warnings"
   ],
   "properties": {
-    "schemaVersion": { "const": "explainer-kit.manifest/v1" },
+    "schemaVersion": { "const": "explainer-kit.manifest/v2" },
     "runId": { "type": "string", "minLength": 1 },
     "slug": {
       "type": "string",
@@ -35,6 +35,7 @@
       }
     },
     "createdAt": { "type": "string", "format": "date-time" },
+    "mode": { "enum": ["unattended", "interactive"] },
     "source": {
       "type": "object",
       "additionalProperties": false,
@@ -42,63 +43,27 @@
       "properties": {
         "factBasePath": { "$ref": "#/$defs/safeRelativePath" },
         "factBaseHash": { "$ref": "#/$defs/hash" },
-        "sourceRevision": { "type": "string", "minLength": 1 },
-        "inputHashes": { "$ref": "#/$defs/hashMap" },
-        "authorResultPaths": {
-          "type": "array",
-          "items": { "$ref": "#/$defs/safeRelativePath" },
-          "minItems": 1,
-          "uniqueItems": true
-        },
-        "backlinks": {
-          "type": "array",
-          "items": { "$ref": "#/$defs/sourceBacklink" },
-          "uniqueItems": true
-        }
+        "inputHashes": { "$ref": "#/$defs/hashMap" }
       }
     },
     "theme": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["path", "hash", "derived"],
+      "required": ["path", "hash"],
       "properties": {
         "path": { "const": "theme.resolved.json" },
-        "hash": { "$ref": "#/$defs/hash" },
-        "derived": { "type": "boolean" }
+        "hash": { "$ref": "#/$defs/hash" }
       }
     },
     "artifacts": {
       "type": "array",
       "items": { "$ref": "#/$defs/artifactEntry" },
+      "minItems": 1,
       "uniqueItems": true
     },
     "immutableHashes": { "$ref": "#/$defs/hashMap" },
     "outcome": {
-      "enum": [
-        "built-durable",
-        "built-not-durable",
-        "built-needs-review",
-        "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" }
-      }
+      "enum": ["built", "built-needs-review", "failed", "incomplete"]
     },
     "warnings": {
       "type": "array",
@@ -113,110 +78,23 @@
     "safeRelativePath": {
       "type": "string",
       "minLength": 1,
-      "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+$"
+      "pattern": "^(?!/)(?!.*//)(?!.*(?:^|/)(?:\\.|\\.\\.)(?:/|$))(?!.*\\\\).+$"
     },
     "hashMap": {
       "type": "object",
-      "description": "Raw-byte SHA-256 coverage for the complete immutable package, including required browser, cohesion, visual-review attempt, and revision evidence.",
       "propertyNames": { "$ref": "#/$defs/safeRelativePath" },
       "additionalProperties": { "$ref": "#/$defs/hash" }
     },
-    "sourceBacklink": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["sourceId", "url"],
-      "properties": {
-        "sourceId": { "type": "string", "minLength": 1 },
-        "url": {
-          "type": "string",
-          "pattern": "^https://github\\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+/blob/[a-f0-9]{40}/[^\\s?#]+#L[1-9][0-9]*(?:-L[1-9][0-9]*)?$"
-        }
-      }
-    },
-    "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"],
+      "required": ["id", "type", "contentPath", "hash", "status"],
       "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" }
+        "status": { "enum": ["built", "failed"] }
       }
     }
   }