@open-agent-toolkit/cli 0.2.41 → 0.2.46

package/assets/agents/oat-phase-implementer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-phase-implementer
-version: 1.0.12
+version: 1.1.1
 description: Implements one plan phase end-to-end, commits each task separately, self-checks between tasks, and handles bounded review fixes when resumed by oat-project-implement.
 tools: Read, Write, Edit, Bash, Grep, Glob, Task
 color: cyan
@@ -131,6 +131,16 @@ After formatting, run the repository's applicable gate set over the produced
 diff, explicitly including artifact writes. This supplements rather than
 replaces every task and phase verification command below.
 
+## Synced-Scope Bookkeeping
+
+Artifact and recovery-ledger bookkeeping commits must first resolve scope with
+`oat project scope "$PROJECT_PATH" --format value`. A `synced` project uses
+`oat project push` with the original bookkeeping message; other scopes keep the
+existing scoped `git add` and `git commit` commands. Scope resolution fails
+closed. A nonzero project-push exit stops bookkeeping until the reported
+recovery is resolved and the push is retried. Planned code task commits such as
+`feat(pNN-tNN)` are unchanged.
+
 ## Prevention and Post-Commit Recovery
 
 Prevention is the first recovery control. Before every planned task commit:

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.41"
+  "oatVersion": "0.2.46"
 }

package/assets/docs/cli-utilities/configuration.md

@@ -76,7 +76,17 @@ Earlier CLI versions returned `config.json` / `config.local.json` / `env` / `def
 
 Common keys in `.oat/config.json`:
 
-- `projects.root` — where tracked projects live
+- `projects.root` — shared-scope project root. Relative values resolve from the
+  repository root; absolute values remain absolute. OAT derives the `local`
+  and `synced` roots as sibling directories named `local` and `synced` under
+  this root's parent, so a custom value relocates all three scope roots as one
+  layout. Synced project creation requires the derived `synced` root to resolve
+  inside the repository; an external absolute root remains usable for `shared`
+  and `local` projects but is rejected before any synced checkout, ref, record,
+  active pointer, or Git index mutation.
+- `projects.defaultScope` — scope used by project creation when `--scope` is
+  omitted (`synced` by default). `OAT_PROJECTS_DEFAULT_SCOPE` overrides the
+  configured value for the current process.
 - `worktrees.root` — where OAT-managed worktrees live
 - `git.defaultBranch` — base branch fallback for PR workflows
 - `documentation.root`, `documentation.tooling`, `documentation.config` — docs-surface ownership

package/assets/docs/cli-utilities/tool-packs.md

@@ -140,6 +140,12 @@ Two independent facts describe a pack:
   release manifest declares for that pack and scope, its presence, and its
   version or content digest.
 
+Versioned skills and agents must match on both version metadata and canonical
+content. A same-version content change is therefore reported as outdated rather
+than current. Content comparison ignores the executable-bit normalization OAT
+intentionally applies while materializing managed scripts, but still detects
+file content, entry-type, and symlink-target changes.
+
 Commands report both. `oat tools list` and `oat tools info` show placement,
 intent source, and completeness. `oat status` and `oat doctor` report drift
 between intent and inventory with a scoped recovery command.
@@ -182,11 +188,12 @@ without qualification. Install the pack at **project scope** when you need its
 agents; `oat tools update` cannot repair this, because it is a scope limitation
 rather than drift.
 
-Repository templates under `.oat/templates/` are **owner overrides**. Once a
-project-scope template exists, OAT will not rewrite it: the managed default now
-lives at user scope and in the bundle. Delete the repository copy to resume
-managed-default behavior. `oat status` and `oat doctor` report retained
-overrides so the divergence is visible rather than silent.
+Repository templates under `.oat/templates/` are **owner-owned seeds**. OAT
+compares a source-backed seed with its bundled default: a byte-equivalent copy
+is reported as current, while an edited copy is retained and reported as a
+`retained-override`. OAT will not rewrite the retained copy. Delete a repository
+template only when you intentionally want the bundled default seeded again;
+never delete edited mutable seed content merely to clear the diagnostic.
 
 ### Evolving pack membership
 
@@ -454,8 +461,15 @@ Key behavior:
 - Every pack's fresh-install default is user scope (`defaultScope` in the release manifest); existing installs keep their current placement on re-install, so a re-install never moves a pack between scopes or creates a second copy at the other one. This applies to the per-pack subcommands too: a bare `oat tools install docs` in a repository where `docs` is already at project scope stays at project scope, and only an explicit `--scope` overrides that
 - Removing a pack from a scope happens only when you explicitly choose a narrower end-state in the interactive flow (e.g. a pack at `both` set to `project` only). All staged removals are shown in a single change summary and applied only after one batch confirmation — declining makes no changes
 - Non-interactive installs (including `--scope project`, `--scope user`, and the default pack set) are strictly additive and never remove a pack from a scope. Removal is interactive-only
-- Tracks installed vs bundled skill versions and reports outdated skills
+- Tracks installed versus bundled skill and agent versions and canonical
+  content, reporting same-version content drift as outdated while ignoring
+  expected executable-bit normalization
 - Writes pack intent into the config file for the scope you installed into: a project install sets `tools.<pack>: true` in `.oat/config.json`, and a user install sets it in `~/.oat/config.json`. A user-only install never writes repository config
+- When a project install discovers existing project-scoped packs whose intent
+  is missing, it writes those exact intents in canonical pack order. Human
+  output prints `Adopted project tool pack: <pack>` once per adopted pack;
+  JSON output adds `adoptedPacks` only when the list is non-empty. This is pack
+  intent reconciliation, not repository PJM adoption
 - A user-only install needs no Git repository and performs no repository writes
 - Refreshes the managed `OAT tools` section in the repository-root `AGENTS.md` **only for project-scope runs of the aggregate `oat tools install`**. The per-pack subcommands (`oat tools install workflows`, `oat tools install docs`, and the rest) never write `AGENTS.md`, at either scope
 - Repository `AGENTS.md` guidance for project management is owned by adoption, not by pack placement. Installing the `project-management` pack no longer upserts a managed `OAT project-management` section; `oat pjm init` writes that repository guidance when the repository actually adopts PJM
@@ -474,12 +488,17 @@ Key behavior:
 
 - Accepts a tool name, `--pack <pack>`, or `--all` (mutually exclusive)
 - With no target, exits without mutation and suggests the explicit bulk command `oat tools update --all`; invalid packs and conflicting targets keep their own targeted diagnostics
-- Compares installed versions against bundled versions and copies updated assets
+- Compares installed versions and canonical content against bundled assets and
+  copies updates; equal version metadata does not hide content drift
 - For `--pack <pack>` and `--all`, an already-installed pack is reconciled to the **current** release membership in the scopes where it is installed, adding newly bundled skills, agents, templates, and scripts
 - A pack whose managed assets are all missing but whose intent is still declared is repaired from intent rather than skipped
 - Managed template and script companions are refreshed at **user** scope. A project-scope repository template is an owner override and is left alone
 - Non-versioned assets are compared by content digest, so an identical refresh is a no-op instead of a rewrite
 - Update persists inferred legacy intent only after a successful explicit mutation, so a read never rewrites your config
+- A successful project-scope update reports the exact newly adopted legacy pack
+  intents in canonical order. Human output uses
+  `Adopted project tool pack: <pack>`; JSON output adds the optional
+  `adoptedPacks` array only when at least one intent was written
 - `--scope all` outside a Git repository completes the user-scope work instead of failing. Unlike `oat status` and `oat doctor`, update skips project scope silently and does not name it in the result; an explicitly requested `--scope project` outside a repository is still a hard failure
 - Dry-run mode with `--dry-run`; auto-sync after mutations by default
 - Use `--no-sync` to skip auto-sync
@@ -735,8 +754,9 @@ Removal and migration use the symmetric contract: the follow-up sync prunes exac
 User-scope tool packs and explicit PJM adoption changed several defaults and
 exit codes. Nothing here is data-destructive, and legacy config keeps working —
 `tools.<pack>: false` still parses, complete pre-adoption PJM scaffolds are
-grandfathered as `inferred-legacy`, and no CLI flag was removed or renamed. But
-several commands you already run behave differently.
+grandfathered as `inferred-legacy`, and existing installs remain additive. One
+inert per-pack install flag was removed, and several commands you already run
+behave differently.
 
 ### Install scope defaults flipped to user
 
@@ -781,6 +801,26 @@ is not installed. Test for a truthy value instead. Legacy `false` values that
 already exist in a config file are still read (see
 [Legacy `false` intent](#legacy-false-intent)) — they are just never written.
 
+Direct config writes now enforce the same true-or-absent contract.
+`oat config set tools.<pack> false` exits `1` without changing the config. To
+remove a project-scoped pack and clear its intent, run:
+
+```bash
+oat tools remove --pack <pack> --scope project
+```
+
+Existing legacy `false` values remain readable migration input.
+
+### Per-pack install `--force` was removed
+
+`oat tools install <pack> --force` is now rejected as an unknown option. The
+flag was inert in the unified additive lifecycle. To reconcile installed
+assets, use the scoped update command instead:
+
+```bash
+oat tools update --pack <pack> --scope <scope>
+```
+
 ### Per-pack install `--json` changed shape
 
 The per-pack subcommands (`oat tools install docs`, `oat tools install
@@ -803,6 +843,12 @@ above. The previous single-scope payload's `scope`, `targetRoot`, `assetsRoot`,
 keying on them reads `undefined` rather than failing. Read `scopes` for the
 scopes acted on, and `results[].request.scopeRoot` for the target root of each.
 
+When a project-scope aggregate install, direct pack install, or update adopts
+missing legacy pack intents, the same single payload also contains
+`"adoptedPacks": ["docs", "workflows"]`. The field is omitted when nothing was
+adopted, and entries follow the manifest's canonical pack order. Human output
+reports the same set as one `Adopted project tool pack: <pack>` line per pack.
+
 ### Other behavior changes worth knowing
 
 - `oat tools remove --pack <pack>` deletes every managed asset the release

package/assets/docs/quickstart.md

@@ -9,6 +9,15 @@ Use this page to choose the OAT path that matches what you are actually trying t
 
 This page is intentionally lightweight. It is not the full command manual. Once you choose a path, continue into the owning section for the deeper operational detail.
 
+## Prerequisites
+
+- Node.js 22.17 or newer
+- Git 2.31 or newer
+
+OAT does not run an up-front Git version check. Git compatibility is evaluated
+best-effort by each command, and a missing or unsupported Git operation exits as
+a system error.
+
 ## Choose a Path
 
 ### Provider Sync

package/assets/docs/reference/cli-reference.md

@@ -56,6 +56,61 @@ The first practical expansion path is to keep improving the existing owners: [Do
 
 Notable commands introduced in the current CLI surface:
 
+- `oat project new <slug> --scope shared|local|synced [--force]` - create a
+  project in an explicit scope. Without `--scope`, creation uses
+  `projects.defaultScope`, which defaults to `synced`. Project slugs are
+  unique across all scopes by default, including recorded or remotely
+  published synced projects. `--force` deliberately permits a duplicate; use
+  an explicit project path with `project open` or `project pause` whenever a
+  slug is ambiguous across scopes.
+- `oat project scope [project] --format value|json` - resolve a project's
+  storage scope without inspecting its path manually.
+- `oat project push [project] [--message <message>]` - commit pending synced
+  artifacts, reconcile with the exact project ref on `origin`, publish it, and
+  refresh an open PR's artifact-links block. Use `--no-refresh-pr` to skip the
+  PR edit. With `--json`, success returns `status` (`pushed` or `up-to-date`),
+  the full project-ref `sha`, the retained `ref`, and optional `prRefresh`;
+  conflict and rejected outcomes return their corresponding `status` and exit
+  nonzero.
+- `oat project pull [project] [--no-commit]` - fetch and materialize or update a synced
+  checkout. Resolve a rebase conflict and run `pull --continue`, or use
+  `pull --abort` to return to the pre-pull state. Coordination children are
+  pulled by default; `--no-children` limits the operation to the selected
+  project. When pull adopts a remote project with no local discovery record,
+  `--no-commit` leaves the new record uncommitted for the caller to persist.
+  With `--json`, the receipt includes `status`, `sha`, and `ref`, plus
+  `conflicts` when applicable and per-child results when coordination children
+  were requested.
+- `oat project links [project] --format markdown|json` - render SHA-pinned
+  links for the linkable artifacts on the project ref. On GitHub origins the
+  artifacts become full-SHA blob links; other hosts degrade to the retained ref
+  and short SHA without guessing a web URL. `--durable-summary <path>` accepts
+  only a path contained in the repository, normalizes it repository-relative,
+  and renders it as a code span rather than a guessed remote link.
+- `oat project pause [project]` - persist the pause state and clear the active
+  project pointer. If synced publication is declined or fails after the pause
+  commit is created, that clean commit is retained; address the publication
+  failure and rerun `pause` to publish it.
+- `oat project prune [project] [--force] [--no-commit]` - remove every
+  checkout, the local and remote project refs, and the tracked record. When the
+  project is omitted, the active project is used. This is the explicit
+  destructive operation; `--force` may discard dirty or unpushed artifacts,
+  while `--no-commit` leaves the parent-record deletion for a library caller to
+  commit. If remote deletion succeeds but local checkout removal fails, the
+  local ref, record, and checkouts are retained. Resolve the reported local
+  obstruction and retry `prune --force`; do not run `project push`, which would
+  republish the deleted remote ref.
+- `oat project migrate <path> --to synced [--no-commit]` - migrate an existing
+  shared project to synced storage while preserving its artifacts and
+  retargeting the active project pointer. `--no-commit` leaves the parent
+  record and source-tree transition uncommitted for a library caller.
+- `oat project list --scope shared|local|synced` - filter tracked projects by
+  scope. Add `--remote` to discover project refs that do not yet have a local
+  record or checkout, and `--include-coordination` to include coordination
+  parents. A malformed discovery record with no materialized checkout appears
+  as a `recorded-invalid` row. When the checkout is materialized, its existing
+  row instead carries the restore hint and `recordError` parse diagnostic in
+  `--json` output.
 - `oat tools migrate --pack <pack> --from <scope> --to <scope>` - move one installed pack between project and user scope. Always previews first, installs and re-inventories the destination before touching the source, and offers source removal only after the destination is verified complete. Declining or running non-interactively leaves the pack installed at both scopes rather than failing. `--dry-run` stops after the preview; there is no force flag. See [Tool Packs](../cli-utilities/tool-packs.md#oat-tools-migrate).
 - `oat pjm doctor --json` - read-only repository PJM diagnostics whose result carries an additive `adoption` object (`state` of `declared` | `inferred-legacy` | `partial-initialization` | `none`, `repoRoot`, and `recovery`). This, not `oat tools has project-management`, is the check that answers whether _this repository_ adopted PJM.
 - `oat config dump --json` - merged config with source attribution
@@ -66,7 +121,7 @@ Notable commands introduced in the current CLI surface:
 - `oat review latest --json` - find the newest review artifact by `oat_generated_at`, scanning the active or specified project's `reviews/` and `reviews/archived/` directories plus ad-hoc review locations. Same-time candidates use target priority, then lifecycle recency (`final` > higher phase/task > lower phase/task). The JSON contract returns `path`, `scope`, `generatedAt`, `kind` (`project` or `adhoc`), `archived`, and `actionable`, with `null` values when no review exists. Archived project reviews remain discoverable as history but return `actionable: false`.
 - `oat project list --json` - summary state for tracked projects under the configured projects root
 - `oat project complete-state <project-path>` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout
-- `oat project archive [project-path] [--project-recap-run <project-relative-path>]` - archive a tracked project through the same local move, summary export, and optional S3 upload path used by completion. When omitted, the project path falls back to the active project. The optional recap path must identify a `project-recap` run inside the project's `explainers/` directory. Archive stages the selected complete package into `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>/`, verifies every manifest-declared immutable file byte, then atomically installs the export before deleting the active project. Existing destinations, incomplete legacy hash coverage, stale bytes, path escapes, and recipe mismatches fail without removing the active project.
+- `oat project archive [project-path] [--project-recap-run <project-relative-path>] [--no-commit]` - archive a tracked project through the same local move, summary export, and optional S3 upload path used by completion. When omitted, the project path falls back to the active project. The optional recap path must identify a `project-recap` run inside the project's `explainers/` directory. Archive stages the selected complete package into `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>/`, verifies every manifest-declared immutable file byte, then atomically installs the export before deleting the active project. Existing destinations, incomplete legacy hash coverage, stale bytes, path escapes, and recipe mismatches fail without removing the active project. `--no-commit` is a manual/library-only option: for a synced project it still removes the checkout but deliberately omits the lifecycle commit receipt. Never pass it through `oat-project-complete`, which requires that receipt.
 - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
 - `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. See [Implementation Execution](../workflows/projects/implementation-execution.md#parallel-phase-groups).
 - `oat project log append|check|synthesize|rollup` - manage the optional append-only project observation log: append validated judgment or structural entries, inspect grammar and synthesis status, complete end-of-run synthesis, and roll observations into `summary.md` plus the configured repository ledger. See [Project Log](../cli-utilities/project-log.md).

package/assets/docs/reference/file-locations.md

@@ -52,6 +52,8 @@ Pack intent is stored per scope:
 - Local runtime config (per-developer state): `.oat/config.local.json`
 - Active idea: `activeIdea` in `.oat/config.local.json` (repo) or `~/.oat/config.json` (user)
 - Projects root config: `projects.root` in `.oat/config.json` (read via `oat config get projects.root`)
+- Default project scope: `projects.defaultScope` in `.oat/config.json`
+  (`synced` by default; override with `OAT_PROJECTS_DEFAULT_SCOPE`)
 - Archive config: `archive.s3Uri`, `archive.s3SyncOnComplete`, `archive.summaryExportPath`, `archive.wrapUpExportPath`, `archive.awsProfile`, and `archive.awsRegion` in `.oat/config.json`
 - Workflow gate config: `workflow.gates.skills` and `workflow.gates.execTargets` in `.oat/config.json`, `.oat/config.local.json`, or `~/.oat/config.json` (manage via `oat gate`)
 - Project sync manifest/config: `.oat/sync/`
@@ -87,16 +89,31 @@ Config ownership note:
 ## Project artifact trees
 
 - Shared: `.oat/projects/shared/<project>/`
+- Synced checkout: `.oat/projects/synced/<project>/` (gitignored nested
+  worktree)
+- Synced record: `.oat/projects/synced/<project>.json` (tracked on the parent
+  branch)
+- Synced ref: `refs/oat/projects/<project>` on `origin`
 - Local: `.oat/projects/local/<project>/`
 - Archived: `.oat/projects/archived/<project>/`
 
+The OAT-managed block in the repository root `.gitattributes` marks shared
+project artifacts as generated for repository hosting UIs. `oat init` and
+`oat tools update` own that block; preserve non-OAT entries outside its markers
+and do not hand-edit the managed entry.
+
 Archive sync surfaces:
 
 - Local archive root: `.oat/projects/archived/`
 - Remote archive base: `archive.s3Uri` in `.oat/config.json`
 - Archive sync command: `oat repo archive sync` or `oat repo archive sync <project-name>`
 - Remote archive snapshot shape: `<archive.s3Uri>/<repo-slug>/projects/YYYYMMDD-<project-name>/`
-- Summary export target: `<repo>/<archive.summaryExportPath>/YYYYMMDD-<project-name>.md` when configured
+- Summary export target:
+  `<repo>/<archive.summaryExportPath>/YYYYMMDD-<project-name>.md` when
+  configured. The archive report returns this absolute filesystem path, while
+  `oat project links --durable-summary` normalizes a contained path to a
+  repository-relative code span. It does not invent a GitHub-style URL for
+  non-GitHub remotes.
 - Wrap-up export target: `<repo>/<archive.wrapUpExportPath>/YYYY-MM-DD-wrap-up-<label>.md` when configured; otherwise `oat-wrap-up` falls back to `<repo>/.oat/repo/reference/wrap-ups/`
 
 ## Ideas — project level (gitignored)

package/assets/docs/reference/oat-directory-structure.md

@@ -24,6 +24,9 @@ Project scope is used for project workflows and repo-local sync state. User scop
   config.local.json
   projects/
     shared/
+    synced/
+      <project>.json
+      <project>/
     local/
     archived/
   ideas/
@@ -47,7 +50,7 @@ Project scope is used for project workflows and repo-local sync state. User scop
 | `.oat/config.json`       | Shared repo runtime config for non-sync settings    | Includes `worktrees.root`, `projects.root`, `git.defaultBranch`, `archive.*`, and `documentation.*`     |
 | `.oat/config.local.json` | Local per-developer runtime state                   | Gitignored; includes `activeProject`, `lastPausedProject`, `activeIdea`                                 |
 | `.oat/state.md`          | Generated repo state dashboard                      | Gitignored; rebuilt with `oat state refresh` from config, project artifacts, and knowledge metadata     |
-| `.oat/projects/`         | OAT project artifacts                               | `shared`, `local`, `archived` scopes                                                                    |
+| `.oat/projects/`         | OAT project artifacts                               | `shared`, `synced`, `local`, and lifecycle `archived` locations                                         |
 | `.oat/ideas/`            | Project-level ideas store                           | Often gitignored                                                                                        |
 | `.oat/sync/`             | Interop sync state/config                           | See details below                                                                                       |
 | `.oat/templates/`        | Artifact templates used by OAT skills               | Source for scaffolding. Includes `docs-app-fuma/` (Fumadocs) and `docs-app-mkdocs/` (MkDocs) templates. |
@@ -105,6 +108,7 @@ Current schema keys:
 | `version`                                                  | `number`                   | `1`                      | Schema version                                                                                                                                                                                                                                                                                          |
 | `worktrees.root`                                           | `string`                   | `".worktrees"`           | Root directory for git worktrees (repo-relative or absolute)                                                                                                                                                                                                                                            |
 | `projects.root`                                            | `string`                   | `".oat/projects/shared"` | Default root directory for OAT projects                                                                                                                                                                                                                                                                 |
+| `projects.defaultScope`                                    | `string`                   | `"synced"`               | Scope used by project creation when `--scope` is omitted: `shared`, `local`, or `synced`. Environment override: `OAT_PROJECTS_DEFAULT_SCOPE`.                                                                                                                                                           |
 | `localPaths`                                               | `string[]`                 | -                        | Gitignored directories to sync between main repo and worktrees. Supports glob patterns. Managed via `oat local add/remove`.                                                                                                                                                                             |
 | `documentation.root`                                       | `string`                   | -                        | Root directory containing documentation source files (e.g., `apps/docs/docs`)                                                                                                                                                                                                                           |
 | `documentation.tooling`                                    | `string`                   | -                        | Documentation framework identifier (`mkdocs` or `fumadocs`)                                                                                                                                                                                                                                             |
@@ -139,7 +143,8 @@ Example:
 {
   "version": 1,
   "projects": {
-    "root": ".oat/projects/shared"
+    "root": ".oat/projects/shared",
+    "defaultScope": "synced"
   },
   "worktrees": {
     "root": ".worktrees"
@@ -173,12 +178,23 @@ For repo-relative values (levels 3-4), paths are resolved from the repository ro
 Each OAT project lives under:
 
 - `.oat/projects/shared/<project>/`
+- `.oat/projects/synced/<project>/` for a gitignored nested worktree whose
+  history is published to `refs/oat/projects/<project>`
+- `.oat/projects/synced/<project>.json` for the tracked discovery record that
+  identifies the ref, remote, and active or complete status
 - `.oat/projects/local/<project>/`
 - `.oat/projects/archived/<project>/`
 
-Archive sync behavior:
+Completion and archive sync behavior:
 
-- `oat-project-complete` always archives locally into `.oat/projects/archived/<project>/`.
+- When archiving is selected, `oat-project-complete` archives locally into
+  `.oat/projects/archived/<project>/`. For a synced project, the snapshot omits
+  the nested checkout's `.git` pointer and `reviews/`, then completion marks
+  the tracked record complete, removes the nested worktree, and retains the
+  project ref so pinned links keep resolving.
+- When archiving is disabled or declined, completion leaves the synced
+  checkout and ref in place, pushes the finalized artifacts, and exact-path
+  commits the tracked record as complete.
 - If `archive.s3SyncOnComplete=true` and `archive.s3Uri` is configured, completion also uploads a dated snapshot such as `<archive.s3Uri>/<repo-slug>/projects/20260401-<project>/`.
 - `oat repo archive sync` syncs all repo archived projects down from S3 into `.oat/projects/archived/`.
 - `oat repo archive sync <project-name>` syncs the latest dated remote snapshot for a single project into `.oat/projects/archived/<project-name>/`.

package/assets/docs/reference/troubleshooting.md

@@ -77,8 +77,10 @@ Use [Instruction Sync](../provider-sync/instruction-sync.md) for the full strate
 
 - Run `oat init tools` to install/update bundled OAT tool packs.
 - In TTY mode, select which outdated skills to update when prompted.
-- In non-interactive mode, rerun the relevant pack subcommand with `--force` if you want to overwrite outdated installed skills.
-- For pack-level drift rather than a single skill, prefer the scoped command doctor prints: `oat tools update --pack <pack> --scope <scope>`.
+- In non-interactive mode, run the scoped command doctor prints:
+  `oat tools update --pack <pack> --scope <scope>`.
+- Per-pack install commands no longer accept the previously inert `--force`
+  option.
 
 ## `sync` reports an unsafe provider parent
 
@@ -147,18 +149,23 @@ Both commands report managed pack state with a scoped recovery command:
 
 - `partial` — some managed assets are missing, or intent is declared with none
   installed. Fix with `oat tools update --pack <pack> --scope <scope>`.
-- `stale` — installed assets are behind the bundled release. Same fix.
+- `stale` — installed assets are behind the bundled release, or a managed skill
+  or agent has the bundled version metadata but different canonical content.
+  Expected executable-bit normalization on managed scripts is ignored. Fix with
+  the same scoped update command.
 - `newer` — installed assets are ahead of the bundle. This is informational and
   usually means the CLI is older than the assets; update the CLI rather than
   downgrading the pack.
-- `retained-override` — an owner-owned seeded asset exists at the scope, so the
-  managed default is intentionally not applied there. This covers repository
-  templates under `.oat/templates/` **and** seeded content such as
-  `.oat/ideas/backlog.md` and `.oat/ideas/scratchpad.md`. Deleting the file is
-  the right move only for a **template** you want OAT to manage again; never
-  delete seeded content you have edited, because the next install or update
-  reseeds the bundled default in its place and your edits are gone. The finding
-  is informational and carries no recovery command for exactly that reason.
+- `retained-override` — a source-backed owner-owned seed differs from its
+  bundled default, so OAT retains the edited copy instead of overwriting it. A
+  bundle-equal seed is current and does not produce this finding. Retained
+  overrides cover repository templates under `.oat/templates/` **and** seeded
+  content such as `.oat/ideas/backlog.md` and `.oat/ideas/scratchpad.md`.
+  Deleting the file is the right move only for a **template** you intentionally
+  want OAT to seed from the bundle again; never delete seeded content you have
+  edited, because the next install or update reseeds the bundled default in its
+  place and your edits are gone. The finding is informational and carries no
+  recovery command for exactly that reason.
 - `user-agent-unmaterialized` — the pack installed canonical agents into
   `~/.agents/agents/`, but user scope materializes no provider view for them
   beyond the bundled managed role files. `oat tools update` cannot fix this.

package/assets/docs/workflows/projects/artifacts.md

@@ -5,7 +5,33 @@ description: 'Project artifact contracts: state.md, spec.md, design.md, plan.md,
 
 # Project Artifacts
 
-Project artifacts live under `.oat/projects/<scope>/<project>/`.
+Project artifacts use one of three active scopes:
+
+- `shared` artifacts live directly on the feature branch under
+  `.oat/projects/shared/<project>/`.
+- `synced` artifacts live in a gitignored nested worktree at
+  `.oat/projects/synced/<project>/`, backed by
+  `refs/oat/projects/<project>` on `origin`. The feature branch tracks only
+  `.oat/projects/synced/<project>.json`.
+- `local` artifacts stay untracked on the current machine under
+  `.oat/projects/local/<project>/`.
+
+`projects.defaultScope` controls creation when a command does not pass
+`--scope`; its default is `synced`.
+
+## Synced artifact bookkeeping
+
+Lifecycle skills write the same project files in every scope. After a synced
+write, they use `oat project push` instead of staging the artifact path on the
+parent branch. The command makes an artifact commit in the nested checkout,
+rebases it on the fetched project ref, and pushes only that ref. Arrival skills
+run `oat project pull` before reading artifacts so a record or remote ref can
+materialize the checkout first.
+
+The tracked JSON record is routing metadata, not a copy of the project. It
+identifies the slug, `origin`, ref, status, and archive snapshot when present.
+The project ref remains the source of truth for active artifact content and
+history.
 
 ## Core artifacts
 

package/assets/docs/workflows/projects/implementation-execution.md

@@ -406,6 +406,28 @@ For a plan-declared parallel group, the root:
 Containment, ownership, base, or fixture-readiness failure in smoke mode aborts
 the run. It never authorizes replacement or sequential degradation.
 
+## Synced projects in worktrees
+
+A tracked `.oat/projects/synced/<project>.json` record lets every repository
+worktree discover the same synced project without putting its artifacts on the
+feature branch. On arrival, project skills run `oat project pull` before they
+read state. Pull fetches the exact `refs/oat/projects/<project>` ref and, when
+needed, materializes a fresh nested checkout at
+`.oat/projects/synced/<project>/`.
+
+Each parent worktree gets an independent detached nested checkout. Those
+checkouts do not share an index or working tree; they reconcile artifact
+history through the project ref on `origin`. If a pull or push encounters an
+overlapping change, resolve the files in the nested checkout and run
+`oat project pull --continue`. Use `oat project pull --abort` to restore the
+pre-pull state instead.
+
+`oat local sync` skips these nested repositories, so local-path hydration does
+not copy or overwrite synced artifact checkouts. Removing a parent worktree
+also needs no special nested-checkout cleanup: the ignored nested worktree does
+not prevent parent removal, and the next `oat project pull` prunes stale Git
+worktree registrations before materializing or updating the current checkout.
+
 ## Codex Depth
 
 Default execution needs the root-to-phase-agent depth. `agents.max_depth >= 2`

package/assets/docs/workflows/projects/index.md

@@ -24,6 +24,8 @@ Projects are where the workflow layer becomes concrete: lifecycle phases, `state
 - [Programmatic Execution](programmatic-execution.md) - Per-harness headless/CLI execution surfaces and where OAT uses them.
 - [Project Artifacts](artifacts.md) - What lives in `state.md`, `discovery.md`, `plan.md`, `implementation.md`, and related files.
 - [Implementation Execution](implementation-execution.md) - Phase dispatch, runtime selection, review/fix loop, and dry-run behavior.
+- [Reviewing OAT PRs](reviewing-oat-prs.md) - Read synced-project records and SHA-pinned reviewer links in a PR.
+- [Picking Up Projects](picking-up-projects.md) - Continue a synced project on another machine or from another user.
 - [Project Splitting](splitting.md) - How broad discoveries or brainstorms become coordination parents and child projects.
 - [State Machine](state-machine.md) - Lifecycle and review status transitions across a project.
 - [Reviews](reviews.md) - How review request/receive loops work inside OAT projects.
@@ -50,6 +52,8 @@ This sub-section is the deep technical surface for how tracked OAT projects exec
 - Split broad scopes into coordination parents and focused children in [Project Splitting](splitting.md).
 - Understand lifecycle and review transitions in [State Machine](state-machine.md).
 - Learn review and PR expectations in [Reviews](reviews.md) and [PR Flow](pr-flow.md).
+- Review a synced project's durable context in [Reviewing OAT PRs](reviewing-oat-prs.md).
+- Continue remote project work with [Picking Up Projects](picking-up-projects.md).
 
 ## Go Deeper
 
@@ -68,4 +72,6 @@ This sub-section is the deep technical surface for how tracked OAT projects exec
 - [State Machine](state-machine.md) - Lifecycle and review status transitions across a project.
 - [Reviews](reviews.md) - How review request/receive loops work inside OAT projects.
 - [PR Flow](pr-flow.md) - Progress and final PR generation expectations.
+- [Reviewing OAT PRs](reviewing-oat-prs.md) - Record metadata, pinned links, and editor discovery for synced projects.
+- [Picking Up Projects](picking-up-projects.md) - Remote discovery, adopting pull, coordination children, and retention boundaries.
 - [Repository PR Comment Analysis](repo-analysis.md) - Repo-wide PR comment collection and triage workflows.

package/assets/docs/workflows/projects/lifecycle.md

@@ -70,13 +70,23 @@ After implementation closeout finishes:
    - GitHub PR feedback delegates to `oat-project-review-receive-remote`
    - Review artifacts delegate to `oat-project-review-receive`
    - After revision tasks complete, state returns to `pr_open`
-5. **Complete** (`oat-project-complete`) — accepts any phase status (`pr_open`, `complete`, `in_progress`), auto-refreshes `summary.md` before closeout when needed, and always archives the project locally
+5. **Complete** (`oat-project-complete`) — accepts any phase status (`pr_open`, `complete`, `in_progress`), auto-refreshes `summary.md` before closeout when needed, and archives when selected by the workflow preference or completion prompt
 
 ### Completion archive behavior
 
-On completion, OAT now treats archive handling as part of the closeout lifecycle:
-
-- Local archive is always written to `.oat/projects/archived/<project>/`.
+On completion, OAT treats archive handling as an explicit closeout choice:
+
+- When archiving is selected, the local archive is written to `.oat/projects/archived/<project>/`.
+- When archiving is disabled or declined, durable projects remain at their
+  active path. Synced completion still finalizes and pushes the project ref,
+  commits the discovery record as `complete`, retains the checkout and ref, and
+  attests a selected recap against the project-ref history.
+- For a synced project, closeout first finalizes the project artifacts and
+  pushes them to `refs/oat/projects/<project>`. Archive then requires a clean,
+  fully pushed checkout; copies it without the `.git` pointer or `reviews/`;
+  marks the tracked record complete; commits the record and configured durable
+  exports on the parent branch; removes the nested checkout; and retains the
+  ref. This order keeps SHA-pinned PR links valid after completion.
 - If `.oat/config.json` enables `archive.s3SyncOnComplete` and sets `archive.s3Uri`, completion also attempts an S3 upload for a dated snapshot such as `<archive.s3Uri>/<repo-slug>/projects/20260401-<project>/`.
 - If `.oat/config.json` sets `archive.awsProfile` and/or `archive.awsRegion`, those values are forwarded to every `aws` invocation triggered by completion (preflight checks + `aws s3 sync`) and override any ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` / `AWS_REGION` / `AWS_DEFAULT_REGION` values. The repo's archive-scoped credentials are treated as deliberate intent so users don't have to unset shell env vars before running completion. See [`config-and-local-state.md`](../../cli-utilities/config-and-local-state.md) for the full precedence chain.
 - If `.oat/config.json` sets `archive.summaryExportPath`, completion copies `summary.md` to `<archive.summaryExportPath>/20260401-<project>.md`.
@@ -130,7 +140,7 @@ summary, documentation, PR, or project completion.
 
 ### Retrospective completion safety net
 
-Before an interactive completion archives the project,
+Before an interactive completion closes the project,
 `oat-project-complete` checks for
 `{PROJECT_PATH}/references/project-retro.md`. If the artifact is missing, it
 offers to generate one before completion. If the artifact exists, completion
@@ -292,6 +302,10 @@ Capture lane progression:
 ## Operational rules
 
 - Keep `state.md`, `plan.md`, and `implementation.md` synchronized.
+- For a synced project, publish lifecycle artifact writes with
+  `oat project push`; do not stage `.oat/projects/synced/<project>/` on the
+  parent branch.
+- On arrival, run `oat project pull` before reading a synced project's state.
 - Stop at configured HiLL checkpoints.
 - Do not move lifecycle forward when required review gates are unresolved.
 - Project entry skills (`oat-project-new`, `oat-project-quick-start`, and `oat-project-import-plan`) surface inherited dirty git state before scaffolding. If the dirty list includes `.oat/sync/manifest.json`, `.claude/`, `.cursor/`, or `.codex/`, the skill calls out that those paths are typically sync output and offers Commit now, Proceed anyway, or Abort.