@open-agent-toolkit/cli 0.1.9 → 0.1.11

package/assets/docs/cli-utilities/config-and-local-state.md

@@ -101,7 +101,7 @@ For the full state model, repair semantics, and examples, see [Instruction Sync]
 
 ## Repo state helpers
 
-- `oat state refresh` - rebuild the `.oat/state.md` dashboard for the repo
+- `oat state refresh` - rebuild the generated, gitignored `.oat/state.md` dashboard for the repo
 - `oat index init` - generate a lightweight `project-index.md` for orientation
 
 ## Internal helpers and diagnostics

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

@@ -45,6 +45,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/ideas/`            | Project-level ideas store                        | Often gitignored                                                                                        |
 | `.oat/sync/`             | Interop sync state/config                        | See details below                                                                                       |

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.9",
-  "docs-config": "0.1.9",
-  "docs-theme": "0.1.9",
-  "docs-transforms": "0.1.9"
+  "cli": "0.1.11",
+  "docs-config": "0.1.11",
+  "docs-theme": "0.1.11",
+  "docs-transforms": "0.1.11"
 }

package/assets/skills/oat-pjm-review-backlog/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-pjm-review-backlog
-version: 1.1.0
+version: 1.2.0
 description: Use when prioritizing the file-backed repo backlog or evaluating roadmap alignment. Produces value-effort ratings, dependency mapping, and execution recommendations.
 argument-hint: '[backlog-root] [--roadmap=<path>] [--output=<path>]'
 disable-model-invocation: true
@@ -48,11 +48,12 @@ When executing this skill, provide lightweight progress feedback so the user can
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 - Before multi-step work, print short step indicators, e.g.:
-  - `[1/5] Resolving backlog inputs…`
-  - `[2/5] Cataloging backlog items…`
-  - `[3/5] Reading codebase context…`
-  - `[4/5] Writing review document…`
-  - `[5/5] Summarizing recommendations…`
+  - `[1/6] Resolving backlog inputs…`
+  - `[2/6] Cataloging backlog items…`
+  - `[3/6] Reading codebase context…`
+  - `[4/6] Writing review document…`
+  - `[5/6] Summarizing recommendations…`
+  - `[6/6] (Optional) Priority-alignment walkthrough…` — only print after the operator accepts the offer in Step 9
 
 ## Arguments
 
@@ -60,7 +61,8 @@ Parse from `$ARGUMENTS`:
 
 - **backlog-root**: (optional) Path to the backlog root directory. Defaults to `.oat/repo/reference/backlog/`.
 - **--roadmap=\<path\>**: (optional) Path to a roadmap document for alignment analysis.
-- **--output=\<path\>**: (optional) Where to write the review. Defaults to `.oat/repo/reviews/backlog-and-roadmap-review.md`.
+- **--output=\<path\>**: (optional) Where to write the living review. Defaults to `.oat/repo/reference/backlog/reviews/backlog-and-roadmap-review.md`.
+- **--archive-dated**: (optional) Also write a dated snapshot alongside the living review at `.oat/repo/reference/backlog/reviews/backlog-and-roadmap-review-YYYY-MM-DD.md`. Default: off.
 
 ## Process
 
@@ -85,7 +87,12 @@ Parse from `$ARGUMENTS`:
 **Output path:**
 
 1. If `--output` is provided, use it directly.
-2. Otherwise, default to `.oat/repo/reviews/backlog-and-roadmap-review.md`.
+2. Otherwise, default to `.oat/repo/reference/backlog/reviews/backlog-and-roadmap-review.md` (the living, single-file review co-located with the backlog).
+3. If the `backlog/reviews/` directory does not exist yet, create it before writing. Do not fall back to `.oat/repo/reviews/` — backlog review artifacts now live under the file-backed backlog, not the repo-wide reviews directory.
+
+**Dated snapshot (optional):**
+
+If `--archive-dated` is passed, also write a copy to `.oat/repo/reference/backlog/reviews/backlog-and-roadmap-review-YYYY-MM-DD.md` in the **same directory** as the living review. Do not write dated snapshots to `.oat/repo/reviews/`.
 
 ### Step 2: Read and Catalog Backlog Items
 
@@ -165,6 +172,8 @@ If a roadmap was provided:
 
 Use the template at `.agents/skills/oat-pjm-review-backlog/references/backlog-review-template.md`.
 
+Write the **living** review to the resolved output path (default `.oat/repo/reference/backlog/reviews/backlog-and-roadmap-review.md`). If `--archive-dated` was passed, also write a dated snapshot alongside it (`backlog-and-roadmap-review-YYYY-MM-DD.md` in the same directory). Never split living and dated outputs across different directories — they must live together under `backlog/reviews/`.
+
 Ensure:
 
 - Every active backlog item file appears in the item catalog
@@ -183,6 +192,39 @@ After writing the review, provide:
 
 When listing specific items in this summary, follow the **Reference Format Convention** above — every backlog item must appear as `` `bl-XXXX` (human-readable title) `` (or the bold-with-em-dash variant in tables). Do not emit bare IDs.
 
+### Step 9: Offer Priority Alignment Walkthrough (Optional, Collaborative)
+
+The full review answers "what's in the backlog and how is each item rated." Operators still have to mentally extract "what should I actually do next, and in what order, with what parallelism." `priority-alignment.md` is the one-page execution companion that makes that extraction explicit.
+
+This step is **optional** and **collaborative** — it requires operator context (recent ships, capacity, calendar, ongoing initiatives) that the skill alone does not have. Do not produce or refresh `priority-alignment.md` without operator participation.
+
+**Decision: should we run the walkthrough?**
+
+After the summary, ask the operator:
+
+> Want to walk through the review together and produce a one-page execution view at `backlog/reviews/priority-alignment.md`? It captures phased order, parallelism, and a recommended kickoff stack — a faster reference than the full review.
+
+If `.oat/repo/reference/backlog/reviews/priority-alignment.md` already exists, frame it as an **update** to the existing document rather than a fresh create. Read the existing file first so the walkthrough builds on it.
+
+If the operator declines, stop after the summary. Do not silently write or modify `priority-alignment.md`.
+
+**If the operator accepts, run the walkthrough:**
+
+1. **Propose a phase breakdown** based on the review's quadrants and dependency graph:
+   - "Finishing / in flight" — items already started or in code review
+   - One or more execution phases that group items by initiative, parallel lane, or sequencing constraint
+   - Surface the natural parallelism boundaries from Step 5 as parallel tracks within a phase
+2. **Solicit operator context** that the review alone cannot capture:
+   - What just shipped or changed since the last alignment? (Goes in the **Status** line and **Changelog**.)
+   - What's the operator's capacity / appetite for parallel work this cycle?
+   - Are there calendar constraints (freezes, releases, time off) that affect ordering?
+   - Does the operator want an optional axis like "planning investment" or "design effort" as a column? (Some repos find this useful; many don't. Default: omit unless operator opts in.)
+3. **Iterate on phase names, ordering, and the kickoff stack** until the operator is satisfied. Phase names should reflect the repo's actual initiatives, not generic placeholders.
+4. **Write or update** `.oat/repo/reference/backlog/reviews/priority-alignment.md` using the template at `.agents/skills/oat-pjm-review-backlog/references/priority-alignment-template.md`. Add a new Changelog entry summarizing what shifted in this pass.
+5. **Confirm the result** with the operator: file path, top-of-doc Status line, and the kickoff stack.
+
+When referencing backlog items inside the priority-alignment doc, the **Reference Format Convention** still applies — link to the item file and pair the ID with a human-readable title.
+
 ## Success Criteria
 
 - Every active backlog item file has a value-effort rating with rationale
@@ -190,4 +232,6 @@ When listing specific items in this summary, follow the **Reference Format Conve
 - Parallel lanes and execution waves are actionable
 - Roadmap alignment gaps are surfaced when roadmap input is present
 - Output document follows the review template structure
+- Living review is written to `.oat/repo/reference/backlog/reviews/backlog-and-roadmap-review.md` (unless `--output` is explicitly overridden); dated snapshots, when emitted, live in the same `backlog/reviews/` directory and never under `.oat/repo/reviews/`
+- The operator is offered (but never forced into) a collaborative walkthrough that produces or updates `backlog/reviews/priority-alignment.md`; if the operator accepts, the file is written using the priority-alignment template and includes a Changelog entry for this pass; if the operator declines, no file is created or modified
 - Every user-facing reference to a backlog item pairs the ID with a human-readable title (per the Reference Format Convention)

package/assets/skills/oat-pjm-review-backlog/references/backlog-review-template.md

@@ -1,10 +1,12 @@
 # Backlog & Roadmap Review
 
 **Date:** {YYYY-MM-DD}
-**Scope:** {Description of what was reviewed, e.g., "All items in backlog.md (Inbox + Planned)"}
-**Roadmap:** {Path to roadmap if included, or "N/A"}
+**Scope:** {Description of what was reviewed, e.g., "All active items under `.oat/repo/reference/backlog/items/`"}
+**Roadmap:** {Path to roadmap if included, e.g. `.oat/repo/reference/roadmap.md`, or "N/A"}
 **Purpose:** Prioritize by value/effort, surface dependencies, and recommend an execution sequence
 
+> If a one-page execution companion exists in this directory, see [`priority-alignment.md`](./priority-alignment.md) — produced via the optional walkthrough at the end of `oat-pjm-review-backlog`. It is the short, ordered "what to do next" view of this full review.
+
 ---
 
 ## 1. Executive Summary

package/assets/skills/oat-pjm-review-backlog/references/priority-alignment-template.md

@@ -0,0 +1,86 @@
+# Backlog Priority Alignment
+
+**Date:** {YYYY-MM-DD}
+**Status:** {Active|Stale} — {one-line snapshot of what just shipped or shifted since the previous alignment, e.g. "Post-PR #XX ship of feature Y; new high-priority item Z promoted"}.
+
+One-page execution guide: recommended order, scope, parallelism, and (optionally) planning investment. For the full value/effort catalog, dependency graph, and quadrant tables, see [backlog-and-roadmap-review.md](./backlog-and-roadmap-review.md).
+
+> This document is produced or refreshed via the optional walkthrough at the end of `oat-pjm-review-backlog`. It is **not** auto-generated — phase shape, parallelism, and the kickoff stack reflect operator judgment captured during the walkthrough.
+
+## Related sources
+
+| Document                                                         | Role                                                                  |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------- |
+| [roadmap.md](../../roadmap.md)                                   | Authoritative Now / Next / Later execution order                      |
+| [current-state.md](../../current-state.md)                       | Shipped capabilities and selected active backlog (if maintained)      |
+| [backlog/index.md](../index.md)                                  | Curated overview + generated item table                               |
+| [backlog/items/](../items/)                                      | Executable backlog records (one file per item)                        |
+| [backlog-and-roadmap-review.md](./backlog-and-roadmap-review.md) | Full `oat-pjm-review-backlog` artifact (catalog, dependencies, waves) |
+| Dated snapshots                                                  | `backlog-and-roadmap-review-YYYY-MM-DD.md` in this directory          |
+
+<!--
+Optional axis: some teams find a "planning investment" or "design effort" column
+useful — it separates discovery/design time from total build time. If you use it,
+define the term inline here so readers don't have to guess. Example:
+
+> **Planning investment** = discovery/design likely needed *before* implementation
+> pays off — not total build time.
+
+If the team doesn't find it useful, omit the column entirely.
+-->
+
+---
+
+## Finishing / in flight
+
+Items already started, in code review, or otherwise mid-flight. Close these out before — or alongside — the next phase.
+
+| Item                                             | Scope      | Notes                                        |
+| ------------------------------------------------ | ---------- | -------------------------------------------- |
+| [Item title](../items/{filename}.md) (`bl-XXXX`) | {S/M/L/XL} | {Status, blocker if any, next concrete step} |
+
+---
+
+<!-- Repeat one section per execution phase. Use repo-specific phase names —
+     organize by initiative, parallel lane, or sequencing constraint, not by
+     generic "Phase 1 / Phase 2". The point of named phases is that operators
+     can talk about them ("the synthesis phase", "the docs IA push"). -->
+
+## Phase {N} — {Repo-specific name}
+
+{One short paragraph: what this phase represents, how many tracks can run in parallel inside it, any kickoff constraints (e.g. "weekly pair is one combined kickoff").}
+
+| Item                                             | Scope      | {Optional column} | Parallel with        | Notes                                   |
+| ------------------------------------------------ | ---------- | ----------------- | -------------------- | --------------------------------------- |
+| [Item title](../items/{filename}.md) (`bl-XXXX`) | {S/M/L/XL} | {Low/Med/High}    | `bl-YYYY`, `bl-ZZZZ` | {One-line context — gotchas, decisions} |
+
+---
+
+## Parallelism cheat sheet
+
+Quick lookup for "can I start X while Y is in flight?"
+
+| Can run together      | Keep sequential            |
+| --------------------- | -------------------------- |
+| `bl-XXXX` ∥ `bl-YYYY` | `bl-AAAA` before `bl-BBBB` |
+| {…}                   | {…}                        |
+
+---
+
+## Suggested next kickoff stack
+
+Three concrete actions for the next development cycle. Not a ranked list of everything — just what to do _first_.
+
+1. **{Close|Kick off|Defer}** [`bl-XXXX`](../items/{filename}.md) — {one-line reason: why now, what it unblocks}
+2. **{Close|Kick off|Defer}** [`bl-YYYY`](../items/{filename}.md) — {one-line reason}
+3. **{Close|Kick off|Defer}** [`bl-ZZZZ`](../items/{filename}.md) — {one-line reason}
+
+---
+
+## Changelog
+
+Append a new row each time this file is refreshed via the `oat-pjm-review-backlog` walkthrough. Keep entries short — what shifted and why.
+
+| Date         | Update                                                                             |
+| ------------ | ---------------------------------------------------------------------------------- |
+| {YYYY-MM-DD} | {What changed this pass: promotions/demotions, new high-pri items, phase reshapes} |

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-complete
-version: 1.4.7
+version: 1.4.8
 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
@@ -519,7 +519,7 @@ Expected changes may include:
 - `{PROJECT_PATH}/implementation.md` (if touched earlier in the lifecycle closeout)
 - `{PROJECT_PATH}/plan.md` (if review receive just ran)
 - `{PROJECT_PATH}/pr/project-pr-*.md` (PR description artifact)
-- `.oat/state.md` (dashboard regenerated in Step 9)
+- `.oat/state.md` is regenerated locally in Step 9 but should not be staged; it is generated dashboard state and normally gitignored.
 - `.oat/config.local.json` (if `activeProject` cleared)
 - Shared-project deletions under `{PROJECTS_ROOT}/{PROJECT_NAME}` (if archived)
 

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-implement
-version: 2.0.18
+version: 2.0.19
 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,10 +23,10 @@ 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 (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.
+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`) as a separate bookkeeping commit. Refresh the repo dashboard with `oat state refresh` before staging when available, but do not stage `.oat/state.md`; it is generated dashboard state and is normally gitignored. 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.
 
 **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.
+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`). If one of those boundaries is next and artifact bookkeeping is still uncommitted, stop and create the bookkeeping commit first.
 
 **CRITICAL — Intentional artifact divergence must be recorded.**
 If implementation intentionally diverges from `spec.md`, `design.md`, or `plan.md`, record the delta in `implementation.md` before the next phase/review boundary. Include what diverged, why it diverged, whether the implementation or original artifact is now source of truth, and any follow-up artifact updates or explicit deferral. Do not leave accepted design drift only in chat, a review artifact, or code comments; final summary generation depends on `implementation.md` preserving the delta.
@@ -909,7 +909,7 @@ For each phase that completed:
 
 ```bash
 oat state refresh
-git add {PROJECT_PATH}/implementation.md {PROJECT_PATH}/state.md {PROJECT_PATH}/plan.md .oat/state.md
+git add {PROJECT_PATH}/implementation.md {PROJECT_PATH}/state.md {PROJECT_PATH}/plan.md
 git commit -m "chore(oat): bookkeeping after {pNN} {pass|fail}"
 ```
 
@@ -990,15 +990,15 @@ When pausing:
 
 **DO NOT SKIP.** This commit prevents state drift across sessions.
 
-After phase summary and task pointer advancement, refresh the repo dashboard and commit all modified OAT tracking files:
+After phase summary and task pointer advancement, refresh the repo dashboard when available and commit all modified project tracking files:
 
 ```bash
 oat state refresh
-git add "$PROJECT_PATH/implementation.md" "$PROJECT_PATH/state.md" "$PROJECT_PATH/plan.md" .oat/state.md
+git add "$PROJECT_PATH/implementation.md" "$PROJECT_PATH/state.md" "$PROJECT_PATH/plan.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 four files listed above (three project artifacts plus the regenerated repo dashboard).
+Do not use `git add -A` or glob patterns. Only commit the three project artifacts listed above; `.oat/state.md` is a generated, gitignored dashboard.
 
 **Note on HiLL types:**
 
@@ -1124,15 +1124,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, refresh the repo dashboard and commit all modified OAT tracking files:
+After updating state.md to reflect implementation completion, refresh the repo dashboard when available and commit all modified project tracking files:
 
 ```bash
 oat state refresh
-git add "$PROJECT_PATH/implementation.md" "$PROJECT_PATH/state.md" "$PROJECT_PATH/plan.md" .oat/state.md
+git add "$PROJECT_PATH/implementation.md" "$PROJECT_PATH/state.md" "$PROJECT_PATH/plan.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 four files listed above (three project artifacts plus the regenerated repo dashboard).
+Do not use `git add -A` or glob patterns. Only commit the three project artifacts listed above; `.oat/state.md` is a generated, gitignored dashboard.
 
 ### Step 13: Final Verification
 

package/assets/skills/oat-project-import-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-import-plan
-version: 1.3.1
+version: 1.3.2
 description: Use when you have an external markdown plan to execute with OAT. Preserves the source plan and normalizes it into canonical plan.md format.
 argument-hint: '<path-to-plan.md> [--provider codex|cursor|claude] [--project <name>]'
 disable-model-invocation: true
@@ -250,4 +250,4 @@ Report:
 - ✅ `oat_plan_hill_phases` left unset in frontmatter (deferred to `oat-project-implement` Step 2.5).
 - ✅ `## Planning Checklist` items left unchecked (HiLL configuration deferred to implementation).
 - ✅ `activeProject` in `.oat/config.local.json` points to the imported project.
-- ✅ `.oat/state.md` has been refreshed after pointer update.
+- ✅ `.oat/state.md` has been refreshed locally after pointer update; it is not staged or committed.

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-new
-version: 1.3.0
+version: 1.3.1
 description: Use when starting a spec-driven OAT project from scratch. Scaffolds a new project under PROJECTS_ROOT and sets it active.
 argument-hint: '<project-name> [--force]'
 disable-model-invocation: true
@@ -77,7 +77,7 @@ Confirm to the user:
 
 - Project path created: `{PROJECTS_ROOT}/{project-name}`
 - Active project set in local config: `.oat/config.local.json` (`activeProject`)
-- Repo State Dashboard refreshed: `.oat/state.md` (if enabled)
+- Repo State Dashboard refreshed locally: `.oat/state.md` (if enabled; generated and normally gitignored)
 
 Then explicitly instruct the user to run discovery next:
 
@@ -88,4 +88,4 @@ Then explicitly instruct the user to run discovery next:
 - ✅ `{PROJECTS_ROOT}/{project-name}/` exists
 - ✅ Standard artifacts exist in the project dir (copied from `.oat/templates/*.md`)
 - ✅ `activeProject` in `.oat/config.local.json` points at the project path
-- ✅ `.oat/state.md` is refreshed (unless disabled)
+- ✅ `.oat/state.md` is refreshed locally unless disabled; it is not staged or committed.

package/assets/skills/oat-project-quick-start/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-quick-start
-version: 2.1.2
+version: 2.1.3
 description: Use when a task is small enough for quick mode or rapid iteration is preferred. Scaffolds a lightweight OAT project from discovery directly to a runnable plan, with optional brainstorming and lightweight design.
 argument-hint: '<project-name> ["project description"]'
 disable-model-invocation: true
@@ -70,7 +70,7 @@ When executing this skill, provide lightweight progress feedback so the user can
 
 - After any write to `discovery.md`, `design.md`, `plan.md`, `implementation.md`, or project `state.md`, ensure the artifact is saved immediately and remains tracked in git.
 - If the skill is about to pause for user input or stop after mutating artifacts, commit the changed artifacts before waiting. Do not leave discovery/design updates only in the working tree.
-- Quick-start handoff is not complete until the changed project artifacts and regenerated `.oat/state.md` dashboard have been committed.
+- Quick-start handoff is not complete until the changed project artifacts have been committed. Refresh `.oat/state.md` when available, but do not stage it; the repo dashboard is generated and normally gitignored.
 - This applies to downstream lifecycle boundaries too: implementation, review, revise, and PR skills must inherit a committed artifact baseline, not an untracked project tree.
 
 ## Process
@@ -226,7 +226,7 @@ oat project complete-discovery "$PROJECT_PATH" --ready-for oat-project-design
 - Commit the promoted discovery/state artifacts before stopping:
 
 ```bash
-git add "$PROJECT_PATH/discovery.md" "$PROJECT_PATH/state.md" ".oat/state.md"
+git add "$PROJECT_PATH/discovery.md" "$PROJECT_PATH/state.md"
 git diff --cached --quiet || git commit -m "chore(oat): promote quick-start discovery for {project-name}"
 ```
 
@@ -552,8 +552,7 @@ for path in \
   "$PROJECT_PATH/design.md" \
   "$PROJECT_PATH/plan.md" \
   "$PROJECT_PATH/implementation.md" \
-  "$PROJECT_PATH/state.md" \
-  ".oat/state.md"; do
+  "$PROJECT_PATH/state.md"; do
   [ -e "$path" ] && git add "$path"
 done
 git diff --cached --quiet || git commit -m "chore(oat): update quick-start artifacts for {project-name}"
@@ -569,7 +568,7 @@ Report:
 - execution shape summary (sequential or declared parallel groups)
 - next options:
   - `oat-project-implement`
-- dashboard location: `.oat/state.md` (confirm it was regenerated)
+- dashboard location: `.oat/state.md` (confirm it was regenerated locally)
 
 ## Success Criteria
 
@@ -578,4 +577,4 @@ Report:
 - ✅ `discovery.md` contains synthesized or backfilled quick discovery decisions from the session context.
 - ✅ `plan.md` is complete and executable (`oat_ready_for: oat-project-implement`).
 - ✅ `implementation.md` is initialized for resumable execution.
-- ✅ Changed quick-start artifacts and refreshed `.oat/state.md` are committed before handoff or pause.
+- ✅ Changed quick-start artifacts are committed before handoff or pause; `.oat/state.md` is refreshed locally when available.

package/assets/skills/oat-project-review-provide/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-review-provide
-version: 1.3.4
+version: 1.3.5
 description: Use when completed work in an active OAT project needs a quality gate before merge. Performs a lifecycle-scoped review after a task, phase, or full implementation, unlike oat-review-provide.
 disable-model-invocation: true
 user-invocable: true
@@ -234,7 +234,7 @@ Before gathering review context, inspect the core project artifacts:
 - `"$PROJECT_PATH/plan.md"`
 - `"$PROJECT_PATH/implementation.md"`
 - `"$PROJECT_PATH/state.md"`
-- `.oat/state.md` (when it exists and was refreshed as part of the project workflow)
+- `.oat/state.md` is generated dashboard state; ignore it for committed artifact baseline checks.
 
 If any of those files are untracked or modified only because the previous workflow step did not finish its bookkeeping commit:
 

package/assets/skills/oat-project-review-receive/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-review-receive
-version: 1.4.2
+version: 1.4.3
 description: Use when review findings from oat-project-review-provide need closure. Converts review artifacts into actionable plan tasks.
 disable-model-invocation: true
 user-invocable: true
@@ -450,7 +450,7 @@ git diff --cached --quiet || git commit -m "chore(oat): record review findings a
 
 Do not use `git add -A` or glob patterns that reach outside `"$PROJECT_PATH/reviews/"`. Do not include unrelated implementation or code files in this commit. Do not defer this commit without explicit user approval — if deferred, clearly state in the summary that bookkeeping is uncommitted so the original agent knows to commit on return.
 
-If the project itself is still untracked because earlier lifecycle steps never committed the initial artifact set, widen this bookkeeping commit to include the untracked core project artifacts (`discovery.md`, `spec.md`, `design.md`, `plan.md`, `implementation.md`, `state.md`, plus `.oat/state.md` when relevant). Do not leave the project tree partially tracked after receive-review finishes.
+If the project itself is still untracked because earlier lifecycle steps never committed the initial artifact set, widen this bookkeeping commit to include the untracked core project artifacts (`discovery.md`, `spec.md`, `design.md`, `plan.md`, `implementation.md`, `state.md`). Do not stage `.oat/state.md`; it is generated dashboard state and normally gitignored. Do not leave the project tree partially tracked after receive-review finishes.
 
 **Note on archived review paths:** When `reviews/archived/` matches a `localPaths` pattern (the default setup), the archived file is gitignored and `git add "$PROJECT_PATH/reviews/"` will only stage the deletion of the original (now-moved) top-level review file. When `reviews/archived/` is tracked, both the deletion and the new archived location are staged. Both cases are safe — the command handles them uniformly.
 

package/dist/commands/init/gitignore.d.ts

@@ -1,6 +1,15 @@
 export interface ApplyOatCoreResult {
     action: 'created' | 'updated' | 'no-change';
     entries: string[];
+    stateDashboardIndexAction: 'untracked' | 'not-tracked' | 'not-git-repo';
 }
 export declare function applyOatCoreGitignore(repoRoot: string): Promise<ApplyOatCoreResult>;
+/**
+ * Removes the generated repo dashboard from the git index once the OAT core
+ * ignore rule is present, while leaving the working-tree file intact.
+ *
+ * @param repoRoot Repository root where the OAT core gitignore section applies.
+ * @returns The index migration outcome for `.oat/state.md`.
+ */
+export declare function untrackOatStateDashboard(repoRoot: string): Promise<ApplyOatCoreResult['stateDashboardIndexAction']>;
 //# sourceMappingURL=gitignore.d.ts.map

package/dist/commands/init/gitignore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gitignore.d.ts","sourceRoot":"","sources":["../../../src/commands/init/gitignore.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IAC5C,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAMD,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,kBAAkB,CAAC,CAgC7B"}
+{"version":3,"file":"gitignore.d.ts","sourceRoot":"","sources":["../../../src/commands/init/gitignore.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IAC5C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,yBAAyB,EAAE,WAAW,GAAG,aAAa,GAAG,cAAc,CAAC;CACzE;AAMD,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,kBAAkB,CAAC,CAgD7B;AAED;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,kBAAkB,CAAC,2BAA2B,CAAC,CAAC,CAyB1D"}

package/dist/commands/init/gitignore.js

@@ -1,8 +1,12 @@
+import { execFile } from 'node:child_process';
 import { readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { promisify } from 'node:util';
 import { fileExists } from '../../fs/io.js';
 const SECTION_START = '# OAT core';
 const SECTION_END = '# END OAT core';
+const OAT_STATE_DASHBOARD_PATH = '.oat/state.md';
+const execFileAsync = promisify(execFile);
 const CORE_ENTRIES = [
     '.oat/config.local.json',
     '.oat/state.md',
@@ -20,7 +24,11 @@ export async function applyOatCoreGitignore(repoRoot) {
     const section = buildSection();
     if (!exists) {
         await writeFile(gitignorePath, `${section}\n`, 'utf8');
-        return { action: 'created', entries: CORE_ENTRIES };
+        return {
+            action: 'created',
+            entries: CORE_ENTRIES,
+            stateDashboardIndexAction: await untrackOatStateDashboard(repoRoot),
+        };
     }
     const content = await readFile(gitignorePath, 'utf8');
     const startIdx = content.indexOf(SECTION_START);
@@ -28,14 +36,51 @@ export async function applyOatCoreGitignore(repoRoot) {
     if (startIdx !== -1 && endIdx !== -1) {
         const existingSection = content.slice(startIdx, endIdx + SECTION_END.length);
         if (existingSection === section) {
-            return { action: 'no-change', entries: CORE_ENTRIES };
+            return {
+                action: 'no-change',
+                entries: CORE_ENTRIES,
+                stateDashboardIndexAction: await untrackOatStateDashboard(repoRoot),
+            };
         }
         const before = content.slice(0, startIdx);
         const after = content.slice(endIdx + SECTION_END.length);
         await writeFile(gitignorePath, `${before}${section}${after}`, 'utf8');
-        return { action: 'updated', entries: CORE_ENTRIES };
+        return {
+            action: 'updated',
+            entries: CORE_ENTRIES,
+            stateDashboardIndexAction: await untrackOatStateDashboard(repoRoot),
+        };
     }
     const separator = content.endsWith('\n') ? '\n' : '\n\n';
     await writeFile(gitignorePath, `${content}${separator}${section}\n`, 'utf8');
-    return { action: 'updated', entries: CORE_ENTRIES };
+    return {
+        action: 'updated',
+        entries: CORE_ENTRIES,
+        stateDashboardIndexAction: await untrackOatStateDashboard(repoRoot),
+    };
+}
+/**
+ * Removes the generated repo dashboard from the git index once the OAT core
+ * ignore rule is present, while leaving the working-tree file intact.
+ *
+ * @param repoRoot Repository root where the OAT core gitignore section applies.
+ * @returns The index migration outcome for `.oat/state.md`.
+ */
+export async function untrackOatStateDashboard(repoRoot) {
+    try {
+        await execFileAsync('git', ['rev-parse', '--is-inside-work-tree'], {
+            cwd: repoRoot,
+        });
+    }
+    catch {
+        return 'not-git-repo';
+    }
+    try {
+        await execFileAsync('git', ['ls-files', '--error-unmatch', OAT_STATE_DASHBOARD_PATH], { cwd: repoRoot });
+    }
+    catch {
+        return 'not-tracked';
+    }
+    await execFileAsync('git', ['rm', '--cached', '--force', '--quiet', '--', OAT_STATE_DASHBOARD_PATH], { cwd: repoRoot });
+    return 'untracked';
 }

package/dist/commands/tools/update/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/tools/update/index.ts"],"names":[],"mappings":"AAaA,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAY,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAKvE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,uBAAuB,EAE7B,MAAM,gBAAgB,CAAC;AAexB,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAAA;CAAE,GAClD,MAAM,EAAE,CAUV;AAgCD,wBAAgB,wBAAwB,CACtC,YAAY,GAAE,uBAA6C,EAC3D,gBAAgB,GAAE,oBAA8C,GAC/D,OAAO,CAuJT;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAI7E;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,YAAY,GACnB,OAAO,CAOT;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,OAAO,GACd,MAAM,CAMR"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/tools/update/index.ts"],"names":[],"mappings":"AAaA,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAY,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAKvE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,uBAAuB,EAE7B,MAAM,gBAAgB,CAAC;AAexB,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAAA;CAAE,GAClD,MAAM,EAAE,CAUV;AAgCD,wBAAgB,wBAAwB,CACtC,YAAY,GAAE,uBAA6C,EAC3D,gBAAgB,GAAE,oBAA8C,GAC/D,OAAO,CA4JT;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAI7E;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,YAAY,GACnB,OAAO,CAOT;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,OAAO,GACd,MAAM,CAMR"}

package/dist/commands/tools/update/index.js

@@ -92,6 +92,9 @@ export function createToolsUpdateCommand(dependencies = defaultDependencies, syn
                 const verb = gitignoreResult.action === 'created' ? 'Created' : 'Updated';
                 logger.info(`${verb} .gitignore OAT core section (${gitignoreResult.entries.length} entries).`);
             }
+            if (gitignoreResult.stateDashboardIndexAction === 'untracked') {
+                logger.info('Untracked generated dashboard from git index: .oat/state.md.');
+            }
         }
         // Refresh ~/.oat/docs/ when the core pack is explicitly updated or
         // reconciled through --all (D3 requirement).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "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.1.9"
+    "@open-agent-toolkit/control-plane": "0.1.11"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",