@open-agent-toolkit/cli 0.2.6 → 0.2.8

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.6",
-  "docs-config": "0.2.6",
-  "docs-theme": "0.2.6",
-  "docs-transforms": "0.2.6"
+  "cli": "0.2.8",
+  "docs-config": "0.2.8",
+  "docs-theme": "0.2.8",
+  "docs-transforms": "0.2.8"
 }

package/assets/skills/explainer-kit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: explainer-kit
-version: 1.0.0
+version: 1.0.1
 description: Use when building destination-neutral visual explainer artifacts from explicit, versioned inputs.
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Agent, mcp__*
@@ -55,6 +55,8 @@ discovery, theme resolution, rendering, QA, and manifest/build-record
 persistence. It runs without OAT files or ambient configuration. Supplied fact
 bases receive only lightweight consistency/freshness checks. Federated inputs
 require a provider-neutral critic callback and invoke it exactly once.
+Optional claim `sections` tags route facts to matching recipe narrative
+sections; untagged claims remain shared context for every required section.
 
 Unattended calls use explicit, already-approved source artifacts, persist their
 review provenance in `source/content-approval.json`, and never prompt.

package/assets/skills/explainer-kit/references/contracts.md

@@ -36,7 +36,10 @@ contract.
   performs only the lightweight consistency and freshness check and never
   invokes the critic.
 - `factBase.mode: federated` names explicit source bindings. File locators
-  contain JSON with a `claims` array of `{ "id", "text", "locator"? }`.
+  contain JSON with a `claims` array of
+  `{ "id", "text", "locator"?, "sections"? }`. Optional `sections` values
+  are recipe `requiredNarrative` IDs; untagged claims remain shared across
+  every required section.
   Non-file bindings require a caller-supplied `sourceLoader(source)` callback.
   Every binding names its recipe `role` and `sourceSetId`. Multiple documents
   may share one source-set ID; recipe cardinality counts distinct sets, not

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

@@ -58,12 +58,17 @@ Each source document contains a schema-compatible source and extracted claims:
       observedAt,
       authoritativeFor,
     },
-    claims: [{ id, text, locator }],
+    claims: [{ id, text, locator, sections }],
   }],
   overrides: [{ claimId, decision, confirmedAt }],
 }
 ```
 
+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

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

@@ -46,6 +46,15 @@
       "type": "string",
       "pattern": "^sha256:[a-f0-9]{64}$"
     },
+    "sectionIds": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+      },
+      "minItems": 1,
+      "uniqueItems": true
+    },
     "source": {
       "type": "object",
       "additionalProperties": false,
@@ -85,6 +94,7 @@
         "id": { "type": "string", "minLength": 1 },
         "text": { "type": "string", "minLength": 1 },
         "status": { "enum": ["confirmed", "overridden"] },
+        "sections": { "$ref": "#/$defs/sectionIds" },
         "citations": {
           "type": "array",
           "items": { "$ref": "#/$defs/citation" },
@@ -108,6 +118,7 @@
             "needs-confirmation"
           ]
         },
+        "sections": { "$ref": "#/$defs/sectionIds" },
         "citations": {
           "type": "array",
           "items": { "$ref": "#/$defs/citation" },

package/assets/skills/explainer-kit/scripts/lib/durability.mjs

@@ -166,10 +166,10 @@ export async function verifyRebuildability(artifact, runRoot) {
       await writeFileAtomic(runRoot, artifact.renderedPath, original);
     }
     return { verified: true, reason: null };
-  } catch (error) {
+  } catch (caught) {
     return {
       verified: false,
-      reason: `Deterministic replay failed: ${errorMessage(error)}`,
+      reason: `Deterministic replay failed: ${errorMessage(caught)}`,
     };
   }
 }

package/assets/skills/explainer-kit/scripts/lib/fact-base.mjs

@@ -2,6 +2,7 @@ import { canonicalHash, validateContract } from './contracts.mjs';
 
 const FACT_BASE_VERSION = 'explainer-kit.fact-base/v1';
 const DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const SECTION_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const FINDING_REASONS = new Set([
   'contradictory',
   'stale',
@@ -107,6 +108,7 @@ async function processFederated(binding, { critic, now }) {
         text: override.decision,
         status: 'overridden',
         citations: citationsFor(entries),
+        ...sectionMetadata(entries),
       });
       continue;
     }
@@ -251,7 +253,8 @@ function collectObservations(documents, sourceById) {
         typeof claim.id !== 'string' ||
         claim.id.length === 0 ||
         typeof claim.text !== 'string' ||
-        claim.text.length === 0
+        claim.text.length === 0 ||
+        !validSections(claim.sections)
       ) {
         throw new Error(
           `Source ${document.source.id} contains an invalid claim.`,
@@ -263,6 +266,7 @@ function collectObservations(documents, sourceById) {
         text: claim.text,
         source: sourceById.get(document.source.id),
         locator: claim.locator ?? document.source.locator,
+        ...(claim.sections && { sections: [...claim.sections] }),
       });
       observations.set(claim.id, entries);
     }
@@ -307,6 +311,7 @@ function resolveObservations(claimId, entries) {
         text: entries[0].text,
         status: 'confirmed',
         citations: citationsFor(entries),
+        ...sectionMetadata(entries),
       },
     };
   }
@@ -341,6 +346,9 @@ function resolveObservations(claimId, entries) {
         citations: citationsFor(
           entries.filter(({ text }) => text === winner.entry.text),
         ),
+        ...sectionMetadata(
+          entries.filter(({ text }) => text === winner.entry.text),
+        ),
       },
     };
   }
@@ -352,6 +360,7 @@ function resolveObservations(claimId, entries) {
       text: `Conflicting values: ${[...byText.keys()].sort().join(' | ')}`,
       reason: 'contradictory',
       citations: citationsFor(entries),
+      ...sectionMetadata(entries),
     },
   };
 }
@@ -441,6 +450,7 @@ function integrateCriticFindings({
     }
 
     const claimIndex = claims.findIndex(({ id }) => id === finding.claimId);
+    const existingClaim = claimIndex >= 0 ? claims[claimIndex] : null;
     if (claimIndex >= 0) {
       claims.splice(claimIndex, 1);
     }
@@ -449,6 +459,7 @@ function integrateCriticFindings({
       text: finding.text,
       reason: finding.classification,
       citations,
+      ...(existingClaim?.sections && { sections: existingClaim.sections }),
     });
   }
 }
@@ -489,6 +500,29 @@ function uniqueCitations(citations) {
   ];
 }
 
+function validSections(sections) {
+  return (
+    sections === undefined ||
+    (Array.isArray(sections) &&
+      sections.length > 0 &&
+      new Set(sections).size === sections.length &&
+      sections.every(
+        (section) =>
+          typeof section === 'string' && SECTION_ID_PATTERN.test(section),
+      ))
+  );
+}
+
+function sectionMetadata(entries) {
+  if (entries.some(({ sections }) => sections === undefined)) {
+    return {};
+  }
+  const sections = [
+    ...new Set(entries.flatMap((entry) => entry.sections ?? [])),
+  ].sort();
+  return sections.length > 0 ? { sections } : {};
+}
+
 function byId(left, right) {
   return left.id.localeCompare(right.id);
 }

package/assets/skills/explainer-kit/scripts/lib/records.mjs

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
+import { readFile, readdir, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { validateContract } from './contracts.mjs';
@@ -70,6 +70,7 @@ export async function initializeRun(request) {
     request: normalizedRequest,
   };
 
+  await clearRunRoot(run);
   await writeJsonAtomic(run.runRoot, 'build-record.json', buildRecord);
   await writeJsonAtomic(
     run.runRoot,
@@ -226,6 +227,58 @@ function assertRun(run) {
   }
 }
 
+async function clearRunRoot(run) {
+  const entries = await readdir(run.runRoot, { withFileTypes: true });
+  if (entries.length === 0) return;
+  await assertOwnedRunRoot(run);
+  const removable = [];
+  for (const entry of entries) {
+    const path = join(run.runRoot, entry.name);
+    if (!(await containsSymlink(path, entry))) {
+      removable.push(path);
+    }
+  }
+  await Promise.all(
+    removable.map((path) => rm(path, { recursive: true, force: true })),
+  );
+}
+
+async function assertOwnedRunRoot(run) {
+  try {
+    const [persistedRequest, persistedRecord] = await Promise.all([
+      readJson(join(run.runRoot, 'run-request.json')),
+      readJson(join(run.runRoot, 'build-record.json')),
+    ]);
+    assertValidContract('run-request', persistedRequest);
+    assertValidContract('build-record', persistedRecord);
+    if (
+      persistedRequest.slug !== run.slug ||
+      persistedRequest.outputRoot !== run.outputRoot
+    ) {
+      throw new Error('Prior run identity does not match this slug.');
+    }
+  } catch {
+    throw new Error(
+      'Existing slug directory is not a prior Explainer Kit run; refusing to clear it.',
+    );
+  }
+}
+
+async function containsSymlink(path, entry) {
+  if (entry.isSymbolicLink()) return true;
+  if (!entry.isDirectory()) return false;
+  for (const child of await readdir(path, { withFileTypes: true })) {
+    if (await containsSymlink(join(path, child.name), child)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, 'utf8'));
+}
+
 function isObject(value) {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }

package/assets/skills/explainer-kit/scripts/run.mjs

@@ -227,7 +227,9 @@ async function loadResumableRun(request) {
     persistedRequest.slug !== normalized.slug ||
     persistedRequest.recipe?.id !== normalized.recipe.id ||
     persistedRequest.recipe?.version !== normalized.recipe.version ||
-    persistedRequest.mode !== normalized.mode
+    persistedRequest.mode !== normalized.mode ||
+    canonicalHash(persistedRequest.factBase) !==
+      canonicalHash(normalized.factBase)
   ) {
     throw codedError(
       'E_APPROVAL_RESUME',
@@ -551,12 +553,25 @@ function manifestFor(state, buildRecord, createdAt, immutableHashes) {
 
 function createContentModel(recipe, artifact, slug, factBase) {
   const facts = [
-    ...factBase.claims.map(({ text }) => text),
-    ...factBase.unresolvedClaims.map(
-      ({ text }) => `Needs confirmation: ${text}`,
+    ...factBase.claims.map(({ text, sections }) => ({ text, sections })),
+    ...factBase.unresolvedClaims.map(({ text, sections }) => ({
+      text: `Needs confirmation: ${text}`,
+      sections,
+    })),
+  ];
+  const unknownSections = [
+    ...new Set(
+      facts
+        .flatMap(({ sections }) => sections ?? [])
+        .filter((section) => !recipe.requiredNarrative.includes(section)),
     ),
   ];
-  const summary = facts.length > 0 ? facts.join(' ') : 'No confirmed facts.';
+  if (unknownSections.length > 0) {
+    throw codedError(
+      'E_CONTENT',
+      `Unknown narrative section tags: ${unknownSections.join(', ')}`,
+    );
+  }
   return {
     artifactId: artifact.id,
     slug,
@@ -564,11 +579,19 @@ function createContentModel(recipe, artifact, slug, factBase) {
     description: `Approved-source ${humanize(recipe.id).toLowerCase()}.`,
     eyebrow: 'Explainer Kit',
     footer: 'Generated from the retained reconciled fact base.',
-    sections: recipe.requiredNarrative.map((id) => ({
-      id,
-      title: humanize(id),
-      content: summary,
-    })),
+    sections: recipe.requiredNarrative.map((id) => {
+      const sectionFacts = facts
+        .filter(({ sections }) => !sections || sections.includes(id))
+        .map(({ text }) => text);
+      return {
+        id,
+        title: humanize(id),
+        content:
+          sectionFacts.length > 0
+            ? sectionFacts.join(' ')
+            : 'No confirmed facts.',
+      };
+    }),
     artifactLinks: [],
   };
 }

package/assets/skills/oat-wave-execute/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-wave-execute
-version: 1.6.1
+version: 1.6.2
 description: Use when executing a wave of external implementation plans as a wrapper OAT project — scaffolding, drift refresh, parallel worktree groups, briefs, gates, merge choreography, and closeout.
 argument-hint: '<wave-id> [plan-names...] (e.g. wave-2 http-listener-before-indexing ...)'
 disable-model-invocation: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -34,7 +34,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.2.6"
+    "@open-agent-toolkit/control-plane": "0.2.8"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

package/assets/skills/oat-wave-execute/assets/program-recap.recipe.json

@@ -1,34 +0,0 @@
-{
-  "schemaVersion": "explainer-kit.recipe/v1",
-  "id": "program-recap",
-  "version": "1",
-  "sourceRoles": [
-    {
-      "role": "program",
-      "required": true,
-      "accepts": ["file", "directory", "git"],
-      "minBindings": 1,
-      "maxBindings": 1
-    }
-  ],
-  "requiredNarrative": [
-    "program-overview",
-    "wave-map",
-    "per-wave-outcomes",
-    "convention-evolution",
-    "aggregate-numbers",
-    "follow-up-ledger"
-  ],
-  "artifacts": [
-    {
-      "id": "program-recap",
-      "type": "hub",
-      "template": "house-style",
-      "required": true
-    }
-  ],
-  "discoveryLimits": {
-    "consecutiveNoNewFindingsRounds": 2,
-    "maxRounds": 8
-  }
-}