@open-agent-toolkit/cli 0.2.0 → 0.2.2

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.0",
-  "docs-config": "0.2.0",
-  "docs-theme": "0.2.0",
-  "docs-transforms": "0.2.0"
+  "cli": "0.2.2",
+  "docs-config": "0.2.2",
+  "docs-theme": "0.2.2",
+  "docs-transforms": "0.2.2"
 }

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

@@ -1,6 +1,6 @@
 ---
 name: oat-wave-execute
-version: 1.5.0
+version: 1.6.0
 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
@@ -303,7 +303,30 @@ archive anything first.
    branch vs main; cherry-pick stragglers), reset the working branch, clean stale
    phase branches, and run `oat-wave-program` `wave-close <wave-id>` so the
    program ledger records the merge (PR, SHA, completion-record link) and flips
-   the wave's plan rows to `done`.
+   the wave's plan rows to `done`. Optionally generate the program recap using
+   the mechanical explainer caller below.
+
+#### Optional program-recap explainer caller
+
+The orchestrator owns fact-base synthesis. It synthesizes an
+`explainer-kit.fact-base/v1` document from the reconciled execution-program
+artifact, wave summaries, and completion records. Its required keys are exactly:
+`schemaVersion, generatedAt, mode, freshnessPolicy, sources, claims, unresolvedClaims, overrides`.
+
+The mechanical caller constructs an `explainer-kit.run-request/v1` document whose
+required keys are exactly:
+`schemaVersion, recipe, slug, outputRoot, factBase, mode`. Set `recipe` to
+`{ "id": "program-recap", "version": "1" }`; this is an object with exactly
+`id` and `version`. Set `outputRoot` to `.oat/repo/explainers/<slug>/`. Bind the
+synthesized fact-base file through `factBase` with the required keys
+`mode, freshnessPolicy`, set `mode` to `"supplied"`, set `freshnessPolicy` to
+`"live-wins"`, and set `path` to that file.
+
+After the run, read the `explainer-kit.manifest/v1` document. Its required keys
+are exactly:
+`schemaVersion, runId, slug, recipe, createdAt, source, theme, artifacts, immutableHashes, outcome, buildRecord, warnings`.
+Record the manifest's `runId` and `outcome` in the wave ledger row. Publishing is
+human-gated; this caller never invokes publish.
 
 ## Success Criteria
 

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

@@ -0,0 +1,34 @@
+{
+  "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
+  }
+}

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

@@ -1,6 +1,6 @@
 ---
 name: oat-wave-program
-version: 1.1.0
+version: 1.2.0
 description: Use when decomposing a corpus of external implementation plans into an ordered wave program — coverage inventory, dependency mapping, wave composition, and the durable execution-program artifact that oat-wave-execute consumes and updates.
 argument-hint: '[new|refresh|wave-close <wave-id>] (default: refresh against the current artifact)'
 disable-model-invocation: false
@@ -89,6 +89,31 @@ target (same disclaimer as the plan indexes).
 2. Update the status ledger row: PR, merge SHA, completion-record link.
 3. Note next-wave unblocks ("W3 merged → W4 token-cost unblocked").
 4. Commit with the wave's closeout bookkeeping.
+5. Optionally run the mechanical program-recap explainer caller described below,
+   then add its manifest `runId` and `outcome` to the wave ledger row.
+
+### Program-close explainer caller
+
+At wave-close or program-close, the orchestrator owns fact-base synthesis. It
+synthesizes an `explainer-kit.fact-base/v1` document from the reconciled
+execution-program artifact, wave summaries, and completion records. Its required
+keys are exactly:
+`schemaVersion, generatedAt, mode, freshnessPolicy, sources, claims, unresolvedClaims, overrides`.
+
+The mechanical caller constructs an `explainer-kit.run-request/v1` document whose
+required keys are exactly:
+`schemaVersion, recipe, slug, outputRoot, factBase, mode`. Set `recipe` to
+`{ "id": "program-recap", "version": "1" }`; this is an object with exactly
+`id` and `version`. Set `outputRoot` to `.oat/repo/explainers/<slug>/`. Bind the
+synthesized fact-base file through `factBase` with the required keys
+`mode, freshnessPolicy`, set `mode` to `"supplied"`, set `freshnessPolicy` to
+`"live-wins"`, and set `path` to that file.
+
+After the run, read the `explainer-kit.manifest/v1` document. Its required keys
+are exactly:
+`schemaVersion, runId, slug, recipe, createdAt, source, theme, artifacts, immutableHashes, outcome, buildRecord, warnings`.
+Record the manifest's `runId` and `outcome` in the wave or program ledger row.
+Publishing is human-gated; this caller never invokes publish.
 
 ## Integration with `oat-wave-execute`
 

package/dist/commands/init/tools/shared/copy-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"copy-helpers.d.ts","sourceRoot":"","sources":["../../../../../src/commands/init/tools/shared/copy-helpers.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAC1D,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,UAAU,CAAC;AAEzD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE/D;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,UAAU,CAAC,CAerB;AAED,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,UAAU,CAAC,CAerB;AAED,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,UAAU,CAAC,CAuBrB"}
+{"version":3,"file":"copy-helpers.d.ts","sourceRoot":"","sources":["../../../../../src/commands/init/tools/shared/copy-helpers.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAC1D,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,UAAU,CAAC;AAEzD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAwBD,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE/D;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,UAAU,CAAC,CAiBrB;AAED,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,UAAU,CAAC,CAerB;AAED,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,UAAU,CAAC,CAyBrB"}

package/dist/commands/init/tools/shared/copy-helpers.js

@@ -1,7 +1,26 @@
-import { rm } from 'node:fs/promises';
+import { chmod, readdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
 import { compareVersions } from '../../../init/tools/shared/version.js';
 import { getSkillVersion } from '../../../shared/frontmatter.js';
 import { copyDirectory, copySingleFile, dirExists, fileExists } from '../../../../fs/io.js';
+async function chmodFilesExecutable(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    for (const entry of entries) {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            await chmodFilesExecutable(path);
+        }
+        else if (entry.isFile()) {
+            await chmod(path, 0o755);
+        }
+    }
+}
+async function ensureNestedScriptsExecutable(destination) {
+    const scriptsDirectory = join(destination, 'scripts');
+    if (await dirExists(scriptsDirectory)) {
+        await chmodFilesExecutable(scriptsDirectory);
+    }
+}
 export async function pathExists(path) {
     return (await fileExists(path)) || (await dirExists(path));
 }
@@ -13,9 +32,11 @@ export async function copyDirWithStatus(source, destination, force) {
     if (exists && force) {
         await rm(destination, { recursive: true, force: true });
         await copyDirectory(source, destination);
+        await ensureNestedScriptsExecutable(destination);
         return 'updated';
     }
     await copyDirectory(source, destination);
+    await ensureNestedScriptsExecutable(destination);
     return 'copied';
 }
 export async function copyFileWithStatus(source, destination, force) {
@@ -35,11 +56,13 @@ export async function copyDirWithVersionCheck(source, destination, force) {
     const exists = await pathExists(destination);
     if (!exists) {
         await copyDirectory(source, destination);
+        await ensureNestedScriptsExecutable(destination);
         return { status: 'copied' };
     }
     if (force) {
         await rm(destination, { recursive: true, force: true });
         await copyDirectory(source, destination);
+        await ensureNestedScriptsExecutable(destination);
         return { status: 'updated' };
     }
     const bundledVersion = await getSkillVersion(source);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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.0"
+    "@open-agent-toolkit/control-plane": "0.2.2"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",