@open-agent-toolkit/cli 0.2.73 → 0.2.74

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

@@ -5,41 +5,28 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion
 metadata:
-  version: 1.0.8
+  version: 1.0.9
 ---
 
 # OAT Explainer Kit
 
-Adapt OAT project context into the versioned request consumed by the canonical
-`explainer-kit` core.
+Adapt OAT project and program context into the agent-authored flow provided by
+the canonical `explainer-kit` core.
 
 ## Responsibilities
 
 - Require a compatible installed `explainer-kit` core.
-- Resolve typed OAT configuration with source attribution.
-- Derive canonical project or repository output roots.
+- Resolve explainer defaults and preserve their source attribution.
+- Derive canonical project or repository output roots with
+  `scripts/resolve-paths.mjs`.
 - Bind OAT lifecycle artifacts to generic recipe source roles.
-- Probe recap seam availability before an unattended run is attempted.
-- Resolve project explainer and recap intent before invoking the core.
-- Resolve one provider-neutral set planner for unattended project recaps.
-- Require lifecycle callers to construct a brief-aware author seam.
-- Require first-class browser-evidence and whole-set visual-review providers
-  for unattended project recaps.
+- Resolve and persist project-explainer and project-recap intent.
+- Run the core's bundle, agent-authoring, verification, and recording stages.
+- Return the terminal outcome and run path to the lifecycle caller.
 
-## Dependency Direction
-
-This adapter depends on `explainer-kit`; the core never depends on this adapter.
-Fail closed when the compatible installed core is unavailable. Do not copy core
-runtime logic into the adapter.
-
-Private wrappers use the core's frozen pre-resolution/request/core-run/manifest/
-post-run seam directly; they do not route presets, vaults, Google Docs, Stoa, or
-personal destinations through this adapter. For the release-candidate sequence,
-rollback, and operator-owned real-wrapper gate, use `references/migration.md`.
-
-Before reading OAT config or invoking the core, call
+Before reading OAT config or preparing a bundle, call
 `scripts/check-core.mjs#checkCoreCompatibility` with this installed skill
-directory and minimum core version `2.1.0`. Continue only when it returns
+directory and the exported `MINIMUM_CORE_VERSION`. Continue only when it returns
 `ok: true`.
 
 - Missing core: stop and show
@@ -54,97 +41,49 @@ Resolve adapter scripts and references relative to this installed skill
 directory. Resolve the core only from its installed canonical skill path. Never
 fall back to a repository source checkout.
 
-## Core Invocation
-
-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.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;
-5. creates one `ExplainerRunRequestV1`;
-6. calls the installed core's `runExplainer(request, options)` export; and
-7. consumes and returns the resulting `explainer-kit.manifest/v1`.
-
-`project-explainer` binds `plan.md`, `design.md`, and `spec.md`.
-`project-recap` additionally binds `implementation.md` and `summary.md`.
-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 an unattended `project-recap`, call
-`scripts/probe-recap-seams.mjs#probeRecapSeams` with the seam inputs you are
-about to pass. The probe is pure and checks all five required seams — author,
-fact critic, browser session, visual critic, and set planner — using the same
-rules `run.mjs` applies. `seams-unavailable` means no provider is configured
-for a required seam: pass the probe result to the intent resolver as
-`seamProbe`, which returns a recordable `skip` with source `capability_probe`
-and a warning. `seams-invalid` means a supplied seam violates a resolution
-rule: fail closed and report the configuration error; it is never a skip. When
-the probe returns `ok: true`, invoke the adapter with unchanged behavior, and
-treat any later failure as `failed` rather than as a skip.
-
-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
-`planSetModulePath` naming a module with a `planSet` function export. The
-adapter resolves this executable capability and passes only the callback to the
-core. It never persists provider configuration or module paths.
-
-Construct exactly one provider-neutral author seam in both modes: in-process
-callers supply `author`, while JSON/CLI callers supply `authorModulePath` naming
-a module with an `author` function export. The core invokes that callback once
-per planned artifact. Every request carries the immutable shared `setContext`,
-the matching `plannedArtifact`, the recipe brief, theme, and any
-recipe-selected artistic shell. Those bundled inputs are the required
-medium-specific guidance; an optional visual-explainer installation may enhance
-provider execution but is never required. The adapter validates and resolves
-executable inputs before passing them to `core.runExplainer`; callbacks and
-module paths never enter the persisted run request.
-
-Also read `references/visual-review-callback.md`. Unattended `project-recap`
-runs require exactly one trusted launched-Chromium browser session and one
-whole-set visual critic. In-process callers supply a branded `browserSession`
-created by the compatible core and `visualCritic`; JSON/CLI callers supply
-`browserSessionModulePath` and `visualCriticModulePath`, naming modules with
-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,
-forged, or deterministic fixture session fails production validation before the
-core runs. A runtime browser or visual-review failure is retained by the core
-as `built-needs-review`, never as a successful durability or publication
-outcome.
-
-Unattended project runs pass `approved-oat-artifacts` provenance to the core's
-content-approval seam and never prompt. Automated completion and
-implementation-tail recaps always use `mode: unattended`.
-
-Federated runs still require an explicit provider-neutral critic callback.
-In-process callers may supply `critic` (or `coreOptions.critic` for
-compatibility); JSON/CLI callers supply `criticModulePath` naming a module whose
-`critic` export implements the same provider-neutral request/result contract.
-Supply exactly one critic seam. Approval provenance does not bypass fact
-reconciliation. Do not read private presets, vault files, provider
-configuration, or ambient destination configuration.
+## Generate
+
+Use this flow for `project-recap`, `program-recap`, or `project-explainer`.
+Lifecycle callers use `mode: unattended` and never prompt.
+
+1. Check the installed core as described above.
+2. Resolve intent with `scripts/resolve-intent.mjs`. Persist a returned record
+   with `scripts/persist-intent.mjs` before generation. A persisted `skip`
+   ends the flow without bundling or authoring.
+3. Resolve only the `explainers.defaults.*` theme values with
+   `scripts/resolve-config.mjs`.
+4. Resolve the parent output root with
+   `scripts/resolve-paths.mjs#resolveExplainerOutputRoot`.
+5. Resolve approved inputs with
+   `scripts/bind-project-sources.mjs`. `project-explainer` uses `plan.md`,
+   `design.md`, `spec.md`, and optional `discovery.md`. `project-recap` also
+   uses completion, summary, project-log, and optional orchestration material.
+   `program-recap` uses the program record and its reconciled summaries.
+6. Run the installed core's `scripts/bundle.mjs` with the selected recipe,
+   input mode, resolved theme JSON, and run root. If it reports `reuse: true`,
+   return that satisfied run without authoring or recording again.
+7. The host agent reads the recipe's `briefRef`, the core's
+   `references/recap-authoring.md`, `source/fact-base.json`,
+   `source/ledger.json`, and `theme.resolved.json`, then authors exactly one
+   `site/index.html` from the recipe shell.
+8. Run `scripts/verify.mjs`. Use the first available rung: host browser capture
+   and inspection at 320, 768, and 1440 pixels; the Playwright probe; or the
+   browser-free `none` rung. Browser-free checks always run.
+9. Run `scripts/record.mjs` with the recipe, slug, `mode: unattended`, and
+   resolved theme. Do not write into the run root after recording.
+10. Return the run path, `runId`, and outcome from
+    `explainer-kit.manifest/v2`. `built` and `built-needs-review` satisfy a
+    `generate` intent; `failed` and `incomplete` do not.
+
+On `failed` or `incomplete`, show the sanitized cause and require retry or an
+explicit skip. A skip after an attempted run must be persisted as
+`skip/failed_attempt` with `failed_attempt_evidence` set to the project-relative
+`explainers/<run-slug>/manifest.json`, or to that run's `failure.json` when
+recording never occurred. The deployed completion consumer validates canonical
+project/run containment and the terminal evidence contract before returning
+the trusted path to `scripts/check-terminal-outcome.mjs`.
+`skip/capability_probe` remains readable only for an existing legacy intent and
+must not be newly written.
 
 ## Progress Indicators (User-Facing)
 
@@ -156,5 +95,6 @@ OAT ▸ EXPLAINER KIT
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-Report compatibility, config, intent, source-binding, core-run, and finalization
-stages. Lifecycle-triggered unattended runs must not prompt.
+Report compatibility, intent, source binding, bundle, authoring, verification,
+recording, and outcome stages. Lifecycle-triggered unattended runs must not
+prompt.

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

@@ -3,41 +3,21 @@
 `oat-explainer-kit` is the OAT-aware boundary around the config-blind
 `explainer-kit` core. The adapter reads each supported stored value with
 `oat config get <key> --json` and preserves its `source` metadata while
-constructing an `explainer-kit.run-request/v1`.
+resolving the theme used by `bundle.mjs`.
 
-## Supported keys
+## Supported explainer defaults
 
-| Key                                    | Stored scopes       | Built-in default |
-| -------------------------------------- | ------------------- | ---------------- |
-| `explainers.defaults.style`            | local, shared, user | `clean-neutral`  |
-| `explainers.defaults.palette`          | local, shared, user | unset            |
-| `explainers.defaults.visualProfile`    | local, shared, user | unset            |
-| `explainers.defaults.themeBundlePath`  | local, shared       | unset            |
-| `explainers.publish.provider`          | shared              | unset            |
-| `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`            |
+| Key                                   | Stored scopes       | Built-in default |
+| ------------------------------------- | ------------------- | ---------------- |
+| `explainers.defaults.style`           | local, shared, user | `clean-neutral`  |
+| `explainers.defaults.palette`         | local, shared, user | unset            |
+| `explainers.defaults.visualProfile`   | local, shared, user | unset            |
+| `explainers.defaults.themeBundlePath` | local, shared       | unset            |
 
-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.
-
-## Seams are invocation inputs, not configuration
-
-No supported key names an author, fact critic, browser session, visual critic,
-or set planner. Every seam is supplied per invocation as a callback or a module
-entry point, so seam availability is discovered by
-`scripts/probe-recap-seams.mjs#probeRecapSeams` against the inputs a caller is
-about to pass, not read from stored config. A host on which those inputs are
-absent has no configuration to correct: the probe reports `seams-unavailable`
-and the lifecycle caller records a `skip / capability_probe` recap intent. The
-`workflow.explainers.projectRecap` preference expresses whether a host _wants_
-a recap and cannot make an unavailable seam available.
+Explicit runtime inputs may override these four keys for one invocation. They
+do not write config. Recipe, slug, fact-base path, output root, and art
+direction are invocation inputs rather than config keys and are rejected from
+the runtime config-override map.
 
 ## Source-sensitive paths
 
@@ -51,39 +31,15 @@ The four curated styles are `clean-neutral`, `business-corporate`,
 `navy-ocean`, and `dark-edgy`. A theme bundle path has highest precedence,
 followed by an explicit style. Legacy palette and visual-profile fields remain
 accepted as an advanced compatibility path and produce deprecation warnings.
-When no source explicitly configures any selection, the adapter leaves the
-request theme empty so the core records its visible `clean-neutral` fallback
-warning. The adapter passes a resolved bundle as `theme.suppliedBundlePath`.
-
-## Publish block
-
-`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.
+When no source explicitly configures a selection, the core records its visible
+`clean-neutral` fallback.
 
 ## Canonical output roots
 
-- Active project: `<resolved-project-path>/explainers/`, for both shared and
-  local projects.
-- Non-project OAT run: `.oat/repo/reference/explainers/`.
-- Direct core caller: an explicit `outputRoot`; the OAT adapter does not infer
-  one.
-
-Derived OAT roots reject traversal and must remain inside their canonical root
-after symlink resolution. The adapter validates all config and paths before the
-core creates output.
-
-## Run-request translation
+- Active project: `<resolved-project-path>/explainers/`.
+- Program or repository run: `.oat/repo/reference/explainers/`.
+- Direct core caller: an explicit parent output root.
 
-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/v2` whose `siteRoot` and
-`manifestPath` point inside `<outputRoot>/<slug>/`.
+Derived OAT roots reject traversal and remain inside their canonical root after
+symlink resolution. The adapter validates config and paths before the core
+creates output.