@open-agent-toolkit/cli 0.1.6 → 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/public-package-versions.json

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

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-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`:

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-summary
-version: 1.1.1
+version: 1.1.2
 description: Use when the user requests or confirms summarizing an active OAT project — e.g. "summarize the project", "generate the summary", "run oat-project-summary", or confirms a previously offered summary run. Do NOT auto-invoke when implementation completes. Generates summary.md from project artifacts as institutional memory.
 disable-model-invocation: false
 user-invocable: true
@@ -149,6 +149,8 @@ For each section, synthesize content from the relevant artifacts. Apply these ru
 
 **Grounding rule:** Prefer implementation.md outcomes over design.md plans. If the implementation diverged from the design, reflect what actually happened.
 
+**Design delta rule:** Populate `Design Deltas` from both direct implementation deviations and review-received design drift decisions recorded in `implementation.md`. A review finding may decide that shipped implementation is defensible and the artifact is stale; when `implementation.md` records that acceptance, carry it forward as a design delta with the rationale and follow-up artifact disposition.
+
 **Section omission rule:** If a section would have no meaningful content, omit it entirely (remove the heading). Do not leave empty sections or "N/A" placeholders.
 
 **Conciseness constraint (NFR3):** Target under 200 lines total. If a draft exceeds this, trim narrative sections (What Was Implemented, Notable Challenges) to essential points. Revision History entries: 2-3 sentences per round max.
@@ -157,18 +159,18 @@ For each section, synthesize content from the relevant artifacts. Apply these ru
 
 **Section sources:**
 
-| Section              | Primary Sources                                             |
-| -------------------- | ----------------------------------------------------------- |
-| Overview             | discovery.md initial request, spec.md problem statement     |
-| What Was Implemented | implementation.md task outcomes, plan.md phase structure    |
-| Key Decisions        | design.md decisions, implementation.md notes/decisions      |
-| Design Deltas        | implementation.md deviations table                          |
-| Notable Challenges   | implementation.md issues/blockers in task notes             |
-| Tradeoffs Made       | implementation.md decisions, design.md tradeoff sections    |
-| Integration Notes    | implementation.md notes about cross-cutting concerns        |
-| Revision History     | plan.md p-revN phases, implementation.md revision notes     |
-| Follow-up Items      | implementation.md deferred findings, plan.md deferred items |
-| Associated Issues    | state.md `associated_issues` field                          |
+| Section              | Primary Sources                                                        |
+| -------------------- | ---------------------------------------------------------------------- |
+| Overview             | discovery.md initial request, spec.md problem statement                |
+| What Was Implemented | implementation.md task outcomes, plan.md phase structure               |
+| Key Decisions        | design.md decisions, implementation.md notes/decisions                 |
+| Design Deltas        | implementation.md deviations table; review-received design drift notes |
+| Notable Challenges   | implementation.md issues/blockers in task notes                        |
+| Tradeoffs Made       | implementation.md decisions, design.md tradeoff sections               |
+| Integration Notes    | implementation.md notes about cross-cutting concerns                   |
+| Revision History     | plan.md p-revN phases, implementation.md revision notes                |
+| Follow-up Items      | implementation.md deferred findings, plan.md deferred items            |
+| Associated Issues    | state.md `associated_issues` field                                     |
 
 **For incremental updates (re-run):**
 

package/assets/templates/implementation.md

@@ -165,13 +165,13 @@ Chronological log of implementation progress.
 
 ---
 
-## Deviations from Plan
+## Deviations from Plan / Design
 
-Document any deviations from the original plan.
+Document any intentional deviations from the original plan, spec, or design. Include accepted review findings where the shipped implementation is source of truth and a lifecycle artifact needs alignment.
 
-| Task | Planned | Actual | Reason |
-| ---- | ------- | ------ | ------ |
-| -    | -       | -      | -      |
+| Task / Review | Source Artifact | Planned / Documented | Actual / Accepted | Reason | Source of Truth | Follow-up |
+| ------------- | --------------- | -------------------- | ----------------- | ------ | --------------- | --------- |
+| -             | -               | -                    | -                 | -      | -               | -         |
 
 ## Test Results
 

package/assets/templates/summary.md

@@ -37,7 +37,8 @@ where decisions were made or changed during implementation.}
 <!-- Omit this section if there were no deviations from the original design. -->
 
 {Where the final result diverged from the original design and why.
-Pull from implementation.md deviations table.}
+Pull from implementation.md deviations table and review-received design drift notes.
+Include accepted cases where shipped implementation became source of truth and a stale lifecycle artifact needs alignment or was explicitly deferred.}
 
 ## Notable Challenges
 

package/package.json

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