@open-agent-toolkit/cli 0.2.30 → 0.2.31

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

@@ -1,6 +1,6 @@
 ---
 name: oat-explainer-kit
-version: 1.0.5
+version: 1.0.6
 description: Use when building project explainers or recaps from OAT configuration, state, and lifecycle artifacts.
 disable-model-invocation: false
 user-invocable: true
@@ -37,7 +37,7 @@ rollback, and operator-owned real-wrapper gate, use `references/migration.md`.
 
 Before reading OAT config or invoking the core, call
 `scripts/check-core.mjs#checkCoreCompatibility` with this installed skill
-directory and minimum core version `2.0.3`. Continue only when it returns
+directory and minimum core version `2.1.0`. Continue only when it returns
 `ok: true`.
 
 - Missing core: stop and show
@@ -58,7 +58,7 @@ Call `scripts/run.mjs#runOatExplainer` with the repository root, project
 invocation, active project path, recipe, slug, lifecycle mode, and any explicit
 runtime overrides. The adapter:
 
-1. checks the user-scoped installed core at minimum version `2.0.3`;
+1. checks the user-scoped installed core at minimum version `2.1.0`;
 2. resolves only the public `explainers.*` and `workflow.explainers.*` keys;
 3. derives the canonical project output root;
 4. binds approved OAT artifacts to the recipe's single `project` source set;
@@ -72,6 +72,13 @@ Missing optional artifacts are omitted, but at least one approved lifecycle
 artifact is required. An explicit supplied fact-base path bypasses artifact
 federation and is passed through as `factBase.mode: supplied`.
 
+New project-recap requests select immutable `project-recap@2`: one
+navigational hub is the floor, while a diagram, walkthrough deck, or deep dive
+is selected only when the planner can state its distinct reader question,
+source evidence, and medium rationale. The installed core continues reading
+`project-recap@1` for replay; the adapter never rewrites a retained request's
+recipe selector.
+
 Before invocation, read `references/author-callback.md`. Unattended
 `project-recap` runs require exactly one provider-neutral set planner:
 in-process callers supply `planSet`, while JSON/CLI callers supply
@@ -99,6 +106,12 @@ matching exports. Bare browser callbacks and caller-authored runtime metadata
 are rejected. These are first-class adapter inputs; do not place either
 provider in `coreOptions`.
 
+The critic judges typography, hierarchy, composition, density, medium leverage,
+template repetition, diagram semantics, and cross-artifact cohesion from the
+bound rendered evidence. Keep those criteria in prose. Preserve the core's
+existing `visual-review-result/v1` contract and actionable `pass`/`correct`
+behavior; do not add adapter-owned scores, layout thresholds, or result fields.
+
 The adapter resolves all executable providers before core invocation, enforces
 direct-versus-module mutual exclusion, and requires distinct identities for
 authoring, fact criticism, browser evidence, and visual criticism. A missing,

package/assets/skills/oat-explainer-kit/references/config-contract.md

@@ -17,11 +17,12 @@ constructing an `explainer-kit.run-request/v1`.
 | `explainers.publish.s3Uri`             | shared              | unset            |
 | `explainers.publish.publicBaseUrl`     | shared              | unset            |
 | `explainers.publish.awsRegion`         | shared              | unset            |
+| `explainers.publish.publicAccess`      | shared              | `public`         |
 | `explainers.publish.awsProfile`        | local, user         | unset            |
 | `workflow.explainers.projectExplainer` | local, shared, user | `ask`            |
 | `workflow.explainers.projectRecap`     | local, shared, user | `ask`            |
 
-Explicit runtime inputs may override these eleven keys for one invocation. They
+Explicit runtime inputs may override these twelve keys for one invocation. They
 do not write config. Recipe, slug, fact-base path, output root, per-run art
 direction, and private wrapper lanes are invocation inputs rather than config
 keys and are rejected from the runtime config-override map.
@@ -44,12 +45,16 @@ warning. The adapter passes a resolved bundle as `theme.suppliedBundlePath`.
 
 ## Publish block
 
-No provider means build-only operation, even if unused destination fields are
-present. When `provider` is `s3-static`, `s3Uri`, `publicBaseUrl`, and
-`awsRegion` are all required. `awsProfile` is optional and uses the normal AWS
-credential chain when absent. Destination roots are normalized without trailing
-slashes. Lifecycle callers must explicitly select publish durability; config
-alone never starts publishing.
+`provider`, `s3Uri`, `publicBaseUrl`, and `awsRegion` form one complete publish
+block. If any field is absent, the adapter returns a structured build-only
+report listing every missing field and does not construct publish config.
+`awsProfile` is optional and uses the normal AWS credential chain when absent.
+`publicAccess` accepts `public` or `protected` and defaults to `public`;
+source metadata is retained and the resolved mode is carried explicitly in the
+versioned core publish request. Destination roots are normalized without trailing
+slashes. Lifecycle callers must explicitly select publish durability; complete
+configuration only makes publication available and never authorizes it. The
+existing human gate remains mandatory.
 
 ## Canonical output roots
 
@@ -68,5 +73,5 @@ core creates output.
 The adapter emits `explainer-kit.run-request/v1` with the requested recipe,
 slug, fact-base binding, mode, derived output root, resolved theme selection,
 privacy choice, and explicit durability strategy. Publish durability adds a
-complete `explainer-kit.publish-request/v1` whose `siteRoot` and
+complete `explainer-kit.publish-request/v2` whose `siteRoot` and
 `manifestPath` point inside `<outputRoot>/<slug>/`.

package/assets/skills/oat-explainer-kit/references/lifecycle-contract.md

@@ -86,6 +86,38 @@ The resolved callback is passed only as the `author` option to
 `run-request.json`, or another retained data contract. Interactive runs use the
 same author contract and differ only at the later approval gate.
 
+## Repository invocation sources
+
+A repository invocation must provide `suppliedFactBasePath`. The adapter binds
+that validated fact-base input with provenance from the exact reviewed
+repository revision returned by `resolveReviewedRepository`; it never resolves
+or reads an active project for this invocation. Missing supplied input fails
+closed before core invocation with an actionable requirement.
+
+Repository runs write beneath `.oat/repo/reference/explainers/<run-slug>/` and
+use repository-level publish roots unchanged. Project invocations retain their
+approved lifecycle-artifact binding and project-local output behavior.
+
+When publish durability is explicitly selected, the adapter constructs the
+core `explainer-kit.publish-request/v2` with the per-invocation derived `s3Uri`,
+`publicBaseUrl`, and source-aware `publicAccess`. New adapter runs emit this v2
+shape atomically; the request carries no project/repository topology fields and
+no credential material. The human-gated publisher returns a complete
+`explainer-kit.publish-receipt/v2`, which the core validates against the
+finalized manifest and generated catalog before the adapter forwards the
+publication summary without destination reinterpretation. The immutable
+`publish-request/v1` and `publish-receipt/v1` contracts remain supported only
+for replay; v2 does not mutate either v1 contract in place. Configuration never
+bypasses the human publication gate.
+
+The adapter forwards the immutable `explainer-kit.publish-summary/v2` lifecycle
+handoff without destination reinterpretation. Every v2 artifact entry retains
+its source identity, rendered path, S3 URI, canonical public URL, content hash,
+object verification, and public verification evidence. A
+`publish-receipt/v1` replay instead yields the reduced immutable
+`explainer-kit.publish-summary/v1` shape, whose artifact entries retain only
+the relative path and public URL. Neither summary contract is mutated in place.
+
 ## Browser and visual-review execution
 
 Every unattended `project-recap` must provide exactly one browser-evidence
@@ -109,10 +141,13 @@ request/result, and byte-bound whole-set review contracts.
 
 The core retains canonical 320, 768, and 1440 viewport screenshots, paired
 `explainer-kit.browser-evidence/v2` metrics with launched Chromium name,
-version, and capture identity, each review request/result, cohesion
+version, and capture identity, each review request and closed local evidence
+projection, cohesion
 observations, and any one-pass revision record. Missing, malformed, forged,
 cross-record mismatched, stale, or failed review-chain evidence terminates as
 `built-needs-review`; durability and publication remain blocked.
+The review chain performs at most one correction and one final review. It never
+starts a second rebuild to chase visual perfection.
 
 ## Tracked-run finalization
 
@@ -124,10 +159,15 @@ repository root, project name, an explicit compatible `coreRoot`, and, for
 dynamically loads the versioned package-coverage contract from that core root;
 it does not maintain an adapter-local path list.
 
-A core `built-needs-review` outcome is a terminal review gate, not a
-non-durable success. The planner rejects it before producing artifact,
-attestation, evidence-commit, or push commands. The recap must instead be
-reviewed and rebuilt to a passing visual-review outcome.
+A core `built-needs-review` or `failed` outcome is terminal evidence, not a
+non-durable success. Provider review and diagnostic prose exists only during
+the in-memory correction attempt. Retained review attempts use the closed
+`visual-review-evidence/v1` projection bound to the adjacent request hash and
+attempt directory. The core retains `terminal-evidence.json` with run identity,
+the manifest hash when available, bounded `stage`/`kind` reason tuples, and the
+evidence disposition. The planner verifies that binding and returns complete
+without artifact, attestation, evidence-commit, or push commands. This preserves
+the handoff without promoting it to durable or publishable success.
 
 The returned stages must run in order:
 
@@ -188,7 +228,11 @@ complete. A later attestation may recover durability without repeating the
 archive.
 
 This recovery path applies only to `built-not-durable`.
-`built-needs-review` cannot be exported, attested, finalized, or pushed.
+`built-needs-review` and `failed` packages may be exported so their compact
+terminal evidence survives project deletion, but they cannot be attested into
+`built-durable`, pushed by the finalizer, or published. Flagged, failed,
+superseded, and `built-not-durable` runs are never publishable. Only a
+review-clean `built-durable` run may cross the explicit human publication gate.
 
 Post-archive summary and PR recap links target `projectRecapExport.exportRoot`
 under `.oat/repo/reference/project-recaps/` on the current head branch. The

package/assets/skills/oat-explainer-kit/references/migration.md

@@ -17,7 +17,8 @@ release candidate passes every acceptance gate.
    Google account data, authentication choices, and personal destination
    topology in private wrapper configuration.
 4. Invoke the core once, consume only `explainer-kit.manifest/v1` and the
-   optional publish receipt, then perform Stoa notes, Google Docs sync, and
+   optional `explainer-kit.publish-receipt/v2` (while retaining v1 replay),
+   then perform Stoa notes, Google Docs sync, and
    private link maintenance as post-run work.
 
 Do not add a plugin, inject private work between core stages, or add private

package/assets/skills/oat-explainer-kit/references/visual-review-callback.md

@@ -51,6 +51,12 @@ viewport-matched screenshot and metrics hashes, observed cohesion claims, and
 the exact browser runtime and capture identity shared by every evidence record.
 Use the evidence reader to inspect the byte snapshot named by the request.
 
+Judge the rendered set as prose-led visual work. Cover typography, hierarchy,
+composition, density, medium leverage, template repetition, diagram semantics,
+and cross-artifact cohesion. Use the set plan and shared ledger to distinguish
+intentional variation from drift. Do not turn those judgments into numeric
+scores, geometry thresholds, or deterministic style checks.
+
 Return `explainer-kit.visual-review-result/v1` with:
 
 - a safe `reviewId`;
@@ -60,6 +66,11 @@ Return `explainer-kit.visual-review-result/v1` with:
 - the complete reviewed `artifactIds`; and
 - structured `findings`.
 
+Return `pass` only when the full set needs no required correction. Return
+`correct` when one bounded review round can address every finding, and give
+each finding an actionable correction tied to an artifact and visible evidence.
+The result shape and its `pass`/`correct`/`fail` dispositions remain unchanged.
+
 The callback must not mutate rendered files, screenshots, or metrics. The core
 revalidates all bound bytes after the callback returns.
 

package/assets/skills/oat-explainer-kit/scripts/bind-project-sources.mjs

@@ -18,6 +18,12 @@ export async function bindProjectSources({
   suppliedFactBasePath,
   reviewedRepository,
 }) {
+  if (suppliedFactBasePath) {
+    const repository =
+      reviewedRepository ??
+      (repoRoot ? await resolveReviewedRepository(repoRoot) : null);
+    return bindSuppliedFactBase(suppliedFactBasePath, repository);
+  }
   if (!projectRoot) {
     throw new TypeError('projectRoot is required to bind OAT artifacts.');
   }
@@ -30,21 +36,6 @@ export async function bindProjectSources({
   const repository =
     reviewedRepository ??
     (repoRoot ? await resolveReviewedRepository(repoRoot) : null);
-  if (suppliedFactBasePath) {
-    const path = await realpath(suppliedFactBasePath);
-    return {
-      factBase: {
-        mode: 'supplied',
-        path,
-        freshnessPolicy: 'live-wins',
-      },
-      reviewedSource: {
-        kind: 'approved-fact-base',
-        locator: repository?.repositoryUrl ?? path,
-        ...(repository && repository),
-      },
-    };
-  }
 
   const sourceSetId = basename(canonicalProjectRoot);
   const sources = [];
@@ -95,6 +86,21 @@ export async function bindProjectSources({
   };
 }
 
+export async function bindRepositorySources({
+  repoRoot,
+  suppliedFactBasePath,
+  reviewedRepository,
+}) {
+  if (!suppliedFactBasePath) {
+    throw new Error(
+      'Repository invocation requires a caller-supplied fact base path.',
+    );
+  }
+  const repository =
+    reviewedRepository ?? (await resolveReviewedRepository(repoRoot));
+  return bindSuppliedFactBase(suppliedFactBasePath, repository);
+}
+
 export async function resolveReviewedRepository(
   repoRoot,
   { command = execFile } = {},
@@ -119,6 +125,22 @@ export async function resolveReviewedRepository(
   };
 }
 
+async function bindSuppliedFactBase(suppliedFactBasePath, repository) {
+  const path = await realpath(suppliedFactBasePath);
+  return {
+    factBase: {
+      mode: 'supplied',
+      path,
+      freshnessPolicy: 'live-wins',
+    },
+    reviewedSource: {
+      kind: 'approved-fact-base',
+      locator: repository?.repositoryUrl ?? path,
+      ...(repository && repository),
+    },
+  };
+}
+
 async function loadOatArtifact(source) {
   return oatArtifactDocument(
     source,

package/assets/skills/oat-explainer-kit/scripts/check-terminal-outcome.mjs

@@ -0,0 +1,83 @@
+import { readFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+
+const TERMINAL_OUTCOMES = new Set([
+  'built-durable',
+  'built-not-durable',
+  'built-needs-review',
+  'failed',
+]);
+
+export function checkTerminalOutcome({ intent, outcome }) {
+  if (intent === 'skip') {
+    return { ok: true, intent, outcome: null };
+  }
+  if (intent !== 'generate') {
+    throw recapOutcomeError('Recap intent must be generate or skip.');
+  }
+  if (!TERMINAL_OUTCOMES.has(outcome)) {
+    throw recapOutcomeError(
+      'Generated project recaps require a terminal recap outcome before approval.',
+    );
+  }
+  return { ok: true, intent, outcome };
+}
+
+async function main(argv) {
+  const { intent, manifestPath } = parseArguments(argv);
+  let outcome;
+  if (manifestPath !== undefined) {
+    let manifest;
+    try {
+      manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+    } catch (error) {
+      throw recapOutcomeError(
+        `Recap manifest could not be read: ${error.message}`,
+      );
+    }
+    outcome = manifest?.outcome;
+  }
+  return checkTerminalOutcome({ intent, outcome });
+}
+
+function parseArguments(argv) {
+  let intent;
+  let manifestPath;
+  for (let index = 0; index < argv.length; index += 2) {
+    const flag = argv[index];
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw recapOutcomeError(`Missing value for ${flag ?? 'argument'}.`);
+    }
+    if (flag === '--intent') {
+      intent = value;
+    } else if (flag === '--manifest') {
+      manifestPath = value;
+    } else {
+      throw recapOutcomeError(`Unsupported argument: ${flag}.`);
+    }
+  }
+  return { intent, manifestPath };
+}
+
+function recapOutcomeError(message) {
+  const error = new Error(message);
+  error.code = 'E_RECAP_OUTCOME';
+  return error;
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  main(process.argv.slice(2))
+    .then((result) => {
+      process.stdout.write(`${JSON.stringify(result)}\n`);
+    })
+    .catch((error) => {
+      process.stderr.write(
+        `${JSON.stringify({ ok: false, code: error.code, message: error.message })}\n`,
+      );
+      process.exitCode = 1;
+    });
+}

package/assets/skills/oat-explainer-kit/scripts/derive-destination.mjs

@@ -0,0 +1,91 @@
+const INVOCATIONS = new Set(['project', 'repo', 'direct']);
+
+export function deriveExplainerDestination({
+  invocation,
+  projectSlug,
+  s3Uri,
+  publicBaseUrl,
+}) {
+  if (!INVOCATIONS.has(invocation)) {
+    throw new Error(`Unsupported explainer invocation: ${invocation}`);
+  }
+  const roots = {
+    s3Uri: normalizeRoot(s3Uri, 's3Uri', 's3:'),
+    publicBaseUrl: normalizeRoot(publicBaseUrl, 'publicBaseUrl', 'https:'),
+  };
+  if (invocation !== 'project') {
+    return roots;
+  }
+
+  const encodedSlug = encodeProjectSlug(projectSlug);
+  return {
+    s3Uri: `${roots.s3Uri}/projects/${encodedSlug}`,
+    publicBaseUrl: `${roots.publicBaseUrl}/projects/${encodedSlug}`,
+  };
+}
+
+function encodeProjectSlug(projectSlug) {
+  if (
+    typeof projectSlug !== 'string' ||
+    !projectSlug.trim() ||
+    projectSlug === '.' ||
+    projectSlug === '..' ||
+    projectSlug.includes('/') ||
+    projectSlug.includes('\\') ||
+    projectSlug.includes('\0')
+  ) {
+    throw new Error(
+      'Project slug must be a non-empty, safe path segment without traversal or separators.',
+    );
+  }
+  return encodeURIComponent(projectSlug);
+}
+
+function normalizeRoot(value, label, protocol) {
+  if (typeof value !== 'string') {
+    throw new Error(`${label} must be a valid destination root.`);
+  }
+  const root = value.trim();
+  const authorityStart = `${protocol}//`;
+  if (
+    !root.startsWith(authorityStart) ||
+    /\s|\\/.test(root) ||
+    root.includes('?') ||
+    root.includes('#')
+  ) {
+    throw new Error(`${label} must be a valid destination root.`);
+  }
+
+  let parsed;
+  try {
+    parsed = new URL(root);
+  } catch {
+    throw new Error(`${label} must be a valid destination root.`);
+  }
+  const authority = root.slice(authorityStart.length).split('/', 1)[0];
+  if (
+    parsed.protocol !== protocol ||
+    !isValidRawAuthority(authority, protocol) ||
+    !parsed.hostname ||
+    parsed.username ||
+    parsed.password ||
+    parsed.search ||
+    parsed.hash
+  ) {
+    throw new Error(`${label} must be a valid destination root.`);
+  }
+  return root.replace(/\/+$/, '');
+}
+
+function isValidRawAuthority(authority, protocol) {
+  if (!authority || authority.includes('@')) {
+    return false;
+  }
+  if (protocol === 's3:') {
+    return /^[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?$/.test(authority);
+  }
+  if (authority.startsWith('[')) {
+    return /^\[[^\]]+\](?::\d+)?$/.test(authority);
+  }
+  return /^[^:]+(?::\d+)?$/.test(authority);
+}

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

@@ -7,6 +7,7 @@ const MODES = new Set(['dedicated', 'completion-bookkeeping']);
 const ARTIFACT_COMMIT_TOKEN = '$ARTIFACT_COMMIT';
 const SHA_PATTERN = /^[a-f0-9]{40}$/;
 const PACKAGE_COVERAGE_VERSION = 'explainer-kit.package-coverage/v2';
+const TERMINAL_EVIDENCE_VERSION = 'explainer-kit.terminal-evidence/v1';
 
 export async function planTrackedRunFinalization(request, context = {}) {
   assertRequest(request);
@@ -24,10 +25,27 @@ export async function planTrackedRunFinalization(request, context = {}) {
       'Finalization requires an explainer-kit.manifest/v1 record.',
     );
   }
-  if (manifest.outcome === 'built-needs-review') {
-    throw new Error(
-      'built-needs-review requires a passing visual review before finalization.',
+  if (['built-needs-review', 'failed'].includes(manifest.outcome)) {
+    const terminalEvidenceContract = await loadTerminalEvidenceContract(
+      context.coreRoot,
     );
+    const { evidence: terminalEvidence } =
+      await terminalEvidenceContract.readTerminalEvidenceFile(runRoot, {
+        manifest,
+      });
+    return {
+      schemaVersion: 'oat-explainer-kit.finalization-plan/v1',
+      status: 'complete',
+      outcome: manifest.outcome,
+      commands: [],
+      push: null,
+      publicationAllowed: false,
+      evidenceDisposition: terminalEvidence.evidenceDisposition,
+      terminalEvidencePath: 'terminal-evidence.json',
+      ...(terminalEvidence.supersededBy && {
+        supersededBy: terminalEvidence.supersededBy,
+      }),
+    };
   }
   const packageCoverage = await loadPackageCoverage(context.coreRoot);
 
@@ -138,11 +156,21 @@ export async function planTrackedRunFinalization(request, context = {}) {
 
 export function verifyTrackedRunFinalization(plan, observation) {
   if (plan?.status === 'complete') {
+    if (
+      !['built-durable', 'built-needs-review', 'failed'].includes(plan.outcome)
+    ) {
+      return failed([
+        error(
+          'invalid-plan',
+          'Complete finalization plan has an unsupported outcome.',
+        ),
+      ]);
+    }
     return {
       ok: true,
-      outcome: 'built-durable',
+      outcome: plan.outcome,
       pushAllowed: false,
-      errors: [],
+      reasons: [],
     };
   }
   const errors = [];
@@ -240,7 +268,7 @@ export function verifyTrackedRunFinalization(plan, observation) {
   }
 
   return errors.length === 0
-    ? { ok: true, outcome, pushAllowed: true, errors: [] }
+    ? { ok: true, outcome, pushAllowed: true, reasons: [] }
     : failed(errors);
 }
 
@@ -329,10 +357,9 @@ async function loadPackageCoverage(coreRoot) {
   let loaded;
   try {
     loaded = await import(pathToFileURL(modulePath).href);
-  } catch (loadError) {
+  } catch {
     throw new Error(
-      `Compatible explainer package coverage could not be loaded from coreRoot: ${loadError.message}`,
-      { cause: loadError },
+      'Compatible explainer package coverage could not be loaded from coreRoot.',
     );
   }
   if (
@@ -347,6 +374,29 @@ async function loadPackageCoverage(coreRoot) {
   return loaded;
 }
 
+async function loadTerminalEvidenceContract(coreRoot) {
+  const root = await realpathRequired(coreRoot, 'coreRoot');
+  const modulePath = join(root, 'scripts', 'lib', 'terminal-evidence.mjs');
+  let loaded;
+  try {
+    loaded = await import(pathToFileURL(modulePath).href);
+  } catch {
+    throw new Error(
+      'Compatible terminal evidence could not be loaded from coreRoot.',
+    );
+  }
+  if (
+    loaded.TERMINAL_EVIDENCE_VERSION !== TERMINAL_EVIDENCE_VERSION ||
+    typeof loaded.assertTerminalEvidence !== 'function' ||
+    typeof loaded.readTerminalEvidenceFile !== 'function'
+  ) {
+    throw new Error(
+      `coreRoot must provide ${TERMINAL_EVIDENCE_VERSION} confined validation.`,
+    );
+  }
+  return loaded;
+}
+
 function resolveRunPath(runRoot, path) {
   const target = resolve(runRoot, path);
   assertWithin(runRoot, target, `Manifest path ${path}`);
@@ -470,6 +520,12 @@ function failed(errors) {
     ok: false,
     outcome: 'built-not-durable',
     pushAllowed: false,
-    errors,
+    reasons: [
+      {
+        stage: 'finalization',
+        kind: 'pipeline-failure',
+        count: Math.min(Math.max(errors.length, 1), 50),
+      },
+    ],
   };
 }