@open-agent-toolkit/cli 0.2.40 → 0.2.45

package/assets/skills/oat-project-complete/scripts/resolve-completion-retry.mjs

@@ -0,0 +1,134 @@
+import { lstat, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import {
+  detectCompletionReceiptCandidate,
+  recoverCompletionPinSource,
+  recoverCompletionReceipts,
+} from './recover-completion-receipts.mjs';
+
+const SKIPPED_MUTATIONS = [
+  'project-log',
+  'review-move',
+  'complete-state',
+  'active-pointer',
+  'pr-artifact',
+];
+
+function completionRetryError(message) {
+  const error = new Error(message);
+  error.code = 'E_COMPLETION_RETRY';
+  return error;
+}
+
+function parseArguments(argv) {
+  const result = { evidencePaths: [] };
+  for (let index = 0; index < argv.length; index += 2) {
+    const flag = argv[index];
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw completionRetryError(`Missing value for ${flag ?? 'argument'}.`);
+    }
+    if (flag === '--project-path') result.projectPath = value;
+    else if (flag === '--retained-ref') result.retainedRef = value;
+    else if (flag === '--pr-artifact') result.prArtifactPath = value;
+    else if (flag === '--evidence-path') result.evidencePaths.push(value);
+    else if (flag === '--remote') result.remote = value;
+    else throw completionRetryError(`Unsupported argument: ${flag}.`);
+  }
+  return result;
+}
+
+async function resolvePrArtifact(projectPath) {
+  let names;
+  try {
+    names = await readdir(join(projectPath, 'pr'));
+  } catch (error) {
+    throw completionRetryError(
+      `Recognized completion receipt requires exactly one PR artifact: ${error.message}`,
+    );
+  }
+
+  const candidates = [];
+  for (const name of names.sort()) {
+    if (!/^project-pr-.*\.md$/.test(name)) continue;
+    const candidate = join(projectPath, 'pr', name);
+    const stat = await lstat(candidate);
+    if (stat.isFile() && !stat.isSymbolicLink()) {
+      candidates.push(`pr/${name}`);
+    }
+  }
+  if (candidates.length !== 1) {
+    throw completionRetryError(
+      'Recognized completion receipt requires exactly one regular, non-symlinked PR artifact.',
+    );
+  }
+  return candidates[0];
+}
+
+export async function resolveCompletionRetry(options) {
+  const candidateResult = await detectCompletionReceiptCandidate(options);
+  if (!candidateResult.candidate) {
+    return {
+      status: 'continue',
+      route: 'normal',
+      candidate: false,
+      nextStep: '3.7',
+      skipMutations: false,
+      skippedMutations: [],
+    };
+  }
+
+  const prArtifactPath =
+    options.prArtifactPath ?? (await resolvePrArtifact(options.projectPath));
+  if (candidateResult.candidateType === 'pin-source') {
+    const pinSource = await recoverCompletionPinSource({
+      ...options,
+      prArtifactPath,
+    });
+    return {
+      ...pinSource,
+      route: 'pin-source',
+      candidate: true,
+      nextStep: '8.6',
+      skipMutations: true,
+      skippedMutations: SKIPPED_MUTATIONS,
+      prArtifactPath,
+    };
+  }
+  const receipts = await recoverCompletionReceipts({
+    ...options,
+    prArtifactPath,
+  });
+
+  return {
+    ...receipts,
+    route: 'recovery',
+    candidate: true,
+    nextStep: '7.5',
+    skipMutations: true,
+    skippedMutations: SKIPPED_MUTATIONS,
+    prArtifactPath,
+  };
+}
+
+async function main(argv) {
+  return resolveCompletionRetry(parseArguments(argv));
+}
+
+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-project-complete/scripts/validate-nonarchive-lifecycle-receipt.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import {
+  basename,
+  dirname,
+  extname,
+  isAbsolute,
+  relative,
+  resolve,
+  sep,
+} from 'node:path';
+
+function fail(message) {
+  process.stderr.write(`Invalid non-archive lifecycle receipt: ${message}\n`);
+  process.exit(1);
+}
+
+function git(cwd, args) {
+  try {
+    return execFileSync('git', args, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+  } catch (error) {
+    const detail =
+      error?.stderr?.toString().trim() || error?.message || String(error);
+    fail(detail);
+  }
+}
+
+function gitRaw(cwd, args) {
+  try {
+    return execFileSync('git', args, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (error) {
+    const detail =
+      error?.stderr?.toString().trim() || error?.message || String(error);
+    fail(detail);
+  }
+}
+
+function gitSucceeds(cwd, args) {
+  try {
+    execFileSync('git', args, {
+      cwd,
+      stdio: ['ignore', 'ignore', 'ignore'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const [recordArgument, commit, projectName] = process.argv.slice(2);
+if (!recordArgument || !/^[0-9a-f]{40}$/.test(commit ?? '') || !projectName) {
+  fail('expected <record-path> <full-commit-sha> <project-name>.');
+}
+
+const unresolvedRecordPath = resolve(recordArgument);
+if (!existsSync(unresolvedRecordPath)) {
+  fail('record path does not exist; restore the synced discovery record.');
+}
+const recordPath = realpathSync(unresolvedRecordPath);
+const repoRoot = realpathSync(
+  git(dirname(recordPath), ['rev-parse', '--show-toplevel']),
+);
+const recordRelative = relative(repoRoot, recordPath);
+if (
+  recordRelative === '' ||
+  recordRelative === '..' ||
+  recordRelative.startsWith(`..${sep}`) ||
+  isAbsolute(recordRelative)
+) {
+  fail('record path is outside the repository root.');
+}
+const gitRecordPath = recordRelative.split(sep).join('/');
+if (basename(gitRecordPath, extname(gitRecordPath)) !== projectName) {
+  fail('record filename must match the project name.');
+}
+if (!gitSucceeds(repoRoot, ['merge-base', '--is-ancestor', commit, 'HEAD'])) {
+  fail('receipt commit must be an ancestor of the current repository HEAD.');
+}
+const changedPaths = git(repoRoot, [
+  'diff-tree',
+  '--root',
+  '--no-commit-id',
+  '--name-only',
+  '-r',
+  '--format=',
+  commit,
+])
+  .split('\n')
+  .filter(Boolean);
+if (changedPaths.length !== 1 || changedPaths[0] !== gitRecordPath) {
+  fail('receipt commit must change exactly the synced discovery record path.');
+}
+const expectedSubject = `chore(oat): complete synced project ${projectName}`;
+const subject = git(repoRoot, ['show', '-s', '--format=%s', commit]);
+if (subject !== expectedSubject) {
+  fail(`commit subject must be "${expectedSubject}".`);
+}
+
+let committedRecordContents;
+let record;
+try {
+  committedRecordContents = gitRaw(repoRoot, [
+    'show',
+    `${commit}:${gitRecordPath}`,
+  ]);
+  record = JSON.parse(committedRecordContents);
+} catch (error) {
+  fail(
+    `committed record is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+  );
+}
+if (readFileSync(recordPath, 'utf8') !== committedRecordContents) {
+  fail('working-tree record content must exactly match the receipt commit.');
+}
+const expectedKeys = new Set([
+  'archiveSnapshot',
+  'completedAt',
+  'createdAt',
+  'ref',
+  'remote',
+  'schemaVersion',
+  'scope',
+  'slug',
+  'status',
+]);
+if (
+  !record ||
+  typeof record !== 'object' ||
+  Array.isArray(record) ||
+  Object.keys(record).some((key) => !expectedKeys.has(key)) ||
+  record.schemaVersion !== 1 ||
+  record.slug !== projectName ||
+  record.scope !== 'synced' ||
+  record.ref !== `refs/oat/projects/${projectName}` ||
+  record.remote !== 'origin' ||
+  record.status !== 'complete' ||
+  typeof record.createdAt !== 'string' ||
+  Number.isNaN(Date.parse(record.createdAt)) ||
+  typeof record.completedAt !== 'string' ||
+  Number.isNaN(Date.parse(record.completedAt)) ||
+  (record.archiveSnapshot !== undefined &&
+    (typeof record.archiveSnapshot !== 'string' ||
+      record.archiveSnapshot.length === 0))
+) {
+  fail(
+    'committed record must be a complete synced record with the exact project identity and lifecycle content.',
+  );
+}
+
+process.stdout.write(`${commit}\n`);

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-design
-version: 2.3.0
+version: 2.3.1
 description: Use when discovery is complete and implementation-ready decisions are needed. Runs a collaborative, selective collaborative, or draft-and-review design flow, confirms requirements and produces both `spec.md` and `design.md`, and commits artifacts before the user-review gate.
 disable-model-invocation: true
 user-invocable: true
@@ -321,8 +321,14 @@ oat_last_updated: { today }
 Commit separately (keeps history clean; lets reviewers fetch spec independently):
 
 ```bash
-git add "$PROJECT_PATH/spec.md"
-git commit -m "docs: confirm requirements for {project-name}"
+PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || { echo "oat: cannot resolve project scope for $PROJECT_PATH; refusing to commit artifacts" >&2; exit 1; }
+# fail closed: never fall back to branch bookkeeping when scope resolution fails
+if [ "$PROJECT_SCOPE" = "synced" ]; then
+  oat project push "$PROJECT_PATH" --message "docs: confirm requirements for {project-name}" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
+else
+  git add "$PROJECT_PATH/spec.md"
+  git commit -m "docs: confirm requirements for {project-name}"
+fi
 ```
 
 ### Step 2.5: Approach Reaffirmation (one divergent moment)
@@ -573,8 +579,14 @@ Even when no HiLL checkpoint is configured, the artifact is committed — consis
 #   oat_ready_for: null
 #   oat_last_updated: {today}
 
-git add "$PROJECT_PATH/spec.md" "$PROJECT_PATH/design.md" "$PROJECT_PATH/state.md"
-git diff --cached --quiet || git commit -m "docs: draft design for {project-name} (awaiting review)"
+PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || { echo "oat: cannot resolve project scope for $PROJECT_PATH; refusing to commit artifacts" >&2; exit 1; }
+# fail closed: never fall back to branch bookkeeping when scope resolution fails
+if [ "$PROJECT_SCOPE" = "synced" ]; then
+  oat project push "$PROJECT_PATH" --message "docs: draft design for {project-name} (awaiting review)" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
+else
+  git add "$PROJECT_PATH/spec.md" "$PROJECT_PATH/design.md" "$PROJECT_PATH/state.md"
+  git diff --cached --quiet || git commit -m "docs: draft design for {project-name} (awaiting review)"
+fi
 ```
 
 **Step 6b: Read state.md frontmatter**
@@ -610,8 +622,14 @@ Wait for user response:
 - Approval → continue to Step 7.
 - Change requests → revise the relevant section(s), re-run Step 5
   (Self-Review), then MAKE A NEW COMMIT:
-    git add "$PROJECT_PATH/spec.md" "$PROJECT_PATH/design.md"
-    git commit -m "docs: revise design after user review feedback"
+    PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || { echo "oat: cannot resolve project scope for $PROJECT_PATH; refusing to commit artifacts" >&2; exit 1; }
+    # fail closed: never fall back to branch bookkeeping when scope resolution fails
+    if [ "$PROJECT_SCOPE" = "synced" ]; then
+      oat project push "$PROJECT_PATH" --message "docs: revise design after user review feedback" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
+    else
+      git add "$PROJECT_PATH/spec.md" "$PROJECT_PATH/design.md"
+      git commit -m "docs: revise design after user review feedback"
+    fi
   Re-present this prompt.
 - If user does not approve yet (wants to pause without explicit change
   requests): keep design frontmatter as oat_status: in_progress /
@@ -759,8 +777,14 @@ Reach this commit step only after the configured gate passes or resolves
 according to its `onFailure` policy.
 
 ```bash
-git add "$PROJECT_PATH/design.md" "$PROJECT_PATH/state.md"
-git diff --cached --quiet || git commit -m "chore(oat): mark design complete for {project-name}"
+PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || { echo "oat: cannot resolve project scope for $PROJECT_PATH; refusing to commit artifacts" >&2; exit 1; }
+# fail closed: never fall back to branch bookkeeping when scope resolution fails
+if [ "$PROJECT_SCOPE" = "synced" ]; then
+  oat project push "$PROJECT_PATH" --message "chore(oat): mark design complete for {project-name}" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
+else
+  git add "$PROJECT_PATH/design.md" "$PROJECT_PATH/state.md"
+  git diff --cached --quiet || git commit -m "chore(oat): mark design complete for {project-name}"
+fi
 ```
 
 ### Step 9: Output Summary

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-discover
-version: 2.2.0
+version: 2.2.1
 description: Use when the user explicitly asks to continue discovery for an active spec-driven OAT project — e.g. "continue discovery", "run discovery", or confirms a previously offered discovery step. Do NOT auto-invoke for new ideas or quick-mode projects. Gathers requirements and context before spec/design.
 disable-model-invocation: false
 user-invocable: true
@@ -549,14 +549,27 @@ according to its `onFailure` policy.
 During implementation of OAT itself, use standard commit format.
 
 ```bash
-git add "$PROJECT_PATH/"
-git commit -m "docs: complete discovery for {project-name}
+PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || { echo "oat: cannot resolve project scope for $PROJECT_PATH; refusing to commit artifacts" >&2; exit 1; }
+# fail closed: never fall back to branch bookkeeping when scope resolution fails
+if [ "$PROJECT_SCOPE" = "synced" ]; then
+  oat project push "$PROJECT_PATH" --message "docs: complete discovery for {project-name}
+
+Key decisions:
+- {Decision 1}
+- {Decision 2}
+
+Ready for design phase" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
+else
+  PROJECT_OUTPUT_PATHS=("$PROJECT_PATH/discovery.md" "$PROJECT_PATH/state.md")
+  git add -- "${PROJECT_OUTPUT_PATHS[@]}"
+  git commit -m "docs: complete discovery for {project-name}
 
 Key decisions:
 - {Decision 1}
 - {Decision 2}
 
 Ready for design phase"
+fi
 ```
 
 ### Step 16: Output Summary

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

@@ -1,11 +1,11 @@
 ---
 name: oat-project-document
-version: 1.8.0
+version: 1.8.1
 description: Use when the user requests or confirms documenting an active OAT project — e.g. "document the project", "update the docs", "run oat-project-document", or confirms a previously offered documentation run. Do NOT auto-invoke when implementation completes. Analyzes project artifacts, presents a documentation delta plan, and applies approved changes.
 argument-hint: '[project-path] [--auto]'
 disable-model-invocation: false
 user-invocable: true
-allowed-tools: Read, Write, Edit, Bash(git:*), Bash(oat tools:*), Glob, Grep, AskUserQuestion, Skill
+allowed-tools: Read, Write, Edit, Bash(git:*), Bash(jq:*), Bash(oat pjm:*), Bash(oat project push:*), Bash(oat project scope:*), Bash(oat tools:*), Glob, Grep, AskUserQuestion, Skill
 ---
 
 # Project Documentation Sync
@@ -524,8 +524,14 @@ Update `$PROJECT_PATH/state.md` frontmatter based on apply outcome:
 - If `$ALL_SUCCEEDED` is false: do **not** set `oat_docs_updated: complete` — leave the field as `null` so the skill can be re-run. Still set `oat_project_state_updated: "{ISO 8601 UTC timestamp}"`. Surface the failures clearly in the summary report (Step 8d) so the user knows which updates failed and why.
 
 ```bash
-git add "$PROJECT_PATH/state.md"
-git diff --cached --quiet || git commit -m "chore({project-name}): mark docs updated"
+PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || { echo "oat: cannot resolve project scope for $PROJECT_PATH; refusing to commit artifacts" >&2; exit 1; }
+# fail closed: never fall back to branch bookkeeping when scope resolution fails
+if [ "$PROJECT_SCOPE" = "synced" ]; then
+  oat project push "$PROJECT_PATH" --message "chore({project-name}): mark docs updated" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
+else
+  git add "$PROJECT_PATH/state.md"
+  git diff --cached --quiet || git commit -m "chore({project-name}): mark docs updated"
+fi
 ```
 
 **8c. Handle edge cases:**