@open-agent-toolkit/cli 0.3.21 → 0.3.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. package/assets/bundle-metadata.json +1 -1
  2. package/assets/docs/reference/cli-reference.md +8 -3
  3. package/assets/docs/reference/configuration.md +3 -0
  4. package/assets/docs/reference/oat-directory-structure.md +1 -1
  5. package/assets/docs/reference/project-artifacts.md +141 -2
  6. package/assets/docs/reference/project-state-machine.md +2 -2
  7. package/assets/docs/workflows/advanced/autonomy.md +29 -12
  8. package/assets/docs/workflows/advanced/cursor-cloud.md +20 -6
  9. package/assets/docs/workflows/advanced/workflow-gates.md +9 -0
  10. package/assets/docs/workflows/projects/closeout/closeout-skills.md +24 -5
  11. package/assets/docs/workflows/projects/closeout/retro.md +6 -2
  12. package/assets/docs/workflows/projects/execution/implementation-execution.md +18 -4
  13. package/assets/docs/workflows/projects/execution/index.md +1 -1
  14. package/assets/docs/workflows/projects/execution/picking-up-projects.md +3 -2
  15. package/assets/docs/workflows/projects/execution/project-log.md +100 -11
  16. package/assets/docs/workflows/projects/lifecycle.md +3 -3
  17. package/assets/docs/workflows/projects/reviews/index.md +18 -0
  18. package/assets/public-package-versions.json +4 -4
  19. package/assets/skills/oat-cursor-cloud-projects/SKILL.md +12 -8
  20. package/assets/skills/oat-cursor-cloud-projects/references/cursor-cloud-mechanics.md +63 -2
  21. package/assets/skills/oat-project-autonomous/SKILL.md +88 -26
  22. package/assets/skills/oat-project-autonomous/references/gate-inventory.md +1 -1
  23. package/assets/skills/oat-project-brief/SKILL.md +1 -1
  24. package/assets/skills/oat-project-brief/references/brief-contract.md +33 -27
  25. package/assets/skills/oat-project-brief/references/docs/autonomy-contract.md +1 -1
  26. package/assets/skills/oat-project-complete/SKILL.md +142 -25
  27. package/assets/skills/oat-project-complete-auto/SKILL.md +4 -4
  28. package/assets/skills/oat-project-dispatch-subagents/SKILL.md +10 -5
  29. package/assets/skills/oat-project-document/SKILL.md +1 -1
  30. package/assets/skills/oat-project-document/references/docs/autonomy-contract.md +1 -1
  31. package/assets/skills/oat-project-goal/SKILL.md +63 -15
  32. package/assets/skills/oat-project-goal/references/docs/autonomy-contract.md +1 -1
  33. package/assets/skills/oat-project-implement/SKILL.md +6 -6
  34. package/assets/skills/oat-project-implement/references/completion-and-closeout.md +28 -7
  35. package/assets/skills/oat-project-implement/references/dispatch-and-dry-run.md +10 -5
  36. package/assets/skills/oat-project-implement/references/docs/autonomy-contract.md +1 -1
  37. package/assets/skills/oat-project-implement/references/phase-execution.md +23 -9
  38. package/assets/skills/oat-project-implement/references/plan-and-resume.md +4 -4
  39. package/assets/skills/oat-project-lite/SKILL.md +1 -1
  40. package/assets/skills/oat-project-lite/references/docs/autonomy-contract.md +1 -1
  41. package/assets/skills/oat-project-pr-final/SKILL.md +6 -1
  42. package/assets/skills/oat-project-pr-final/references/docs/autonomy-contract.md +1 -1
  43. package/assets/skills/oat-project-pr-progress/SKILL.md +6 -1
  44. package/assets/skills/oat-project-quick-start/SKILL.md +1 -1
  45. package/assets/skills/oat-project-quick-start/references/docs/autonomy-contract.md +1 -1
  46. package/assets/skills/oat-project-reconcile/SKILL.md +13 -19
  47. package/assets/skills/oat-project-retro/SKILL.md +5 -2
  48. package/assets/skills/oat-project-retro/references/evidence-and-lanes.md +9 -3
  49. package/assets/skills/oat-project-review-provide/SKILL.md +28 -3
  50. package/assets/skills/oat-project-review-receive/SKILL.md +32 -18
  51. package/assets/skills/oat-project-review-receive-remote/SKILL.md +10 -6
  52. package/assets/skills/oat-project-revise/SKILL.md +9 -2
  53. package/assets/skills/oat-project-summary/SKILL.md +166 -37
  54. package/assets/skills/oat-worktree-bootstrap-auto/SKILL.md +3 -3
  55. package/assets/templates/implementation-brief.md +5 -36
  56. package/assets/templates/implementation.md +11 -81
  57. package/assets/templates/project-log.md +2 -31
  58. package/assets/templates/project-retro.md +4 -1
  59. package/assets/templates/summary.md +13 -5
  60. package/dist/commands/config/index.d.ts.map +1 -1
  61. package/dist/commands/config/index.js +44 -1
  62. package/dist/commands/project/archive/archive-utils.d.ts +205 -8
  63. package/dist/commands/project/archive/archive-utils.d.ts.map +1 -1
  64. package/dist/commands/project/archive/archive-utils.js +708 -44
  65. package/dist/commands/project/archive/index.d.ts.map +1 -1
  66. package/dist/commands/project/archive/index.js +1 -0
  67. package/dist/commands/project/archive/push-runner.d.ts +9 -1
  68. package/dist/commands/project/archive/push-runner.d.ts.map +1 -1
  69. package/dist/commands/project/archive/push-runner.js +56 -18
  70. package/dist/commands/project/archive/sync-runner.d.ts +28 -0
  71. package/dist/commands/project/archive/sync-runner.d.ts.map +1 -1
  72. package/dist/commands/project/archive/sync-runner.js +44 -22
  73. package/dist/commands/project/complete-state/index.d.ts.map +1 -1
  74. package/dist/commands/project/complete-state/index.js +45 -0
  75. package/dist/commands/project/dispatch/index.d.ts.map +1 -1
  76. package/dist/commands/project/dispatch/index.js +24 -2
  77. package/dist/commands/project/dispatch/record.d.ts +54 -1
  78. package/dist/commands/project/dispatch/record.d.ts.map +1 -1
  79. package/dist/commands/project/dispatch/record.js +229 -1
  80. package/dist/commands/project/index.d.ts.map +1 -1
  81. package/dist/commands/project/index.js +2 -0
  82. package/dist/commands/project/journal-check/evaluator.d.ts +17 -0
  83. package/dist/commands/project/journal-check/evaluator.d.ts.map +1 -0
  84. package/dist/commands/project/journal-check/evaluator.js +140 -0
  85. package/dist/commands/project/journal-check/index.d.ts +34 -0
  86. package/dist/commands/project/journal-check/index.d.ts.map +1 -0
  87. package/dist/commands/project/journal-check/index.js +163 -0
  88. package/dist/commands/project/journal-check/rules.d.ts +68 -0
  89. package/dist/commands/project/journal-check/rules.d.ts.map +1 -0
  90. package/dist/commands/project/journal-check/rules.js +994 -0
  91. package/dist/commands/project/journal-check/types.d.ts +63 -0
  92. package/dist/commands/project/journal-check/types.d.ts.map +1 -0
  93. package/dist/commands/project/journal-check/types.js +26 -0
  94. package/dist/commands/project/log/append.d.ts +6 -0
  95. package/dist/commands/project/log/append.d.ts.map +1 -1
  96. package/dist/commands/project/log/append.js +114 -6
  97. package/dist/commands/project/log/check.d.ts +23 -1
  98. package/dist/commands/project/log/check.d.ts.map +1 -1
  99. package/dist/commands/project/log/check.js +20 -3
  100. package/dist/commands/project/log/grammar.d.ts +37 -0
  101. package/dist/commands/project/log/grammar.d.ts.map +1 -1
  102. package/dist/commands/project/log/grammar.js +72 -0
  103. package/dist/commands/project/log/rollup.d.ts +87 -1
  104. package/dist/commands/project/log/rollup.d.ts.map +1 -1
  105. package/dist/commands/project/log/rollup.js +257 -5
  106. package/dist/config/oat-config.d.ts +14 -0
  107. package/dist/config/oat-config.d.ts.map +1 -1
  108. package/dist/config/oat-config.js +17 -0
  109. package/dist/config/resolve.d.ts.map +1 -1
  110. package/dist/config/resolve.js +5 -1
  111. package/dist/providers/identity/generic-dispatch-record.d.ts +33 -0
  112. package/dist/providers/identity/generic-dispatch-record.d.ts.map +1 -1
  113. package/dist/providers/identity/generic-dispatch-record.js +60 -1
  114. package/package.json +2 -2
@@ -206,13 +206,13 @@ unit in document order within the active scope.
206
206
 
207
207
  ## 9. Record ownership
208
208
 
209
- | Record | Owns |
210
- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
211
- | `plan.md` (the brief) | Intent: outcomes, approach, decisions, phases, review table. |
212
- | `state.md` | Routing, dispatch policy, gate overrides, and the `oat_brief_gate` record. |
213
- | `implementation.md` | The per-phase journal: status, anchors, verification results, review disposition, authority changes, deviations, next action, records. |
214
- | `project-log.md` | Observations and phase amendments, when the project log is enabled. |
215
- | `references/research/` | Research and imported material. |
209
+ | Record | Owns |
210
+ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
211
+ | `plan.md` (the brief) | Intent: outcomes, approach, decisions, phases, review table. |
212
+ | `state.md` | Routing, dispatch policy, gate overrides, and the `oat_brief_gate` record. |
213
+ | `implementation.md` | The per-phase journal: status, anchors, verification results, review disposition, authority changes, next action, records; fixed slots `## Orchestration Runs` (one run line per request id), `## Reviews and Gates` (multi-phase receipts, gate lines), `## Deferred Findings` (approved deferrals, excluded phases, unmerged worktrees), `## Deviations from Plan / Design` (deviations, override lines), `## References` last. |
214
+ | `project-log.md` | Observations and phase amendments, when the project log is enabled. |
215
+ | `references/research/` | Research and imported material. |
216
216
 
217
217
  `pr/` and archived reviews are gitignored; nothing authoritative lives only
218
218
  there.
@@ -392,20 +392,20 @@ milestone's ordered phase set.
392
392
 
393
393
  ### 12.3 Transitions and owners
394
394
 
395
- | From → To | Owner | Prerequisite |
396
- | -------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
397
- | new → aligning | `oat-project-goal` | scaffold rendered `oat_plan_source: goal` |
398
- | aligning → implementing | `oat-project-goal` | artifact review passed, `plan` carrier `allowed`, approval, and the next phase and every member of the next dispatched group concrete |
399
- | implementing → reviewing | implement milestone closeout | every unit in the milestone scope accepted; `exit` carrier `allowed` and fresh |
400
- | reviewing → delivering | `oat-project-review-receive` | clean receive of the exact integrated review (`passed`) with scope, revisions and exit carrier still valid |
401
- | reviewing → implementing | `oat-project-review-receive` | fixes queued from the integrated review |
402
- | delivering → implementing | `oat-project-review-receive` | fixes queued from a delivery-time review |
403
- | delivered \| delivering → implementing | `oat-project-revise` | inline feedback with an explicit active-milestone target; the appended `p-revN` joins the milestone row; delivery evidence invalidated (writes status and pointer) |
404
- | delivering → reviewing | `oat-project-pr-progress` | `oat project delivery refresh` reports the integrated review or `exit` carrier stale for the active milestone's delivery |
405
- | delivered → reviewing | `oat-project-pr-progress` | `oat-project-goal` hands back a stale `delivered` milestone (Step 5.5 item 3a) and refresh or check reports its registered delivery's integrated review or `exit` carrier not fresh; `oat_phase_status` is left for the next activation to reset |
406
- | delivering → delivered | `oat-project-pr-progress` | delivery registered, members open, review fresh; for an already-registered delivery, a deliverable check of that `dNN` (no new registration) |
407
- | delivered → aligning | `oat-project-goal` | learnings captured (section 12.10) and fresh observations establish the previous delivery at its agreed endpoint; the activation that follows also writes `oat_phase_status: in_progress` and projects `oat_pr_status`/`oat_pr_url` from the latest member's observed status |
408
- | delivered → terminal | `oat-project-goal` (user declaration) | exhaustive outcome audit recorded (section 12.9) |
395
+ | From → To | Owner | Prerequisite |
396
+ | -------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
397
+ | new → aligning | `oat-project-goal` | scaffold rendered `oat_plan_source: goal` |
398
+ | aligning → implementing | `oat-project-goal` | artifact review passed, `plan` carrier `allowed`, approval, and the next phase and every member of the next dispatched group concrete |
399
+ | implementing → reviewing | implement milestone closeout | every unit in the milestone scope accepted; `exit` carrier `allowed` and fresh |
400
+ | reviewing → delivering | `oat-project-review-receive` | clean receive of the exact integrated review (`passed`) with scope, revisions and exit carrier still valid |
401
+ | reviewing → implementing | `oat-project-review-receive` | fixes queued from the integrated review |
402
+ | delivering → implementing | `oat-project-review-receive` | fixes queued from a delivery-time review |
403
+ | delivered \| delivering → implementing | `oat-project-revise` | inline feedback with an explicit active-milestone target; the appended `p-revN` joins the milestone row; delivery evidence invalidated (writes status and pointer) |
404
+ | delivering → reviewing | `oat-project-pr-progress` | `oat project delivery refresh` reports the integrated review or `exit` carrier stale for the active milestone's delivery |
405
+ | delivered → reviewing | `oat-project-pr-progress` | `oat-project-goal` hands back a stale `delivered` milestone (Step 5.5 item 3a) and refresh or check reports its registered delivery's integrated review or `exit` carrier not fresh; `oat_phase_status` is left for the next activation to reset |
406
+ | delivering → delivered | `oat-project-pr-progress` | delivery registered, members open, review fresh; for an already-registered delivery, a deliverable check of that `dNN` (no new registration) |
407
+ | delivered → aligning | `oat-project-goal` | learnings captured (section 12.10: the categorized project-log write, or its warned attempt when the log is disabled and absent) and fresh observations establish the previous delivery at its agreed endpoint; the activation that follows also writes `oat_phase_status: in_progress` and projects `oat_pr_status`/`oat_pr_url` from the latest member's observed status |
408
+ | delivered → terminal | `oat-project-goal` (user declaration) | exhaustive outcome audit recorded (section 12.9) |
409
409
 
410
410
  Review-provide records its Reviews event as `received` and never writes
411
411
  `delivering`; `fixes_completed` is not a passed review. The router reads only
@@ -726,18 +726,24 @@ review, the next milestone's `plan` carrier, one approval), and activates only
726
726
  once the previous delivery is observed at its agreed endpoint.
727
727
 
728
728
  **Learnings captured** (the `delivered → aligning` prerequisite) is a concrete
729
- write, not a reflection: one judgment entry (`worked-well` or `friction`)
730
- through `oat project log append` when the project log is enabled; otherwise a
731
- dated entry in the project's `oat-execution-learnings.md`
732
- (created when absent, append-only).
729
+ write, not a reflection: at least one category-bearing judgment entry through
730
+ `oat project log append` with `--category`, a stable per-observation
731
+ `--source` reused as `--idempotency-key`, and `--origin oat-project-goal`
732
+ (the goal skill's learning write). The append consults `workflow.projectLog` only while `project-log.md` does
733
+ not exist. When the project log is disabled and absent the append skips
734
+ (`status: skipped`); the producer prints one warning line and continues, and
735
+ the attempt satisfies the prerequisite. An existing `project-log.md` keeps
736
+ accepting the write whatever the flag says
737
+ (`DR-260718-automatic-create-on-first`). No producer creates
738
+ `oat-execution-learnings.md`.
733
739
 
734
740
  **Structural log entries.** `oat-project-goal` appends exactly one structural
735
741
  entry with `oat project log append --structural --producer oat-project-goal
736
742
  --ref mNN` at each milestone activation and one at each re-alignment entry.
737
743
  The delivery registration owners append one per registration (section 12.7
738
744
  owners: `--producer oat-project-pr-progress --ref dNN` or
739
- `--producer oat-project-pr-final --ref dNN`). Skills never pre-check log
740
- configuration: the helper no-ops when logging is disabled.
745
+ `--producer oat-project-pr-final --ref dNN`). Skills do not read `workflow.projectLog` themselves: the append creates no
746
+ log while it is disabled, and an existing log keeps accepting entries.
741
747
 
742
748
  ### 12.11 Extraction
743
749
 
@@ -324,7 +324,7 @@ remains immutable baseline evidence for the original p01-t01 verification.
324
324
  | `oat-project-summary/SKILL.md` | `68c197c44c18 -> NG`; `a8983fec040c -> NG`; `a167d03559fa -> NG`; `cf317c17c586 -> SUMMARY-01`; `f3e49b727752 -> NG`; `f979b2342d28 -> NG`; `803bf40ec423 -> NG`; `c8fced47ef8e -> NG`; `d7ea1e2a4f5f -> NG`; `5f315ab87cb1 -> NG` |
325
325
  | `oat-project-pr-final/SKILL.md` | `601ac2b890f2 -> NG`; `c264a64398f0 -> NG`; `9efcbcee42ea -> NG`; `655d61df0a8f -> NG`; `cf317c17c586 -> PRFINAL-01`; `2de348a391c0 -> PRFINAL-03` |
326
326
  | `oat-project-pr-final/references/docs/autonomy-contract.md` | `* -> NG` |
327
- | `oat-project-complete/SKILL.md` | `6ed459f9e462 -> NG`; `a167d03559fa -> NG`; `79c2eeed668c -> COMPLETE-01`; `2c1514b9d9af -> COMPLETE-01`; `31c750b4fea7 -> COMPLETE-01`; `cfba413b1293 -> COMPLETE-01`; `7fcfce0423ac -> COMPLETE-01`; `7bcbf58b54e9 -> NG`; `4c7f88a7f942 -> COMPLETE-02`; `6a1a95acc8cc -> COMPLETE-02`; `3b559956b3eb -> COMPLETE-03`; `14d161cdf99b -> COMPLETE-03`; `fffe5eea5ebd -> NG`; `e7dc6fdc4eb3 -> COMPLETE-01`; `e5460e437299 -> NG`; `882b61c9096c -> NG`; `9ffa1c752505 -> NG`; `8c5e599f6bac -> NG` |
327
+ | `oat-project-complete/SKILL.md` | `6ed459f9e462 -> NG`; `a167d03559fa -> NG`; `79c2eeed668c -> COMPLETE-01`; `2c1514b9d9af -> COMPLETE-01`; `31c750b4fea7 -> COMPLETE-01`; `cfba413b1293 -> COMPLETE-01`; `7fcfce0423ac -> COMPLETE-01`; `4c7f88a7f942 -> COMPLETE-02`; `6a1a95acc8cc -> COMPLETE-02`; `3b559956b3eb -> COMPLETE-03`; `14d161cdf99b -> COMPLETE-03`; `fffe5eea5ebd -> NG`; `e7dc6fdc4eb3 -> COMPLETE-01`; `e5460e437299 -> NG`; `882b61c9096c -> NG`; `9ffa1c752505 -> NG`; `8c5e599f6bac -> NG` |
328
328
  | `oat-project-review-provide/SKILL.md` | `1f4b981cac8b -> NG`; `adaeca152bb2 -> NG`; `2f7c201c3c06 -> NG`; `88f79700afdc -> NG`; `655d61df0a8f -> NG`; `efafde9ef5a0 -> NG`; `d2a3861d6323 -> REVIEWPROVIDE-02`; `65f5b9cf49cd -> REVIEWPROVIDE-04`; `962cb38d246a -> REVIEWPROVIDE-04`; `1a568483ba0b -> REVIEWPROVIDE-04`; `610e27edfe85 -> REVIEWPROVIDE-04`; `bb0096e95c47 -> REVIEWPROVIDE-06`; `55f6357a987d -> REVIEWPROVIDE-06`; `e3c08ecdab17 -> REVIEWPROVIDE-06`; `1bee61f8531c -> REVIEWPROVIDE-07`; `3d35091607a1 -> REVIEWPROVIDE-08`; `fb40c4341c4c -> NG`; `b22d16885150 -> NG`; `d2b25906242e -> REVIEWPROVIDE-08`; `fd8ebf72b3c4 -> NG`; `79c8103e8656 -> NG`; `4fbd78337e33 -> NG`; `c3d50ea7cf69 -> NG`; `09b1b8dd445c -> NG`; `7acc8f3718d2 -> REVIEWPROVIDE-09`; `b2fa883fc4a2 -> NG`; `fe4421531b4c -> NG` |
329
329
  | `oat-project-review-receive/SKILL.md` | `9b8a3743d626 -> NG`; `49ed2780983b -> NG`; `4ee8730382d3 -> NG`; `655d61df0a8f -> NG`; `765f897d67ac -> NG`; `53b58d16dd32 -> NG`; `fb8755a3bdf4 -> NG`; `1d710fb4cc66 -> NG`; `1f7dd98dff2f -> NG`; `56f78c6740e6 -> NG`; `76f5fb5a88cd -> NG`; `085abfa3599f -> REVIEWRECEIVE-01`; `92578f7df686 -> NG`; `a7d114059bb6 -> NG`; `ac88cfaa83d9 -> NG`; `594bbf70346c -> REVIEWRECEIVE-08`; `f31f07284718 -> REVIEWRECEIVE-02`; `e4c0625439f8 -> REVIEWRECEIVE-04`; `505ad8389c0a -> REVIEWRECEIVE-05`; `20e05e1a4381 -> REVIEWRECEIVE-06`; `e30e06f39281 -> REVIEWRECEIVE-07`; `f8fd58180ecf -> NG`; `c3abcdc02d9f -> NG`; `f2ebdd6abb9b -> NG` |
330
330
  | `oat-project-review-provide/SKILL.md` | `2e794bf4fc4a -> REVIEWPROVIDE-08`; `5441ab977b46 -> REVIEWPROVIDE-08` |
@@ -5,7 +5,7 @@ disable-model-invocation: true
5
5
  user-invocable: true
6
6
  allowed-tools: Read, Write, Bash, AskUserQuestion
7
7
  metadata:
8
- version: 1.7.17
8
+ version: 1.7.18
9
9
  ---
10
10
 
11
11
  # Complete Project
@@ -404,6 +404,11 @@ Also preflight summary status using the same freshness rules as `oat-project-sum
404
404
  endpoint); `summary.md` is `stale` when its `oat_summary_phase_fingerprint`
405
405
  is absent or differs from the recomputed value and `current` when they
406
406
  match. `oat_summary_last_task` is not consulted for a brief or goal project.
407
+ - In every workflow mode, also recompute `summary_learnings_fingerprint` with
408
+ the `oat-project-summary` Step 3 function and compare it with
409
+ `oat_summary_learnings_fingerprint`. A mismatch, or a missing
410
+ `oat_summary_learnings_fingerprint` field, makes `summary.md` `stale` on its
411
+ own, whatever the task, revision or phase tracking says.
407
412
 
408
413
  Preflight `{PROJECT_PATH}/references/project-retro.md` alongside the summary.
409
414
  The safety-net offer is governed by how this completion run executes, not by how
@@ -464,15 +469,15 @@ If `oat_pr_url` is present, show it in the completion summary.
464
469
 
465
470
  ### Step 3: Check Completion Gates
466
471
 
467
- #### 3.0: Phase Status Permissiveness
472
+ #### 3.0: Phase Status at Completion
468
473
 
469
- Read `oat_phase_status` from `state.md` frontmatter and handle permissively:
474
+ Read `oat_phase_status` from `state.md` frontmatter and route on it:
470
475
 
471
476
  - **`pr_open`:** Proceed normally. This is the expected entry point after `oat-project-pr-final`.
472
477
  - **`complete`:** Proceed normally. Implementation is done.
473
- - **`in_progress`:** Note: "Project is still in progress. Completing anyway." — proceed without additional confirmation.
478
+ - **`in_progress`:** Stop and route back to `oat-project-implement`. At completion the journal and `state.md` must agree: the Step 3.55 journal check and `oat project complete-state` refuse `state-status-disagrees` for `oat_phase_status: in_progress`. Status disagreement is not an override-eligible gap, so no override line can complete it; finish implementation (its Step 16 writes the terminal headers) and run completion again.
474
479
 
475
- All three are valid starting states for completion. Do not block on any phase status value. The Step 1.5 closeout invariant gate still applies to every phase status.
480
+ `pr_open` and `complete` are the valid starting states for completion. The Step 1.5 closeout invariant gate still applies to both.
476
481
 
477
482
  #### 3.1: Final Review Status
478
483
 
@@ -510,7 +515,10 @@ IMPL_FILE="${PROJECT_PATH}/implementation.md"
510
515
 
511
516
  if [[ -f "$IMPL_FILE" ]]; then
512
517
  medium_items=$(awk '
513
- BEGIN { in_medium = 0 }
518
+ BEGIN { in_medium = 0; in_slot = 0 }
519
+ /^## Deferred Findings[[:space:]]*$/ { in_slot = 1; next }
520
+ /^## / { in_slot = 0 }
521
+ in_slot && /^[[:space:]]*-[[:space:]]+/ && /Medium/ { print; next }
514
522
  /^\*\*Deferred Findings \(Medium\):\*\*/ { in_medium = 1; next }
515
523
  /^\*\*Deferred Findings \(Medium\/Minor\):\*\*/ { in_medium = 1; next }
516
524
  in_medium && /^\*\*/ { in_medium = 0; next }
@@ -570,9 +578,9 @@ After collecting all warnings from 3.1, 3.2, and 3.3:
570
578
 
571
579
  Check if `{PROJECT_PATH}/summary.md` exists and whether it is current against the implementation state:
572
580
 
573
- - If `summary.md` is missing or stale and `SHOULD_GENERATE_SUMMARY="true"`, generate or refresh it before completing.
581
+ - If `summary.md` is missing or stale and `SHOULD_GENERATE_SUMMARY="true"`, generate or refresh it before completing, as a **staged** invocation: state `staged: true` so the summary skill writes only its `summary.md` sections and freshness frontmatter, records any selected promotions without appending them, and suspends before its Step 6 roll-up. Record `SUMMARY_STAGED="true"`; Step 3.7 sends `resume: roll-up` only after Step 3.55's final journal check succeeds.
574
582
  - When skill-to-skill invocation is available in the current host/runtime, load the current `oat-project-summary/SKILL.md` and follow it; never synthesize the summary from a remembered version of that skill.
575
- - If direct skill invocation is unavailable, generate or update `summary.md` inline by following the same synthesis rules as `oat-project-summary` (validate implementation state, read the same project artifacts, apply the same freshness checks, update the same frontmatter tracking fields, and write a complete `summary.md` before continuing).
583
+ - If direct skill invocation is unavailable, generate or update `summary.md` inline by following the same synthesis rules as `oat-project-summary` (validate implementation state, read the same project artifacts, apply the same freshness checks, update the same frontmatter tracking fields, and write a complete `summary.md` before continuing). The inline fallback honors the same suspension point: it writes no project-log append, roll-up, ledger write or promotion before `resume: roll-up`.
576
584
  - Do not assume `oat-project-summary` is a shell command on `PATH`. Only execute a shell command with that name if the environment explicitly provides a real executable.
577
585
  - If `summary.md` is missing or stale and `SHOULD_GENERATE_SUMMARY="false"`, emit: `Warning: Proceeding without summary generation.`
578
586
  - If summary generation succeeds, proceed with the refreshed `summary.md` available for PR and archive steps.
@@ -581,6 +589,52 @@ Check if `{PROJECT_PATH}/summary.md` exists and whether it is current against th
581
589
  - Used as source for the PR description (in Step 7)
582
590
  - Preserved in the archived project directory (in Step 8)
583
591
 
592
+ ### Step 3.55: Terminal Prose and Final Journal Validation
593
+
594
+ Run this step on every completion, after the summary refresh and before any
595
+ roll-up, promotion append, seal, archive or lifecycle write.
596
+
597
+ **Terminal prose refresh.** Rewrite only the journal's
598
+ `## Final Summary (for PR/docs)` and `summary.md` prose from observed facts:
599
+ present-tense status that the journal and `state.md` now contradict ("PR
600
+ pending", "phase in progress") is rewritten; real follow-ups and timestamped
601
+ historical observations stay. Never rewrite task blocks, receipts, completed
602
+ synthesis, or project-log entries: a wrong log judgment is corrected by
603
+ appending a source-linked correction before the seal. A mechanical pointer or
604
+ projection refresh (overview totals, resume pointers, a run line re-render)
605
+ creates no task; a substantive evidence correction stays traceable work.
606
+
607
+ **Final journal check.**
608
+
609
+ ```bash
610
+ JOURNAL_CHECK_EXIT=0
611
+ JOURNAL_CHECK_JSON=$(oat project journal check --project "$PROJECT_PATH" --at completion --json) || JOURNAL_CHECK_EXIT=$?
612
+ ```
613
+
614
+ Continue only when `status` is `ok`. On `refused` (or a command error), stop
615
+ completion: report each reason's `code`, `path:line` and `owner`, and route the
616
+ correction to that owner. The prose refresh above may remain; nothing else
617
+ happens: no `resume: roll-up`, no deferred promotion append, no roll-up, no
618
+ ledger graduation, no seal, no archive or export, and no lifecycle write.
619
+
620
+ **Overrides.** When every remaining reason is an overridable gap (a missing
621
+ task block, an incomplete task, missing commit evidence, or an unaccepted
622
+ phase) and the user authorizes an override with a decision identity, record it
623
+ as exactly one line under `## Deviations from Plan / Design`:
624
+
625
+ ```markdown
626
+ **Override:** <scope-disposition-approved|evidence-lost|operator-accepted-gap> · **Authorized by:** <decision id> · **Scope:** <pNN-tNN|pNN> · <reason>
627
+ ```
628
+
629
+ Write it idempotently: when a line with the same code, scope and decision id
630
+ already exists, write nothing. When the project log is enabled and not sealed,
631
+ also append one structural entry for it
632
+ (`oat project log append --structural --producer oat-project-complete --ref override --idempotency-key "oat-override:<code>:<scope>:<decision id>" --body "... oat-override:<code>:<scope>:<decision id>"`)
633
+ before any seal. Commit both, then run the journal check again. Under
634
+ `OAT_AUTONOMOUS=1` never author an override: refuse and report. No override
635
+ bypasses the closeout invariant, the goal audit, delivery coverage, the
636
+ project-log ambiguity refusal or the seal guards.
637
+
584
638
  ### Step 3.5.5: Retro Safety-Net
585
639
 
586
640
  When `SHOULD_GENERATE_RETRO="true"`, dispatch `oat-project-retro` in generate
@@ -898,6 +952,12 @@ Skip this roll-up entirely when the probe reported `sealed: true`; a sealed log
898
952
  has already been rolled up and sealed, and the seal must remain its final
899
953
  entry.
900
954
 
955
+ When `SUMMARY_STAGED="true"`, send the suspended summary run `resume: roll-up`
956
+ now, after Step 3.55's journal check returned `ok`: it performs its deferred
957
+ promotion appends first and then its Step 6 roll-up, and that roll-up result is
958
+ the one reused below. A staged run is resumed only here, never after a refused
959
+ journal check.
960
+
901
961
  For an unsealed log with entries, reuse the summary flow's structured roll-up
902
962
  result only
903
963
  when this completion run has that exact result in memory and it reports
@@ -1011,9 +1071,16 @@ oat project complete-state "${COMPLETE_STATE_ARGS[@]}"
1011
1071
 
1012
1072
  Re-run the closeout check immediately before `complete-state`, because the
1013
1073
  Step 3 gates ran children that can change `state.md`. `complete-state`
1014
- evaluates the same invariant and refuses an incomplete closeout without
1074
+ evaluates the same invariant and the final journal evaluator (the Step 3.55
1075
+ check, on the bytes it is about to complete) and refuses either without
1015
1076
  writing.
1016
1077
 
1078
+ After `complete-state` succeeds and before any archive, record when the PR
1079
+ fields were observed: set `oat_pr_status_observed_at: '<UTC ISO 8601 now>'` in
1080
+ `state.md` frontmatter beside `oat_pr_status` (only when `oat_pr_status` is not
1081
+ `null`). An archived `oat_pr_status`/`oat_pr_url` is an observation at that
1082
+ time, not a live PR state.
1083
+
1017
1084
  For `synced`, keep this finalized lifecycle state in the project checkout until
1018
1085
  Step 7.5 publishes it together with every later pre-archive artifact write. Do
1019
1086
  not push here: Step 7 may still create or replace the PR-description artifact,
@@ -1123,6 +1190,36 @@ When archiving, the project artifacts at `{PROJECT_PATH}/{plan,implementation,di
1123
1190
 
1124
1191
  Anti-pattern: do not "rescue" a dropped artifact by linking to its archived path under `.oat/projects/archived/<name>/...`. That path is gitignored on every checkout and never reaches the remote.
1125
1192
 
1193
+ **Carry the PR body across the archive (archive completion only).** Step 8
1194
+ copies the project into an archive that never retains `pr/` (review and PR
1195
+ evidence are not archived) and then removes the active project, so after Step 8
1196
+ the PR-description artifact exists nowhere on disk. Once the artifact above is
1197
+ final and before Step 8 runs, copy its frontmatter-stripped body to a
1198
+ run-scoped temporary file recorded as `PR_BODY_FILE`:
1199
+
1200
+ ```bash
1201
+ PR_BODY_FILE=""
1202
+ if [[ "$SHOULD_ARCHIVE" == "true" && "$IS_DURABLE_PROJECT" == "true" ]]; then
1203
+ test -f "$PR_DESCRIPTION_PATH" || exit 1
1204
+ PR_BODY_FILE=$(mktemp "${TMPDIR:-/tmp}/oat-pr-body.XXXXXX") || exit 1
1205
+ awk 'NR == 1 && $0 == "---" { in_frontmatter = 1; next }
1206
+ in_frontmatter { if ($0 == "---") in_frontmatter = 0; next }
1207
+ !started && /^[[:space:]]*$/ { next }
1208
+ { started = 1; print }' "$PR_DESCRIPTION_PATH" > "$PR_BODY_FILE" || exit 1
1209
+ head -n 1 "$PR_BODY_FILE" | grep -q '^# ' || {
1210
+ echo "The PR body carried from $PR_DESCRIPTION_PATH does not start with a markdown heading; refusing to archive." >&2
1211
+ exit 1
1212
+ }
1213
+ fi
1214
+ ```
1215
+
1216
+ Every later read or edit of an archive completion's PR body uses
1217
+ `PR_BODY_FILE`: the Step 8 recap-link rewrite, the Step 8.6 links block, and
1218
+ Steps 11 and 11.5. Never read `pr/` from `ARCHIVE_PATH`. A resumed archive run
1219
+ (`SHARED_ARCHIVE_RESUME="true"` or `SYNCED_ARCHIVE_RESUME="true"`) skips this
1220
+ step, so it carries no body: treat an unset `PR_BODY_FILE` as empty
1221
+ (`${PR_BODY_FILE:-}`). Non-archive completion keeps `PR_DESCRIPTION_PATH`.
1222
+
1126
1223
  #### Step 7.5: Publish Synced Project Pin Source
1127
1224
 
1128
1225
  For `synced`, publish only after Step 7 has finished every pre-archive project
@@ -1310,9 +1407,10 @@ Rewrite recap links in the tracked summary export and the PR description body fr
1310
1407
  Use a repository-relative path under
1311
1408
  `.oat/repo/reference/project-recaps/` and a blob URL on the current head branch
1312
1409
  while the PR is open. If `summaryExportFile` is non-null, update its concise
1313
- `Explainer Outcome` recap link. Update the archived PR-description artifact
1410
+ `Explainer Outcome` recap link. Update the carried PR body (`PR_BODY_FILE`)
1314
1411
  used by Step 11 or 11.5 so its recap reference points to the same tracked HTML page.
1315
- Omit either link when its containing artifact does not exist.
1412
+ Omit either link when its containing artifact does not exist (an empty
1413
+ `PR_BODY_FILE` on a resumed archive run).
1316
1414
 
1317
1415
  Use the current head branch for the blob URL while the PR is open. Never link to `.oat/projects/archived/`; it is gitignored and will return 404 remotely.
1318
1416
 
@@ -1325,8 +1423,12 @@ Run this for every synced completion after the final project ref or archive SHA
1325
1423
  is known. It is required even when no project recap was selected and
1326
1424
  `summaryExportFile` is null.
1327
1425
 
1328
- Locate the PR-description artifact under the current `PROJECT_PATH` (which is
1329
- the archive path after Step 8). Render the canonical pinned block:
1426
+ Render into the PR body this run publishes. For archive completion that is the
1427
+ carried `PR_BODY_FILE` from Step 7 (the archive keeps no `pr/`, so never look
1428
+ under `ARCHIVE_PATH`); when `PR_BODY_FILE` is empty on a resumed archive run,
1429
+ skip the insertion and let Step 11.5 report the skipped sync. For non-archive
1430
+ synced completion it is the active PR-description artifact. Render the
1431
+ canonical pinned block:
1330
1432
 
1331
1433
  ```bash
1332
1434
  FINAL_LINK_ARGS=("$PROJECT_NAME" --format markdown)
@@ -1438,7 +1540,9 @@ Expected changes may include:
1438
1540
  - `{PROJECT_PATH}/state.md`
1439
1541
  - `{PROJECT_PATH}/implementation.md` (if touched earlier in the lifecycle closeout)
1440
1542
  - `{PROJECT_PATH}/plan.md` (if review receive just ran)
1441
- - `{PROJECT_PATH}/pr/project-pr-*.md` (PR description artifact)
1543
+ - `PR_DESCRIPTION_PATH` (the active PR description artifact, non-archive
1544
+ completion only; an archive completion carries the body in `PR_BODY_FILE`
1545
+ and the archive keeps no `pr/`)
1442
1546
  - `.oat/state.md` is regenerated locally in Step 9 but should not be staged; it is generated dashboard state and normally gitignored.
1443
1547
  - `.oat/config.local.json` (if `activeProject` cleared)
1444
1548
  - Shared-project deletions; synced archive record deletion is already sealed by
@@ -1519,8 +1623,10 @@ The local artifact file contains YAML frontmatter (`---` delimited block at the
1519
1623
 
1520
1624
  Steps:
1521
1625
 
1522
- 1. Locate the PR description artifact at `{PROJECT_PATH}/pr/project-pr-*.md`.
1523
- 2. Write the stripped body to a temporary file (remove all lines from the opening `---` through the closing `---`, inclusive).
1626
+ 1. For archive completion, use the carried body: `TMP_BODY="$PR_BODY_FILE"`
1627
+ (Step 7 already stripped and verified it). Otherwise locate the PR
1628
+ description artifact at `PR_DESCRIPTION_PATH`.
1629
+ 2. For the non-archive artifact, write the stripped body to a temporary file (remove all lines from the opening `---` through the closing `---`, inclusive).
1524
1630
  3. Verify the temp file does not start with YAML frontmatter keys.
1525
1631
  4. Create the PR from the branch already pushed in Step 10:
1526
1632
 
@@ -1528,7 +1634,9 @@ Steps:
1528
1634
  gh pr create --base main --title "{title}" --body-file "$TMP_BODY"
1529
1635
  ```
1530
1636
 
1531
- 5. Clean up the temp file.
1637
+ 5. Clean up the temp file, including `PR_BODY_FILE`, once the PR is created.
1638
+ When `gh` is missing or `gh pr create` fails, keep it and report its path
1639
+ in Step 12.
1532
1640
 
1533
1641
  Do not assume `gh` is installed; if missing, instruct manual PR creation using the file contents.
1534
1642
 
@@ -1553,8 +1661,14 @@ Skip this step when:
1553
1661
 
1554
1662
  Steps:
1555
1663
 
1556
- 1. Locate the exact PR description artifact. After archive, use
1557
- `{ARCHIVE_PATH}/pr/project-pr-*.md`. For non-archive synced completion, use
1664
+ 1. Locate the exact PR description body. After archive, use the carried body:
1665
+ `TMP_BODY="$PR_BODY_FILE"` (Step 7 already stripped and verified it; skip
1666
+ step 2). The archive keeps no `pr/`, so never read `{ARCHIVE_PATH}/pr/`.
1667
+ When `${PR_BODY_FILE:-}` is empty after an archive, the run resumed an
1668
+ archive whose regenerated body was not carried across the interruption: do
1669
+ not fail; skip steps 2 through 5 and print
1670
+ `PR description not synced: this resumed archive run carries no archive-aware body; update the tracked PR description manually.`
1671
+ For non-archive synced completion, use
1558
1672
  `PR_DESCRIPTION_PATH`, require the retained remote ref to contain
1559
1673
  `PROJECT_REF_COMMIT`, and require
1560
1674
  `git show "$PROJECT_REF_COMMIT:$PR_DESCRIPTION_RELATIVE_PATH"` to equal the
@@ -1587,15 +1701,18 @@ Steps:
1587
1701
  fi
1588
1702
  ```
1589
1703
 
1590
- 5. Clean up the temp file.
1704
+ 5. Clean up the temp file, including `PR_BODY_FILE`, once the PR body is
1705
+ updated. When the update failed, keep it for the manual update.
1591
1706
 
1592
1707
  Failure handling:
1593
1708
 
1594
1709
  - If `gh` is missing or `gh pr edit` fails, always print the manual-update path.
1595
- For a synced archive completion this tracked-PR update is required: stop
1596
- before Step 12, retain the active pointer, and let the next invocation resume
1597
- recordlessly. Other completion shapes retain their existing warning-only
1598
- behavior and Step 12 summary guidance.
1710
+ For a synced archive completion, stop before Step 12 and retain the active
1711
+ pointer; the failed run keeps `PR_BODY_FILE` and prints its path. The next
1712
+ invocation resumes recordlessly without a carried body, so it reports the
1713
+ skipped sync (Step 12) rather than retrying the update: apply the retained
1714
+ body to the tracked PR by hand. Other completion shapes retain their existing
1715
+ warning-only behavior and Step 12 summary guidance.
1599
1716
  - A shared archive completion also reaches this step with the pointer still
1600
1717
  retained, but its sync failure stays warning-only. Its shared-scope resume
1601
1718
  goes straight to the Step 12 clear and would not retry this PR update, so
@@ -1649,4 +1766,4 @@ Show user:
1649
1766
  already sealed — and it stays a report, never a completion failure.
1650
1767
  - If PR was opened: include the PR URL.
1651
1768
  - If `oat_pr_url` is present, show it in the completion summary even when PR creation was skipped because the project already tracked an open PR.
1652
- - If Step 11.5 ran, report whether the PR description was synced (e.g. `PR description synced: <PR URL>`) or warn that the sync failed and surface the artifact path so the user can update it manually.
1769
+ - If Step 11.5 ran, report whether the PR description was synced (e.g. `PR description synced: <PR URL>`), that it was skipped because a resumed archive run carried no body, or warn that the sync failed and surface the retained body path (`PR_BODY_FILE` for archive completion) so the user can update it manually.
@@ -6,7 +6,7 @@ disable-model-invocation: false
6
6
  user-invocable: false
7
7
  allowed-tools: Read, Write, Edit, Bash, Glob, Grep
8
8
  metadata:
9
- version: 1.0.0
9
+ version: 1.0.1
10
10
  ---
11
11
 
12
12
  # Autonomous Project Completion
@@ -275,9 +275,9 @@ steps never reach it.
275
275
 
276
276
  Only when the PR-merge precondition passed through the exception row, append
277
277
  this block to the project's `implementation.md` before any other write. Place
278
- it at the end of the `## Implementation Log` section, or at the end of the file
279
- when that section is absent, and do not append a second block for the same PR
280
- and requesting step:
278
+ it under `## Deviations from Plan / Design`, after that section's existing
279
+ content and before the next `##` heading (never after `## References`), and do
280
+ not append a second block for the same PR and requesting step:
281
281
 
282
282
  ```markdown
283
283
  ### Completion-before-merge exception ({UTC timestamp})
@@ -5,7 +5,7 @@ disable-model-invocation: true
5
5
  user-invocable: false
6
6
  allowed-tools: Read, Bash
7
7
  metadata:
8
- version: 1.1.8
8
+ version: 1.1.9
9
9
  ---
10
10
 
11
11
  # Dispatching OAT Project Subagents
@@ -156,10 +156,15 @@ For every lifecycle dispatch:
156
156
 
157
157
  For project-aware launches, construct and redact the complete generic record
158
158
  plus OAT event before the native host call. When the call returns accepted or
159
- `blocked-before-start`, the calling workflow writes the request ID, the
160
- `Dispatch:` stamp, the launch status, and later the terminal outcome into its
161
- run record in `implementation.md`; that run record is the only launch record.
162
- `oat project dispatch record` validates a record and writes nothing.
159
+ `blocked-before-start`, the calling workflow renders the run line with
160
+ `oat project dispatch record --event-file <input> --format line --dispatch-stamp "<resolver dispatchStamp>"`
161
+ and writes it as one list item under `## Orchestration Runs` in
162
+ `implementation.md`; after the terminal outcome it re-renders the line from the
163
+ record carrying that outcome and replaces the line with the same request ID in
164
+ place. That one line per request ID (request ID, `Dispatch:` stamp, launch
165
+ status, terminal outcome) is the run record and the only launch record; the record and event
166
+ JSON are never pasted into the journal. `oat project dispatch record` validates a
167
+ record and writes nothing.
163
168
 
164
169
  An accepted launch closes replacement. A rejected record must include
165
170
  `provesNoChildStarted: true` before one target-preserving canonical-instruction
@@ -6,7 +6,7 @@ disable-model-invocation: false
6
6
  user-invocable: true
7
7
  allowed-tools: Read, Write, Edit, Bash(git:*), Bash(jq:*), Bash(oat pjm:*), Bash(oat project push:*), Bash(oat project scope:*), Bash(oat tools:*), Glob, Grep, AskUserQuestion, Skill
8
8
  metadata:
9
- version: 1.8.10
9
+ version: 1.8.11
10
10
  ---
11
11
 
12
12
  # Project Documentation Sync