@open-agent-toolkit/cli 0.3.15 → 0.3.17

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

@@ -5,13 +5,17 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.0.3
+  version: 1.0.4
 ---
 
 # Capture Untracked Work
 
 Retroactively create an OAT project from work that happened outside the structured workflow. Populates `discovery.md` from conversation context and `implementation.md` from commit history, producing a tracked project ready for review or PR.
 
+## 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`.
+
 ## When to Use
 
 Use when:
@@ -268,8 +272,8 @@ PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || {
 if [ "$PROJECT_SCOPE" = "synced" ]; then
   oat project push "$PROJECT_PATH" --message "chore(oat): capture existing work for {name}" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
 else
-  git add "$PROJECT_PATH/discovery.md" "$PROJECT_PATH/implementation.md" "$PROJECT_PATH/state.md"
-  git diff --cached --quiet || git commit -m "chore(oat): capture existing work for {name}"
+  OWNED_COMMIT_PATHS=("$PROJECT_PATH/discovery.md" "$PROJECT_PATH/implementation.md" "$PROJECT_PATH/state.md")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-capture:1" --message "chore(oat): capture existing work for {name}" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 fi
 ```
 

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

@@ -5,13 +5,17 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash, AskUserQuestion
 metadata:
-  version: 1.7.14
+  version: 1.7.15
 ---
 
 # Complete Project
 
 Mark the active OAT project lifecycle as complete.
 
+## 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`.
+
 ## Progress Indicators (User-Facing)
 
 When executing this skill, provide lightweight progress feedback so the user can tell what's happening after they confirm.
@@ -1237,21 +1241,23 @@ another lifecycle commit. `removed` is the completed-only terminal shape;
 `retained` is the equally terminal same-SHA active alias shape. A differing-SHA
 state is never a successful report.
 
-When `SELECTED_PROJECT_RECAP_RUN` is non-empty, also require the report's
-`projectRecapExport.sourceRunRoot`, `projectRecapExport.exportRoot`, and
-`projectRecapExport.manifest.relativePath === "manifest.json"`. Confirm the
-reported source is the selected run under the pre-archive project path and the
-export root is inside the tracked
-`.oat/repo/reference/project-recaps/` root. Record:
-
-- `sourceRunRoot` as the relocation source;
-- `exportRoot` as the final recap run root; and
-- `exportRoot/manifest.relativePath` as the final manifest.
-
-Do not infer or reconstruct the recap export root. The archive report is
-authoritative. A missing, malformed, mismatched, outside-root, or gitignored
-export report is an archive failure; stop before lifecycle bookkeeping.
-Never use the gitignored archive as evidence or a link target.
+When `SELECTED_PROJECT_RECAP_RUN` is non-empty, require the report's
+`projectRecapExport.sourceRunRoot`, `exportRoot`, `runId`,
+`page.sourceRelativePath`, `page.originalSha256`, `page.exportedSha256`, and
+positive `verifiedArtifactCount`. The export is one tracked
+`.oat/repo/reference/project-recaps/<snapshotId>.html` page. Confirm the source
+is the selected run under the pre-archive project path, or under `archivePath`
+on a terminal retry. Verify the run ID and manifest-declared original page/hash
+against the retained archived run, and the exported hash against the tracked
+page. Record `exportRoot` as the final page, never as a package directory.
+
+The archive report is authoritative. A missing, malformed, mismatched,
+outside-root, or gitignored export report is an archive failure; stop before
+lifecycle bookkeeping. Link only to the tracked page. The full original run,
+including source, manifest, and QA evidence, remains in the archived project;
+it is retained evidence rather than a remote link target. Persisted older
+receipts with `manifest.relativePath === "manifest.json"` remain readable as
+legacy package receipts; new exports never create a tracked manifest sidecar.
 
 SELECTED_PROJECT_RECAP_RUN must be project-relative. Never add `--project-recap-run` when `SELECTED_PROJECT_RECAP_RUN` is empty. The empty case remains the existing archive behavior. Because this step runs only for durable projects, local-scope projects never pass a recap archive argument.
 
@@ -1286,12 +1292,12 @@ final synced links,
 dashboard refresh, the required bookkeeping push, tracked-PR closeout when
 applicable, and final confirmation.
 
-Rewrite recap links in the tracked summary export and the PR description body from `projectRecapExport.exportRoot`; do not derive them from the local archive.
+Rewrite recap links in the tracked summary export and the PR description body from the reported HTML `projectRecapExport.exportRoot`; do not derive them from the local archive. Preserve the reported run ID and original/exported page hashes in the summary outcome. On resume use `EXPORTED_PAGE_PATH`; `EXPORTED_MANIFEST_PATH` is populated only for a persisted legacy package receipt.
 Use a repository-relative path under
 `.oat/repo/reference/project-recaps/` and a blob URL on the current head branch
 while the PR is open. If `summaryExportFile` is non-null, update its concise
 `Explainer Outcome` recap link. Update the archived PR-description artifact
-used by Step 11 or 11.5 so its recap reference points to the same tracked root.
+used by Step 11 or 11.5 so its recap reference points to the same tracked HTML page.
 Omit either link when its containing artifact does not exist.
 
 Use the current head branch for the blob URL while the PR is open. Never link to `.oat/projects/archived/`; it is gitignored and will return 404 remotely.
@@ -1423,9 +1429,16 @@ Expected changes may include:
 - `.oat/config.local.json` (if `activeProject` cleared)
 - Shared-project deletions; synced archive record deletion is already sealed by
   the archive-owned lifecycle commit
-- The complete tracked recap export and tracked summary export reported by
+- The tracked recap page and tracked summary export reported by
   archive (if present)
 
+Initialize `COMPLETION_OUTPUT_PATHS=()` before closeout writes. Each producer
+appends its exact successful output paths from the expected changes above,
+including tracked removals and both names of a rename; omit ignored local
+config/dashboard outputs. Retain that list for retries. Do not infer ownership
+from the staged index or pass project/export directories. The synced record
+producer already supplies the single exact `SYNCED_RECORD_PATH`.
+
 Run:
 
 ```bash
@@ -1433,23 +1446,15 @@ if [[ "$PROJECT_SCOPE" == "synced" ]]; then
   if [[ "$SHOULD_ARCHIVE" == "true" ]]; then
     test -n "$LIFECYCLE_COMMIT"
   else
-    git add -- "$SYNCED_RECORD_PATH"
-    if git diff --cached --quiet -- "$SYNCED_RECORD_PATH"; then
-      LIFECYCLE_COMMIT=$(git log -1 --format=%H -- "$SYNCED_RECORD_PATH")
-      node "$NONARCHIVE_LIFECYCLE_RECEIPT_SCRIPT" \
-        "$SYNCED_RECORD_PATH" "$LIFECYCLE_COMMIT" "$PROJECT_NAME" || exit 1
-    else
-      git commit --only "$SYNCED_RECORD_PATH" \
-        -m "chore(oat): complete synced project ${PROJECT_NAME}" &&
-        LIFECYCLE_COMMIT=$(git rev-parse HEAD) &&
-        node "$NONARCHIVE_LIFECYCLE_RECEIPT_SCRIPT" \
-          "$SYNCED_RECORD_PATH" "$LIFECYCLE_COMMIT" "$PROJECT_NAME" || exit 1
-    fi
+    oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-complete:1" --message "chore(oat): complete synced project ${PROJECT_NAME}" -- "$SYNCED_RECORD_PATH" || exit 1
+    LIFECYCLE_COMMIT=$(git log -1 --format=%H -- "$SYNCED_RECORD_PATH") || exit 1
+    node "$NONARCHIVE_LIFECYCLE_RECEIPT_SCRIPT" \
+      "$SYNCED_RECORD_PATH" "$LIFECYCLE_COMMIT" "$PROJECT_NAME" || exit 1
   fi
 else
   git status --short
-  git add -- <exact completion and lifecycle paths>
-  git commit -m "chore(oat): complete project lifecycle for ${PROJECT_NAME}"
+  : "${COMPLETION_OUTPUT_PATHS:?retain the exact lifecycle producer file list}"
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-complete:2" --message "chore(oat): complete project lifecycle for ${PROJECT_NAME}" -- "${COMPLETION_OUTPUT_PATHS[@]}" || exit 1
   LIFECYCLE_COMMIT=$(git rev-parse HEAD)
 fi
 ```
@@ -1623,7 +1628,7 @@ Show user:
 - If archived: "Archived location: **{PROJECT_PATH}**"
 - If S3 archive sync ran: include `ARCHIVE_S3_CONTEXT` when the archive command reported profile/region details. If only `ARCHIVE_S3_PATH` is available, include the S3 destination and note that profile/region context was not reported by the command. Never echo raw credentials (`AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, etc.).
 - Include the lifecycle bookkeeping commit hash and the single push result.
-- Report the final recap outcome and tracked reference root.
+- Report the final recap outcome and tracked recap page path.
 - Report every absorbed-project retirement finding from the Step 3.7 sweep with
   its disposition. This is the required destination whenever the sweep could not
   append them to the project log — an absent log, or a resume whose log is

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',
   };