@open-agent-toolkit/cli 0.2.5 → 0.2.7

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

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+
+import { readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { bindProjectSources } from './bind-project-sources.mjs';
+import { checkCoreCompatibility } from './check-core.mjs';
+import {
+  resolveExplainerConfig,
+  toExplainerRunRequest,
+} from './resolve-config.mjs';
+import { resolveExplainerOutputRoot } from './resolve-paths.mjs';
+
+const MINIMUM_CORE_VERSION = '1.0.0';
+const ADAPTER_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+export async function runOatExplainer({
+  adapterRoot = ADAPTER_ROOT,
+  userSkillsRoot,
+  repoRoot,
+  invocation,
+  activeProject,
+  recipe,
+  slug,
+  suppliedFactBasePath,
+  runtimeOverrides = {},
+  getConfig,
+  mode = 'unattended',
+  durabilityStrategy = 'none',
+  artDirection,
+  defaultMode,
+  renderStrategy,
+  retainRawArtDirection = false,
+  critic,
+  criticModulePath,
+  coreOptions = {},
+}) {
+  const compatibility = await checkCoreCompatibility({
+    adapterRoot,
+    ...(userSkillsRoot && { userSkillsRoot }),
+    minimumVersion: MINIMUM_CORE_VERSION,
+  });
+  if (!compatibility.ok) {
+    const error = new Error(
+      `${compatibility.message} Run \`${compatibility.guidance}\`.`,
+    );
+    error.code =
+      compatibility.code === 'missing'
+        ? 'E_CORE_MISSING'
+        : 'E_CORE_INCOMPATIBLE';
+    error.compatibility = compatibility;
+    throw error;
+  }
+
+  const resolvedConfig = await resolveExplainerConfig({
+    repoRoot,
+    runtimeOverrides,
+    ...(getConfig && { getConfig }),
+  });
+  const outputRoot = await resolveExplainerOutputRoot({
+    repoRoot,
+    invocation,
+    activeProject,
+  });
+  if (invocation !== 'project' || !activeProject) {
+    throw new Error(
+      'Project artifact binding requires a project invocation and activeProject.',
+    );
+  }
+  const projectRoot = resolve(repoRoot, activeProject);
+  const bound = await bindProjectSources({
+    projectRoot,
+    recipe,
+    suppliedFactBasePath,
+  });
+  const request = toExplainerRunRequest({
+    resolvedConfig,
+    recipe,
+    slug,
+    outputRoot,
+    factBase: bound.factBase,
+    mode,
+    durabilityStrategy,
+    artDirection,
+    defaultMode,
+    renderStrategy,
+    retainRawArtDirection,
+  });
+
+  const coreModulePath = join(compatibility.coreRoot, 'scripts', 'run.mjs');
+  let core;
+  try {
+    core = await import(pathToFileURL(coreModulePath).href);
+  } catch (cause) {
+    const error = new Error(
+      `Compatible explainer-kit is missing its run entry point. Run \`${compatibility.guidance ?? 'oat tools update --pack utility --scope user'}\`.`,
+      { cause },
+    );
+    error.code = 'E_CORE_INCOMPATIBLE';
+    throw error;
+  }
+  if (typeof core.runExplainer !== 'function') {
+    const error = new Error(
+      'Compatible explainer-kit does not export runExplainer(request, options).',
+    );
+    error.code = 'E_CORE_INCOMPATIBLE';
+    throw error;
+  }
+
+  const lifecycleCritic = await resolveLifecycleCritic({
+    critic,
+    criticModulePath,
+    coreOptions,
+  });
+  const result = await core.runExplainer(request, {
+    ...coreOptions,
+    ...(lifecycleCritic && { critic: lifecycleCritic }),
+    ...(bound.sourceLoader && { sourceLoader: bound.sourceLoader }),
+    reviewedSource: bound.reviewedSource,
+  });
+  const criticContractError = result?.errors?.find(
+    ({ message }) =>
+      typeof message === 'string' && message.includes('critic result contract'),
+  );
+  if (criticContractError) {
+    throw new Error(criticContractError.message);
+  }
+  const manifest = await readManifest(result, request);
+  return {
+    compatibility,
+    request,
+    manifest,
+    result,
+    outputRoot,
+  };
+}
+
+async function resolveLifecycleCritic({
+  critic,
+  criticModulePath,
+  coreOptions,
+}) {
+  const candidates = [
+    typeof critic === 'function' ? critic : null,
+    typeof coreOptions?.critic === 'function' ? coreOptions.critic : null,
+    criticModulePath ? criticModulePath : null,
+  ].filter(Boolean);
+  if (candidates.length > 1) {
+    throw new Error(
+      'Supply only one provider-neutral critic callback or critic module entry point.',
+    );
+  }
+  if (critic !== undefined && typeof critic !== 'function') {
+    throw new TypeError('critic must be a function when supplied.');
+  }
+  if (
+    coreOptions?.critic !== undefined &&
+    typeof coreOptions.critic !== 'function'
+  ) {
+    throw new TypeError('coreOptions.critic must be a function when supplied.');
+  }
+
+  let callback = critic ?? coreOptions?.critic;
+  if (criticModulePath !== undefined) {
+    if (
+      typeof criticModulePath !== 'string' ||
+      criticModulePath.trim().length === 0
+    ) {
+      throw new TypeError('criticModulePath must be a non-empty path.');
+    }
+    let criticModule;
+    try {
+      criticModule = await import(
+        pathToFileURL(resolve(criticModulePath)).href
+      );
+    } catch (cause) {
+      throw new Error(
+        `Unable to load provider-neutral critic module at ${criticModulePath}.`,
+        { cause },
+      );
+    }
+    if (typeof criticModule.critic !== 'function') {
+      throw new TypeError(
+        'Provider-neutral critic module must export a critic function.',
+      );
+    }
+    callback = criticModule.critic;
+  }
+
+  if (!callback) {
+    return null;
+  }
+  return async (request) => {
+    const result = await callback(request);
+    if (
+      !result ||
+      typeof result !== 'object' ||
+      typeof result.criticId !== 'string' ||
+      !/^[a-z0-9][a-z0-9._-]*$/.test(result.criticId) ||
+      !Array.isArray(result.findings) ||
+      (result.executedAt !== undefined &&
+        (typeof result.executedAt !== 'string' ||
+          Number.isNaN(Date.parse(result.executedAt))))
+    ) {
+      throw new Error(
+        'Provider-neutral critic result does not match the critic result contract.',
+      );
+    }
+    return result;
+  };
+}
+
+async function readManifest(result, request) {
+  if (
+    !result ||
+    typeof result !== 'object' ||
+    typeof result.manifestPath !== 'string'
+  ) {
+    throw new Error('explainer-kit returned no manifestPath.');
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(result.manifestPath, 'utf8'));
+  } catch (error) {
+    if (
+      error?.code === 'ENOENT' &&
+      (result.outcome === 'failed' || result.outcome === 'incomplete')
+    ) {
+      return null;
+    }
+    throw error;
+  }
+  if (manifest.schemaVersion !== 'explainer-kit.manifest/v1') {
+    throw new Error(
+      `Unsupported core manifest version: ${manifest.schemaVersion ?? 'missing'}.`,
+    );
+  }
+  if (
+    manifest.recipe?.id !== request.recipe.id ||
+    manifest.recipe?.version !== request.recipe.version
+  ) {
+    throw new Error(
+      'Core manifest recipe does not match the normalized request.',
+    );
+  }
+  return manifest;
+}
+
+async function runCli(argv = process.argv.slice(2), io = console) {
+  try {
+    if (argv.length !== 2 || argv[0] !== '--context') {
+      throw new Error('Usage: run.mjs --context <adapter-context.json>');
+    }
+    const context = JSON.parse(await readFile(argv[1], 'utf8'));
+    const result = await runOatExplainer(context);
+    io.log(JSON.stringify(result, null, 2));
+    return result.result.outcome === 'failed' ? 1 : 0;
+  } catch (error) {
+    io.error(
+      JSON.stringify(
+        {
+          outcome: 'failed',
+          errors: [
+            {
+              code: error.code ?? 'E_ADAPTER',
+              message: error instanceof Error ? error.message : String(error),
+            },
+          ],
+        },
+        null,
+        2,
+      ),
+    );
+    return 1;
+  }
+}
+
+if (
+  process.argv[1] &&
+  pathToFileURL(process.argv[1]).href === import.meta.url
+) {
+  process.exitCode = await runCli();
+}

package/assets/skills/oat-project-autonomous/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-autonomous
-version: 1.0.4
+version: 1.0.5
 description: Use when a user explicitly asks to run an OAT project autonomously end-to-end. Activates session-only autonomy, resumes the correct lifecycle phase, and drives the existing OAT skills through final PR or a reported boundary.
 argument-hint: '<goal | project-slug | ticket-ref>'
 disable-model-invocation: true
@@ -234,6 +234,27 @@ a product-judgment boundary.
 Invoke `oat-project-new` for spec-driven mode or `oat-project-quick-start` for
 quick mode. Existing projects retain their persisted workflow mode.
 
+### Step 2.5: Persist Autonomous Explainer Intent
+
+As soon as the selected creation skill has created a new project, or after an
+existing project is resolved, use the `oat-explainer-kit` lifecycle intent
+resolver and persistence helper against that project's `state.md`.
+
+Resolve and persist `projectRecap` as `generate` with source `autonomous_policy` after project creation or resolution.
+Reassert this forced recap intent on resume; a stale lower-precedence skip is overridden, warned, and recorded.
+The autonomous mode policy has precedence over project state and workflow
+preference, so `never` does not suppress the recap.
+
+Resolve and persist `projectExplainer` as `generate` with source `kickoff_prompt` only when the kickoff request explicitly asks for a project explainer.
+A general autonomous goal, project creation, or normal planning does not count as an explainer request.
+When no explicit kickoff explainer request exists, do not persist a project-explainer intent record.
+Do not infer this request from the presence of a plan, from the selected
+workflow mode, or from a generic request to run through PR.
+
+Use the state content hash expected by the adapter persistence contract. On a
+stale-write conflict, re-read `state.md`, rerun autonomous resolution, and
+persist only the newly returned record; never retry a stale record blindly.
+
 ### Step 3: Perform External-Integration Research
 
 Before planning, extensively research every integrated system, service,

package/assets/skills/oat-project-autonomous/references/gate-inventory.md

@@ -142,6 +142,7 @@ remains.
 | PLAN-09          | `oat-project-plan`               | Plan artifact-review findings                 | Accept offered Medium/Minor fixes                         | Apply unambiguous artifact-local fixes and re-review; unresolved Critical or material ambiguity stops                                                                                                                                                                        | `auto-resolve` / `boundary:unresolved-critical-findings`                        | Plan review row and residuals                                        |
 | PLAN-10          | `oat-project-plan`               | Parallel-group proposal                       | Confirm a candidate group                                 | Accept only when write-set and dependency evidence proves independence; otherwise keep sequential and record why                                                                                                                                                             | `auto-resolve`                                                                  | Plan Parallelism section                                             |
 | PLAN-11          | `oat-project-plan`               | Configured exit gate                          | `block`, `prompt`, or `warn` after failure                | Apply configured failure semantics; `prompt` becomes a reported boundary                                                                                                                                                                                                     | `auto-resolve` / `boundary:repository-policy-approval`                          | Structured gate result and disposition                               |
+| PLAN-12          | `oat-project-plan`               | Project-explainer intent                      | Generate or skip the project explainer                    | Preserve explicit or persisted intent; in autonomy generate only when kickoff explicitly requested it and never prompt                                                                                                                                                       | `auto-resolve`                                                                  | Persisted project-explainer intent                                   |
 | IMPORT-01        | `oat-project-import-plan`        | Inherited dirty tree                          | Commit, proceed, or abort                                 | Proceed without staging unrelated files; destructive cleanup stops                                                                                                                                                                                                           | `auto-resolve` / `boundary:destructive-change-risk`                             | Import preflight note                                                |
 | IMPORT-02        | `oat-project-import-plan`        | Missing project                               | Ask for project identity                                  | Use explicit invocation context; otherwise stop rather than guess                                                                                                                                                                                                            | `boundary:product-judgment`                                                     | Resolved project path                                                |
 | IMPORT-03        | `oat-project-import-plan`        | Source plan selection or extension exception  | Choose a candidate/path or confirm nonstandard Markdown   | Use an explicit unique source; ambiguity or nonstandard content stops                                                                                                                                                                                                        | `auto-resolve` / `boundary:product-judgment`                                    | Import reference metadata                                            |
@@ -169,6 +170,7 @@ remains.
 | IMPLEMENT-16     | `oat-project-implement`          | Final HiLL approval                           | Approve, decline, or defer between pre/post steps         | After passing auto-review and successful pre-approval steps, record approval and continue post-approval steps; otherwise stop                                                                                                                                                | `auto-resolve` / `boundary:unresolved-critical-findings`                        | Sequence snapshot, review artifact, dispatch record                  |
 | IMPLEMENT-17     | `oat-project-implement`          | Next-step prompt                              | Choose lifecycle tail actions                             | Unreachable when the autonomous sequence snapshot exists; never present the prompt                                                                                                                                                                                           | `auto-resolve`                                                                  | Completed sequence snapshot                                          |
 | IMPLEMENT-18     | `oat-project-implement`          | Configured exit gate                          | `block`, `prompt`, or `warn` after validated findings     | Apply configured failure semantics only to a validated, receive-eligible `blocked` envelope after durable receive; all operational, validation, correlation, malformed/contradictory-envelope, launch, and receive failures stop regardless of `onFailure`, including `warn` | `auto-resolve` / `boundary:repository-policy-approval`                          | Validated structured gate result, completed receive, and disposition |
+| IMPLEMENT-19     | `oat-project-implement`          | Implementation-tail project recap             | Generate or skip the final project recap                  | In autonomy attempt one recap when no fresh recap exists; preserve resolved interactive intent otherwise, and never block completion on recap outcome                                                                                                                        | `auto-resolve`                                                                  | Recap manifest and outcome record                                    |
 | DOCUMENT-01      | `oat-project-document`           | Missing project path                          | Ask for a path                                            | Use explicit/active project only; otherwise stop                                                                                                                                                                                                                             | `boundary:product-judgment`                                                     | Resolved project path                                                |
 | DOCUMENT-02      | `oat-project-document`           | Documentation delta approval                  | Apply all, individual, or skip                            | Invoke the existing `--auto` path and apply all non-destructive recommendations                                                                                                                                                                                              | `auto-resolve`                                                                  | Documentation delta and state update                                 |
 | DOCUMENT-03      | `oat-project-document`           | Delete or restructure docs                    | Require explicit approval                                 | Stop before destructive or broad restructuring not already authorized by the plan                                                                                                                                                                                            | `boundary:destructive-change-risk`                                              | Documentation blocker                                                |
@@ -256,7 +258,9 @@ remains immutable baseline evidence for the original p01-t01 verification.
 | `oat-dispatch-subagents/references/provider-cursor.md`         | `ca11e28923eb -> NG`; `be0a84c48fc0 -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `oat-dispatch-subagents/references/record-schema.md`           | `78f8069274a8 -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `oat-project-dispatch-subagents/SKILL.md`                      | `eca03ad1ca12 -> PDISPATCH-01`; `59fbcdc79cea -> PDISPATCH-01`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `oat-project-complete/SKILL.md`                                | `b4934a85feee -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `oat-project-plan/SKILL.md`                                    | `f99e44b39932 -> PLAN-12`; `7e6a9854504b -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `oat-project-implement/references/completion-and-closeout.md`  | `6909a5a5a1fa -> IMPLEMENT-19`; `a7c02ef670fd -> IMPLEMENT-19`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `oat-project-complete/SKILL.md`                                | `ffad9f909dba -> COMPLETE-01`; `ffe636f736e8 -> COMPLETE-01`; `ea2dced337be -> COMPLETE-01`; `93d3e4ee3355 -> COMPLETE-01`; `2407ebed0921 -> NG`; `0177956707aa -> NG`; `8305b5bb65ef -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 
 ## Prompt-scan comparison