@open-agent-toolkit/cli 0.1.5 → 0.1.7

package/assets/agents/oat-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-reviewer
-version: 1.0.1
+version: 1.0.2
 description: Unified reviewer for OAT projects - mode-aware verification of requirements/design alignment and code quality. Writes review artifact to disk.
 tools: Read, Bash, Grep, Glob, Write
 color: yellow
@@ -32,6 +32,8 @@ Reviews catch issues before they ship:
 
 Your review artifact feeds into `oat-project-review-receive`, which converts findings into plan tasks for systematic gap closure.
 
+Some findings are artifact drift rather than implementation defects. If shipped implementation is defensible but `spec.md`, `design.md`, or `plan.md` is stale, frame the issue as artifact alignment and say which artifact should change. Do not require a code fix solely because the design artifact lagged behind implementation.
+
 ## Inputs
 
 You will be given a "Review Scope" block including:
@@ -161,6 +163,11 @@ For each design decision relevant to scope:
    - Do endpoints match the design?
    - Are error responses as specified?
 
+4. **Artifact drift classification**
+   - If implementation diverges from design/spec/plan, decide whether the implementation is wrong or the artifact is stale.
+   - When the implementation is defensible, write the finding as stale-artifact alignment guidance instead of a code defect.
+   - Include enough rationale for `oat-project-review-receive` to convert the finding into an artifact-alignment task or explicit deferral.
+
 ### Step 6: Verify Code Quality
 
 This step applies to **code reviews** only.
@@ -204,6 +211,7 @@ Group findings by severity:
 - Missing error handling
 - Significant maintainability issues
 - Missing tests for important paths
+- Stale spec/design/plan artifact that conflicts with a defensible implementation and should be aligned before closeout
 
 **Minor** (fix if time permits)
 
@@ -211,6 +219,7 @@ Group findings by severity:
 - Style issues
 - Minor refactoring opportunities
 - Documentation gaps
+- Low-impact artifact wording drift where implementation is defensible and the stale wording is unlikely to mislead near-term work
 
 ### Step 8: Write Review Artifact
 

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

@@ -29,11 +29,28 @@ Mode-sensitive notes:
 - `reviews/*.md`: phase/final review files
 - `pr/*.md`: generated PR descriptions
 - `references/imported-plan.md`: preserved source plan for import mode
+- `references/split-plan.json`: persisted split plan for a coordination parent, used as the durable resume source when `oat-project-split` is interrupted
 
 ## Contract
 
 Artifacts are the project system of record; automation and routing should derive from these files, not memory.
 
+## Coordination parents
+
+Project splitting introduces a coordination-only parent artifact. It records shared context and child relationships, but it is not an executable lifecycle project.
+
+A coordination parent uses:
+
+- `oat_kind: coordination`
+- `oat_phase: decomposition`
+- `oat_phase_status: complete`
+
+Coordination parents do not contain executable phase files. `spec.md`, `design.md`, `plan.md`, and `implementation.md` are removed from the parent and represented in state prose as not applicable.
+
+The parent still keeps `state.md`, `discovery.md`, and `references/split-plan.json`. Child projects are flat siblings and link back to the parent through state metadata. Each child starts from a distilled discovery seed and must revalidate inherited context before moving beyond discovery/design.
+
+See [Project Splitting](splitting.md) for the full parent/child model.
+
 ### plan.md frontmatter
 
 `plan.md` carries frontmatter that the implementation skill consumes. Notable fields:

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

@@ -17,12 +17,14 @@ This sub-section is the deep technical surface for how tracked OAT projects exec
 
 - Start with [Lifecycle](lifecycle.md) for the end-to-end flow.
 - Read [Artifacts](artifacts.md) once you need the file contract behind project execution.
+- Use [Project Splitting](splitting.md) when one discovery or brainstorm should become coordinated child projects.
 - Use [HiLL Checkpoints](hill-checkpoints.md) when you want to understand pause/approval behavior.
 
 ## Common Tasks
 
 - Understand lifecycle order and alternate lanes in [Lifecycle](lifecycle.md).
 - Learn the artifact system of record in [Artifacts](artifacts.md).
+- 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).
 
@@ -32,6 +34,7 @@ This sub-section is the deep technical surface for how tracked OAT projects exec
 - [Design Modes](design-modes.md) - How full design balances collaborative, selective collaborative, and draft-and-review interaction.
 - [HiLL Checkpoints](hill-checkpoints.md) - Human-in-the-Loop Lifecycle configuration and approval behavior.
 - [Artifacts](artifacts.md) - What lives in `state.md`, `discovery.md`, `plan.md`, `implementation.md`, and related files.
+- [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.
 - [PR Flow](pr-flow.md) - Progress and final PR generation expectations.

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

@@ -0,0 +1,79 @@
+---
+title: Project Splitting
+description: 'How OAT splits broad discoveries or brainstorms into a coordination parent and focused child projects.'
+---
+
+# Project Splitting
+
+Use project splitting when one discovery or brainstorming thread turns into several independently shippable projects that should keep shared context but execute separately.
+
+`oat-project-split` is the handoff skill for that moment. It creates a durable coordination parent, scaffolds flat sibling child projects, seeds each child with focused discovery context, and activates the first child by dependency or value order.
+
+## When To Split
+
+Split when the work has multiple deliverables that can ship independently, no single shared design surface owns all of them, separate PRs are expected, or the scope clearly spans distinct subsystems.
+
+Do not split just because a project has many tasks. A large but coherent implementation can stay one project when it has one design surface and one release boundary.
+
+## Entry Paths
+
+Splitting can start from either discovery or brainstorming:
+
+- **Declared:** the user states multi-project intent up front. `oat-brainstorm` skips detection and hands off to `oat-project-split`.
+- **Detected mid-stream:** `oat-project-discover` evaluates codified split signals during solution-space exploration and prompts when the threshold is crossed.
+- **Detected at convergence:** `oat-project-discover` performs an end-of-discovery scope check, and `oat-brainstorm` can expose a split destination when the accumulated scope is large.
+
+Declared non-interactive runs can proceed. Detected non-interactive runs record the split recommendation and fail fast rather than silently creating projects.
+
+## Coordination Parent
+
+The parent becomes a coordination artifact, not an implementation project.
+
+It stays in place under `.oat/projects/<scope>/<parent>/` with:
+
+- `oat_kind: coordination`
+- `oat_phase: decomposition`
+- `oat_phase_status: complete`
+- broad context, split rationale, shared constraints, child registry, and integration sketch
+- `references/split-plan.json` as the durable resume source
+
+Coordination parents do not keep executable phase artifacts. They should not contain `spec.md`, `design.md`, `plan.md`, or `implementation.md`.
+
+## Child Projects
+
+Children are flat sibling projects under the same projects root. They are not nested under the parent.
+
+Each child gets:
+
+- parent backlink and sibling links in `state.md`
+- `depends-on` metadata when ordering or dependency constraints exist
+- a seeded `discovery.md` with Origin, Inherited Context, Child Scope, Known Dependencies, Assumptions To Revalidate, Likely Workflow Mode, and Sibling Projects
+- `oat_inherited_context_revalidated: false` until the child revalidates inherited assumptions
+
+Only one child is activated immediately. The rest remain parked until opened or resumed.
+
+## Resume And Recovery
+
+The split plan is persisted before child writes. If a split is interrupted, resume reads `references/split-plan.json` from the coordination parent instead of reconstructing child inputs from state.
+
+Resume requires explicit confirmation and seeds only missing child projects.
+
+## Listing And Dashboard Behavior
+
+Completed coordination parents are hidden from default `oat project list` output so normal project lists stay focused on executable work.
+
+Use:
+
+```bash
+oat project list --include-coordination
+```
+
+to show them. Completed coordination parents render as `decomposition (complete)` with recommendation `none`.
+
+`oat state refresh` also groups completed coordination parents under the repo dashboard's decompositions section.
+
+## Related Pages
+
+- [Lifecycle](lifecycle.md)
+- [Artifacts](artifacts.md)
+- [Implementation Execution](implementation-execution.md)

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

@@ -18,6 +18,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 - Resume an existing project: `oat-project-open` and `oat-project-progress`
 - Execute a ready plan: `oat-project-implement`
 - Import an existing plan: `oat-project-import-plan`
+- Split a broad discovery or brainstorm into child projects: `oat-project-split`
 - Retroactively capture existing work: `oat-project-capture`
 - Run or receive reviews: `oat-project-review-provide`, `oat-project-review-receive`, or the non-project review variants
 - Capture a scoped, shippable backlog item: `oat-pjm-add-backlog-item` directly when the work is already scoped, or `oat-brainstorm` when the thought hasn't converged yet — the brainstorm dispatcher's "scoped backlog item" destination pre-fills the title / description / acceptance criteria / scope estimate / priority from the conversation and then runs `oat-pjm-add-backlog-item` with confirmed inputs
@@ -53,6 +54,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
     - `oat-project-design`
     - `oat-project-plan`
     - `oat-project-plan-writing`
+    - `oat-project-split`
     - `oat-project-implement`
     - `oat-project-progress`
     - `oat-project-next`

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.5",
-  "docs-config": "0.1.5",
-  "docs-theme": "0.1.5",
-  "docs-transforms": "0.1.5"
+  "cli": "0.1.7",
+  "docs-config": "0.1.7",
+  "docs-theme": "0.1.7",
+  "docs-transforms": "0.1.7"
 }

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

@@ -1,6 +1,6 @@
 ---
 name: oat-brainstorm
-version: 1.0.2
+version: 1.0.4
 description: Use when the user explicitly invokes the `brainstorm` verb, including `/oat-brainstorm`, "let's brainstorm", "brainstorm this", "can we brainstorm X", or "help me brainstorm X". For ambiguous exploratory phrasing ("I've been thinking", "what if", "help me think through"), do NOT auto-enter; respond conversationally and offer mode only after ≥2 sustained exploratory turns. Do NOT use for review, debug, PR, status, implementation, or active-workflow questions.
 disable-model-invocation: false
 user-invocable: true
@@ -29,6 +29,21 @@ Enter OAT brainstorm mode immediately when the user invokes `/oat-brainstorm` or
 
 Hard Activation runs the full Process flow below: print the mode banner (Step 2), assess visual need (Step 3), detect packs and active project (Step 4), and proceed.
 
+### Declared Multi-Project Mode
+
+If the opening request explicitly says the scope is multiple projects, several sub-projects, an umbrella project, or otherwise declares decomposition intent, still enter brainstorm mode through Hard Activation, but switch the conversation shape immediately to umbrella framing. This is a first-class split path, not an ordinary destination guess.
+
+Do not treat ambiguous exploratory phrasing as declared mode. Put another way: do not treat ambiguous exploratory phrasing as declared mode. Messages like "help me think through a broad thing", "what if this has multiple parts", or "this might get big" remain on the Soft Exploratory Path unless the user explicitly declares that the desired outcome is multiple projects.
+
+In declared mode, ask this boundary question before ordinary free brainstorming:
+
+> "Do you already know the child projects, or should we decompose the scope together?"
+
+- If the user already knows the children, capture light parent-level context: shared context, child list, dependencies, sequencing, and integration risks.
+- If the children are unknown, brainstorm the boundaries first until a child list is clear.
+
+Once the child list is clear, invoke `oat-project-split` with a `SplitPayload` using `origin: "declared"`, `interactive: true`, `declaredChildren`, and the parent/umbrella slug when known. The brainstorm hook only frames and hands off; `oat-project-split` owns normalization, parent writing, child scaffolding, and activation.
+
 ### Soft Exploratory Path
 
 Do **not** print the banner, assert mode, run pack detection, or offer the visual companion on the first response. Answer normally with brainstorm-quality structure (options, tradeoffs, open questions, no premature implementation, no destination guess). Examples:
@@ -278,7 +293,21 @@ If "keep going", return to step 5. If "wrap up", surface the **pack-filtered ter
    - Gated by `PJM_INSTALLED == "true"`: `Scoped backlog item`.
    - Gated by `WORKFLOWS_INSTALLED == "true"` AND `ACTIVE_PROJECT_VALID != "true"`: `Promote to new OAT project`.
    - Gated by `WORKFLOWS_INSTALLED == "true"` AND `ACTIVE_PROJECT_VALID == "true"`: `Active project: fold-back` and `Active project: brainstorming reference file`. When this branch fires, present the **3-way active-project router first** (see step 9 active-project branches) — its outcome controls whether the rest of the picker is even surfaced.
-3. Present the filtered list to the user. Wait for selection.
+3. Evaluate whether the accumulated brainstorm scope is large enough to offer a split destination. Track the same four split signals used by discovery and evaluate them through the installed CLI:
+
+   ```bash
+   oat project split evaluate-signals --fired "<comma-list>"
+   ```
+
+   Use the local-development fallback only when the installed `oat` command is unavailable:
+
+   ```bash
+   pnpm run cli -- project split evaluate-signals --fired "<comma-list>"
+   ```
+
+   If the JSON result has `triggered: true`, add `Promote to N projects` to the picker. Below 2 split signals, do not show this option.
+
+4. Present the filtered list to the user. Wait for selection.
 
 Once a destination is identified (either path), proceed to step 7.
 
@@ -581,6 +610,16 @@ git commit -m "chore(oat): capture brainstorming reference for <project-name>"
 
 Use only `git add -- <path>` so unrelated working-tree changes are not swept into the commit. After the commit succeeds, capture the short hash via `git rev-parse --short HEAD` and report it alongside the absolute path written (for example: "Wrote `<absolute-path>` and committed as `<hash>`."). End mode assertion.
 
+#### 9k — Promote to N projects
+
+This branch is available only when the step 6 picker added `Promote to N projects` after `oat project split evaluate-signals` returned `triggered: true`.
+
+Confirm the parent/umbrella slug and the inferred child list at step 8 using the minimal confirmation pattern. If the child list is still unclear, ask one boundary question and return briefly to step 5 to decompose the scope.
+
+When confirmed, invoke `oat-project-split` with a `SplitPayload` using `origin: "brainstorm-picker"`, `interactive: true`, `inferredChildren`, the parent/umbrella slug when known, and the brainstorm session note as inherited parent context. The brainstorm hook does not create project directories itself; `oat-project-split` owns normalization, `SplitPlanDocument` validation, coordination-parent writing, child seeding, activation, and dashboard refresh.
+
+End mode assertion when the split handoff completes or reports its own blocker.
+
 ## Success Criteria
 
 - ✅ Activation Contract is honored: Hard Activation fires only on explicit brainstorm-verb phrasing or `/oat-brainstorm`; Soft Exploratory Path messages ("help me think through", "I've been thinking about", "what if we") respond conversationally without the banner and offer mode only after ≥2 sustained exploratory turns; No Activation Path messages (advisory / review / debug / PR / status / implementation / active-workflow) get a direct response with no banner and no offer.
@@ -590,9 +629,10 @@ Use only `git add -- <path>` so unrelated working-tree changes are not swept int
 - ✅ Pack and active-project detection (`oat config get tools.<pack>` and `oat config get activeProject`) runs once per session at step 4, before the conversation starts.
 - ✅ Conversation cadence holds the Superpowers contract: one question at a time, multiple-choice preferred, 2-3 distinct approaches with a recommendation, per-question visual-companion routing.
 - ✅ Destination is identified via either trigger-phrase opportunistic surfacing (loose substring + paraphrase tolerance, not regex; ambiguity → ask) or convergence cue (pack-filtered terminal-state picker).
+- ✅ The terminal-state picker conditionally includes `Promote to N projects` only when `oat project split evaluate-signals` reports `triggered: true`; small-scope convergence keeps the option hidden.
 - ✅ Synthesis payload is built per the design Data Models `SynthesizedPayload` schema: `title`, `summary`, `motivation`, `vision`, `approachesConsidered[]`, `chosenDirection`, `openQuestions[]`, `nextSteps[]`, `transcriptSessionNote`.
 - ✅ Confirmation pattern matches `references/destinations.md`: `full` for scoped backlog item (field-by-field with example wording), `minimal` for slug/path/artifact destinations, `none` for inline-only and summarize-idea-directly.
-- ✅ Each handoff branch (9a-9j) reads the correct downstream `SKILL.md` path and enters at the documented step. Project promotion writes `discovery.md` only — never `design.md` — and does not auto-chain into the next phase.
+- ✅ Each handoff branch (9a-9k) reads the correct downstream `SKILL.md` path and enters at the documented step. Project promotion writes `discovery.md` only — never `design.md` — and does not auto-chain into the next phase.
 - ✅ Doc-to-path validation handles all four cases: path-is-directory, parent-missing (with explicit out-of-repo confirmation), file-already-exists (overwrite or rename), unwritable (surface OS error).
 - ✅ Fold-back commit safety contract honored: preflight `git status --porcelain -- "$ARTIFACT_PATH"` runs before any artifact mutation; clean → append + `git add -- "$ARTIFACT_PATH"` (explicit `--`, never `-A`, never globs) + scoped commit; dirty → three-option picker (commit-prior-first / mix / abort-to-reference-file); handoff prompt prints only after `git commit` succeeds.
 - ✅ Handoff target for fold-back resolves correctly per `oat_workflow_mode` + `oat_pr_status`: `oat-project-plan` (spec-driven, no/closed PR) / `oat-project-quick-start` (quick, no/closed PR) / `oat-project-revise` (either mode, open PR).

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

@@ -1,10 +1,10 @@
 ---
 name: oat-project-discover
-version: 2.0.0
+version: 2.0.2
 description: Use when starting a project or when requirements are still unclear. Runs structured discovery to gather requirements, constraints, and context.
 disable-model-invocation: true
 user-invocable: true
-allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion
+allowed-tools: Read, Write, Bash(git:*), Bash(oat:*), Bash(pnpm:*), Glob, Grep, AskUserQuestion
 ---
 
 # Discovery Phase
@@ -262,6 +262,59 @@ This focuses the conversation on what matters most to the user.
 
 Before converging on an approach, invest in genuine divergent exploration. Simple projects are where unexamined assumptions cause the most wasted work.
 
+**Step 9 Split Detection: Evaluate Multi-Project Signals**
+
+During solution-space exploration, silently evaluate whether the current thread is really multiple loosely related projects. Re-evaluate after each user turn while approaches are being shaped; do not interrupt normal discovery unless the threshold is met.
+
+Track the four codified signals:
+
+1. `independently-shippable` — at least two deliverables can ship independently.
+2. `no-shared-design-surface` — the work lacks a single shared design surface.
+3. `expect-separate-prs` — a reviewer would reasonably expect separate PRs.
+4. `distinct-subsystems` — the work spans distinct subsystems, packages, layers, or ownership areas.
+
+Evaluate the current comma-separated signal list through the installed CLI:
+
+```bash
+oat project split evaluate-signals --fired "<comma-list>"
+```
+
+Use the local-development fallback only when the installed `oat` command is unavailable:
+
+```bash
+pnpm run cli -- project split evaluate-signals --fired "<comma-list>"
+```
+
+Parse the JSON output:
+
+```json
+{ "fired": [], "triggered": false, "confidence": "below" }
+```
+
+Branch on `confidence`:
+
+- `high` — both load-bearing signals 1 and 2 fired. Use high-confidence wording and ask directly: "This looks like multiple independent projects. Split now, do one round of broad cross-cutting discovery first, or keep this as one project?"
+- `soft` — at least two signals fired, but not both load-bearing signals. Use soft wording: "This may be multiple projects. Split, do one round of broad cross-cutting discovery first, or keep it as one project?"
+- `below` — Below 2 signals, do not surface a split offer.
+
+If the user confirms split, invoke the `oat-project-split` skill with a `SplitPayload` using `origin: "detected-mid-stream"`, `interactive: true`, the active discovery path as `priorDiscovery.path`, and any inferred children already named in the conversation. The discover hook only detects and hands off; it does not scaffold children or write the coordination parent itself.
+
+**Non-interactive branch:** if `OAT_NON_INTERACTIVE=1` and detection triggers (`confidence` is `high` or `soft`), do not show an offer prompt and do not silently choose. Append this section to `"$PROJECT_PATH/discovery.md"` and exit non-zero:
+
+```markdown
+## Detected Split Recommendation
+
+Discovery detected multi-project scope via `oat project split evaluate-signals`.
+
+- Fired signals: <comma-list>
+- Confidence: <high|soft>
+- Recommendation: rerun discovery interactively and choose whether to invoke `oat-project-split`.
+```
+
+```bash
+exit 1
+```
+
 **Step 9a: Propose Approaches**
 
 Propose 2-3 **genuinely distinct** approaches (not minor variations). For each:
@@ -313,6 +366,19 @@ Update discovery.md sections:
 
 ### Step 11: Human-in-the-Loop Lifecycle (HiLL) Gate (If Configured)
 
+Before the HiLL gate or discovery completion, run the same split signal evaluation one final time.
+
+**Non-interactive convergence branch:** if `OAT_NON_INTERACTIVE=1`, do not show the scope-check prompt and do not silently choose. Parse the final `oat project split evaluate-signals --fired "<comma-list>"` result:
+
+- `high` or `soft` — append the same section to `"$PROJECT_PATH/discovery.md"` as the Step 9 non-interactive branch, using the final fired signal list and confidence, then exit non-zero.
+- `below` — proceed as one cohesive project without prompting.
+
+For interactive runs, show an always-visible scope-check confirmation. The prompt is required even when no mid-stream offer fired:
+
+> "This reads as one cohesive project — proceed, or split into multiple?"
+
+Pre-fill the recommendation from `oat project split evaluate-signals --fired "<comma-list>"`: recommend splitting for `high`, suggest considering a split for `soft`, and recommend proceeding as one cohesive project for `below`. If the user chooses split at this convergence point, invoke `oat-project-split` with `origin: "detected-convergence"` and `interactive: true`.
+
 Read `"$PROJECT_PATH/state.md"` frontmatter:
 
 - `oat_hill_checkpoints`
@@ -342,13 +408,11 @@ If discovery is not configured as a HiLL checkpoint, or user explicitly approves
 
 ### Step 12: Mark Discovery Complete
 
-Update frontmatter:
+Use the CLI completion boundary so split-created child discoveries cannot
+complete until inherited context has been revalidated:
 
-```yaml
----
-oat_status: complete
-oat_ready_for: oat-project-design
----
+```bash
+oat project complete-discovery "$PROJECT_PATH" --ready-for oat-project-design
 ```
 
 ### Step 13: Update Project State

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-implement
-version: 2.0.16
+version: 2.0.17
 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
@@ -28,6 +28,9 @@ After every code commit and after every phase/review-fix completion, you MUST co
 **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.
 
+**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.
+
 ## Progress Indicators (User-Facing)
 
 When executing this skill, provide lightweight progress feedback so the user can tell what's happening after they confirm.
@@ -557,6 +560,7 @@ For each phase `pNN` in the plan (or each phase in the current parallel group),
      spec: {PROJECT_PATH}/spec.md
      implementation: {PROJECT_PATH}/implementation.md
      discovery: {PROJECT_PATH}/discovery.md
+   delta_recording: record any intentional divergence from spec/design/plan in implementation.md with rationale, source of truth, and follow-up artifact disposition
    commit_convention: {from plan.md header}
    workflow_mode: {from state.md or plan.md frontmatter}
    model_axis: {selected:<value> | inherited | not-applicable | host-auto; omit if unknown}
@@ -793,6 +797,14 @@ Append a new entry to the `## Orchestration Runs` section between the `<!-- orch
 #### Outstanding Items
 
 - {None | list of excluded phases with review paths and worktree paths}
+
+#### Artifact / Design Deltas
+
+Run-scoped snapshot only. The durable record is `## Deviations from Plan / Design`; consolidate any non-`None` entries there at the next phase boundary.
+
+| Task / Review                 | Source Artifact                     | Planned / Documented            | Actual / Accepted                      | Reason                       | Source of Truth           | Follow-up                                   |
+| ----------------------------- | ----------------------------------- | ------------------------------- | -------------------------------------- | ---------------------------- | ------------------------- | ------------------------------------------- |
+| {task_id/review_id or `None`} | {spec.md/design.md/plan.md section} | {planned behavior/taxonomy/API} | {actual shipped behavior/taxonomy/API} | {why divergence is accepted} | {implementation/artifact} | {artifact update task or explicit deferral} |
 ```
 
 Append only — never overwrite prior run entries.
@@ -887,6 +899,14 @@ When pausing:
   - Verification run
   - Notable decisions/deviations
 
+**Design/artifact deltas (required when present):**
+
+- If a completed task intentionally diverged from `spec.md`, `design.md`, or `plan.md`, update the `## Deviations from Plan / Design` table in `implementation.md`.
+- For existing project artifacts, treat any `## Deviations...` heading as the deviations section; migrate to the preferred `## Deviations from Plan / Design` heading and table shape when already touching the section.
+- Each delta must include: the affected source artifact/section, the planned/documented expectation, the actual shipped implementation, the reason the divergence is accepted, the current source of truth, and any follow-up artifact update task or explicit deferral.
+- If the implementation is now source of truth and the design/spec/plan is stale, write that directly. Do not treat the stale artifact as a no-op just because code is correct.
+- If no deltas exist for the phase, do not invent one; leave the table unchanged.
+
 **Bookkeeping commit (required):**
 
 **DO NOT SKIP.** This commit prevents state drift across sessions.

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-quick-start
-version: 2.1.0
+version: 2.1.1
 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
@@ -211,10 +211,12 @@ Use `AskUserQuestion` to present this choice.
 
 **If user chooses "Promote to spec-driven":**
 
-- Update `discovery.md` frontmatter:
-  - `oat_status: complete`
-  - `oat_ready_for: oat-project-design`
-  - `oat_last_updated: {today}`
+- Complete discovery through the CLI validation boundary:
+
+```bash
+oat project complete-discovery "$PROJECT_PATH" --ready-for oat-project-design
+```
+
 - Update `state.md`:
   - `oat_workflow_mode: spec-driven`
   - `oat_phase: discovery`
@@ -287,6 +289,13 @@ fi
 # Route the user accordingly. Do NOT loop back into the gate.
 ```
 
+Before continuing to Step 3, complete discovery through the CLI validation
+boundary:
+
+```bash
+oat project complete-discovery "$PROJECT_PATH" --ready-for oat-project-quick-start
+```
+
 ### Step 2.75a: Lightweight Design Mode Choice
 
 Resolve the interaction mode before drafting. Same mechanics as the full `oat-project-design` skill (Component 1): argument precedes env var, config fallback, **explicit** non-interactive fallback to draft.

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-review-provide
-version: 1.3.3
+version: 1.3.4
 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
@@ -15,6 +15,8 @@ Request and execute a code or artifact review for the current project scope.
 
 Produce an independent review artifact that verifies requirements/design alignment (mode-aware) and code quality.
 
+Reviewers should distinguish implementation defects from artifact drift. If code is defensible but `spec.md`, `design.md`, or `plan.md` is stale, frame the finding as artifact alignment rather than a required code change.
+
 ## Prerequisites
 
 **Required:** Active project with at least one completed task.
@@ -481,6 +483,12 @@ Build the "Review Scope" metadata for the reviewer:
 - Deferred Medium count: {DEFERRED_MEDIUM_COUNT}
 - Deferred Minor count: {DEFERRED_MINOR_COUNT}
   {DEFERRED_LEDGER}
+
+**Design Drift Review Guidance:**
+
+- If implementation differs from `spec.md`, `design.md`, or `plan.md`, decide whether the code should change or whether the artifact is stale.
+- Use artifact-alignment framing when shipped implementation is defensible and the lifecycle artifact should be updated.
+- Do not force a code-defect framing for accepted design drift; `oat-project-review-receive` can convert artifact drift into alignment tasks or explicit deferrals.
 ```
 
 ### Step 6: Execute Review (3-Tier Capability Model)

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-review-receive
-version: 1.4.1
+version: 1.4.2
 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
@@ -52,6 +52,7 @@ When executing this skill, provide lightweight progress feedback so the user can
 - No re-reviewing
 - For `artifact` reviews: no converting findings into plan tasks
 - For `artifact` reviews: no deferring findings by default
+- No treating accepted design/code drift as a no-op; accepted drift must be converted to an artifact-alignment task or explicitly deferred, with an `implementation.md` note
 
 **ALLOWED Activities:**
 
@@ -167,6 +168,10 @@ For each finding, build a structured register entry:
 - Agent analysis (agree/disagree + why)
 - Recommendation (convert to task now vs defer with rationale)
 - Task Scope (`Large` | `Moderate` | `Minor` | `Negligible`)
+- Drift disposition, when applicable:
+  - `code_fix_required` — implementation should change
+  - `artifact_alignment_required` — shipped implementation is defensible; design/docs/plan should be aligned
+  - `explicit_deferral` — drift is accepted for now with a concrete rationale and follow-up trigger
 - For `artifact` reviews, use dispositions:
   - `resolve_in_artifact`
   - `rejected_with_rationale` (invalid/not applicable)
@@ -386,6 +391,10 @@ Add a note to implementation.md:
 
 **New tasks added:** {task_ids}
 
+**Design drift / artifact alignment notes:**
+
+- {finding_id}: {review found stale design/spec/plan relative to shipped implementation; why the implementation is accepted; source of truth; artifact-alignment task ID or explicit deferral}
+
 **Next:** Execute fix tasks via the `oat-project-implement` skill.
 
 After the fix tasks are complete:
@@ -399,6 +408,10 @@ After the fix tasks are complete:
 - If `{PROJECT_PATH}/implementation.md` exists, ensure it will resume correctly after this skill:
   - If `oat_current_task_id` is `null` (or points at already-completed work), set it to the **first newly-added review-fix task ID** (or the next incomplete task in plan order).
   - Update the Progress Overview table totals (tasks + completed) if they are present and depend on task counts.
+  - If any finding is resolved by accepting the shipped implementation and aligning stale artifacts instead of changing code, add an explicit review note under the current "Review Received" section and update `## Deviations from Plan / Design` when that table exists.
+    - For existing project artifacts, treat any `## Deviations...` heading as the deviations section; migrate to the preferred `## Deviations from Plan / Design` heading and table shape when already touching the section.
+    - The note must say the review found design/spec/plan drift, why the shipped implementation is accepted, which source is now authoritative, and which artifact-alignment task will update the stale artifact.
+    - If the artifact update is intentionally deferred, record the deferral rationale and follow-up trigger in `implementation.md`.
   - Update `{PROJECT_PATH}/state.md` frontmatter so routing/UI is accurate:
     - `oat_phase: implement`
     - `oat_phase_status: in_progress`
@@ -503,6 +516,13 @@ If any Medium is proposed for deferral:
 - If user declines deferral, convert that Medium to a fix task now.
 - If user approves deferral, record rationale in `implementation.md` under "Deferred Findings (Medium)".
 
+Design drift handling applies before Medium/Minor convenience deferrals:
+
+- If a review finding reveals that the design artifact is stale relative to a defensible implementation, do not treat this as a no-op.
+- Either convert the finding to an artifact-alignment task or record an explicit deferral.
+- In both cases, add an `implementation.md` review note so final summary generation can preserve the design delta.
+- The note must include what drift was found, why the implementation is accepted, whether implementation or artifact is source of truth, and the artifact task or deferral that will align the lifecycle record.
+
 Minor findings handling is scope-aware:
 
 - If `scope != final`: