@open-agent-toolkit/cli 0.0.64 → 0.0.66

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

@@ -21,7 +21,7 @@ For detailed `.oat/` tree semantics, see:
 - 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`)
-- Archive config: `archive.s3Uri`, `archive.s3SyncOnComplete`, `archive.summaryExportPath`, and `archive.wrapUpExportPath` in `.oat/config.json`
+- Archive config: `archive.s3Uri`, `archive.s3SyncOnComplete`, `archive.summaryExportPath`, `archive.wrapUpExportPath`, `archive.awsProfile`, and `archive.awsRegion` in `.oat/config.json`
 - Project manifests/config: `.oat/sync/`
 
 Config discovery via CLI:

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

@@ -108,6 +108,8 @@ Current schema keys:
 | `archive.s3SyncOnComplete`                  | `boolean`  | `false`                  | When `true`, `oat-project-complete` uploads the archived project to the configured S3 archive after local archive succeeds                                                                                                                                                                              |
 | `archive.summaryExportPath`                 | `string`   | -                        | Repo-relative directory where completion exports `summary.md` as a dated snapshot like `20260401-<project-name>.md` for durable tracked reference                                                                                                                                                       |
 | `archive.wrapUpExportPath`                  | `string`   | -                        | Repo-relative directory where `oat-wrap-up` writes dated reports like `20260413-wrap-up-past-week.md`; when unset, the skill falls back to `.oat/repo/reference/wrap-ups/`                                                                                                                              |
+| `archive.awsProfile`                        | `string`   | -                        | Optional AWS named profile forwarded as `AWS_PROFILE` to every `aws` invocation in archive flows (`oat-project-complete` S3 sync, `oat project archive sync`). Overrides ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` when set.                                                                  |
+| `archive.awsRegion`                         | `string`   | -                        | Optional AWS region forwarded as `AWS_REGION` to every `aws` invocation in archive flows. Overrides ambient shell `AWS_REGION` / `AWS_DEFAULT_REGION` when set.                                                                                                                                         |
 
 All `documentation.*` keys are managed via `oat config get/set` and are set automatically by `oat docs init`.
 The `git.defaultBranch` key is auto-detected during `oat init` and can be overridden via `oat config set git.defaultBranch <branch>`.

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

@@ -62,6 +62,7 @@ On completion, OAT now treats archive handling as part of the closeout lifecycle
 
 - Local archive is always written to `.oat/projects/archived/<project>/`.
 - 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`.
 - Missing or unusable AWS CLI configuration produces warnings during completion instead of blocking closeout.
 - `oat project archive sync` can later sync all archived projects, or one named archived project, back down from S3; it selects the latest dated remote snapshot and materializes it into the local bare archive tree.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.0.64",
-  "docs-config": "0.0.64",
-  "docs-theme": "0.0.64",
-  "docs-transforms": "0.0.64"
+  "cli": "0.0.66",
+  "docs-config": "0.0.66",
+  "docs-theme": "0.0.66",
+  "docs-transforms": "0.0.66"
 }

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-complete
-version: 1.4.4
+version: 1.4.5
 description: Use when all implementation work is finished and the project is ready to close. Marks the OAT project lifecycle as complete.
 disable-model-invocation: true
 user-invocable: true
@@ -379,10 +379,56 @@ echo "Project archived to $ARCHIVE_PATH"
 
 - Always archive locally first. The local archive is the authoritative completion artifact even when remote sync is also configured.
 - If `archive.summaryExportPath` is configured and `summary.md` exists after archive, copy it to `{repoRoot}/{archive.summaryExportPath}/YYYYMMDD-{PROJECT_NAME}.md`.
-- If `archive.s3SyncOnComplete=true` and `archive.s3Uri` is configured, sync the archived project to `{archive.s3Uri}/{repo-slug}/{PROJECT_NAME}/`. The S3 sync excludes process artifacts (`reviews/*`, `pr/*`) — only core deliverables (discovery, spec, design, plan, implementation, summary, state) are uploaded. The CLI enforces this via `S3_ARCHIVE_SYNC_EXCLUDES` in `archive-utils.ts`.
+- If `archive.s3SyncOnComplete=true` and `archive.s3Uri` is configured, sync the archived project to `{archive.s3Uri}/{repo-slug}/projects/YYYYMMDD-{PROJECT_NAME}/`. The S3 sync excludes process artifacts (`reviews/*`, `pr/*`) — only core deliverables (discovery, spec, design, plan, implementation, summary, state) are uploaded. The CLI enforces this via `S3_ARCHIVE_SYNC_EXCLUDES` in `archive-utils.ts`.
 - If AWS CLI is missing or unusable for that S3 sync, warn and continue. Completion must not fail after the local archive succeeds.
 - If `archive.s3SyncOnComplete` is false or `archive.s3Uri` is unset, skip remote sync without prompting.
 
+**AWS credential handling for archive S3 sync (required):**
+
+When `archive.s3SyncOnComplete=true` and `archive.s3Uri` is set, the agent MUST honor the repo's archive-scoped AWS credentials instead of falling back to whatever shell profile/region happens to be active. The contract mirrors `buildAwsEnv` in `packages/cli/src/commands/project/archive/archive-utils.ts`.
+
+- **Read both keys from OAT config before any AWS CLI call:**
+
+  ```bash
+  ARCHIVE_AWS_PROFILE=$(oat config get archive.awsProfile 2>/dev/null || true)
+  ARCHIVE_AWS_REGION=$(oat config get archive.awsRegion 2>/dev/null || true)
+  ```
+
+- **Apply them to every `aws` invocation tied to archive sync** — preflight checks (`aws --version`, `aws sts get-caller-identity`), bucket access probes (`aws s3 ls`), and the actual `aws s3 sync`. Do not mix configured values across some calls and ambient values across others.
+- **Configured archive values WIN over ambient shell AWS env vars.** A non-empty `archive.awsProfile` overrides any `AWS_PROFILE` or `AWS_DEFAULT_PROFILE` already exported in the shell. A non-empty `archive.awsRegion` overrides `AWS_REGION` and `AWS_DEFAULT_REGION`. Treat the repo's archive-scoped declaration as deliberate intent — users should not have to unset shell env vars to get correct archive credentials. Empty/unset config values fall through to the AWS CLI's normal resolution chain.
+- **Prefer the OAT CLI when it is available.** If you delegate archive sync to an `oat project archive ...` invocation, the CLI applies the canonical handling for you (config-resolved profile/region clobber the spawned env). Do not pass `--profile` / `--region` flags unless the user asked for a one-off override different from the repo config.
+- **Manual AWS CLI fallback** — when no OAT command wraps the operation and the agent must call `aws` directly, pass the configured profile/region explicitly. Either use flags:
+
+  ```bash
+  AWS_FLAGS=()
+  if [[ -n "$ARCHIVE_AWS_PROFILE" ]]; then
+    AWS_FLAGS+=(--profile "$ARCHIVE_AWS_PROFILE")
+  fi
+  if [[ -n "$ARCHIVE_AWS_REGION" ]]; then
+    AWS_FLAGS+=(--region "$ARCHIVE_AWS_REGION")
+  fi
+
+  aws "${AWS_FLAGS[@]}" sts get-caller-identity
+  aws "${AWS_FLAGS[@]}" s3 sync \
+    "$ARCHIVE_PATH" \
+    "${ARCHIVE_S3_URI%/}/${REPO_SLUG}/projects/${SNAPSHOT_NAME}/" \
+    --exclude 'reviews/*' --exclude 'pr/*'
+  ```
+
+  …or set the equivalent env vars for the spawned process so the same precedence applies:
+
+  ```bash
+  AWS_ENV=()
+  [[ -n "$ARCHIVE_AWS_PROFILE" ]] && AWS_ENV+=("AWS_PROFILE=$ARCHIVE_AWS_PROFILE")
+  [[ -n "$ARCHIVE_AWS_REGION" ]] && AWS_ENV+=("AWS_REGION=$ARCHIVE_AWS_REGION")
+  env "${AWS_ENV[@]}" aws s3 sync ...
+  ```
+
+  Both shapes are acceptable; the AWS CLI treats `--profile` / `--region` and `AWS_PROFILE` / `AWS_REGION` env as higher precedence than `AWS_DEFAULT_*`, so the configured values win.
+
+- **Report the resolved profile/region in the completion summary** so the user can confirm the right identity ran the sync, e.g. `Archive S3 sync used AWS profile=tkstang-artifact-sync region=us-east-1`. Do not echo raw access keys, session tokens, or any value from `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN`. If `archive.awsProfile` or `archive.awsRegion` is unset, report `<unset; using shell default>` for that field.
+- **AccessDenied troubleshooting** — if `aws s3 sync` returns AccessDenied, confirm before retrying that the spawn actually used `archive.awsProfile` (not the ambient shell profile). A common pitfall is invoking `aws s3 sync` without flags from a shell where `AWS_PROFILE` points at an unrelated identity; rerun with the configured profile/region applied as above.
+
 **Worktree durability guard (required):**
 
 - If running in a worktree and the primary repo archive path is unavailable, do not silently continue with a local-only archive.
@@ -488,6 +534,7 @@ Show user:
 
 - "Project **{PROJECT_NAME}** marked as complete."
 - If archived: "Archived location: **{PROJECT_PATH}**"
+- If S3 archive sync ran: include the resolved AWS profile and region used (e.g. `Archive S3 sync: profile=<archive.awsProfile> region=<archive.awsRegion>`). Show `<unset; using shell default>` for any field the config did not provide. Never echo raw credentials (`AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, etc.).
 - Include commit hash and push result for the bookkeeping changes.
 - If PR was opened: include the PR URL.
 - If `oat_pr_url` is present, show it in the completion summary even when PR creation was skipped because the project already tracked an open PR.

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-implement
-version: 2.0.6
+version: 2.0.7
 description: Use when plan.md is ready for execution. Dispatches phase-level subagents with bounded fix loops; supports plan-declared parallel phase groups with worktree-isolated execution and ordered fan-in.
 argument-hint: '[--retry-limit <N>] [--dry-run]'
 disable-model-invocation: true
@@ -23,7 +23,7 @@ Execute the implementation plan task-by-task with full state tracking.
 **Purpose:** Execute plan tasks with TDD discipline, track progress, handle blockers.
 
 **CRITICAL — Bookkeeping commits are mandatory, not optional.**
-After every code commit and after every phase/review-fix completion, you MUST commit the OAT tracking files (`implementation.md`, `state.md`, `plan.md`) as a separate bookkeeping commit. Do not defer, batch, or skip these commits under the reasoning that they "aren't related to the implementation." Skipping a bookkeeping commit is the primary cause of cross-session state drift and will cause the next implementation run to fail bookkeeping cross-checks. If bookkeeping commits feel frequent, that is the intended design — they are cheap and they prevent drift.
+After every code commit and after every phase/review-fix completion, you MUST commit the OAT tracking files (project: `implementation.md`, `state.md`, `plan.md`; repo dashboard: `.oat/state.md`) as a separate bookkeeping commit. Refresh the repo dashboard with `oat state refresh` immediately before staging so `.oat/state.md` reflects the just-completed phase/task. Do not defer, batch, or skip these commits under the reasoning that they "aren't related to the implementation." Skipping a bookkeeping commit (or skipping the dashboard refresh) is the primary cause of cross-session state drift and will cause the next implementation run to fail bookkeeping cross-checks. If bookkeeping commits feel frequent, that is the intended design — they are cheap and they prevent drift.
 
 **CRITICAL — Review boundaries require a committed artifact baseline.**
 Do not enter checkpoint review, final review, revise, or PR-final handoff with dirty core project artifacts (`discovery.md`, `spec.md`, `design.md`, `plan.md`, `implementation.md`, `state.md`, plus `.oat/state.md` when refreshed). If one of those boundaries is next and artifact bookkeeping is still uncommitted, stop and create the bookkeeping commit first.
@@ -646,7 +646,8 @@ For each phase that completed:
 **Bookkeeping commit (mandatory):**
 
 ```bash
-git add {PROJECT_PATH}/implementation.md {PROJECT_PATH}/state.md {PROJECT_PATH}/plan.md
+oat state refresh
+git add {PROJECT_PATH}/implementation.md {PROJECT_PATH}/state.md {PROJECT_PATH}/plan.md .oat/state.md
 git commit -m "chore(oat): bookkeeping after {pNN} {pass|fail}"
 ```
 
@@ -719,14 +720,15 @@ When pausing:
 
 **DO NOT SKIP.** This commit prevents state drift across sessions.
 
-After phase summary and task pointer advancement, commit all modified OAT tracking files:
+After phase summary and task pointer advancement, refresh the repo dashboard and commit all modified OAT tracking files:
 
 ```bash
-git add "$PROJECT_PATH/implementation.md" "$PROJECT_PATH/state.md" "$PROJECT_PATH/plan.md"
+oat state refresh
+git add "$PROJECT_PATH/implementation.md" "$PROJECT_PATH/state.md" "$PROJECT_PATH/plan.md" .oat/state.md
 git diff --cached --quiet || git commit -m "chore(oat): update tracking artifacts for {phase} completion"
 ```
 
-Do not use `git add -A` or glob patterns. Only commit the three OAT project files listed above.
+Do not use `git add -A` or glob patterns. Only commit the four files listed above (three project artifacts plus the regenerated repo dashboard).
 
 **Note on HiLL types:**
 
@@ -852,14 +854,15 @@ Implementation - Tasks complete; awaiting final review.
 
 **DO NOT SKIP.** This commit prevents state drift across sessions.
 
-After updating state.md to reflect implementation completion, commit all modified OAT tracking files:
+After updating state.md to reflect implementation completion, refresh the repo dashboard and commit all modified OAT tracking files:
 
 ```bash
-git add "$PROJECT_PATH/implementation.md" "$PROJECT_PATH/state.md" "$PROJECT_PATH/plan.md"
+oat state refresh
+git add "$PROJECT_PATH/implementation.md" "$PROJECT_PATH/state.md" "$PROJECT_PATH/plan.md" .oat/state.md
 git diff --cached --quiet || git commit -m "chore(oat): update tracking artifacts for implementation complete"
 ```
 
-Do not use `git add -A` or glob patterns. Only commit the three OAT project files listed above.
+Do not use `git add -A` or glob patterns. Only commit the four files listed above (three project artifacts plus the regenerated repo dashboard).
 
 ### Step 13: Final Verification
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.0.64",
+  "version": "0.0.66",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -33,7 +33,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.0.64"
+    "@open-agent-toolkit/control-plane": "0.0.66"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",