@open-agent-toolkit/cli 0.2.40 → 0.2.45

package/assets/docs/workflows/projects/picking-up-projects.md

@@ -0,0 +1,75 @@
+---
+title: Picking Up Projects
+description: Continue a synced OAT project on another machine or from another user through its dedicated Git ref.
+---
+
+# Picking Up a Project on Another Machine or From Another User
+
+Synced projects travel through ordinary Git refs on `origin`. Their artifact
+history is independent from the implementation branch, so a teammate or a
+second machine can continue the project even before the branch carrying its
+record file merges.
+
+## Discover and adopt
+
+From any checkout with access to `origin`:
+
+```bash
+oat project list --remote
+oat project pull <project>
+```
+
+`list --remote` discovers `refs/oat/projects/*` directly. `pull` can adopt a
+remote project that has no local record yet: it writes the record and creates
+the nested checkout. When the selected project is a coordination parent, pull
+also discovers and pulls its child projects by default. Pass `--no-children`
+only when you intentionally want the selected project alone.
+
+After adoption, set or open the project through the normal lifecycle command
+you are using. Arrival-aware project skills pull before reading its artifacts.
+
+## What travels
+
+- The project ref carries the complete active artifact tree and its history.
+- The tracked JSON record travels once the branch containing it is shared or
+  merged.
+- Coordination relationships travel in the artifacts and records pulled with
+  the project.
+
+## What does not travel automatically
+
+- `local` projects never leave their original machine.
+- GitHub forks copy branches and tags, but not the `refs/oat/*` namespace. A
+  fork collaborator needs access to the upstream remote or an explicit ref
+  transfer.
+- A normal `git clone` fetches branches and tags, not custom OAT refs. OAT
+  handles remote discovery with `ls-remote` and explicitly fetches the selected
+  project ref during sync operations such as `pull`; do not expect a generic
+  clone or `git fetch` to materialize the checkout.
+
+## Why retained refs remain durable
+
+`refs/oat/projects/<project>` is a real Git ref locally and on `origin`. The
+objects reachable from it remain garbage-collection roots even when no nested
+checkout exists. Branch pruning, remote-tracking-ref pruning, and
+`git worktree prune` do not delete the project ref. Completion deliberately
+retains it so pinned PR links remain valid.
+
+Only the explicit destructive operation `oat project prune` removes the local
+and remote project refs. Treat it as permanent project-history deletion and
+review its warnings before using `--force`.
+
+## Archive contents
+
+When archive is selected, completion copies a synced project into
+`.oat/projects/archived/<project>/` without the nested checkout's `.git`
+pointer or `reviews/`. S3 snapshots also omit `pr/`, following the existing
+archive policy. When archive is disabled or declined, the active synced
+checkout remains in place. Both paths retain the project ref and commit the
+tracked record as `complete`; only the archive path records an archive snapshot.
+
+## Related
+
+- [Reviewing OAT PRs](reviewing-oat-prs.md)
+- [Project Artifacts](artifacts.md)
+- [Implementation Execution](implementation-execution.md#synced-projects-in-worktrees)

package/assets/docs/workflows/projects/pr-flow.md

@@ -34,6 +34,25 @@ GitHub PR body policy:
 - Keep YAML frontmatter in local artifact
 - Strip frontmatter from submitted PR body
 
+## Synced project links
+
+For a synced project, PR creation follows a six-step order:
+
+1. write and format the local PR artifact;
+2. run `oat project push` so the project ref contains the latest artifacts;
+3. run `oat project links --format markdown` to generate the delimited links
+   block from that exact ref commit;
+4. include the block in the submitted PR body;
+5. persist `oat_pr_status` and `oat_pr_url` in `state.md`; and
+6. push again so subsequent artifact writes can refresh the open PR body.
+
+The generated block links only `discovery.md`, `design.md`, and `summary.md`
+when present. The URLs are pinned to the project ref's exact commit SHA rather
+than a moving branch name. `plan.md`, `state.md`, `implementation.md`, and
+`reviews/` are intentionally excluded because they contain agent-facing
+execution detail rather than the reviewer-oriented project narrative. See
+[Reviewing OAT PRs](reviewing-oat-prs.md).
+
 ## Post-PR state
 
 After `oat-project-pr-final` creates the PR, `state.md` transitions to `oat_phase_status: pr_open`. This signals "awaiting human review" rather than "done."
@@ -57,7 +76,9 @@ Both completion orderings are supported:
 
 An open PR is not a completion blocker. When completion archives project
 artifacts, the archive-aware flow regenerates and synchronizes the open PR body
-so its artifact links remain valid.
+so its artifact links remain valid. Synced completion retains the project ref,
+which keeps its SHA-pinned links resolvable after the nested checkout is
+removed.
 
 ## Reference artifacts
 

package/assets/docs/workflows/projects/reviewing-oat-prs.md

@@ -0,0 +1,60 @@
+---
+title: Reviewing OAT PRs
+description: Understand synced-project records, SHA-pinned artifact links, and the reviewer-facing PR experience.
+---
+
+# Reviewing OAT PRs
+
+A PR for a synced OAT project contains the implementation diff without placing
+the agent-facing project tree on the feature branch. Reviewers get durable
+project context through a small tracked record and a generated links block in
+the PR body.
+
+## The synced record
+
+`.oat/projects/synced/<project>.json` is tracked on the feature branch. It
+names the project slug, `origin`, `refs/oat/projects/<project>`, whether the
+project is active or complete, and the archive snapshot when completion has
+created one. It is discovery and lifecycle metadata; the project artifacts
+themselves live on the project ref.
+
+## The artifact links block
+
+`oat project links` generates a delimited Markdown block for the PR body. Each
+URL points at the exact project-ref commit current when the block was rendered,
+so later pushes cannot silently change the content behind an existing link.
+`oat project push` refreshes the block when the project's `state.md` identifies
+an open PR.
+
+The block includes the reviewer-oriented artifacts that exist:
+
+- `discovery.md` for problem framing and constraints;
+- `design.md` for the selected architecture; and
+- `summary.md` for the concise outcome and durable decisions.
+
+It does not link `plan.md`, `state.md`, `implementation.md`, or `reviews/`.
+Those files are operational agent context, can be noisy or transient, and are
+not part of the stable reviewer narrative. The implementation diff and normal
+PR review remain authoritative for the code change.
+
+## Editor discovery
+
+The project checkout is a nested Git worktree. VS Code and Cursor may not show
+it in Source Control unless repository scanning includes nested repositories.
+Add the synced root to `git.scanRepositories` in workspace settings when you
+want editor Git integration for these checkouts:
+
+```json
+{
+  "git.scanRepositories": [".oat/projects/synced"]
+}
+```
+
+This setting is an editor convenience. OAT's `push`, `pull`, and `links`
+commands do not depend on editor discovery.
+
+## Related
+
+- [PR Flow](pr-flow.md)
+- [Project Artifacts](artifacts.md)
+- [Picking Up Projects](picking-up-projects.md)

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.40",
-  "docs-config": "0.2.40",
-  "docs-theme": "0.2.40",
-  "docs-transforms": "0.2.40"
+  "cli": "0.2.45",
+  "docs-config": "0.2.45",
+  "docs-theme": "0.2.45",
+  "docs-transforms": "0.2.45"
 }

package/assets/skills/analyze/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: analyze
-version: 0.1.0
+version: 0.1.1
 description: Multi-angle analysis of existing artifacts, codebases, documents, or systems. Examines what you have from six analysis angles and produces structured findings with prioritized recommendations.
 argument-hint: 'target [--context path]'
 user-invocable: true
@@ -258,10 +258,18 @@ Then ask the user via `AskUserQuestion` (Claude Code), structured user-input too
 
 `[10/10] Writing artifact…`
 
-Write the structured analysis artifact using:
-
-- Base schema structure (Executive Summary, Methodology, Findings, Sources & References) from `../deep-research/references/schema-base.md`
-- Analysis extended schema sections (Per-Angle Findings, Cross-Angle Synthesis, Prioritized Recommendations) from `../deep-research/references/schema-analysis.md`
+Write the structured analysis artifact using the `deep-research` schema
+references. Independently probe each required `<name>/SKILL.md` in order:
+`${SKILL_DIR}/..` from this loaded skill, `${HOME}/.agents/skills`, then
+`<repo-root>/.agents/skills`. Bind the first match for `deep-research` to its
+own `${RESEARCH_SKILLS_ROOT}`; never ambient discovery. On a miss, name the
+skill, stop before writing the artifact instead of inventing a schema, and give
+its intended-scope recovery command:
+`oat tools install research --scope <user|project>` or
+`oat tools update --pack research --scope <user|project>`.
+
+- Base schema structure (Executive Summary, Methodology, Findings, Sources & References) from `${RESEARCH_SKILLS_ROOT}/deep-research/references/schema-base.md`
+- Analysis extended schema sections (Per-Angle Findings, Cross-Angle Synthesis, Prioritized Recommendations) from `${RESEARCH_SKILLS_ROOT}/deep-research/references/schema-analysis.md`
 
 Artifact frontmatter contract:
 

package/assets/skills/compare/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: compare
-version: 0.1.0
+version: 0.1.1
 description: Domain-aware comparative analysis with clear recommendations. Compares options across auto-detected or user-specified dimensions and produces a qualitative assessment with a clear winner.
 argument-hint: 'item1 item2 [item3...] [--save] [--context path] [--dimensions "dim1, dim2, ..."]'
 user-invocable: true
@@ -167,7 +167,16 @@ Condensed comparison with:
 
 **Artifact output (`--save` flag):**
 
-Write artifact using the `comparative` extended schema from `.agents/skills/deep-research/references/schema-comparative.md`:
+Write artifact using the `comparative` extended schema owned by the
+`deep-research` skill. Independently probe each required `<name>/SKILL.md` in order:
+`${SKILL_DIR}/..` from this loaded skill, `${HOME}/.agents/skills`, then
+`<repo-root>/.agents/skills`. Bind the first match for `deep-research` to its
+own `${RESEARCH_SKILLS_ROOT}`; never ambient discovery. On a miss, name the
+skill, stop before writing the artifact instead of inventing a schema, and give
+its intended-scope recovery command:
+`oat tools install research --scope <user|project>` or
+`oat tools update --pack research --scope <user|project>`. Then read
+`${RESEARCH_SKILLS_ROOT}/deep-research/references/schema-comparative.md`:
 
 - Include artifact frontmatter contract:
 

package/assets/skills/oat-brainstorm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-brainstorm
-version: 1.3.1
+version: 1.3.4
 description: Use when the user explicitly invokes the `brainstorm` verb, including `/oat-brainstorm`, "let's brainstorm", "brainstorm this", "can we brainstorm X", or "help me brainstorm X". For ambiguous exploratory phrasing ("I've been thinking", "what if", "help me think through"), do NOT auto-enter; respond conversationally and offer mode only after ≥2 sustained exploratory turns. Do NOT use for review, debug, PR, status, implementation, or active-workflow questions.
 disable-model-invocation: false
 user-invocable: true
@@ -89,9 +89,9 @@ These messages get a direct response, not a workflow takeover. If the model has
 - No formal requirements / specs / architectural designs (the design phase belongs to `oat-project-design`, not here).
 - No auto-routing to a destination before convergence — the destination is identified at the end of the conversation, not the beginning. Opportunistic surfacing on a clear trigger phrase is allowed; pre-emptively forcing a destination is not.
 - Visual-companion offer must run only when the topic is visual-likely OR the user has explicitly asked for it. Never offer when the topic is text-likely; never skip when the topic is visual-likely.
-- No fold-back commit on a dirty working tree without running the preflight `git status` check first (see Process step 9 active-project branches).
-- No `git add -A` and no directory globs for the fold-back commit. Staging is always scoped: `git add -- "$ARTIFACT_PATH"`.
-- No printing the fold-back handoff prompt before `git commit` actually succeeds. The prompt references a hash; a missing commit makes the prompt misleading.
+- No fold-back persistence on a dirty artifact, or from a synced checkout with any dirty project file, without running the preflight `git status` check first (see Process step 9 active-project branches).
+- For shared/local fold-back, no `git add -A` or directory globs: stage only `git add -- "$ARTIFACT_PATH"`. For synced fold-back, never stage on the parent branch; use the validated `oat project push --json` receipt.
+- No printing the fold-back handoff prompt before the scope-appropriate branch commit or synced push succeeds. The prompt references a hash; a missing persistence receipt makes it misleading.
 
 **ALLOWED Activities:**
 
@@ -100,7 +100,7 @@ These messages get a direct response, not a workflow takeover. If the model has
 - Pack and active-project detection at convergence time (`oat tools has <pack>` / `oat config get activeProject`).
 - Reading downstream skill files (`oat-idea-*`, `oat-pjm-add-backlog-item`, `oat-project-*`) and following their process inline using the synthesized payload as pre-filled answers.
 - Rendering the doc-to-path artifact from `templates/brainstorm-doc.md`.
-- Active-project fold-back: appending synthesis to the chosen upstream artifact and committing — only after the safety contract (preflight, scoped staging, conditional handoff print) is satisfied.
+- Active-project fold-back: appending synthesis to the chosen upstream artifact and persisting by scope — exact-path branch commit for shared/local, validated project-ref push for synced — only after the safety contract is satisfied.
 
 **Self-Correction Protocol:**
 If you catch yourself:
@@ -110,9 +110,9 @@ If you catch yourself:
 - Forcing a destination before convergence → STOP. Return to free brainstorming and let convergence happen via trigger phrase or natural soft cue.
 - Skipping the visual-companion offer when visual content is coming → STOP. Print the offer as its own message before continuing.
 - Offering the visual companion before a text-likely brainstorm has any visual need → STOP. Set `VISUAL_COMPANION = "deferred"` and continue text-only.
-- Running the fold-back commit on a dirty working tree without preflight → STOP. Re-route through the dirty-tree handler (three-option picker) before any artifact mutation.
-- Staging with `-A` or a directory glob during fold-back → STOP. The fold-back commit must be `git add -- "$ARTIFACT_PATH"` only.
-- Printing the fold-back handoff prompt before the commit succeeds → STOP. Surface the commit error and let the user resolve it before the prompt is emitted.
+- Running fold-back persistence on a dirty artifact without preflight → STOP. Re-route through the dirty-tree handler (three-option picker) before any artifact mutation.
+- For shared/local scope, staging with `-A` or a directory glob during fold-back → STOP; use `git add -- "$ARTIFACT_PATH"` only. For synced scope, any parent-branch staging → STOP; use `oat project push`.
+- Printing the fold-back handoff prompt before the branch commit or synced push succeeds → STOP. Surface the persistence error and let the user resolve it before the prompt is emitted.
 
 **Recovery:**
 
@@ -302,7 +302,21 @@ If "keep going", return to step 5. If "wrap up", surface the **pack-filtered ter
    - Gated by `WORKFLOWS_INSTALLED == "true"` AND `ACTIVE_PROJECT_VALID == "true"`: `Active project: fold-back` and `Active project: brainstorming reference file`. When this branch fires, present the **3-way active-project router first** (see step 9 active-project branches) — its outcome controls whether the rest of the picker is even surfaced.
 3. Evaluate whether the accumulated brainstorm scope is large enough to offer a split destination. Track the same four split signals used by discovery and evaluate them through the installed CLI:
 
+   Define this fail-closed parser once before any synced persistence below. If
+   it rejects a receipt, print the complete CLI JSON, run
+   `oat project pull "$ACTIVE_PROJECT"`, resolve any reported conflict, and
+   retry the original push; never infer a commit from local Git state.
+
    ```bash
+   parse_synced_push_receipt() {
+     node -e '
+   let value;
+   try { value = JSON.parse(process.argv[1]); } catch { process.exit(1); }
+   if (!["pushed", "up-to-date"].includes(value.status) || !/^[0-9a-f]{40}$/.test(value.sha)) process.exit(1);
+   process.stdout.write(value.sha);
+   ' "$1"
+   }
+
    oat project split evaluate-signals --fired "<comma-list>"
    ```
 
@@ -392,7 +406,7 @@ After confirmation succeeds, proceed to step 9 (handoff).
 
 ### Step 9: Handoff
 
-Branch on the destination. Each branch executes its handoff inline using the confirmed payload. The non-fold-back destinations are listed first; the active-project router and fold-back commit safety contract are detailed at the end of this step.
+Branch on the destination. Each branch executes its handoff inline using the confirmed payload. The non-fold-back destinations are listed first; the active-project router and scope-aware fold-back persistence contract are detailed at the end of this step.
 
 **Resolving `${SKILLS_ROOT}` for chained skills.** The `ideas` and
 `project-management` packs default to user scope just as `brainstorm` does, so a
@@ -552,15 +566,35 @@ Uniform across spec-driven and quick modes. Differs only in which plan-authoring
 
 Confirm the chosen artifact with the user (minimal confirmation per `references/destinations.md`). Set `ARTIFACT_PATH` to the absolute path.
 
-**Step 2 — Preflight `git status` check.** Run **before** any artifact mutation, scoped to the chosen artifact only:
+**Persistence invariant:** shared and local project artifacts remain ordinary
+parent-checkout files and use exact-path branch commits. Synced project
+artifacts live only in the nested project checkout and become durable only
+through a validated `oat project push --json` receipt on
+`refs/oat/projects/<slug>`; never stage a synced artifact on the parent branch.
+This invariant applies equally to clean fold-back, both dirty fold-back choices,
+and the brainstorming reference-file route.
+
+**Step 2 — Preflight `git status` check.** Run **before** any artifact mutation.
+For shared/local projects, scope the check to the chosen artifact. For synced
+projects, inspect the full nested checkout because `oat project push` persists
+every pending project file:
 
 ```bash
-git status --porcelain -- "$ARTIFACT_PATH"
+PROJECT_SCOPE=$(oat project scope "$ACTIVE_PROJECT" --format value) || { echo "oat: cannot resolve project scope for $ACTIVE_PROJECT; refusing to commit artifacts" >&2; exit 1; }
+# fail closed: never fall back to branch bookkeeping when scope resolution fails
+if [ "$PROJECT_SCOPE" = "synced" ]; then
+  git -C "$ACTIVE_PROJECT" status --porcelain
+else
+  git status --porcelain -- "$ARTIFACT_PATH"
+fi
 ```
 
 The check happens before any append, so the skill can route around the dirty case without having half-written the synthesis.
 
-**Step 3 — If the artifact is clean** (no entry in the porcelain output): this is the happy path.
+**Step 3 — If the artifact is clean** (no entry in the porcelain output): this
+is the happy path. For synced projects, "artifact is clean" additionally
+requires the entire project checkout to be clean; a clean chosen artifact
+beside another dirty project file must take Step 4.
 
 1. Append the synthesis as a clearly-marked section to `ARTIFACT_PATH`:
 
@@ -570,33 +604,90 @@ The check happens before any append, so the skill can route around the dirty cas
 
    Section body contains: `chosenDirection` (with rationale), key decisions (extracted from the conversation), and a transcript appendix (`transcriptSessionNote`). Optionally include `openQuestions` and `nextSteps` if surfaced.
 
-2. Stage **only** the artifact:
+2. Persist **only** the artifact under the scope guard:
 
    ```bash
-   git add -- "$ARTIFACT_PATH"
+   PROJECT_SCOPE=$(oat project scope "$ACTIVE_PROJECT" --format value) || { echo "oat: cannot resolve project scope for $ACTIVE_PROJECT; refusing to commit artifacts" >&2; exit 1; }
+   # fail closed: never fall back to branch bookkeeping when scope resolution fails
+   if [ "$PROJECT_SCOPE" = "synced" ]; then
+     FOLD_BACK_PUSH=$(oat project push "$ACTIVE_PROJECT" --message "chore(oat): integrate brainstorm into <artifact-basename> for <project-name>" --json) || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
+     FOLD_BACK_COMMIT_SHA=$(parse_synced_push_receipt "$FOLD_BACK_PUSH") || { printf '%s\n' "$FOLD_BACK_PUSH" >&2; echo "Recovery: run oat project pull \"$ACTIVE_PROJECT\", resolve conflicts, then retry this push." >&2; exit 1; }
+   else
+     git add -- "$ARTIFACT_PATH"
+     git commit -m "chore(oat): integrate brainstorm into <artifact-basename> for <project-name>"
+     FOLD_BACK_COMMIT_SHA=$(git rev-parse HEAD)
+   fi
    ```
 
-   Use the explicit `--` filename form. **Never `git add -A`. Never directory globs.** Other working-tree paths are not touched by this commit.
+   For non-synced projects, use the explicit `--` filename form. **Never `git add -A`. Never directory globs.** Other working-tree paths are not touched by this commit. For synced projects, `FOLD_BACK_COMMIT_SHA` comes from the push JSON rather than the parent branch.
 
-3. Commit with the canonical message:
+3. `<artifact-basename>` is `design.md` or `discovery.md` depending on which was chosen. `<project-name>` is the active project's slug.
 
-   ```bash
-   git commit -m "chore(oat): integrate brainstorm into <artifact-basename> for <project-name>"
-   ```
+4. If the guarded persistence succeeded → proceed to step 5 (handoff prompt).
+
+**Step 4 — If the artifact is dirty** (any entry in the porcelain output):
+pause the fold-back, present the user with three options before any artifact
+mutation occurs. For synced projects, any dirty project file makes this branch
+apply; name other dirty project files in the warning so the user knows
+`oat project push` would include them. Carry the scope resolved by the preflight
+into the selected branch and resolve it again inside every persistence block so
+failures remain fail-closed.
 
-   `<artifact-basename>` is `design.md` or `discovery.md` depending on which was chosen. `<project-name>` is the active project's slug.
+- **Option A — Commit current artifact changes first** (recommended when prior changes are unrelated to the brainstorm). Ask the user for a one-line subject and persist the existing artifact state before appending the synthesis:
 
-4. If `git commit` succeeded → proceed to step 5 (handoff prompt).
+  ```bash
+  PROJECT_SCOPE=$(oat project scope "$ACTIVE_PROJECT" --format value) || { echo "oat: cannot resolve project scope for $ACTIVE_PROJECT; refusing to commit artifacts" >&2; exit 1; }
+  if [ "$PROJECT_SCOPE" = "synced" ]; then
+    CURRENT_ARTIFACT_PUSH=$(oat project push "$ACTIVE_PROJECT" --message "$CURRENT_ARTIFACT_SUBJECT" --json) || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
+    CURRENT_ARTIFACT_COMMIT_SHA=$(parse_synced_push_receipt "$CURRENT_ARTIFACT_PUSH") || { printf '%s\n' "$CURRENT_ARTIFACT_PUSH" >&2; echo "Recovery: run oat project pull \"$ACTIVE_PROJECT\", resolve conflicts, then retry this push." >&2; exit 1; }
+  else
+    git add -- "$ARTIFACT_PATH"
+    git commit --only -m "$CURRENT_ARTIFACT_SUBJECT" -- "$ARTIFACT_PATH"
+    CURRENT_ARTIFACT_COMMIT_SHA=$(git rev-parse HEAD)
+  fi
+  ```
+
+  Only after that succeeds, append the synthesis. Persist the fold-back as a
+  second commit on the same scope:
+
+  ```bash
+  PROJECT_SCOPE=$(oat project scope "$ACTIVE_PROJECT" --format value) || { echo "oat: cannot resolve project scope for $ACTIVE_PROJECT; refusing to commit artifacts" >&2; exit 1; }
+  if [ "$PROJECT_SCOPE" = "synced" ]; then
+    FOLD_BACK_PUSH=$(oat project push "$ACTIVE_PROJECT" --message "chore(oat): integrate brainstorm into <artifact-basename> for <project-name>" --json) || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
+    FOLD_BACK_COMMIT_SHA=$(parse_synced_push_receipt "$FOLD_BACK_PUSH") || { printf '%s\n' "$FOLD_BACK_PUSH" >&2; echo "Recovery: run oat project pull \"$ACTIVE_PROJECT\", resolve conflicts, then retry this push." >&2; exit 1; }
+  else
+    git add -- "$ARTIFACT_PATH"
+    git commit --only -m "chore(oat): integrate brainstorm into <artifact-basename> for <project-name>" -- "$ARTIFACT_PATH"
+    FOLD_BACK_COMMIT_SHA=$(git rev-parse HEAD)
+  fi
+  ```
 
-**Step 4 — If the artifact is dirty** (any entry in the porcelain output): pause the fold-back, present the user with three options before any artifact mutation occurs:
+  For synced projects, the two returned project-ref SHAs prove that the prior
+  dirty state was pushed before the fold-back.
+
+- **Option B — Include current changes in the fold-back persistence.** Warn explicitly: "The persisted fold-back will mix prior unrelated edits with the brainstorm synthesis. The handoff prompt's receipt SHA will reference both. Confirm?" If the user accepts, append the synthesis and persist the combined state once:
+
+  ```bash
+  PROJECT_SCOPE=$(oat project scope "$ACTIVE_PROJECT" --format value) || { echo "oat: cannot resolve project scope for $ACTIVE_PROJECT; refusing to commit artifacts" >&2; exit 1; }
+  if [ "$PROJECT_SCOPE" = "synced" ]; then
+    MIXED_FOLD_BACK_PUSH=$(oat project push "$ACTIVE_PROJECT" --message "chore(oat): integrate brainstorm + prior edits into <artifact-basename> for <project-name>" --json) || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
+    FOLD_BACK_COMMIT_SHA=$(parse_synced_push_receipt "$MIXED_FOLD_BACK_PUSH") || { printf '%s\n' "$MIXED_FOLD_BACK_PUSH" >&2; echo "Recovery: run oat project pull \"$ACTIVE_PROJECT\", resolve conflicts, then retry this push." >&2; exit 1; }
+  else
+    git add -- "$ARTIFACT_PATH"
+    git commit --only -m "chore(oat): integrate brainstorm + prior edits into <artifact-basename> for <project-name>" -- "$ARTIFACT_PATH"
+    FOLD_BACK_COMMIT_SHA=$(git rev-parse HEAD)
+  fi
+  ```
+
+  The `--only` path commit retains the existing non-synced Git route while
+  preserving unrelated staged state. A synced dirty branch never runs parent
+  `git add` for the project artifact.
 
-- **Option A — Commit current artifact changes first** (recommended when prior changes are unrelated to the brainstorm). Skill commits the existing artifact state with a separate, user-described commit message (ask the user for a one-line subject), then proceeds with fold-back as a new scoped commit on top.
-- **Option B — Include current changes in the fold-back commit.** Skill warns explicitly: "The fold-back commit will mix prior unrelated edits with the brainstorm synthesis. The handoff prompt's commit hash will reference both. Confirm?" If user accepts, append synthesis, then `git add -- "$ARTIFACT_PATH"`, then commit with an adjusted message acknowledging the mix (e.g., `chore(oat): integrate brainstorm + prior edits into <artifact> for <project-name>`).
 - **Option C — Abort fold-back; capture as reference file instead.** Switch the destination to **branch 9j** (active-project brainstorming reference file). Upstream artifact is left untouched.
 
-After the user picks A or B and the resulting commit succeeds, proceed to step 5. After option C, jump to branch 9j.
+After the user picks A or B and the resulting branch commit or synced push succeeds, proceed to step 5. After option C, jump to branch 9j.
 
-**Step 5 — Handoff prompt.** Print **only after the scoped commit succeeds.** If `git commit` failed (pre-commit hooks rejected, signing failed, anything else), surface the error verbatim and **do NOT print the handoff prompt** — the prompt references a commit hash, and a missing commit makes the prompt actively misleading. The user resolves the failure (or re-routes via option C above) before fold-back can complete.
+**Step 5 — Handoff prompt.** Print **only after the scoped commit or synced push succeeds.** If persistence failed (pre-commit hooks rejected, signing failed, push failed, anything else), surface the error verbatim and **do NOT print the handoff prompt** — the prompt references a commit hash, and a missing commit makes the prompt actively misleading. The user resolves the failure (or re-routes via option C above) before fold-back can complete.
 
 Resolve the handoff target by `ACTIVE_PROJECT_MODE` and `ACTIVE_PROJECT_PR_STATUS`:
 
@@ -606,7 +697,7 @@ Resolve the handoff target by `ACTIVE_PROJECT_MODE` and `ACTIVE_PROJECT_PR_STATU
 | quick       | none / closed                | `oat-project-quick-start` |
 | either      | open (`oat_pr_status: open`) | `oat-project-revise`      |
 
-Print the handoff prompt template, substituting `<skill-name>`, `<artifact>`, `<hash>`, and `<subject>` from the actual commit:
+Print the handoff prompt template, substituting `<skill-name>`, `<artifact>`, `<hash>`, and `<subject>` from the actual branch commit or synced push receipt:
 
 ```
 Run `<skill-name>` with this context:
@@ -634,14 +725,26 @@ If `<ACTIVE_PROJECT>/brainstorming/` does not exist, create it (`mkdir -p`). The
 
 Render `${SKILL_DIR}/templates/brainstorm-doc.md` (resolve `${SKILL_DIR}` per the rule in step 3) with the synthesized payload (same shape as the doc-to-path destination) and write to the resolved path.
 
-After writing, commit the file with scoped staging (mirror the discipline of the active-project fold-back commit safety contract):
+After writing, persist the file with the same fail-closed scope guard:
 
 ```bash
-git add -- "<active-project-relative-path>"
-git commit -m "chore(oat): capture brainstorming reference for <project-name>"
+PROJECT_SCOPE=$(oat project scope "$ACTIVE_PROJECT" --format value) || { echo "oat: cannot resolve project scope for $ACTIVE_PROJECT; refusing to commit artifacts" >&2; exit 1; }
+# fail closed: never fall back to branch bookkeeping when scope resolution fails
+if [ "$PROJECT_SCOPE" = "synced" ]; then
+  REFERENCE_PUSH=$(oat project push "$ACTIVE_PROJECT" --message "chore(oat): capture brainstorming reference for <project-name>" --json) || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
+  REFERENCE_COMMIT_SHA=$(parse_synced_push_receipt "$REFERENCE_PUSH") || { printf '%s\n' "$REFERENCE_PUSH" >&2; echo "Recovery: run oat project pull \"$ACTIVE_PROJECT\", resolve conflicts, then retry this push." >&2; exit 1; }
+else
+  git add -- "<active-project-relative-path>"
+  git commit -m "chore(oat): capture brainstorming reference for <project-name>"
+  REFERENCE_COMMIT_SHA=$(git rev-parse HEAD)
+fi
 ```
 
-Use only `git add -- <path>` so unrelated working-tree changes are not swept into the commit. After the commit succeeds, capture the short hash via `git rev-parse --short HEAD` and report it alongside the absolute path written (for example: "Wrote `<absolute-path>` and committed as `<hash>`."). End mode assertion.
+For shared/local scope, use only `git add -- <path>` so unrelated working-tree changes are not swept into the commit, then capture `git rev-parse --short HEAD`. For synced scope, use the validated push receipt SHA and never stage the artifact on the parent branch. Report the resulting SHA alongside the absolute path written, then end mode assertion.
+
+For synced projects, the preceding short-hash sentence is superseded by the
+full `REFERENCE_COMMIT_SHA` returned from `oat project push --json`; no parent
+branch artifact commit occurs.
 
 #### 9k — Promote to N projects
 
@@ -667,7 +770,7 @@ End mode assertion when the split handoff completes or reports its own blocker.
 - ✅ Confirmation pattern matches `references/destinations.md`: `full` for scoped backlog item (field-by-field with example wording), `minimal` for slug/path/artifact destinations, `none` for inline-only and summarize-idea-directly.
 - ✅ Each handoff branch (9a-9k) reads the correct downstream `SKILL.md` path and enters at the documented step. Project promotion writes `discovery.md` only — never `design.md` — and does not auto-chain into the next phase.
 - ✅ Doc-to-path validation handles all four cases: path-is-directory, parent-missing (with explicit out-of-repo confirmation), file-already-exists (overwrite or rename), unwritable (surface OS error).
-- ✅ Fold-back commit safety contract honored: preflight `git status --porcelain -- "$ARTIFACT_PATH"` runs before any artifact mutation; clean → append + `git add -- "$ARTIFACT_PATH"` (explicit `--`, never `-A`, never globs) + scoped commit; dirty → three-option picker (commit-prior-first / mix / abort-to-reference-file); handoff prompt prints only after `git commit` succeeds.
+- ✅ Fold-back persistence safety contract honored: preflight `git status --porcelain -- "$ARTIFACT_PATH"` runs before any artifact mutation; clean → append + exact-path branch commit for shared/local or validated `oat project push --json` for synced; dirty → three-option picker (persist-prior-first / mix / abort-to-reference-file); handoff prompt prints only after the scope-appropriate receipt succeeds.
 - ✅ Handoff target for fold-back resolves correctly per `oat_workflow_mode` + `oat_pr_status`: `oat-project-plan` (spec-driven, no/closed PR) / `oat-project-quick-start` (quick, no/closed PR) / `oat-project-revise` (either mode, open PR).
 - ✅ Active-project 3-way router (related / independent / supplementary) fires before the standard pack-filtered picker when both `WORKFLOWS_INSTALLED == "true"` and `ACTIVE_PROJECT_VALID == "true"`.
 - ✅ Skill validates cleanly under `pnpm oat:validate-skills` (frontmatter contract, allowed-tools, mode-assertion structure).

package/assets/skills/oat-brainstorm/references/destinations.md

@@ -138,10 +138,13 @@ Skill proposes `quick` vs `spec-driven` mode based on `chosenDirection` and scop
 
 The fold-back commit safety contract is non-negotiable:
 
-1. Preflight `git status --porcelain -- "$ARTIFACT_PATH"` _before_ any artifact mutation.
-2. If clean: append the synthesis section, then `git add -- "$ARTIFACT_PATH"` (explicit `--` form, never `-A`, never globs) followed by `git commit -m "chore(oat): integrate brainstorm into <artifact> for <project-name>"`.
-3. If dirty: present the user with three options before any mutation — (a) commit current artifact changes first then fold-back as new scoped commit, (b) include current changes in the fold-back commit (warn that prior edits are mixed in; user explicitly accepts), or (c) abort fold-back and switch destination to "active project: brainstorming reference file" instead.
-4. Handoff prompt prints only after the scoped commit succeeds. If `git commit` fails (pre-commit hooks reject, signing fails, etc.), surface the error and do NOT print the handoff prompt.
+1. Resolve scope fail-closed, then preflight the full nested checkout with `git -C "$ACTIVE_PROJECT" status --porcelain` for synced or the exact artifact with `git status --porcelain -- "$ARTIFACT_PATH"` for shared/local, _before_ any artifact mutation. Synced checks must include every project file because the later push persists the whole checkout.
+2. If clean: append the synthesis section, then use a validated `oat project push --json` receipt for synced (capture its project-ref `sha`) or `git add -- "$ARTIFACT_PATH"` followed by an exact-path branch commit for shared/local.
+3. If dirty: present the user with three options before any mutation. Every persistence step remains scope-aware:
+   - (a) persist the current artifact changes first, then fold back in a second persistence step. Each step uses a validated `oat project push --json` receipt for synced or an exact-path branch commit for shared/local.
+   - (b) include current changes in the fold-back persistence step (warn that prior edits are mixed in; user explicitly accepts), using a validated project-ref push for synced or an exact-path branch commit for shared/local.
+   - (c) abort fold-back and switch destination to "active project: brainstorming reference file" instead; that route independently resolves scope and uses the same synced-push versus shared/local-commit split.
+4. Handoff prompt prints only after the scoped commit or synced push succeeds. On persistence failure, surface the error and do NOT print the handoff prompt.
 
 **Handoff target:** Append synthesis to the chosen upstream artifact, commit immediately (per safety contract above), then print the handoff prompt template:
 
@@ -175,6 +178,6 @@ After printing the prompt, the skill stops. The user runs the plan-authoring ski
 **Trigger phrases:** "this is supplementary for the active project", "save this with the project but don't change the design", "park this as a reference for the project", "stash this in the project's brainstorming folder". Also offered as the third option when the active-project 3-way router fires (related but supplementary → reference file).
 **Required template fields:** `title` (slug-friendly), filename (defaults to `YYYY-MM-DD-<topic>.md`), the synthesized payload (rendered using the same shape as `templates/brainstorm-doc.md`).
 **Optional template fields:** `motivation`, `vision`, `openQuestions`, `nextSteps` — same as doc-to-path destination.
-**Confirmation pattern:** `minimal` (filename + commit hash). After the file is written, the skill commits it on the active branch and reports the short commit hash alongside the absolute path (for example: "Wrote `<absolute-path>` and committed as `<hash>`.").
-**Handoff target:** no downstream skill invocation. Write the synthesized payload to `<active-project>/brainstorming/YYYY-MM-DD-<topic>.md` using the doc-to-path template shape. The `brainstorming/` subdirectory is created if it doesn't exist (parallel to `pr/` and `reviews/`). The reference file is a **durable tracked artifact**: after writing, the skill stages only the new file via `git add -- <reference-path>` and commits it with `chore(oat): capture brainstorming reference for <project-name>` — mirroring the scoped-staging discipline of the fold-back commit safety contract so the working tree is clean when the skill exits.
+**Confirmation pattern:** `minimal` (filename + persistence SHA). After the file is written, the skill reports the absolute path and scope-appropriate SHA: the exact-path branch commit for shared/local or the detached project-ref commit from the validated synced push receipt.
+**Handoff target:** no downstream skill invocation. Write the synthesized payload to `<active-project>/brainstorming/YYYY-MM-DD-<topic>.md` using the doc-to-path template shape. The `brainstorming/` subdirectory is created if it doesn't exist (parallel to `pr/` and `reviews/`). The reference file is a **durable project artifact**: persist it with the fail-closed scope guard so synced projects use `oat project push --json` and capture its `sha`, while other scopes retain scoped staging and the existing branch commit.
 **If user wants to keep brainstorming after this is offered:** return to flow with destination = active-project-reference-file. Available regardless of active project's phase or PR status; no special probing.

package/assets/skills/oat-cursor-cloud-projects/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-cursor-cloud-projects
-version: 1.0.2
+version: 1.1.1
 description: Use when OAT work is mentioned in a Cursor Cloud environment. Orients agents to cloud detection, repo-rooted project homes, user-first assets, CLI availability, and Cursor dispatch context without owning lifecycle execution.
 disable-model-invocation: false
 user-invocable: true
@@ -153,8 +153,18 @@ Resolve from the target repository:
 PROJECTS_ROOT="${OAT_PROJECTS_ROOT:-$(oat config get projects.root 2>/dev/null || echo ".oat/projects/shared")}"
 PROJECTS_ROOT="${PROJECTS_ROOT%/}"
 PROJECT_PATH=$(oat config get activeProject 2>/dev/null || true)
+if [ -n "$PROJECT_PATH" ]; then
+  PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || exit 1
+  if [ "$PROJECT_SCOPE" = "synced" ]; then
+    oat project pull "$PROJECT_PATH"
+  fi
+fi
 ```
 
+Run this guard from the target repository before reading project artifacts. A
+record-backed synced path whose checkout is absent is materialized by the pull;
+remote-only projects are adopted by the same command.
+
 Rules:
 
 - **Single-repo workspace:** the sole target repository owns `.oat/`, local

package/assets/skills/oat-dispatch-subagents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-dispatch-subagents
-version: 1.2.2
+version: 1.2.3
 description: Use when an OAT skill or workflow needs provider-neutral selection, launch, recovery, or evidence for bounded subagent work without project lifecycle policy.
 disable-model-invocation: true
 user-invocable: false
@@ -51,10 +51,22 @@ contract.
 
 Model-selection policy lives in the `subagent-orchestration` skill (same
 pack); this skill owns launch mechanics. Read this file before every
-OAT-managed subagent dispatch, then read
-`.agents/skills/subagent-orchestration/references/model-selection-principles.md`.
+OAT-managed subagent dispatch.
+
+Independently probe each required `<name>/SKILL.md` in order: `${SKILL_DIR}/..`
+from this loaded skill, `${HOME}/.agents/skills`, then
+`<repo-root>/.agents/skills`. Bind the first match for `subagent-orchestration`
+to its own `${ORCHESTRATION_SKILLS_ROOT}`; never ambient discovery. On a miss,
+name the skill, stop class-constrained dispatch, and give its intended-scope
+recovery command: `oat tools install utility --scope <user|project>` or
+`oat tools update --pack utility --scope <user|project>`.
+
+Then read
+`${ORCHESTRATION_SKILLS_ROOT}/subagent-orchestration/references/model-selection-principles.md`.
 Resolve the active provider and read exactly one selection reference from
-that skill plus the matching mechanics reference from this one:
+`${ORCHESTRATION_SKILLS_ROOT}/subagent-orchestration/references/` plus the
+matching mechanics reference from this skill's own `references/`. The
+short-form paths below are relative to those two already-bound roots:
 
 - Claude: `subagent-orchestration/references/provider-claude.md`, then
   `references/provider-claude.md`
@@ -69,8 +81,9 @@ mappings; the mechanics reference contains surface-specific launch controls.
 For an unsupported provider, apply the provider-neutral contract and fail
 closed when exact launch controls cannot be established.
 
-If the `subagent-orchestration` skill is not installed, treat model guidance
-as unresolved: fail closed for class-constrained dispatch, and for
+If no candidate root resolves `subagent-orchestration/SKILL.md`, treat model
+guidance as unresolved: fail closed for class-constrained dispatch, name the
+missing skill with its `utility` recovery commands above, and for
 unconstrained dispatch select only through active user and repository
 instructions intersected with the live catalog.