@open-agent-toolkit/cli 0.2.5 → 0.2.7

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

@@ -0,0 +1,143 @@
+# Lifecycle intent contract
+
+The OAT adapter resolves `projectExplainer` and `projectRecap` intent without
+reading or mutating project files. Lifecycle callers pass explicit inputs to
+`resolveIntent(...)` and persist only the returned `record`, when present.
+
+## Resolution
+
+Precedence is:
+
+1. lifecycle mode policy;
+2. valid project state;
+3. `workflow.explainers.*` preference;
+4. the built-in `ask` default.
+
+`resolveIntent({ product, mode, state, preference, kickoffRequest, answer,
+now })` is pure. Its result contains the effective `decision`, the
+`resolutionSource`, whether a prompt is needed, an optional state `record`, and
+warnings.
+
+In autonomous mode, `projectRecap` always resolves to `generate` with source
+`autonomous_policy`. A lower-precedence skip or `never` preference is overridden
+and reported as a warning. Autonomous `projectExplainer` resolves to `generate`
+only when the kickoff prompt explicitly requested it; otherwise it resolves to
+`skip` without writing an invalid prompt-source skip record.
+
+In interactive mode, an existing valid project record prevents another prompt.
+Preferences `always` and `never` resolve directly but are not copied into
+project state: doing so would freeze a workflow preference snapshot.
+An unresolved `ask` prompts once. Either answer produces an `interactive`
+record, so a decision made at any lifecycle gate can be persisted and reused.
+
+## State records
+
+Records use the Phase 1 state contract:
+
+```yaml
+oat_project_explainer:
+  decision: generate
+  source: kickoff_prompt
+  decided_at: '2026-07-18T02:30:00Z'
+oat_project_recap:
+  decision: generate
+  source: autonomous_policy
+  decided_at: '2026-07-18T02:30:00Z'
+```
+
+Allowed decision/source pairs are:
+
+| Product            | Allowed pairs                                                            |
+| ------------------ | ------------------------------------------------------------------------ |
+| `projectExplainer` | `generate/interactive`, `skip/interactive`, `generate/kickoff_prompt`    |
+| `projectRecap`     | `generate/interactive`, `skip/interactive`, `generate/autonomous_policy` |
+
+In particular, `skip/autonomous_policy` is invalid.
+
+## Safe persistence
+
+`hashStateContent(content)` creates the optimistic concurrency token used by
+`persistIntent(...)`. A caller reads `state.md`, resolves intent, and supplies
+that content hash with the chosen record. Persistence:
+
+- accepts only a regular `state.md` file and rejects symlinks;
+- validates the closed record and product-specific source matrix;
+- rejects a changed file with `E_INTENT_STALE_WRITE`;
+- replaces only the selected top-level intent block while preserving unrelated
+  frontmatter fields and the Markdown body; and
+- writes a same-directory temporary file and atomically renames it.
+
+On a stale-write conflict, the caller must re-read state, resolve precedence
+again, and decide whether a write is still required. It must not retry the old
+record blindly.
+
+## Tracked-run finalization
+
+`planTrackedRunFinalization(request, context)` is the shared command planner for
+tracked project explainer and recap runs. The request contains `runRoot`,
+`manifestPath`, `commitMode`, and optional `relocatedFrom`. Context supplies the
+repository root, project name, and, for `completion-bookkeeping`, the existing
+full artifact commit SHA.
+
+The returned stages must run in order:
+
+1. In `dedicated` mode, commit exactly the manifest-declared immutable package
+   with `docs(oat): persist <recipe> for <project>`. In
+   `completion-bookkeeping` mode, reuse the caller's existing lifecycle commit.
+2. Replace `$ARTIFACT_COMMIT` with the created full SHA when present, then pass
+   the planned durability request to the compatible core's
+   `recordDurability(...)`. The core verifies commit blobs and updates records;
+   it never invokes Git or creates commits.
+3. Commit only `manifest.json` and `build-record.json` as the evidence update.
+4. Call `verifyTrackedRunFinalization(...)`, then push once so the artifact and
+   evidence commits travel together.
+
+Artifact evidence contains retained fact-base, content, theme, and rendered
+paths. It always excludes mutable `manifest.json` and `build-record.json`.
+Generated Git commands use explicit pathspecs and `commit --only`; callers must
+also snapshot unrelated working-tree changes before execution and supply the
+before/after lists to the verifier. A mismatch prevents pushing.
+
+An evidence-verification failure is a successful finalizer termination with
+run outcome `built-not-durable`: commit the warning-bearing mutable records and
+push them with the artifact commit. It does not block project completion. A
+later attempt reuses the same artifact commit, supplies the current HEAD as
+`currentHead`, invokes core verification again, and appends a new evidence
+commit. If the manifest already contains matching durable commit evidence, the
+planner returns `complete` with no commands, making repeat termination
+idempotent.
+
+For archive relocation, `relocatedFrom` identifies the prior active run for
+caller reporting. The current run's immutable paths and the export bookkeeping
+commit are submitted to the core; core evidence supersession remains the
+authoritative relocation record.
+
+## Completion-time archive relocation
+
+Completion consumes the machine-readable `oat project archive --json` report.
+When a recap was selected, `projectRecapExport.sourceRunRoot`,
+`projectRecapExport.exportRoot`, and
+`projectRecapExport.manifest.relativePath` identify the relocation. The caller
+must not predict the dated export path or substitute the gitignored local
+archive.
+
+Archive completion is exactly two commits: the lifecycle bookkeeping commit, then the exported recap evidence commit. The bookkeeping commit contains the
+tracked export and active-tree deletion and is passed to the finalizer as the
+existing artifact commit in `completion-bookkeeping` mode. The finalizer
+attests only immutable package paths under the reported export root. The
+second commit contains only the updated exported `manifest.json` and
+`build-record.json`; one push follows both commits.
+
+The exported-path evidence supersedes the selected run's prior active-path evidence. Mutable records are never part of their own commit evidence, and no
+path under `.oat/projects/archived/` is evidence.
+
+Failure to verify the exported commit evidence is non-blocking. The tracked
+export remains committed, the mutable records retain the warning and
+`built-not-durable` outcome, and the evidence-record commit and push still
+complete. A later attestation may recover durability without repeating the
+archive.
+
+Post-archive summary and PR recap links target `projectRecapExport.exportRoot`
+under `.oat/repo/reference/project-recaps/` on the current head branch. The
+tracked summary export and the PR body may carry that link; the gitignored
+archive never does.

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

@@ -0,0 +1,143 @@
+# Private-wrapper migration
+
+This runbook migrates the externally owned private wrapper from the monolithic
+`oat-explainer-kit` 0.4.1 workflow to the frozen v1 pre/core/post seam. Keep the
+0.4.1 installation and its private configuration available until one unchanged
+release candidate passes every acceptance gate.
+
+## Prepare the private wrapper
+
+1. Back up the installed 0.4.1 skill, private presets, Stoa configuration, and
+   Google Docs settings. Confirm the backup contains `SKILL.md`, scripts,
+   references, and templates.
+2. Install the candidate `explainer-kit` at user scope and verify that the
+   wrapper resolves that installed copy, never a source checkout.
+3. Change wrapper pre-resolution to produce one
+   `explainer-kit.run-request/v1`. Keep preset selection, vault/Stoa paths,
+   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
+   private link maintenance as post-run work.
+
+Do not add a plugin, inject private work between core stages, or add private
+lanes to public OAT config.
+
+### Private `presets.example.json`
+
+The private wrapper's `personal-oat` example should carry the confirmed public
+root:
+
+```json
+{
+  "presets": {
+    "personal-oat": {
+      "publicBaseUrl": "https://dy4vzrzaexuy5.cloudfront.net"
+    }
+  }
+}
+```
+
+Copy `presets.example.json` to an untracked `presets.json` before adding
+accounts or authentication details.
+
+### Private Stoa configuration
+
+The eventual private Stoa configuration may use the same confirmed public root
+to create manifest-derived links:
+
+```json
+{
+  "explainerLinks": {
+    "publicBaseUrl": "https://dy4vzrzaexuy5.cloudfront.net",
+    "source": "explainer-kit.manifest/v1"
+  }
+}
+```
+
+This is private-wrapper migration/config context, not a public core default or
+neutral fixture.
+
+## Release-candidate sequence
+
+1. Build and retain the packaged RC in a dedicated builder-owned directory;
+   record its immutable RC identity:
+
+   ```bash
+   node tools/release/build-explainer-rc.mjs \
+     --output dist/explainer-kit-rc \
+     --record .oat/repo/reference/explainer-kit-acceptance/v1/rc.json
+   ```
+
+   The builder rejects repository/source roots, symlinks, and unowned existing
+   directories. Reuse only an output carrying its ownership marker.
+
+2. Run packaged direct-core and OAT-adapter build-only smoke tests.
+3. Migrate the real private wrapper against that exact RC.
+4. Run the operator-owned wrapper E2E as an executable pre/core/post sequence:
+   resolve the private preset and external request; invoke the packaged core;
+   then publish the manifest, retain its complete receipt, and perform
+   vault/Stoa, Google Docs, and personal-link work. Verify all post-run evidence
+   against the immutable core execution record.
+5. Run the live S3/CDN acceptance against the same unchanged RC.
+6. Promote only when both retained acceptance records pass and reference the
+   same RC identity.
+
+Every packaged invocation supplies the retained artifacts explicitly; there is
+no current-working-directory fallback. The wrapper core stage does not declare
+post-run receipt evidence:
+
+```bash
+node tools/release/run-explainer-rc.mjs \
+  --rc-manifest .oat/repo/reference/explainer-kit-acceptance/v1/rc.json \
+  --artifacts-dir dist/explainer-kit-rc \
+  --entry scripts/run.mjs \
+  --record .oat/repo/reference/explainer-kit-acceptance/v1/private-wrapper-execution.json \
+  -- \
+  --request /path/to/private/run-request.json
+```
+
+The packaged CLI emits exactly one complete JSON result document; pretty
+printing across lines is valid and progress text is not. After that command
+returns, the private wrapper publishes and links the core manifest. Retain
+`private-wrapper-manifest.json`,
+`private-wrapper-publish-receipt.json`, and
+`private-wrapper-result.json` beside the RC identity. Wrapper acceptance reads
+and validates the full receipt as a separate post-run stage and rejects a
+foreign run ID, sentinel, artifact set, or manifest hash even when caller-owned
+files repeat the same receipt hash.
+
+The live connector stage is a separate packaged invocation:
+
+```bash
+node tools/release/run-explainer-rc.mjs \
+  --rc-manifest .oat/repo/reference/explainer-kit-acceptance/v1/rc.json \
+  --artifacts-dir dist/explainer-kit-rc \
+  --entry scripts/publish.mjs \
+  --record .oat/repo/reference/explainer-kit-acceptance/v1/live-publish-result.json \
+  -- \
+  --request .oat/repo/reference/explainer-kit-acceptance/v1/live-publish-request.json \
+  --receipt .oat/repo/reference/explainer-kit-acceptance/v1/publish-receipt.json \
+  --confirm-publish
+```
+
+Retain the execution record produced by that command. Acceptance binds it to
+the canonical request, manifest, receipt, and core run ID and rejects stale
+cross-run evidence.
+
+The in-repository compatibility fixture is a development guard. It does not
+satisfy the operator-owned real-wrapper gate.
+
+## Rollback
+
+If migration or acceptance fails, do not promote the candidate:
+
+1. Preserve the failed candidate's sanitized diagnostics and issue a new RC
+   only after correcting the public seam or private wrapper.
+2. Restore the backed-up 0.4.1 skill and private configuration.
+3. Remove the candidate user-scope core and refresh provider views with
+   `oat sync --scope all`.
+4. Verify one known-good 0.4.1 build before resuming normal wrapper use.
+
+Do not retire the backup until the unchanged promoted RC has passed the
+operator-owned wrapper and live-publish gates.

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

@@ -0,0 +1,103 @@
+import { access, readFile, realpath } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+
+const RECIPE_ARTIFACTS = Object.freeze({
+  'project-explainer': ['plan', 'design', 'spec'],
+  'project-recap': ['plan', 'design', 'spec', 'implementation', 'summary'],
+});
+
+export async function bindProjectSources({
+  projectRoot,
+  recipe,
+  suppliedFactBasePath,
+}) {
+  if (!projectRoot) {
+    throw new TypeError('projectRoot is required to bind OAT artifacts.');
+  }
+  const artifactIds = RECIPE_ARTIFACTS[recipe];
+  if (!artifactIds) {
+    throw new Error(`Unsupported OAT project recipe: ${recipe}`);
+  }
+
+  const canonicalProjectRoot = await realpath(projectRoot);
+  if (suppliedFactBasePath) {
+    const path = await realpath(suppliedFactBasePath);
+    return {
+      factBase: {
+        mode: 'supplied',
+        path,
+        freshnessPolicy: 'live-wins',
+      },
+      reviewedSource: {
+        kind: 'approved-fact-base',
+        locator: path,
+      },
+    };
+  }
+
+  const sourceSetId = basename(canonicalProjectRoot);
+  const sources = [];
+  for (const id of artifactIds) {
+    const locator = join(canonicalProjectRoot, `${id}.md`);
+    try {
+      await access(locator);
+    } catch (error) {
+      if (error?.code === 'ENOENT') continue;
+      throw error;
+    }
+    sources.push({
+      id,
+      kind: 'file',
+      locator: await realpath(locator),
+      role: 'project',
+      sourceSetId,
+      authoritativeFor: authoritativeTopics(id),
+    });
+  }
+  if (sources.length === 0) {
+    throw new Error(
+      `No approved OAT lifecycle artifacts were found for ${recipe}.`,
+    );
+  }
+
+  return {
+    factBase: {
+      mode: 'federated',
+      freshnessPolicy: 'live-wins',
+      sources,
+    },
+    reviewedSource: {
+      kind: 'approved-oat-artifacts',
+      locator: canonicalProjectRoot,
+    },
+    sourceLoader: loadOatArtifact,
+  };
+}
+
+async function loadOatArtifact(source) {
+  const text = (await readFile(source.locator, 'utf8')).trim();
+  return {
+    claims: [
+      {
+        id: source.id,
+        text,
+        locator: source.locator,
+      },
+    ],
+  };
+}
+
+function authoritativeTopics(id) {
+  return {
+    plan: ['phases', 'validation-approach'],
+    design: ['planned-architecture', 'decisions', 'risks'],
+    spec: ['original-request', 'requirements'],
+    implementation: [
+      'key-agent-decisions',
+      'as-built-architecture',
+      'implementation-record',
+      'validation-evidence',
+    ],
+    summary: ['outcome'],
+  }[id];
+}

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

@@ -0,0 +1,127 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+
+export const CORE_INSTALL_COMMAND = 'oat tools install utility --scope user';
+export const CORE_UPDATE_COMMAND =
+  'oat tools update --pack utility --scope user';
+
+export async function checkCoreCompatibility({
+  adapterRoot,
+  userSkillsRoot = join(homedir(), '.agents', 'skills'),
+  minimumVersion,
+}) {
+  const minimum = parseVersion(minimumVersion);
+  if (minimum === null) {
+    throw new TypeError(
+      `minimumVersion must be a semantic version, received: ${minimumVersion}`,
+    );
+  }
+
+  const canonicalAdapterRoot = resolve(adapterRoot);
+  const adapterSkillsRoot = dirname(canonicalAdapterRoot);
+  const canonicalUserSkillsRoot = resolve(userSkillsRoot);
+  const coreRoot = join(canonicalUserSkillsRoot, 'explainer-kit');
+  if (
+    basename(canonicalAdapterRoot) !== 'oat-explainer-kit' ||
+    basename(adapterSkillsRoot) !== 'skills' ||
+    basename(dirname(adapterSkillsRoot)) !== '.agents' ||
+    basename(canonicalUserSkillsRoot) !== 'skills' ||
+    basename(dirname(canonicalUserSkillsRoot)) !== '.agents'
+  ) {
+    return failure({
+      code: 'invalid-layout',
+      coreRoot,
+      minimumVersion,
+      message:
+        'oat-explainer-kit is not running from an installed canonical .agents/skills path.',
+      guidance: CORE_INSTALL_COMMAND,
+    });
+  }
+
+  let skill;
+  try {
+    skill = await readFile(join(coreRoot, 'SKILL.md'), 'utf8');
+  } catch (error) {
+    if (error && typeof error === 'object' && error.code === 'ENOENT') {
+      return failure({
+        code: 'missing',
+        coreRoot,
+        minimumVersion,
+        message: 'A canonical installed explainer-kit core was not found.',
+        guidance: CORE_INSTALL_COMMAND,
+      });
+    }
+    throw error;
+  }
+
+  const installedVersion = readFrontmatterVersion(skill);
+  const installed = parseVersion(installedVersion);
+  if (
+    installed === null ||
+    installed.major !== minimum.major ||
+    installed.minor < minimum.minor
+  ) {
+    return failure({
+      code: 'incompatible',
+      coreRoot,
+      installedVersion,
+      minimumVersion,
+      message: installedVersion
+        ? `Installed explainer-kit ${installedVersion} is incompatible with required ${minimumVersion}.`
+        : 'Installed explainer-kit has no valid version.',
+      guidance: CORE_UPDATE_COMMAND,
+    });
+  }
+
+  return {
+    ok: true,
+    code: 'compatible',
+    coreRoot,
+    installedVersion,
+    minimumVersion,
+    message: `Installed explainer-kit ${installedVersion} is compatible.`,
+    guidance: null,
+  };
+}
+
+function failure({
+  code,
+  coreRoot,
+  installedVersion = null,
+  minimumVersion,
+  message,
+  guidance,
+}) {
+  return {
+    ok: false,
+    code,
+    coreRoot,
+    installedVersion,
+    minimumVersion,
+    message,
+    guidance,
+  };
+}
+
+function readFrontmatterVersion(content) {
+  const match = content.match(/^version:\s*([^\s#]+)\s*(?:#.*)?$/m);
+  return match?.[1] ?? null;
+}
+
+function parseVersion(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const match = value.match(
+    /^(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?$/,
+  );
+  if (!match) {
+    return null;
+  }
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+  };
+}