@open-agent-toolkit/cli 0.3.16 → 0.3.17

package/assets/skills/oat-project-complete/scripts/execute-synced-archive-entry.mjs

@@ -1,7 +1,17 @@
 import { execFile as execFileCallback } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { realpathSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { isAbsolute, posix, relative, sep, resolve } from 'node:path';
+import {
+  isAbsolute,
+  posix,
+  relative,
+  sep,
+  resolve,
+  join,
+  dirname,
+  basename,
+} from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
 
@@ -23,45 +33,112 @@ async function buildPostArchiveContinuation(
 ) {
   let selectedProjectRecapRun = '';
   let exportedManifestPath = '';
-  if (archiveReport.projectRecapExport != null) {
-    const sourceRunRoot = archiveReport.projectRecapExport?.sourceRunRoot;
-    const exportRoot = archiveReport.projectRecapExport?.exportRoot;
-    const manifestPath =
-      archiveReport.projectRecapExport?.manifest?.relativePath;
-    if (
-      typeof sourceRunRoot !== 'string' ||
-      typeof exportRoot !== 'string' ||
-      manifestPath !== 'manifest.json'
-    ) {
-      throw executionError(
-        'Archive resume report has an invalid project recap export receipt.',
-      );
+  let exportedPagePath = '';
+  const canonicalPath = (value) => {
+    try {
+      return realpathSync(value);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      const parent = dirname(value);
+      if (parent === value) throw error;
+      return join(canonicalPath(parent), basename(value));
     }
-    selectedProjectRecapRun = relative(projectPath, sourceRunRoot)
-      .split(sep)
-      .join('/');
+  };
+  const recap = archiveReport.projectRecapExport;
+  if (recap != null) {
+    const inside = (root, target) => {
+      if (typeof target !== 'string' || !isAbsolute(target)) return null;
+      const child = relative(canonicalPath(root), canonicalPath(target))
+        .split(sep)
+        .join('/');
+      return child && !/^\.\.(?:[/\\]|$)/.test(child) && !isAbsolute(child)
+        ? child
+        : null;
+    };
+    selectedProjectRecapRun =
+      inside(projectPath, recap.sourceRunRoot) ??
+      inside(archiveReport.archivePath, recap.sourceRunRoot);
+    const exportRelative = inside(
+      join(repoRoot, '.oat/repo/reference/project-recaps'),
+      recap.exportRoot,
+    );
     if (
-      selectedProjectRecapRun.length === 0 ||
-      /^\.\.(?:[/\\]|$)/.test(selectedProjectRecapRun) ||
-      isAbsolute(selectedProjectRecapRun)
+      !selectedProjectRecapRun?.startsWith('explainers/') ||
+      !exportRelative
     ) {
       throw executionError(
-        'Archive resume recap source is outside the original project path.',
+        'Archive resume recap source or export is outside its allowed root.',
       );
     }
-    const exportRootRelative = relative(repoRoot, exportRoot)
+    const repoRelativeExport = relative(
+      canonicalPath(repoRoot),
+      canonicalPath(recap.exportRoot),
+    )
       .split(sep)
       .join('/');
     if (
-      exportRootRelative.length === 0 ||
-      /^\.\.(?:[/\\]|$)/.test(exportRootRelative) ||
-      isAbsolute(exportRootRelative)
+      recap.manifest?.relativePath === 'manifest.json' &&
+      recap.page == null
     ) {
-      throw executionError(
-        'Archive resume recap export is outside the repository root.',
+      // Persisted pre-flat-export receipts remain readable.
+      exportedManifestPath = posix.join(repoRelativeExport, 'manifest.json');
+    } else {
+      const page = recap.page;
+      const sourcePage = page?.sourceRelativePath;
+      if (
+        exportRelative !== `${archiveReport.snapshotId}.html` ||
+        typeof recap.runId !== 'string' ||
+        !recap.runId ||
+        !Number.isInteger(recap.verifiedArtifactCount) ||
+        recap.verifiedArtifactCount < 1 ||
+        typeof sourcePage !== 'string' ||
+        !sourcePage.startsWith('site/') ||
+        !sourcePage.endsWith('.html') ||
+        sourcePage.split('/').some((part) => part === '..') ||
+        !/^sha256:[0-9a-f]{64}$/.test(page?.originalSha256) ||
+        !/^sha256:[0-9a-f]{64}$/.test(page?.exportedSha256)
+      )
+        throw executionError(
+          'Archive resume report has an invalid flat recap receipt.',
+        );
+      const archivedRun = join(
+        archiveReport.archivePath,
+        selectedProjectRecapRun,
       );
+      const hash = (bytes) =>
+        `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+      try {
+        if (
+          !inside(archiveReport.archivePath, archivedRun) ||
+          !inside(archivedRun, join(archivedRun, sourcePage)) ||
+          !inside(archivedRun, join(archivedRun, 'manifest.json'))
+        )
+          throw new Error('archived source escapes its root');
+        const manifest = JSON.parse(
+          await readFile(join(archivedRun, 'manifest.json'), 'utf8'),
+        );
+        const original = await readFile(join(archivedRun, sourcePage));
+        const exported = await readFile(recap.exportRoot);
+        if (
+          manifest.runId !== recap.runId ||
+          Object.keys(manifest.immutableHashes).length !==
+            recap.verifiedArtifactCount ||
+          !manifest.artifacts.some(
+            (artifact) =>
+              (artifact.renderedPath ?? artifact.contentPath) === sourcePage,
+          ) ||
+          manifest.immutableHashes[sourcePage] !== page.originalSha256 ||
+          hash(original) !== page.originalSha256 ||
+          hash(exported) !== page.exportedSha256
+        )
+          throw new Error('run, page, or hash mismatch');
+      } catch (error) {
+        throw executionError(
+          `Archive resume flat recap identity failed: ${error.message}`,
+        );
+      }
+      exportedPagePath = repoRelativeExport;
     }
-    exportedManifestPath = posix.join(exportRootRelative, manifestPath);
   }
   return {
     required: true,
@@ -73,6 +150,7 @@ async function buildPostArchiveContinuation(
     selectedProjectRecapRun,
     projectRecapExport: archiveReport.projectRecapExport ?? null,
     exportedManifestPath,
+    exportedPagePath,
   };
 }
 

package/assets/skills/oat-project-complete/scripts/parse-synced-archive-resume-fields.mjs

@@ -15,6 +15,21 @@ function shellQuote(value) {
 export function parseSyncedArchiveResumeFields(result) {
   const continuation = result?.continuation;
   const hasRecapExport = continuation?.projectRecapExport !== null;
+  const recap = continuation?.projectRecapExport;
+  const flatPage = `.oat/repo/reference/project-recaps/${result?.archiveReport?.snapshotId}.html`;
+  const invalidFlat =
+    recap?.page &&
+    (typeof recap.runId !== 'string' ||
+      !recap.runId ||
+      typeof recap.page.sourceRelativePath !== 'string' ||
+      !recap.page.sourceRelativePath.startsWith('site/') ||
+      !/^sha256:[0-9a-f]{64}$/.test(recap.page.originalSha256) ||
+      !/^sha256:[0-9a-f]{64}$/.test(recap.page.exportedSha256) ||
+      !Number.isInteger(recap.verifiedArtifactCount) ||
+      recap.verifiedArtifactCount < 1 ||
+      continuation.exportedPagePath !== flatPage ||
+      typeof recap.exportRoot !== 'string' ||
+      !recap.exportRoot.endsWith(`/${flatPage}`));
   const allowedContinuationFields = new Set([
     'required',
     'rejoinStep',
@@ -25,6 +40,7 @@ export function parseSyncedArchiveResumeFields(result) {
     'selectedProjectRecapRun',
     'projectRecapExport',
     'exportedManifestPath',
+    'exportedPagePath',
   ]);
   if (
     !continuation ||
@@ -42,10 +58,20 @@ export function parseSyncedArchiveResumeFields(result) {
     continuation.archivePath.length === 0 ||
     typeof continuation.lifecycleCommit !== 'string' ||
     !/^[0-9a-f]{40}$/.test(continuation.lifecycleCommit) ||
+    invalidFlat ||
     (hasRecapExport &&
-      (typeof continuation.exportedManifestPath !== 'string' ||
-        continuation.exportedManifestPath.length === 0)) ||
-    (!hasRecapExport && continuation.exportedManifestPath !== '')
+      (JSON.stringify(continuation.projectRecapExport) !==
+        JSON.stringify(result.archiveReport?.projectRecapExport) ||
+        (continuation.projectRecapExport?.page
+          ? typeof continuation.exportedPagePath !== 'string' ||
+            !continuation.exportedPagePath.endsWith('.html') ||
+            continuation.exportedManifestPath !== ''
+          : typeof continuation.exportedManifestPath !== 'string' ||
+            !continuation.exportedManifestPath.endsWith('/manifest.json') ||
+            Boolean(continuation.exportedPagePath)))) ||
+    (!hasRecapExport &&
+      (continuation.exportedManifestPath !== '' ||
+        Boolean(continuation.exportedPagePath)))
   ) {
     throw fieldsError(
       'Synced archive resume result has no verified post-archive continuation.',
@@ -66,6 +92,7 @@ export function parseSyncedArchiveResumeFields(result) {
       continuation.projectRecapExport ?? null,
     ),
     EXPORTED_MANIFEST_PATH: continuation.exportedManifestPath,
+    EXPORTED_PAGE_PATH: continuation.exportedPagePath ?? '',
     PROJECT_REF_COMMIT: '',
     SHOULD_OPEN_PR: 'false',
   };

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

@@ -5,13 +5,17 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Bash(oat template:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: 2.3.7
+  version: 2.3.8
 ---
 
 # Design Phase
 
 Transform specification requirements into a detailed technical design with architecture, components, and implementation strategy.
 
+## Hook-safe exact-path commits
+
+Before a parent-branch commit, verify `oat internal commit-paths --help` succeeds. If unavailable, stop and update the OAT CLI; never fall back to a staged-index or pathspec-only commit. Set `COMMIT_IDENTITY` to a unique operation/artifact identity before the first attempt and retain it for every retry; use a new identity for a new operation. Pass only the exact produced file list, including tracked removals and both names of a rename. A blocked/failed result stops the workflow; retain its receipt and follow its diagnostics. Hooks remain enabled. Synced project artifacts continue through `oat project push`.
+
 ## Prerequisites
 
 **Required:** Completed discovery (`discovery.md` with `oat_status: complete`). Specification is optional — this skill folds requirements confirmation into its flow and produces `spec.md` as a byproduct (see Step 2). If the user already ran `oat-project-spec` standalone, that spec is reused.
@@ -328,8 +332,8 @@ PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || { echo "oat
 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}"
+  OWNED_COMMIT_PATHS=("$PROJECT_PATH/spec.md")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-design:1" --message "docs: confirm requirements for {project-name}" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 fi
 ```
 
@@ -603,8 +607,8 @@ PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || { echo "oat
 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)"
+  OWNED_COMMIT_PATHS=("$PROJECT_PATH/spec.md" "$PROJECT_PATH/design.md" "$PROJECT_PATH/state.md")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-design:2" --message "docs: draft design for {project-name} (awaiting review)" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 fi
 ```
 
@@ -646,8 +650,7 @@ Wait for user response:
     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"
+      oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-design:3" --message "docs: revise design after user review feedback" -- "$PROJECT_PATH/spec.md" "$PROJECT_PATH/design.md" || exit 1
     fi
   Re-present this prompt.
 - If user does not approve yet (wants to pause without explicit change
@@ -813,8 +816,8 @@ PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || { echo "oat
 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}"
+  OWNED_COMMIT_PATHS=("$PROJECT_PATH/design.md" "$PROJECT_PATH/state.md")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-design:4" --message "chore(oat): mark design complete for {project-name}" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 fi
 ```
 

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

@@ -5,13 +5,17 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Bash(oat:*), Bash(pnpm:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: 2.2.8
+  version: 2.2.9
 ---
 
 # Discovery Phase
 
 Gather requirements and understand the problem space through natural collaborative dialogue.
 
+## Hook-safe exact-path commits
+
+Before a parent-branch commit, verify `oat internal commit-paths --help` succeeds. If unavailable, stop and update the OAT CLI; never fall back to a staged-index or pathspec-only commit. Set `COMMIT_IDENTITY` to a unique operation/artifact identity before the first attempt and retain it for every retry; use a new identity for a new operation. Pass only the exact produced file list, including tracked removals and both names of a rename. A blocked/failed result stops the workflow; retain its receipt and follow its diagnostics. Hooks remain enabled. Synced project artifacts continue through `oat project push`.
+
 ## Prerequisites
 
 **Required:** Knowledge base must exist. If missing, run the `oat-repo-knowledge-index` skill first.
@@ -575,14 +579,14 @@ Key decisions:
 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}
+  OWNED_COMMIT_PATHS=("${PROJECT_OUTPUT_PATHS[@]}")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-discover:1" --message "docs: complete discovery for {project-name}
 
 Key decisions:
 - {Decision 1}
 - {Decision 2}
 
-Ready for design phase"
+Ready for design phase" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 fi
 ```
 

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

@@ -6,13 +6,17 @@ disable-model-invocation: false
 user-invocable: true
 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
 metadata:
-  version: 1.8.7
+  version: 1.8.8
 ---
 
 # Project Documentation Sync
 
 Read project artifacts and implementation code to identify documentation surfaces that need updating, present a delta plan for approval, and apply changes — all in a single invocation.
 
+## Hook-safe exact-path commits
+
+Before a parent-branch commit, verify `oat internal commit-paths --help` succeeds. If unavailable, stop and update the OAT CLI; never fall back to a staged-index or pathspec-only commit. Set `COMMIT_IDENTITY` to a unique operation/artifact identity before the first attempt and retain it for every retry; use a new identity for a new operation. Pass only the exact produced file list, including tracked removals and both names of a rename. A blocked/failed result stops the workflow; retain its receipt and follow its diagnostics. Hooks remain enabled. Synced project artifacts continue through `oat project push`.
+
 ## Prerequisites
 
 **Required:**
@@ -490,6 +494,11 @@ Track which recommendations were approved for Step 7.
 
 ### Step 7: Apply Approved Changes
 
+Initialize `OWNED_OUTPUT_FILES=()` before documentation writes. Append each
+exact successfully written or removed documentation path, including both
+rename sides and generated index/navigation files actually changed. Retain this
+producer list for the Step 8a helper commit and retries.
+
 Execute the approved documentation updates.
 
 **For each approved recommendation:**
@@ -540,8 +549,8 @@ If `$DOCS_CONFIG` exists and new files were created in the docs directory:
 **8a. Stage and commit documentation changes:**
 
 ```bash
-git add {list of changed/created documentation files}
-git diff --cached --quiet || git commit -m "docs({project-name}): update documentation from project artifacts"
+OWNED_COMMIT_PATHS=("${OWNED_OUTPUT_FILES[@]}")
+oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-document:1" --message "docs({project-name}): update documentation from project artifacts" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 ```
 
 Only stage files that were actually changed or created in Step 7. Do not use `git add -A`.
@@ -559,8 +568,8 @@ PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || { echo "oat
 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"
+  OWNED_COMMIT_PATHS=("$PROJECT_PATH/state.md")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-document:2" --message "chore({project-name}): mark docs updated" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 fi
 ```