@open-agent-toolkit/cli 0.0.42 → 0.0.50

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 (80) hide show
  1. package/assets/agents/oat-phase-implementer.md +230 -0
  2. package/assets/agents/oat-reviewer.md +3 -3
  3. package/assets/docs/cli-utilities/configuration.md +15 -3
  4. package/assets/docs/docs-tooling/add-docs-to-a-repo.md +12 -1
  5. package/assets/docs/docs-tooling/commands.md +4 -0
  6. package/assets/docs/reference/cli-reference.md +17 -14
  7. package/assets/docs/reference/oat-directory-structure.md +17 -17
  8. package/assets/docs/workflows/projects/artifacts.md +34 -0
  9. package/assets/docs/workflows/projects/implementation-execution.md +161 -0
  10. package/assets/docs/workflows/projects/lifecycle.md +22 -29
  11. package/assets/docs/workflows/projects/reviews.md +4 -2
  12. package/assets/docs/workflows/skills/index.md +0 -1
  13. package/assets/public-package-versions.json +4 -4
  14. package/assets/skills/oat-docs-bootstrap/SKILL.md +11 -3
  15. package/assets/skills/oat-doctor/SKILL.md +3 -3
  16. package/assets/skills/oat-project-implement/SKILL.md +368 -126
  17. package/assets/skills/oat-project-import-plan/SKILL.md +2 -3
  18. package/assets/skills/oat-project-next/SKILL.md +11 -12
  19. package/assets/skills/oat-project-plan/SKILL.md +23 -5
  20. package/assets/skills/oat-project-plan-writing/SKILL.md +2 -2
  21. package/assets/skills/oat-project-progress/SKILL.md +29 -35
  22. package/assets/skills/oat-project-quick-start/SKILL.md +14 -3
  23. package/assets/skills/oat-project-review-provide/SKILL.md +24 -2
  24. package/assets/skills/oat-project-review-receive/SKILL.md +5 -1
  25. package/assets/skills/oat-worktree-bootstrap-auto/SKILL.md +2 -2
  26. package/assets/templates/docs-app-fuma/docs/index.md +2 -0
  27. package/assets/templates/implementation.md +8 -3
  28. package/assets/templates/plan.md +24 -3
  29. package/assets/templates/state.md +1 -1
  30. package/dist/commands/config/index.d.ts.map +1 -1
  31. package/dist/commands/config/index.js +17 -4
  32. package/dist/commands/docs/index-generate/index.d.ts +1 -0
  33. package/dist/commands/docs/index-generate/index.d.ts.map +1 -1
  34. package/dist/commands/docs/index-generate/index.js +8 -1
  35. package/dist/commands/docs/init/index.d.ts.map +1 -1
  36. package/dist/commands/docs/init/index.js +46 -0
  37. package/dist/commands/docs/init/resolve-options.d.ts +2 -0
  38. package/dist/commands/docs/init/resolve-options.d.ts.map +1 -1
  39. package/dist/commands/docs/init/resolve-options.js +1 -0
  40. package/dist/commands/docs/init/root-package.d.ts +23 -0
  41. package/dist/commands/docs/init/root-package.d.ts.map +1 -0
  42. package/dist/commands/docs/init/root-package.js +226 -0
  43. package/dist/commands/init/tools/index.js +1 -1
  44. package/dist/commands/init/tools/shared/skill-manifest.d.ts +2 -2
  45. package/dist/commands/init/tools/shared/skill-manifest.d.ts.map +1 -1
  46. package/dist/commands/init/tools/shared/skill-manifest.js +1 -1
  47. package/dist/commands/project/index.d.ts.map +1 -1
  48. package/dist/commands/project/index.js +3 -1
  49. package/dist/commands/project/set-mode/index.d.ts +0 -6
  50. package/dist/commands/project/set-mode/index.d.ts.map +1 -1
  51. package/dist/commands/project/set-mode/index.js +16 -96
  52. package/dist/commands/project/validate-plan/index.d.ts +3 -0
  53. package/dist/commands/project/validate-plan/index.d.ts.map +1 -0
  54. package/dist/commands/project/validate-plan/index.js +44 -0
  55. package/dist/commands/project/validate-plan/validate-plan.d.ts +20 -0
  56. package/dist/commands/project/validate-plan/validate-plan.d.ts.map +1 -0
  57. package/dist/commands/project/validate-plan/validate-plan.js +77 -0
  58. package/dist/commands/tools/update/index.d.ts +4 -0
  59. package/dist/commands/tools/update/index.d.ts.map +1 -1
  60. package/dist/commands/tools/update/index.js +17 -1
  61. package/dist/commands/tools/update/update-tools.d.ts +1 -0
  62. package/dist/commands/tools/update/update-tools.d.ts.map +1 -1
  63. package/dist/commands/tools/update/update-tools.js +80 -1
  64. package/dist/config/oat-config.d.ts +1 -0
  65. package/dist/config/oat-config.d.ts.map +1 -1
  66. package/dist/config/oat-config.js +3 -0
  67. package/dist/config/resolve.d.ts.map +1 -1
  68. package/dist/config/resolve.js +9 -0
  69. package/package.json +2 -2
  70. package/assets/skills/oat-project-subagent-implement/SKILL.md +0 -549
  71. package/assets/skills/oat-project-subagent-implement/examples/pattern-hill-checkpoint.md +0 -110
  72. package/assets/skills/oat-project-subagent-implement/examples/pattern-parallel-phases.md +0 -118
  73. package/assets/skills/oat-project-subagent-implement/scripts/dispatch.sh +0 -133
  74. package/assets/skills/oat-project-subagent-implement/scripts/reconcile.sh +0 -182
  75. package/assets/skills/oat-project-subagent-implement/scripts/review-gate.sh +0 -187
  76. package/assets/skills/oat-project-subagent-implement/tests/fixtures/sample-plan.md +0 -234
  77. package/assets/skills/oat-project-subagent-implement/tests/test-dry-run.sh +0 -126
  78. package/assets/skills/oat-project-subagent-implement/tests/test-hill-checkpoint.sh +0 -127
  79. package/assets/skills/oat-project-subagent-implement/tests/test-reconcile.sh +0 -254
  80. package/assets/skills/oat-project-subagent-implement/tests/test-review-gate.sh +0 -220
package/assets/skills/oat-project-import-plan/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: oat-project-import-plan
3
- version: 1.2.0
3
+ version: 1.2.1
4
4
  description: Use when you have an external markdown plan to execute with OAT. Preserves the source plan and normalizes it into canonical plan.md format.
5
5
  argument-hint: '<path-to-plan.md> [--provider codex|cursor|claude] [--project <name>]'
6
6
  disable-model-invocation: true
@@ -212,8 +212,7 @@ Report:
212
212
  - active project pointer path
213
213
  - dashboard refresh status
214
214
  - next options:
215
- - `oat-project-implement` (sequential, default)
216
- - `oat-project-subagent-implement` (parallel with autonomous review gates)
215
+ - `oat-project-implement` (sequential by default; parallel when `oat_plan_parallel_groups` is declared)
217
216
 
218
217
  ## Success Criteria
219
218
 
package/assets/skills/oat-project-next/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: oat-project-next
3
- version: 1.0.1
3
+ version: 1.0.3
4
4
  description: Use when continuing work on the active OAT project. Reads project state, determines the next lifecycle action, and invokes the appropriate skill automatically.
5
5
  disable-model-invocation: true
6
6
  user-invocable: true
@@ -101,15 +101,14 @@ ls -d "$PROJECTS_ROOT"/*/ 2>/dev/null
101
101
 
102
102
  Read `"$PROJECT_PATH/state.md"` frontmatter and extract:
103
103
 
104
- | Field | Used For |
105
- | ---------------------- | --------------------------------------------------------------------------------------- |
106
- | `oat_phase` | Current lifecycle position (discovery, spec, design, plan, implement) |
107
- | `oat_phase_status` | Phase completion state (in_progress, complete, pr_open) |
108
- | `oat_workflow_mode` | Routing table selection (spec-driven, quick, import). Default: `spec-driven` |
109
- | `oat_execution_mode` | Implementation skill variant (single-thread, subagent-driven). Default: `single-thread` |
110
- | `oat_hill_checkpoints` | Which phases require HiLL approval |
111
- | `oat_hill_completed` | Which HiLL gates have been passed |
112
- | `oat_blockers` | Informational warnings (not routing gates) |
104
+ | Field | Used For |
105
+ | ---------------------- | ---------------------------------------------------------------------------- |
106
+ | `oat_phase` | Current lifecycle position (discovery, spec, design, plan, implement) |
107
+ | `oat_phase_status` | Phase completion state (in_progress, complete, pr_open) |
108
+ | `oat_workflow_mode` | Routing table selection (spec-driven, quick, import). Default: `spec-driven` |
109
+ | `oat_hill_checkpoints` | Which phases require HiLL approval |
110
+ | `oat_hill_completed` | Which HiLL gates have been passed |
111
+ | `oat_blockers` | Informational warnings (not routing gates) |
113
112
 
114
113
  **If state.md is missing or unreadable:** Report error and suggest running the relevant phase skill directly. STOP.
115
114
 
@@ -231,7 +230,7 @@ Otherwise, look up the target skill from the routing table for the current `oat_
231
230
  | plan | complete | tier 1 | `oat-project-implement` \* |
232
231
  | implement | in_progress | — | `oat-project-implement` \* |
233
232
 
234
- \* When `oat_execution_mode: subagent-driven`, use `oat-project-subagent-implement` instead.
233
+ \* `oat-project-implement` handles both sequential and parallel execution.
235
234
 
236
235
  ### Step 4: Check for Unprocessed Reviews (Review Safety Check)
237
236
 
@@ -261,7 +260,7 @@ Apply the following checks in priority order. Stop at the first match:
261
260
  **5.1: Incomplete revision tasks**
262
261
 
263
262
  Grep plan.md for `p-revN` phases. If any `p-revN` tasks exist with status != completed in implementation.md:
264
- → Route to `oat-project-implement` (or `oat-project-subagent-implement` if subagent-driven)
263
+ → Route to `oat-project-implement`
265
264
  → Announce: "Revision tasks pending — continuing implementation"
266
265
 
267
266
  **5.2: Unprocessed reviews**
package/assets/skills/oat-project-plan/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: oat-project-plan
3
- version: 1.2.0
3
+ version: 1.3.1
4
4
  description: Use when design.md is complete and executable implementation tasks are needed. Breaks design into bite-sized TDD tasks in canonical plan.md format.
5
5
  disable-model-invocation: true
6
6
  user-invocable: true
@@ -271,12 +271,13 @@ For each task, include:
271
271
  - **Files:** Exact paths for create/modify/delete
272
272
  - **Signatures:** Interface definitions, function signatures, type declarations
273
273
  - **Test cases:** Test file paths and test descriptions (pseudocode OK for test bodies)
274
- - **Commands:** Exact verification commands
274
+ - **Commands:** Exact verification commands that match the claimed scope. If the task says "run this file" or "run this test target," use the real runner invocation that actually scopes to that target rather than a shortcut that may execute the full package suite.
275
275
  - **Commit:** Conventional commit message with task ID (e.g., `feat(p01-t03): ...`)
276
276
 
277
277
  **Avoid:**
278
278
  - Vague instructions ("update the file")
279
279
  - Missing verification steps
280
+ - Verification shortcuts that claim file-scoped coverage but actually run a broader suite
280
281
  - Bundled unrelated changes
281
282
  - Full implementation code (leave that for oat-project-implement)
282
283
 
@@ -342,6 +343,25 @@ oat_last_updated: {today}
342
343
  ---
343
344
  ````
344
345
 
346
+ ### Step 14.5: Propose Parallel Groups (Optional)
347
+
348
+ After all phases are drafted, evaluate whether any phases have non-overlapping file boundaries:
349
+
350
+ 1. For each pair of adjacent phases in the plan, check the `Files:` section of all tasks in each phase.
351
+ 2. If no file appears in both phases' task files sections, they are candidates for a parallel group.
352
+ 3. Propose to the user:
353
+
354
+ ```
355
+ I noticed phases p02 and p03 have disjoint file boundaries (no overlap).
356
+ Declare them as a parallel group? This lets oat-project-implement run them
357
+ concurrently in worktrees, cutting wall-clock time.
358
+ ```
359
+
360
+ 4. If the user confirms, update `oat_plan_parallel_groups` in the plan frontmatter.
361
+ 5. If no phases are obviously independent, skip this step silently — do not invent parallelism.
362
+
363
+ Never silently infer parallelism without explicit user confirmation.
364
+
345
365
  ### Step 14: Update Project State
346
366
 
347
367
  Update `"$PROJECT_PATH/state.md"`:
@@ -400,9 +420,7 @@ Phases:
400
420
 
401
421
  Total: {N} tasks
402
422
 
403
- Next: Choose your implementation approach:
404
- - oat-project-implement — Sequential task execution (default)
405
- - oat-project-subagent-implement — Parallel worktree execution with autonomous review gates
423
+ Next: Run oat-project-implement to begin execution.
406
424
  ```
407
425
 
408
426
  ## Success Criteria
package/assets/skills/oat-project-plan-writing/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: oat-project-plan-writing
3
- version: 1.2.0
3
+ version: 1.2.1
4
4
  description: Use when authoring or mutating plan.md in any OAT workflow. Defines canonical format invariants — stable task IDs, required sections, review table rules, and resume guardrails.
5
5
  disable-model-invocation: true
6
6
  user-invocable: false
@@ -47,7 +47,7 @@ Planning-time default:
47
47
  Runtime routing note:
48
48
 
49
49
  - Keep `oat_ready_for` canonical as `oat-project-implement`.
50
- - Use `oat_execution_mode` in `state.md` (`single-thread` or `subagent-driven`) to choose sequential vs subagent implementation flow at runtime.
50
+ - Declare parallelism via `oat_plan_parallel_groups` in plan.md frontmatter (empty = sequential; nested arrays of phase IDs = parallel groups). `oat-project-implement` reads this field to choose sequential vs worktree-isolated parallel execution.
51
51
 
52
52
  Additional frontmatter keys (`oat_phase`, `oat_phase_status`, `oat_blockers`, `oat_last_updated`, `oat_generated`, `oat_template`, `oat_import_reference`, `oat_import_source_path`, `oat_import_provider`) are set by calling skills as needed.
53
53
 
package/assets/skills/oat-project-progress/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: oat-project-progress
3
- version: 1.2.0
3
+ version: 1.2.2
4
4
  description: Use when resuming work, checking status, or unsure which OAT skill to run next. Evaluates project progress and routes to the appropriate next step.
5
5
  disable-model-invocation: true
6
6
  user-invocable: true
@@ -180,11 +180,6 @@ Read `oat_workflow_mode` from `state.md` frontmatter:
180
180
  - `quick`
181
181
  - `import`
182
182
 
183
- Read `oat_execution_mode` from `state.md` frontmatter:
184
-
185
- - `single-thread` (default if missing)
186
- - `subagent-driven`
187
-
188
183
  **HiLL override (apply before phase routing):**
189
184
 
190
185
  - If current `oat_phase` is listed in `oat_hill_checkpoints` **and** not listed in `oat_hill_completed`, the phase's HiLL gate is still pending.
@@ -228,38 +223,38 @@ Routing matrix by mode:
228
223
 
229
224
  **Spec-Driven mode (`oat_workflow_mode: spec-driven`):**
230
225
 
231
- | oat_phase | oat_phase_status | Next Skill |
232
- | --------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
233
- | discovery | in_progress | Continue `oat-project-discover` |
234
- | discovery | complete | `oat-project-spec` |
235
- | spec | in_progress | Continue `oat-project-spec` |
236
- | spec | complete | `oat-project-design` |
237
- | design | in_progress | Continue `oat-project-design` |
238
- | design | complete | `oat-project-plan` |
239
- | plan | in_progress | Continue `oat-project-plan` |
240
- | plan | complete | `oat-project-subagent-implement` when `oat_execution_mode: subagent-driven`, otherwise `oat-project-implement` |
241
- | implement | in_progress | Continue `oat-project-subagent-implement` when `oat_execution_mode: subagent-driven`, otherwise `oat-project-implement`. If artifacts appear out of sync with recent commits (e.g., `implementation.md` has fewer completed tasks than commits suggest), also mention `oat-project-reconcile` as an option. |
242
- | implement | complete | Ready for final review / PR |
226
+ | oat_phase | oat_phase_status | Next Skill |
227
+ | --------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
228
+ | discovery | in_progress | Continue `oat-project-discover` |
229
+ | discovery | complete | `oat-project-spec` |
230
+ | spec | in_progress | Continue `oat-project-spec` |
231
+ | spec | complete | `oat-project-design` |
232
+ | design | in_progress | Continue `oat-project-design` |
233
+ | design | complete | `oat-project-plan` |
234
+ | plan | in_progress | Continue `oat-project-plan` |
235
+ | plan | complete | `oat-project-implement` |
236
+ | implement | in_progress | Continue `oat-project-implement`. If artifacts appear out of sync with recent commits (e.g., `implementation.md` has fewer completed tasks than commits suggest), also mention `oat-project-reconcile` as an option. |
237
+ | implement | complete | Ready for final review / PR |
243
238
 
244
239
  **Quick mode (`oat_workflow_mode: quick`):**
245
240
 
246
- | oat_phase | oat_phase_status | Next Skill |
247
- | --------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
248
- | discovery | in_progress | Continue `oat-project-discover` |
249
- | discovery | complete | `oat-project-plan` |
250
- | plan | in_progress | Continue `oat-project-plan` |
251
- | plan | complete | `oat-project-subagent-implement` when `oat_execution_mode: subagent-driven`, otherwise `oat-project-implement` |
252
- | implement | in_progress | Continue `oat-project-subagent-implement` when `oat_execution_mode: subagent-driven`, otherwise `oat-project-implement`. If drift detected (see drift detection above), also mention `oat-project-reconcile` as an option. |
253
- | implement | complete | Ready for final review / PR |
241
+ | oat_phase | oat_phase_status | Next Skill |
242
+ | --------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
243
+ | discovery | in_progress | Continue `oat-project-discover` |
244
+ | discovery | complete | `oat-project-plan` |
245
+ | plan | in_progress | Continue `oat-project-plan` |
246
+ | plan | complete | `oat-project-implement` |
247
+ | implement | in_progress | Continue `oat-project-implement`. If drift detected (see drift detection above), also mention `oat-project-reconcile` as an option. |
248
+ | implement | complete | Ready for final review / PR |
254
249
 
255
250
  **Import mode (`oat_workflow_mode: import`):**
256
251
 
257
- | oat_phase | oat_phase_status | Next Skill |
258
- | --------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
259
- | plan | in_progress | Continue `oat-project-import-plan` |
260
- | plan | complete | `oat-project-subagent-implement` when `oat_execution_mode: subagent-driven`, otherwise `oat-project-implement` |
261
- | implement | in_progress | Continue `oat-project-subagent-implement` when `oat_execution_mode: subagent-driven`, otherwise `oat-project-implement`. If drift detected (see drift detection above), also mention `oat-project-reconcile` as an option. |
262
- | implement | complete | Ready for final review / PR |
252
+ | oat_phase | oat_phase_status | Next Skill |
253
+ | --------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
254
+ | plan | in_progress | Continue `oat-project-import-plan` |
255
+ | plan | complete | `oat-project-implement` |
256
+ | implement | in_progress | Continue `oat-project-implement`. If drift detected (see drift detection above), also mention `oat-project-reconcile` as an option. |
257
+ | implement | complete | Ready for final review / PR |
263
258
 
264
259
  **If blockers exist:**
265
260
 
@@ -272,7 +267,7 @@ Address blocker before continuing.
272
267
  Execution-mode note:
273
268
 
274
269
  - Keep `oat_ready_for` in `plan.md` canonical (`oat-project-implement`).
275
- - Runtime routing at plan completion is controlled by `oat_execution_mode` in `state.md`.
270
+ - Runtime execution is handled by `oat-project-implement`; parallelism is declared in plan.md via `oat_plan_parallel_groups`.
276
271
 
277
272
  ### Step 6: Show Available Skills
278
273
 
@@ -290,8 +285,7 @@ Workflow:
290
285
  oat-project-spec - Create specification from discovery
291
286
  oat-project-design - Create technical design from spec
292
287
  oat-project-plan - Create implementation plan from design (spec-driven mode)
293
- oat-project-implement - Execute implementation plan
294
- oat-project-subagent-implement - Execute implementation plan with subagent orchestration
288
+ oat-project-implement - Execute implementation plan (sequential or parallel)
295
289
  oat-project-reconcile - Reconcile manual/human commits with plan tasks
296
290
 
297
291
  Status:
package/assets/skills/oat-project-quick-start/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: oat-project-quick-start
3
- version: 1.3.3
3
+ version: 1.3.6
4
4
  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.
5
5
  argument-hint: '<project-name> ["project description"]'
6
6
  disable-model-invocation: true
@@ -70,6 +70,7 @@ When executing this skill, provide lightweight progress feedback so the user can
70
70
  - After any write to `discovery.md`, `design.md`, `plan.md`, `implementation.md`, or project `state.md`, ensure the artifact is saved immediately and remains tracked in git.
71
71
  - If the skill is about to pause for user input or stop after mutating artifacts, commit the changed artifacts before waiting. Do not leave discovery/design updates only in the working tree.
72
72
  - Quick-start handoff is not complete until the changed project artifacts and regenerated `.oat/state.md` dashboard have been committed.
73
+ - This applies to downstream lifecycle boundaries too: implementation, review, revise, and PR skills must inherit a committed artifact baseline, not an untracked project tree.
73
74
 
74
75
  ## Process
75
76
 
@@ -300,6 +301,16 @@ Plan requirements — apply `oat-project-plan-writing` canonical format invarian
300
301
  - Required sections: `## Reviews`, `## Implementation Complete`, `## References`
301
302
  - Review table preservation rules (never delete existing rows)
302
303
 
304
+ Required parallelism pass before finalizing the plan:
305
+
306
+ - Evaluate adjacent phases for phase-level parallelism before treating the plan as complete.
307
+ - Set `oat_plan_parallel_groups` whenever phases can run independently in isolated worktrees with disjoint write boundaries and independent verification.
308
+ - Keep dependent tasks in the same phase when they must run sequentially.
309
+ - Do not declare parallel groups when phases share a fragile migration, require the same generated artifact, or one phase's tests depend on another phase's behavior.
310
+ - Add a short `## Parallelism` section to `plan.md` explaining the dependency and write-set reasoning, including why groups were declared or why the plan remains sequential.
311
+ - Quick mode is not "sequential by default." A quick-start plan is sequential only when the dependency and write-set analysis says it should be.
312
+ - When a task claims scoped verification, prefer the exact runner invocation that truly scopes to the intended file, test, or target instead of package-level shortcuts that may execute the full suite.
313
+
303
314
  ### Step 4: Sync Project State
304
315
 
305
316
  Update `"$PROJECT_PATH/state.md"`:
@@ -354,9 +365,9 @@ Report:
354
365
  - workflow mode (`quick`)
355
366
  - total phases/tasks generated
356
367
  - first task ID
368
+ - execution shape summary (sequential or declared parallel groups)
357
369
  - next options:
358
- - `oat-project-implement` (sequential, default)
359
- - `oat-project-subagent-implement` (parallel with autonomous review gates)
370
+ - `oat-project-implement`
360
371
  - dashboard location: `.oat/state.md` (confirm it was regenerated)
361
372
 
362
373
  ## Success Criteria
package/assets/skills/oat-project-review-provide/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: oat-project-review-provide
3
- version: 1.3.0
3
+ version: 1.3.1
4
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.
5
5
  disable-model-invocation: true
6
6
  user-invocable: true
@@ -19,6 +19,8 @@ Produce an independent review artifact that verifies requirements/design alignme
19
19
 
20
20
  **Required:** Active project with at least one completed task.
21
21
 
22
+ **Required:** Core project artifacts are already committed before the review begins. Review should not be the first step that notices an untracked project tree or pending bookkeeping-only artifact edits.
23
+
22
24
  ## Mode Assertion
23
25
 
24
26
  **OAT MODE: Review Request**
@@ -218,7 +220,27 @@ TARGET_BRANCH="${TARGET_BRANCH:-$CURRENT_BRANCH}" # from user scope, worktree c
218
220
 
219
221
  - If user chooses option 1: run `git checkout {TARGET_BRANCH}`, then proceed.
220
222
  - If user chooses option 2: set `INLINE_ONLY=true` — skip artifact write (Step 7/8) and output review findings directly in the session. The user can manually save the output.
221
- - If user chooses option 3: stop and suggest `oat-worktree-bootstrap-auto`.
223
+
224
+ ### Step 1.6: Enforce Committed Artifact Baseline
225
+
226
+ Before gathering review context, inspect the core project artifacts:
227
+
228
+ - `"$PROJECT_PATH/discovery.md"`
229
+ - `"$PROJECT_PATH/spec.md"`
230
+ - `"$PROJECT_PATH/design.md"`
231
+ - `"$PROJECT_PATH/plan.md"`
232
+ - `"$PROJECT_PATH/implementation.md"`
233
+ - `"$PROJECT_PATH/state.md"`
234
+ - `.oat/state.md` (when it exists and was refreshed as part of the project workflow)
235
+
236
+ If any of those files are untracked or modified only because the previous workflow step did not finish its bookkeeping commit:
237
+
238
+ - Stop and tell the user to commit the pending artifact bookkeeping first, or resume the originating workflow skill so it can do that commit.
239
+ - Do not write a review artifact against that half-tracked state.
240
+
241
+ If the review is intentionally inline-only and the user explicitly wants to inspect an uncommitted artifact state, say so clearly in the output and skip writing the review artifact to disk.
242
+
243
+ - If user chooses option 3: stop and suggest `oat-worktree-bootstrap-auto`.
222
244
 
223
245
  ### Step 2: Validate Artifacts Exist (Mode-Aware)
224
246
 
package/assets/skills/oat-project-review-receive/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: oat-project-review-receive
3
- version: 1.4.0
3
+ version: 1.4.1
4
4
  description: Use when review findings from oat-project-review-provide need closure. Converts review artifacts into actionable plan tasks.
5
5
  disable-model-invocation: true
6
6
  user-invocable: true
@@ -19,6 +19,8 @@ Turn review output into plan changes and a clear next action. This closes the fe
19
19
 
20
20
  **Required:** An active review artifact exists in the top level of `{PROJECT_PATH}/reviews/` (not in `reviews/archived/`).
21
21
 
22
+ This skill assumes the reviewed project artifacts were already committed before the review ran. If you discover untracked core project artifacts here, treat that as earlier workflow drift and include them in the bookkeeping fix instead of leaving the project partially tracked.
23
+
22
24
  ## Mode Assertion
23
25
 
24
26
  **OAT MODE: Receive Review**
@@ -435,6 +437,8 @@ git diff --cached --quiet || git commit -m "chore(oat): record review findings a
435
437
 
436
438
  Do not use `git add -A` or glob patterns that reach outside `"$PROJECT_PATH/reviews/"`. Do not include unrelated implementation or code files in this commit. Do not defer this commit without explicit user approval — if deferred, clearly state in the summary that bookkeeping is uncommitted so the original agent knows to commit on return.
437
439
 
440
+ If the project itself is still untracked because earlier lifecycle steps never committed the initial artifact set, widen this bookkeeping commit to include the untracked core project artifacts (`discovery.md`, `spec.md`, `design.md`, `plan.md`, `implementation.md`, `state.md`, plus `.oat/state.md` when relevant). Do not leave the project tree partially tracked after receive-review finishes.
441
+
438
442
  **Note on archived review paths:** When `reviews/archived/` matches a `localPaths` pattern (the default setup), the archived file is gitignored and `git add "$PROJECT_PATH/reviews/"` will only stage the deletion of the original (now-moved) top-level review file. When `reviews/archived/` is tracked, both the deletion and the new archived location are staged. Both cases are safe — the command handles them uniformly.
439
443
 
440
444
  **Worktree handling:** If the project was resolved via a worktree in Step 0, run the git commands scoped to the worktree (`git -C "$WORKTREE_PATH" ...`) so the commit lands on the worktree branch.
package/assets/skills/oat-worktree-bootstrap-auto/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: oat-worktree-bootstrap-auto
3
- version: 1.2.0
3
+ version: 1.2.1
4
4
  description: Use when an orchestrator/subagent needs autonomous worktree bootstrap. Non-interactive companion to oat-worktree-bootstrap.
5
5
  argument-hint: '<branch-name> [--base <ref>] [--path <root>] [--baseline-policy <strict|allow-failing>]'
6
6
  disable-model-invocation: true
@@ -226,7 +226,7 @@ Append to `implementation.md` under `## Implementation Log`:
226
226
 
227
227
  **Orchestrator integration:**
228
228
 
229
- - When invoked by `oat-project-subagent-implement`, the baseline policy is passed through from the orchestration run policy.
229
+ - When invoked by `oat-project-implement` in parallel mode, the baseline policy is passed through from the orchestration run policy.
230
230
  - The orchestrator may set `--baseline-policy allow-failing` for exploratory runs and `strict` for production-quality execution.
231
231
  - The bootstrap skill does not interpret HiLL checkpoints — that responsibility belongs to the orchestrator.
232
232
 
package/assets/templates/docs-app-fuma/docs/index.md CHANGED
@@ -3,6 +3,8 @@ title: '{{SITE_NAME}}'
3
3
  description: '{{SITE_DESCRIPTION}}'
4
4
  ---
5
5
 
6
+ <!-- AUTOGENERATED by `oat docs generate-index`. Do not hand-edit; changes are clobbered on every `predev` / `prebuild`. -->
7
+
6
8
  # {{SITE_NAME}}
7
9
 
8
10
  Use this file as the map to the repository's central documentation site. The site is organized to support both human readers and AI agents, with every directory exposing an `index.md` entrypoint.
package/assets/templates/implementation.md CHANGED
@@ -112,11 +112,16 @@ oat_template_name: implementation
112
112
 
113
113
  ## Orchestration Runs
114
114
 
115
- > This section is used by `oat-project-subagent-implement` to log parallel execution runs.
116
- > Each run appends a new subsection — never overwrite prior entries.
117
- > For single-thread execution (via `oat-project-implement`), this section remains empty.
115
+ _Each run from `oat-project-implement` appends an entry below with:_
116
+ _- Run header (number, timestamp, branch, tier, policy, phase counts)_
117
+ _- Phase Outcomes table_
118
+ _- Parallel Groups list_
119
+ _- Outstanding Items_
118
120
 
119
121
  <!-- orchestration-runs-start -->
122
+
123
+ _Orchestration runs from `oat-project-implement` are appended here, most-recent-first within the file but append-only at the bottom of the log._
124
+
120
125
  <!-- orchestration-runs-end -->
121
126
 
122
127
  ---
package/assets/templates/plan.md CHANGED
@@ -6,6 +6,7 @@ oat_last_updated: YYYY-MM-DD
6
6
  oat_phase: plan
7
7
  oat_phase_status: in_progress
8
8
  oat_plan_hill_phases: [] # phases to pause AFTER completing (empty = every phase)
9
+ oat_plan_parallel_groups: [] # groups of phases that run concurrently in worktrees; [] = fully sequential
9
10
  oat_plan_source: spec-driven # spec-driven | quick | imported
10
11
  oat_import_reference: null # e.g., references/imported-plan.md
11
12
  oat_import_source_path: null # original source path provided by user
@@ -17,7 +18,7 @@ oat_template_name: plan
17
18
 
18
19
  # Implementation Plan: {Project Name}
19
20
 
20
- > Execute this plan using `oat-project-implement` (sequential) or `oat-project-subagent-implement` (parallel), with phase checkpoints and review gates.
21
+ > Execute this plan using `oat-project-implement` — sequential by default, parallel when `oat_plan_parallel_groups` is declared.
21
22
 
22
23
  **Goal:** {Brief goal statement from spec}
23
24
 
@@ -31,6 +32,22 @@ oat_template_name: plan
31
32
 
32
33
  - [ ] Confirmed HiLL checkpoints with user
33
34
  - [ ] Set `oat_plan_hill_phases` in frontmatter
35
+ - [ ] Evaluated phases for parallelism opportunities
36
+ - [ ] Set `oat_plan_parallel_groups` in frontmatter
37
+
38
+ ---
39
+
40
+ ## Parallelism
41
+
42
+ Phases that have no overlapping file modifications may run concurrently. To declare parallelism:
43
+
44
+ ```yaml
45
+ oat_plan_parallel_groups: [['p02', 'p03']]
46
+ ```
47
+
48
+ Each inner array is a group of phases that execute in parallel (each in its own worktree) and merge back in plan order after all pass. Groups themselves run sequentially.
49
+
50
+ Default is `[]` (fully sequential, no worktrees). Only declare parallelism when phases are genuinely file-disjoint — overlap will produce merge conflicts that stop the run.
34
51
 
35
52
  ---
36
53
 
@@ -54,7 +71,7 @@ describe('{feature}', () => {
54
71
  });
55
72
  ```
56
73
 
57
- Run: `pnpm test {path/to/file.test.ts}`
74
+ Run: `pnpm --filter {package-name} exec vitest run {path/to/file.test.ts}`
58
75
  Expected: Test fails (RED)
59
76
 
60
77
  **Step 2: Implement (GREEN)**
@@ -64,9 +81,11 @@ Expected: Test fails (RED)
64
81
  // Implementation code or interface signatures
65
82
  ```
66
83
 
67
- Run: `pnpm test {path/to/file.test.ts}`
84
+ Run: `pnpm --filter {package-name} exec vitest run {path/to/file.test.ts}`
68
85
  Expected: Test passes (GREEN)
69
86
 
87
+ Use the actual runner command that scopes to the intended file or test target. Do not write a package-level shortcut unless it truly executes only the scope the task claims.
88
+
70
89
  **Step 3: Refactor**
71
90
 
72
91
  {Any cleanup or improvements while tests stay green}
@@ -108,6 +127,8 @@ git commit -m "feat(p01-t01): {description}"
108
127
  Run: `{verification command}`
109
128
  Expected: {output}
110
129
 
130
+ Verification commands should be behaviorally accurate. If the task claims a file-scoped or test-scoped check, use the concrete runner invocation that really scopes to that target.
131
+
111
132
  **Step 5: Commit**
112
133
 
113
134
  ```bash
package/assets/templates/state.md CHANGED
@@ -8,7 +8,7 @@ oat_hill_completed: [] # Progress: which HiLL checkpoints have been completed
8
8
  oat_parallel_execution: false
9
9
  oat_phase: { OAT_PHASE } # Current phase: discovery | spec | design | plan | implement
10
10
  oat_phase_status: in_progress # Status: in_progress | complete | pr_open
11
- oat_execution_mode: single-thread # single-thread | subagent-driven
11
+ # oat_orchestration_retry_limit: 2 # optional; override fix-loop retry limit (range 0-5)
12
12
  oat_workflow_mode: { OAT_WORKFLOW_MODE } # spec-driven | quick | import
13
13
  oat_workflow_origin: native # native | imported
14
14
  oat_docs_updated: null # null | skipped | complete — documentation sync status
package/dist/commands/config/index.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGhF,OAAO,EACL,KAAK,SAAS,EACd,KAAK,cAAc,EAGnB,KAAK,UAAU,EAOhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoDpC,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,eAAe,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AAyiCD,wBAAgB,mBAAmB,CACjC,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CA0GT"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGhF,OAAO,EACL,KAAK,SAAS,EACd,KAAK,cAAc,EAGnB,KAAK,UAAU,EAOhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqDpC,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,eAAe,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AAwjCD,wBAAgB,mBAAmB,CACjC,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CA0GT"}
package/dist/commands/config/index.js CHANGED
@@ -34,6 +34,7 @@ const KEY_ORDER = [
34
34
  'workflow.createPrOnComplete',
35
35
  'workflow.postImplementSequence',
36
36
  'workflow.reviewExecutionModel',
37
+ 'workflow.autoReviewAtHillCheckpoints',
37
38
  'workflow.autoNarrowReReviewScope',
38
39
  'worktrees.root',
39
40
  ];
@@ -80,7 +81,7 @@ const CONFIG_CATALOG = [
80
81
  defaultValue: 'false',
81
82
  mutability: 'read/write',
82
83
  owningCommand: 'oat config set autoReviewAtCheckpoints <true|false>',
83
- description: 'Controls whether OAT automatically runs review gates at configured phase checkpoints.',
84
+ description: 'Deprecated compatibility alias for workflow.autoReviewAtHillCheckpoints. Prefer `oat config set workflow.autoReviewAtHillCheckpoints <true|false>`.',
84
85
  },
85
86
  {
86
87
  key: 'documentation.root',
@@ -346,6 +347,17 @@ const CONFIG_CATALOG = [
346
347
  owningCommand: 'oat config set workflow.reviewExecutionModel <value>',
347
348
  description: 'Default execution model for the final review step in oat-project-implement: "subagent" dispatches a review subagent, "inline" runs the review in-context, "fresh-session" prints guidance for running the review in a separate session (with an escape hatch to subagent/inline). When unset, the skill prompts. Resolution: env > local > shared > user > default.',
348
349
  },
350
+ {
351
+ key: 'workflow.autoReviewAtHillCheckpoints',
352
+ group: 'Workflow Preferences (3-layer: local > shared > user)',
353
+ file: '.oat/config.local.json | .oat/config.json | ~/.oat/config.json',
354
+ scope: 'workflow',
355
+ type: 'boolean',
356
+ defaultValue: 'unset',
357
+ mutability: 'read/write',
358
+ owningCommand: 'oat config set workflow.autoReviewAtHillCheckpoints <true|false>',
359
+ description: 'Automatically run the extra lifecycle review when a HiLL checkpoint is reached. This does not control Tier 1 per-phase oat-reviewer gates. When unset, the skill prompts. Resolution: env > local > shared > user > legacy autoReviewAtCheckpoints > default.',
360
+ },
349
361
  {
350
362
  key: 'workflow.autoNarrowReReviewScope',
351
363
  group: 'Workflow Preferences (3-layer: local > shared > user)',
@@ -422,6 +434,7 @@ const WORKFLOW_ENUM_VALUES = {
422
434
  const WORKFLOW_BOOLEAN_KEYS = new Set([
423
435
  'workflow.archiveOnComplete',
424
436
  'workflow.createPrOnComplete',
437
+ 'workflow.autoReviewAtHillCheckpoints',
425
438
  'workflow.autoNarrowReReviewScope',
426
439
  ]);
427
440
  function isWorkflowKey(key) {
@@ -467,10 +480,10 @@ function validateSurfaceForKey(key, surface) {
467
480
  }
468
481
  return;
469
482
  }
470
- // autoReviewAtCheckpoints is currently shared-only. Multi-surface support
471
- // for behavioral keys is out of scope for p01-t04 (workflow.* keys only).
483
+ // Legacy alias remains shared-only. The preferred multi-surface key is
484
+ // workflow.autoReviewAtHillCheckpoints.
472
485
  if (key === 'autoReviewAtCheckpoints' && surface !== 'shared') {
473
- throw new Error(`Cannot set 'autoReviewAtCheckpoints' at '${surface}' scope. This key is currently shared-only.`);
486
+ throw new Error(`Cannot set 'autoReviewAtCheckpoints' at '${surface}' scope. This legacy key is shared-only; use workflow.autoReviewAtHillCheckpoints for local/user overrides.`);
474
487
  }
475
488
  // Workflow keys accept any non-auto surface.
476
489
  }
package/dist/commands/docs/index-generate/index.d.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import { type CommandContext, type GlobalOptions } from '../../../app/command-context.js';
2
2
  import { Command } from 'commander';
3
+ export declare const GENERATED_INDEX_WARNING = "<!-- AUTOGENERATED by `oat docs generate-index`. Do not hand-edit; changes are clobbered on every `predev` / `prebuild`. -->";
3
4
  interface IndexGenerateFileDependencies {
4
5
  generateIndex: (docsDir: string) => Promise<import('./generator.js').IndexEntry[]>;
5
6
  renderIndex: (entries: import('./generator.js').IndexEntry[]) => string;
package/dist/commands/docs/index-generate/index.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAS5C,UAAU,6BAA6B;IACrC,aAAa,EAAE,CACb,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC,CAAC;IACjD,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,KAAK,MAAM,CAAC;IACrE,SAAS,EAAE,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,aAAa,EAAE,CACb,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,OAAO,oBAAoB,EAAE,SAAS,CAAC,CAAC;IACrD,cAAc,EAAE,CACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,oBAAoB,EAAE,SAAS,KAC3C,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACnD;AAED,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,QAAQ,EAAE,6BAA6B,CAAC;CACzC;AAwED,wBAAgB,8BAA8B,CAC5C,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAsBT"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAI5C,eAAO,MAAM,uBAAuB,iIAC4F,CAAC;AAOjI,UAAU,6BAA6B;IACrC,aAAa,EAAE,CACb,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC,CAAC;IACjD,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,KAAK,MAAM,CAAC;IACrE,SAAS,EAAE,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,aAAa,EAAE,CACb,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,OAAO,oBAAoB,EAAE,SAAS,CAAC,CAAC;IACrD,cAAc,EAAE,CACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,oBAAoB,EAAE,SAAS,KAC3C,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACnD;AAED,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,QAAQ,EAAE,6BAA6B,CAAC;CACzC;AAgFD,wBAAgB,8BAA8B,CAC5C,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAsBT"}
package/dist/commands/docs/index-generate/index.js CHANGED
@@ -6,6 +6,7 @@ import { readOatConfig, writeOatConfig } from '../../../config/oat-config.js';
6
6
  import { resolveProjectRoot } from '../../../fs/paths.js';
7
7
  import { Command, Option } from 'commander';
8
8
  import { generateIndex, renderIndex } from './generator.js';
9
+ export const GENERATED_INDEX_WARNING = '<!-- AUTOGENERATED by `oat docs generate-index`. Do not hand-edit; changes are clobbered on every `predev` / `prebuild`. -->';
9
10
  const DEFAULT_FILE_DEPS = {
10
11
  generateIndex,
11
12
  renderIndex,
@@ -18,13 +19,19 @@ const DEFAULT_DEPENDENCIES = {
18
19
  buildCommandContext,
19
20
  fileDeps: DEFAULT_FILE_DEPS,
20
21
  };
22
+ function buildGeneratedIndexOutput(content) {
23
+ if (!content) {
24
+ return GENERATED_INDEX_WARNING;
25
+ }
26
+ return `${GENERATED_INDEX_WARNING}\n\n${content}`;
27
+ }
21
28
  async function runIndexGenerate(context, options, deps) {
22
29
  const docsDir = join(context.cwd, options.docsDir);
23
30
  const outputPath = options.output
24
31
  ? join(context.cwd, options.output)
25
32
  : join(context.cwd, 'index.md');
26
33
  const entries = await deps.generateIndex(docsDir);
27
- const content = deps.renderIndex(entries);
34
+ const content = buildGeneratedIndexOutput(deps.renderIndex(entries));
28
35
  await deps.writeFile(outputPath, content, 'utf8');
29
36
  const repoRoot = await deps.resolveRepoRoot(context.cwd);
30
37
  const config = await deps.readOatConfig(repoRoot);