@open-agent-toolkit/cli 0.1.64 → 0.1.66

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 (49) hide show
  1. package/assets/agents/oat-reviewer.md +3 -2
  2. package/assets/docs/cli-utilities/backlog-lifecycle.md +2 -2
  3. package/assets/docs/cli-utilities/config-and-local-state.md +20 -6
  4. package/assets/docs/cli-utilities/tool-packs.md +1 -0
  5. package/assets/docs/cli-utilities/workflow-gates.md +3 -1
  6. package/assets/docs/contributing/code.md +18 -0
  7. package/assets/public-package-versions.json +4 -4
  8. package/assets/skills/oat-agent-instructions-analyze/SKILL.md +3 -2
  9. package/assets/skills/oat-pjm-add-backlog-item/SKILL.md +17 -72
  10. package/assets/skills/oat-project-autonomous/references/gate-inventory.md +4 -4
  11. package/assets/skills/oat-project-design/SKILL.md +88 -75
  12. package/assets/skills/oat-project-discover/SKILL.md +83 -64
  13. package/assets/skills/oat-project-document/references/docs/autonomy-contract.md +4 -4
  14. package/assets/skills/oat-project-implement/references/docs/autonomy-contract.md +4 -4
  15. package/assets/skills/oat-project-plan/SKILL.md +64 -56
  16. package/assets/skills/oat-project-pr-final/references/docs/autonomy-contract.md +4 -4
  17. package/assets/skills/oat-project-quick-start/SKILL.md +63 -55
  18. package/assets/skills/oat-project-quick-start/references/docs/autonomy-contract.md +4 -4
  19. package/assets/skills/oat-project-summary/SKILL.md +9 -4
  20. package/assets/templates/plan.md +2 -0
  21. package/dist/commands/backlog/archive.d.ts.map +1 -1
  22. package/dist/commands/backlog/archive.js +5 -5
  23. package/dist/commands/backlog/index.d.ts +4 -0
  24. package/dist/commands/backlog/index.d.ts.map +1 -1
  25. package/dist/commands/backlog/index.js +55 -0
  26. package/dist/commands/backlog/new.d.ts +27 -0
  27. package/dist/commands/backlog/new.d.ts.map +1 -0
  28. package/dist/commands/backlog/new.js +158 -0
  29. package/dist/commands/backlog/regenerate-index.d.ts.map +1 -1
  30. package/dist/commands/backlog/regenerate-index.js +42 -3
  31. package/dist/commands/decision/index.d.ts.map +1 -1
  32. package/dist/commands/decision/index.js +4 -0
  33. package/dist/commands/decision/new.d.ts +2 -0
  34. package/dist/commands/decision/new.d.ts.map +1 -1
  35. package/dist/commands/decision/new.js +4 -2
  36. package/dist/commands/doctor/index.d.ts +1 -0
  37. package/dist/commands/doctor/index.d.ts.map +1 -1
  38. package/dist/commands/doctor/index.js +3 -0
  39. package/dist/commands/doctor/stale-invocations.d.ts +3 -0
  40. package/dist/commands/doctor/stale-invocations.d.ts.map +1 -0
  41. package/dist/commands/doctor/stale-invocations.js +173 -0
  42. package/dist/commands/gate/index.d.ts +1 -0
  43. package/dist/commands/gate/index.d.ts.map +1 -1
  44. package/dist/commands/gate/index.js +5 -1
  45. package/dist/commands/project/new/scaffold.d.ts.map +1 -1
  46. package/dist/commands/project/new/scaffold.js +24 -9
  47. package/dist/commands/tools/update/index.d.ts.map +1 -1
  48. package/dist/commands/tools/update/index.js +22 -12
  49. package/package.json +2 -2
package/assets/agents/oat-reviewer.md CHANGED
@@ -304,7 +304,7 @@ Use a seconds-precision **UTC** timestamp token (`YYYY-MM-DDTHHMMSSZ`, from `dat
304
304
  - Task review: `{project}/reviews/pNN-tNN-review-YYYY-MM-DDTHHMMSSZ.md`
305
305
  - Range review: `{project}/reviews/range-review-YYYY-MM-DDTHHMMSSZ.md`
306
306
 
307
- The timestamp token must match the `oat_generated_at` frontmatter for the same run. In the unlikely event a file with that exact second already exists, append `-v2`, `-v3`, etc.
307
+ The timestamp token and `oat_generated_at` frontmatter must represent the same instant from the same `date -u` capture. The filename uses the colon-free form (`YYYY-MM-DDTHHMMSSZ`) of the frontmatter value (`YYYY-MM-DDTHH:MM:SSZ`) because colons are not filename-safe. In the unlikely event a file with that exact second already exists, append `-v2`, `-v3`, etc.
308
308
 
309
309
  **Review artifact template:**
310
310
 
@@ -396,12 +396,13 @@ Run these to verify the implementation:
396
396
  {command 1}
397
397
  {command 2}
398
398
  ```
399
- ````
400
399
 
401
400
  ## Recommended Next Step
402
401
 
403
402
  Run the `oat-project-review-receive` skill to convert findings into plan tasks.
404
403
 
404
+ ````
405
+
405
406
  ```
406
407
 
407
408
  Gate parsing contract: artifact-mode reviews, including reviews spawned by `oat gate review`, MUST include either the complete `Findings: {N} critical, {N} important, {N} medium, {N} minor` count line or the standard `## Findings` sections shown above with every severity subsection present.
package/assets/docs/cli-utilities/backlog-lifecycle.md CHANGED
@@ -42,11 +42,11 @@ oat backlog archive BL-260705-example --wont-do --summary "superseded by BL-2607
42
42
  A single `oat backlog archive` run performs the whole close-out so its parts cannot drift apart:
43
43
 
44
44
  1. Sets the terminal `status` (`closed` by default, `wont_do` with `--wont-do`) and stamps `updated`.
45
- 2. Appends a canonical newest-first entry to `completed.md`. `closed` items always get an entry (with a visible `TODO: summarize outcome` placeholder when `--summary` is omitted, so the gap stays visible); `wont_do` items get one only when you pass `--summary`.
45
+ 2. Validates and trims a nonblank `--summary` before mutating a `closed` item, then appends its canonical newest-first `completed.md` entry. `wont_do` items may omit the summary and get an entry only when one is provided.
46
46
  3. Moves `items/<id>.md` into `archived/` — with `git mv` inside a work tree, or a plain rename outside git.
47
47
  4. Regenerates the managed backlog index.
48
48
 
49
- The command is safe to re-run: an item already in `archived/` produces a no-op warning with no writes. An out-of-enum current status (for example a hand-set `done`) is a hard error that names the file, lists the valid statuses, and tells you how to recover. See the [command reference](config-and-local-state.md#oat-backlog-archive) for exit codes and the `--json` payload.
49
+ The command is safe to re-run: an item already in `archived/` produces a no-op warning with no writes. A missing closed-item summary or an out-of-enum current status (for example a hand-set `done`) is a hard error before mutation and includes recovery guidance. See the [command reference](config-and-local-state.md#oat-backlog-archive) for exit codes and the `--json` payload.
50
50
 
51
51
  ## Catching lifecycle drift
52
52
 
package/assets/docs/cli-utilities/config-and-local-state.md CHANGED
@@ -14,6 +14,7 @@ Use these commands when you need operational support around the toolkit rather t
14
14
  Use the `oat backlog` group when you want direct CLI support for the file-backed backlog under `.oat/repo/pjm/backlog/`.
15
15
 
16
16
  - `oat backlog init` - scaffold `.oat/repo/pjm/backlog/` with starter files and directories for a fresh repo
17
+ - `oat backlog new <title>` - validate and create a file-backed backlog item from the canonical template, then regenerate the managed index
17
18
  - `oat backlog generate-id <title>` - generate a deterministic `BL-YYMMDD-slug` backlog ID from a title
18
19
  - `oat backlog generate-id <title> --created-at <timestamp>` - generate a reproducible ID for a known creation timestamp
19
20
  - `oat backlog archive <id>` - atomic close-out: set a terminal status, record the completion in `completed.md`, move the item into `archived/`, and regenerate the index in one step
@@ -21,10 +22,18 @@ Use the `oat backlog` group when you want direct CLI support for the file-backed
21
22
 
22
23
  Backlog IDs are deterministic date+slug identifiers (`BL-YYMMDD-slug`) derived from the creation date and title, so two machines or worktrees produce the same ID for the same record without scanning the local checkout. The slug is capped at 30 characters at the last whole-word boundary (with trailing stop-words trimmed), so prefer concise, meaningful titles. Index regeneration is deterministic and safe to re-run when resolving an index merge conflict.
23
24
 
24
- Run `oat backlog init` first when the local backlog scaffold does not exist yet in a fresh repo. This command group is primarily used by the `oat-pjm-*` project-management skills, but it is also available directly when you need to inspect or repair backlog metadata by hand.
25
+ Run `oat backlog init` directly when you need to create or repair only the backlog scaffold. `oat backlog new` initializes a missing scaffold automatically after validating its inputs. This command group is primarily used by the `oat-pjm-*` project-management skills, but it is also available directly when you need to inspect or repair backlog metadata by hand.
25
26
 
26
27
  For the end-to-end states an item moves through — and how `oat backlog archive` and `oat pjm doctor` keep the backlog honest — see [Backlog Lifecycle](backlog-lifecycle.md).
27
28
 
29
+ ### `oat backlog new`
30
+
31
+ `oat backlog new <title> [--priority <priority>] [--scope <scope>] [--scope-estimate <size>] [--labels <labels>] [--description <text>] [--backlog-root <path>]` creates one active item and refreshes the managed backlog index.
32
+
33
+ Defaults are `priority: medium` and `scope: task`. Valid priorities are `urgent`, `high`, `medium`, `low`, and `none`; valid scopes are `idea`, `task`, `feature`, and `initiative`; scope estimates accept `XS`, `S`, `M`, `L`, `XL`, or `XXL`. Pass labels as a comma-delimited list.
34
+
35
+ The command validates all inputs before creating the scaffold or writing an item. It uses the repo-local canonical backlog template when available, falls back to the CLI's bundled template, writes structured YAML frontmatter, and rejects an ID collision in either `items/` or `archived/` without overwriting the existing record. If managed-index regeneration fails after the item write, OAT removes only the new item and restores the prior index.
36
+
28
37
  ### `oat backlog archive`
29
38
 
30
39
  `oat backlog archive <id> [--wont-do] [--summary <text>] [--json] [--backlog-root <path>]` performs the full close-out for a backlog item so status flip, completed-log entry, file move, and index regeneration never drift apart.
@@ -33,22 +42,23 @@ For the end-to-end states an item moves through — and how `oat backlog archive
33
42
 
34
43
  - `<id>` (required) - the backlog item id (`BL-YYMMDD-slug`); the item file must live under `items/`.
35
44
  - `--wont-do` - close the item as `wont_do` instead of the default terminal status `closed`.
36
- - `--summary <text>` - one-line outcome summary recorded in `completed.md`.
45
+ - `--summary <text>` - one-line outcome summary recorded in `completed.md`; required and nonblank for the default `closed` path.
37
46
  - `--backlog-root <path>` - override the backlog root (defaults to `.oat/repo/pjm/backlog`).
38
47
  - `--json` - emit the machine-readable result payload instead of human log lines.
39
48
 
40
49
  **Behavior:**
41
50
 
42
51
  - Validates the item's current `status` against the enum (`open | in_progress | closed | wont_do`); an out-of-enum value such as `done` is a hard error with a fix hint. Archiving is legal from any valid status — a `closed` item still in `items/` just gets its move finished.
52
+ - For the default `closed` path, validates and trims a nonblank `--summary` before any file or index mutation. The `wont_do` path may omit the summary and completion-ledger entry.
43
53
  - Rewrites only the `status:` and `updated:` frontmatter lines (preserving any inline enum comment), then moves the item from `items/` to `archived/` with `git mv` inside a work tree, falling back to a plain rename (with a warning) outside git or if `git mv` fails.
44
- - `closed` archives always append a canonical newest-first `completed.md` entry (`YYYY-MM-DD — <id> — Title — summary`); when `--summary` is omitted the entry carries a visible `TODO: summarize outcome` placeholder. `wont_do` archives append an entry only when `--summary` is provided. A missing `completed.md` is scaffolded from the starter template; a missing `## Completed Items` heading is scaffolded with a warning.
54
+ - `closed` archives append a canonical newest-first `completed.md` entry (`YYYY-MM-DD — <id> — Title — summary`). `wont_do` archives append an entry only when `--summary` is provided. A missing `completed.md` is scaffolded from the starter template; a missing `## Completed Items` heading is scaffolded with a warning.
45
55
  - Regenerates the managed backlog index after the move.
46
56
  - Idempotent: re-running on an item already in `archived/` is a no-op warning with no writes.
47
57
 
48
58
  **Exit codes:**
49
59
 
50
60
  - `0` - item archived, or already-archived no-op.
51
- - `1` - actionable error: unknown id (no file under `items/`) or an out-of-enum current status. The message names the file path, the valid statuses, and the fix.
61
+ - `1` - actionable error: unknown id, out-of-enum current status, duplicate active/archived ID, or a missing closed-item summary. The message includes the recovery action.
52
62
  - `2` - reserved for unexpected system/runtime failures.
53
63
 
54
64
  **JSON payload (`--json`):**
@@ -76,10 +86,12 @@ For full project-management repo-reference setup, use [`oat pjm init`](tool-pack
76
86
  Use the `oat decision` group for file-per-record decisions under `.oat/repo/reference/decisions/`. Each decision is its own file with a deterministic `DR-YYMMDD-slug` ID (the slug is capped at 30 characters at the last whole-word boundary, with trailing stop-words trimmed), and the human-facing index is a committed generated view.
77
87
 
78
88
  - `oat decision init` - scaffold `.oat/repo/reference/decisions/` and the managed decision index
79
- - `oat decision new <title>` - create a new decision record; supports `--status`, `--context`, and `--created-at`
89
+ - `oat decision new <title>` - create a new decision record; supports `--status`, `--context`, `--decision`, `--consequences`, and `--created-at`
80
90
  - `oat decision regenerate-index` - rebuild the managed decision index table from record frontmatter
81
91
  - `oat decision migrate` - convert a legacy single `decision-record.md` into file-per-record decisions, preserving each old `ADR-NNN`/`DR-NNN` ID as `legacy_id`; applies by default, so pass `--dry-run` to preview the legacy-to-new mappings without writing, and `--delete-legacy` to remove the source file after a verified migration (unlike `oat pjm migrate`, which defaults to dry-run)
82
92
 
93
+ Pass `--context`, `--decision`, and `--consequences` together when creating a resolved decision so every substantive template section is complete in the same atomic creation step. Callers that omit them retain the template's placeholder content for later editing.
94
+
83
95
  The decision index uses managed marker pairs and is deterministic, so an index merge conflict can be resolved by re-running `oat decision regenerate-index` and staging the result. Decision records replace the legacy single `decision-record.md`; repos still on the old layout migrate with `oat decision migrate` (or the broader `oat pjm migrate`).
84
96
 
85
97
  ## `oat local ...`
@@ -239,4 +251,6 @@ For the full state model, repair semantics, and examples, see [Instruction Sync]
239
251
  - `oat internal validate-oat-skills` - validate `oat-*` skill contracts and metadata
240
252
  - `oat doctor` - run environment and setup diagnostics, including installed-vs-bundled skill version checks
241
253
 
242
- `oat doctor` is the quickest way to confirm that your runtime, directory structure, and installed OAT assets are healthy before deeper debugging. The `/oat-doctor` skill (installed via the core pack) provides richer diagnostics with check and summary modes, including config explanations sourced from bundled documentation.
254
+ `oat doctor` is the quickest way to confirm that your runtime, directory structure, and installed OAT assets are healthy before deeper debugging. At project scope it also scans bounded repository script and documentation surfaces for known-stale CLI grammar, such as `oat --scope all sync`, and reports file/line evidence plus the current `oat sync --scope all` form. Generated provider views, OAT lifecycle artifacts, archived content, dependencies, build output, and nested worktrees are excluded.
255
+
256
+ The `/oat-doctor` skill (installed via the core pack) provides richer diagnostics with check and summary modes, including config explanations sourced from bundled documentation.
package/assets/docs/cli-utilities/tool-packs.md CHANGED
@@ -171,6 +171,7 @@ Purpose:
171
171
  Key behavior:
172
172
 
173
173
  - Accepts a tool name, `--pack <pack>`, or `--all` (mutually exclusive)
174
+ - With no target, exits without mutation and suggests the explicit bulk command `oat tools update --all`; invalid packs and conflicting targets keep their own targeted diagnostics
174
175
  - Compares installed versions against bundled versions and copies updated assets
175
176
  - For `--pack <pack>` and `--all`, an already-installed pack is reconciled to include newly added bundled skills or agents in that same scope
176
177
  - Pack-targeted updates intentionally rewrite bundled template and script companions in place, even when the pack's installed skills are already current
package/assets/docs/cli-utilities/workflow-gates.md CHANGED
@@ -451,7 +451,9 @@ By default the dispatcher:
451
451
  5. Applies `--avoid same-family`.
452
452
  6. Checks candidate availability in descending priority order, with target id as
453
453
  the tie-breaker.
454
- 7. Runs the chosen `baseCommand` with the selected model and prompt appended.
454
+ 7. Runs the chosen `baseCommand` with the selected model and prompt appended. The
455
+ prompt is carried in argv, stdin is closed, and stdout/stderr remain captured
456
+ for diagnostics and liveness tracking.
455
457
  8. Exits with the child process status.
456
458
 
457
459
  Use `--target <id>` to pin one target and skip detection/avoidance:
package/assets/docs/contributing/code.md CHANGED
@@ -96,6 +96,24 @@ not the steady-state path.
96
96
  - Make verification explicit in commit-adjacent notes or review artifacts.
97
97
  - If docs behavior changes, update the docs surface in the same change window.
98
98
 
99
+ ### Breaking CLI grammar changes
100
+
101
+ When a command, option name, or option placement changes, make the migration visible to both reviewers and release-note readers:
102
+
103
+ - Use a `BREAKING:` PR title or prominent callout so generated release notes retain the warning.
104
+ - Include the old and new copy-pasteable commands.
105
+ - State the migration action for scripts, docs, and automation that use the old grammar.
106
+
107
+ For example:
108
+
109
+ **Breaking change title/callout:** `BREAKING: move scope after the sync command`
110
+
111
+ **Before:** `oat --scope all sync` <!-- oat-doctor: allow-stale-invocation -->
112
+
113
+ **After:** `oat sync --scope all`
114
+
115
+ **Migration action:** Update repository scripts and documentation, then run `oat doctor --scope project` to find known-stale invocations.
116
+
99
117
  ## Related Guides
100
118
 
101
119
  - [Contributing Docs](documentation.md)
package/assets/public-package-versions.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
- "cli": "0.1.64",
3
- "docs-config": "0.1.64",
4
- "docs-theme": "0.1.64",
5
- "docs-transforms": "0.1.64"
2
+ "cli": "0.1.66",
3
+ "docs-config": "0.1.66",
4
+ "docs-theme": "0.1.66",
5
+ "docs-transforms": "0.1.66"
6
6
  }
package/assets/skills/oat-agent-instructions-analyze/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: oat-agent-instructions-analyze
3
- version: 1.11.0
3
+ version: 1.11.1
4
4
  description: Run when you need to evaluate agent instruction file coverage, quality, and drift. Produces a severity-rated analysis artifact. Run before oat-agent-instructions-apply to identify what needs improvement.
5
5
  disable-model-invocation: true
6
6
  user-invocable: true
@@ -405,7 +405,8 @@ PACKS_DIR="${BUNDLE_DIR}/packs"
405
405
  mkdir -p "$PACKS_DIR"
406
406
  ```
407
407
 
408
- Fill in all template sections with findings from Steps 2-7.
408
+ Fill in all template sections with findings from Steps 2–7, including Step
409
+ 3.5's existing-rule validation.
409
410
 
410
411
  Write the human-readable markdown artifact to `$ARTIFACT_PATH`.
411
412
 
package/assets/skills/oat-pjm-add-backlog-item/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: oat-pjm-add-backlog-item
3
- version: 1.3.0
3
+ version: 1.3.1
4
4
  description: Use when the user requests or confirms adding a new repo backlog item — e.g. "add a backlog item for X", "capture that as backlog", "track that follow-up", "file a backlog ticket", or confirms a previously offered backlog capture. Do NOT auto-invoke when a follow-up is mentioned. Creates the item file in the file-per-item backlog structure, regenerates the index, and prompts for curated overview updates.
5
5
  disable-model-invocation: false
6
6
  user-invocable: true
@@ -29,8 +29,8 @@ When executing this skill, provide lightweight progress feedback so the user can
29
29
 
30
30
  - Before multi-step work, print short step indicators, e.g.:
31
31
  - `[1/4] Resolving item details…`
32
- - `[2/4] Generating ID + populating template…`
33
- - `[3/4] Regenerating backlog index…`
32
+ - `[2/4] Creating the item + managed index atomically…`
33
+ - `[3/4] Enriching acceptance criteria…`
34
34
  - `[4/4] Updating curated overview guidance…`
35
35
 
36
36
  ## Process
@@ -47,85 +47,30 @@ Collect the item details from the user or surrounding context:
47
47
  If the title is missing, ask the user.
48
48
  If the description is missing, ask for 1-3 sentences of context.
49
49
 
50
- ### Step 2: Ensure Backlog Scaffold
50
+ Propose an initial scope estimate (`XS`, `S`, `M`, `L`, `XL`, or `XXL`) from the described work, then ask the user to confirm or adjust it before creation.
51
51
 
52
- Before generating IDs or editing backlog files, run:
52
+ ### Step 2: Create the Backlog Item Atomically
53
53
 
54
- ```bash
55
- oat backlog init
56
- ```
57
-
58
- This command is idempotent. Use it even in existing repos so the canonical backlog scaffold and exact managed index markers are present before `oat backlog regenerate-index` runs.
59
-
60
- Do not hand-create the managed marker block in `backlog/index.md`. The scaffold writes the exact markers required by the CLI:
61
-
62
- ```md
63
- <!-- OAT BACKLOG-INDEX -->
64
- <!-- END OAT BACKLOG-INDEX -->
65
- ```
66
-
67
- ### Step 3: Generate ID
68
-
69
- Run:
70
-
71
- ```bash
72
- oat backlog generate-id "{title}"
73
- ```
74
-
75
- The CLI returns a deterministic `BL-YYMMDD-slug` value derived from the creation date and the title. It performs no scan, hash, counter, or random allocation.
76
-
77
- If the command reports a same-day same-slug filename collision against an existing `items/<id>.md` or `archived/<id>.md`, do not overwrite the existing record. Disambiguate by using a more specific title and re-running `oat backlog generate-id`.
78
-
79
- ### Step 4: Prepare Output Path
80
-
81
- Set the output path using the returned ID so the filename stem equals the ID:
54
+ Run the single creation command with the confirmed values:
82
55
 
83
56
  ```bash
84
- ITEM_PATH=".oat/repo/pjm/backlog/items/{id}.md"
57
+ oat backlog new "{title}" --priority "<priority>" --scope "<scope>" --scope-estimate "<confirmed-scope-estimate>" --labels "<comma-delimited-labels>" --description "<description>"
85
58
  ```
86
59
 
87
- ### Step 5: Copy Template and Fill Frontmatter
88
-
89
- 1. Use `.oat/templates/backlog-item.md` as the source template.
90
- 2. Fill:
91
- - `id`
92
- - `title`
93
- - `created`
94
- - `updated`
95
- - `status` (default `open`)
96
- - `priority` (default `medium` unless the user says otherwise)
97
- - `scope` (default `task` unless the user says otherwise)
98
- - `labels`
99
- - `assignee`
100
- - `associated_issues`
101
- - `external_plans` (initialize to `[]`; `oat-repo-improve` owns later reverse-link additions)
102
- 3. Keep `external_plans` as a YAML string array of repo-relative paths under `.oat/repo/reference/external-plans/`. Do not pre-populate it from discussion or anticipated work.
103
- 4. The agent should propose an initial `scope_estimate` based on the described work, then ask the user to confirm or adjust it.
104
- 5. Write the item body with:
105
- - `## Description`
106
- - `## Acceptance Criteria`
107
-
108
- ### Step 6: Write the Backlog Item
109
-
110
- Write the completed file to the path resolved in Step 4:
60
+ The command validates all inputs, initializes the scaffold when needed, generates and collision-checks the `BL-YYMMDD-slug` ID, renders the canonical template, writes the item, and regenerates the managed index. If it reports a collision, do not overwrite the existing active or archived record; use a more specific title and rerun the same command.
111
61
 
112
- ```bash
113
- .oat/repo/pjm/backlog/items/{id}.md
114
- ```
115
-
116
- Use the template field order from `.oat/templates/backlog-item.md`.
62
+ Use the item path and ID reported by the command. Do not hand-author frontmatter or edit the managed index block. The command initializes `external_plans: []`; `oat-repo-improve` owns later reverse-link additions.
117
63
 
118
- ### Step 7: Regenerate Managed Index
64
+ ### Step 3: Enrich Acceptance Criteria
119
65
 
120
- Run:
66
+ Read the created item and replace only the placeholder bullets under `## Acceptance Criteria` with the acceptance criteria confirmed in Step 1. Preserve the command-generated frontmatter and description. This post-create enrichment is safe because Acceptance Criteria are not index-visible fields.
121
67
 
122
- ```bash
123
- oat backlog regenerate-index
124
- ```
68
+ The item must retain both required body sections:
125
69
 
126
- This refreshes the managed table inside `.oat/repo/pjm/backlog/index.md`.
70
+ - `## Description`
71
+ - `## Acceptance Criteria`
127
72
 
128
- ### Step 8: Update Curated Overview
73
+ ### Step 4: Update Curated Overview
129
74
 
130
75
  Read `.oat/repo/pjm/backlog/index.md` and update the `## Curated Overview` section with a brief human-written note when helpful, for example:
131
76
 
@@ -135,7 +80,7 @@ Read `.oat/repo/pjm/backlog/index.md` and update the `## Curated Overview` secti
135
80
 
136
81
  Do not edit inside the managed marker section.
137
82
 
138
- ### Step 9: Summarize to the User
83
+ ### Step 5: Summarize to the User
139
84
 
140
85
  Report:
141
86
 
@@ -151,5 +96,5 @@ Report:
151
96
  - Item includes populated frontmatter and both required body sections
152
97
  - Item initializes `external_plans: []` for future reverse links
153
98
  - `scope_estimate` was proposed and confirmed
154
- - `oat backlog regenerate-index` ran successfully
99
+ - `oat backlog new` created the item and regenerated the managed index successfully
155
100
  - `.oat/repo/pjm/backlog/index.md` remains valid, with managed section untouched except by regeneration
package/assets/skills/oat-project-autonomous/references/gate-inventory.md CHANGED
@@ -218,12 +218,12 @@ remains immutable baseline evidence for the original p01-t01 verification.
218
218
  | Skill root / file | Stable prompt-site mappings |
219
219
  | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
220
220
  | `oat-project-new/SKILL.md` | `f7ca8635452f -> NG`; `b137f73db20c -> NEW-01`; `45b699c1c0b5 -> NEW-01`; `ba6d120791c1 -> NEW-01`; `33ce6a6c30aa -> NEW-02`; `0f5a90f34f63 -> NG`; `d0ea3a91261d -> NG` |
221
- | `oat-project-quick-start/SKILL.md` | `f7ca8635452f -> NG`; `c493a38b89f2 -> QS-04`; `655d61df0a8f -> NG`; `b137f73db20c -> QS-01`; `45b699c1c0b5 -> QS-01`; `ba6d120791c1 -> QS-01`; `1a5ee85164ff -> QS-02`; `af8e2bea90d7 -> QS-04`; `a823cf5aeaec -> QS-04`; `7753dc323083 -> QS-04`; `1f557da5e03c -> QS-04`; `0960c3eb1564 -> NG`; `c24787334ade -> QS-05`; `021ba03c82c5 -> QS-05`; `5d1a9d1b661d -> QS-05`; `318f304ee3b3 -> QS-05`; `cc700d4d2cab -> QS-05`; `7ef6aa642400 -> QS-05`; `4d389b234556 -> QS-05`; `84c506dac106 -> QS-05`; `caf7622a2e02 -> QS-05`; `8917190b2e98 -> QS-06`; `5a028d846aa5 -> QS-06`; `b1d92192b8ca -> QS-06`; `bdbb18955cc4 -> QS-06`; `6d159a2e8f8e -> QS-06`; `61a9849f4dfc -> QS-06`; `31cb92052ea6 -> QS-06`; `39e3fe23dd85 -> QS-07`; `2cb069a2590b -> NG`; `fd0aff270853 -> NG`; `a114b27f8b4b -> NG`; `77dc8e1b728a -> QS-08`; `d3e3fba65b96 -> QS-09`; `71c2a0ba99bf -> QS-09`; `f47f9f9c0d03 -> QS-09`; `224a4b43fb29 -> QS-10`; `744f130d4116 -> QS-12`; `bee4c4aa34c6 -> NG`; `3f0b53056edd -> QS-12`; `857e91aa3095 -> NG` |
221
+ | `oat-project-quick-start/SKILL.md` | `f7ca8635452f -> NG`; `c493a38b89f2 -> QS-04`; `655d61df0a8f -> NG`; `b137f73db20c -> QS-01`; `45b699c1c0b5 -> QS-01`; `ba6d120791c1 -> QS-01`; `1a5ee85164ff -> QS-02`; `af8e2bea90d7 -> QS-04`; `a823cf5aeaec -> QS-04`; `7753dc323083 -> QS-04`; `1f557da5e03c -> QS-04`; `0960c3eb1564 -> NG`; `c24787334ade -> QS-05`; `021ba03c82c5 -> QS-05`; `5d1a9d1b661d -> QS-05`; `318f304ee3b3 -> QS-05`; `cc700d4d2cab -> QS-05`; `7ef6aa642400 -> QS-05`; `4d389b234556 -> QS-05`; `84c506dac106 -> QS-05`; `caf7622a2e02 -> QS-05`; `8917190b2e98 -> QS-06`; `5a028d846aa5 -> QS-06`; `b1d92192b8ca -> QS-06`; `bdbb18955cc4 -> QS-06`; `6d159a2e8f8e -> QS-06`; `61a9849f4dfc -> QS-06`; `31cb92052ea6 -> QS-06`; `39e3fe23dd85 -> QS-07`; `2cb069a2590b -> NG`; `fd0aff270853 -> NG`; `a114b27f8b4b -> NG`; `77dc8e1b728a -> QS-08`; `d3e3fba65b96 -> QS-09`; `71c2a0ba99bf -> QS-09`; `f47f9f9c0d03 -> QS-09`; `224a4b43fb29 -> QS-10`; `744f130d4116 -> QS-12`; `bee4c4aa34c6 -> NG`; `3f0b53056edd -> QS-12`; `857e91aa3095 -> NG`; `b4af2220eb91 -> QS-12` |
222
222
  | `oat-project-quick-start/references/docs/autonomy-contract.md` | `* -> NG` |
223
- | `oat-project-discover/SKILL.md` | `8fe35bbfbcd6 -> NG`; `6acc57686847 -> NG`; `4df56b83b98e -> NG`; `660fcdb9dd0d -> NG`; `655d61df0a8f -> NG`; `302f5a4e2f7e -> DISC-03`; `8ee1861bb37c -> DISC-03`; `5c8d5f04f6e2 -> DISC-05`; `73964bb042ab -> DISC-05`; `82cc79370b80 -> DISC-05`; `ff09e8f7774f -> DISC-06`; `323e71dca05d -> DISC-06`; `012bab5b478e -> DISC-06`; `523764981692 -> DISC-06`; `7eaa40e078b9 -> DISC-07`; `b57408be1e7b -> DISC-07`; `4683ea4a7d2f -> DISC-07`; `1195a16a0bc5 -> NG`; `d20eb00f1887 -> DISC-08`; `3f0b53056edd -> DISC-08`; `b92484ef7ca4 -> DISC-08`; `3cf10a406501 -> DISC-08` |
224
- | `oat-project-design/SKILL.md` | `d942bb5a75dc -> NG`; `5eb3949f32e1 -> NG`; `8bdedbff2084 -> NG`; `655d61df0a8f -> NG`; `cf317c17c586 -> DES-01`; `2fd9e4306093 -> NG`; `30aaa490f54f -> NG`; `5d39260a7350 -> DES-03`; `925238b3a9b8 -> DES-03`; `f44832c14f8f -> DES-03`; `7f6ed9174a80 -> DES-03`; `ea8a45cff484 -> DES-03`; `ae06e7f3590d -> DES-03`; `ad9715bfa9b5 -> DES-03`; `235f4eba81d9 -> DES-03`; `86d15c022ff2 -> DES-03`; `c08ee2c84186 -> DES-03`; `bd3ee332d171 -> DES-03`; `ec88b585a24d -> DES-03`; `a9595a6486f1 -> DES-04`; `accb06cd6f3c -> DES-04`; `806001c2c365 -> DES-04`; `696587b33f1e -> DES-04`; `8678cdb975d0 -> NG`; `8ad2a4dc63d2 -> DES-05`; `33cc7540d89e -> DES-05`; `51a2b698ba14 -> DES-05`; `81085592cc91 -> DES-05`; `74b952cc1121 -> DES-05`; `da7551391a41 -> DES-05`; `02c93ec05a4a -> DES-06`; `6864967fd8a4 -> DES-06`; `84e9be719156 -> DES-06`; `7ed89c44264b -> DES-06`; `dc7ba56c1cd4 -> DES-06`; `57ccefb935bf -> DES-06`; `9d27238332b2 -> NG`; `a0c758ab26aa -> NG`; `0e17c1a2de0b -> DES-07`; `e9ea8625567c -> DES-07`; `908e710e7304 -> DES-07`; `38a0adf2dcd6 -> DES-07`; `16c2036990df -> DES-07`; `b23bbe0c4282 -> DES-07`; `71972778f6b8 -> DES-07`; `7f88caab1f38 -> DES-07`; `7eb6f3a2d666 -> DES-07`; `e7a364820674 -> DES-07`; `241de26a0b0b -> DES-07`; `9d7a898331a3 -> DES-07`; `686152516d78 -> DES-07`; `8ca3cff907f3 -> DES-07`; `13e6349960fb -> DES-07`; `fd3d71fade25 -> DES-07`; `8daa828dfad0 -> NG`; `d20eb00f1887 -> DES-08`; `3f0b53056edd -> DES-08`; `b92484ef7ca4 -> DES-08`; `3cf10a406501 -> DES-08`; `033fb711de49 -> NG` |
223
+ | `oat-project-discover/SKILL.md` | `8fe35bbfbcd6 -> NG`; `6acc57686847 -> NG`; `4df56b83b98e -> NG`; `660fcdb9dd0d -> NG`; `655d61df0a8f -> NG`; `302f5a4e2f7e -> DISC-03`; `8ee1861bb37c -> DISC-03`; `5c8d5f04f6e2 -> DISC-05`; `73964bb042ab -> DISC-05`; `82cc79370b80 -> DISC-05`; `ff09e8f7774f -> DISC-06`; `323e71dca05d -> DISC-06`; `012bab5b478e -> DISC-06`; `523764981692 -> DISC-06`; `7eaa40e078b9 -> DISC-07`; `b57408be1e7b -> DISC-07`; `4683ea4a7d2f -> DISC-07`; `04454a79d998 -> DISC-08`; `54444ee79fc8 -> DISC-08`; `dd3b5d3d6424 -> DISC-08`; `f64efa435cb2 -> DISC-08`; `1f802b9bc5ad -> DISC-08`; `3fad0405b2bc -> NG`; `2eeba46b7d76 -> DISC-08` |
224
+ | `oat-project-design/SKILL.md` | `d942bb5a75dc -> NG`; `5eb3949f32e1 -> NG`; `8bdedbff2084 -> NG`; `655d61df0a8f -> NG`; `cf317c17c586 -> DES-01`; `2fd9e4306093 -> NG`; `30aaa490f54f -> NG`; `5d39260a7350 -> DES-03`; `925238b3a9b8 -> DES-03`; `f44832c14f8f -> DES-03`; `7f6ed9174a80 -> DES-03`; `ea8a45cff484 -> DES-03`; `ae06e7f3590d -> DES-03`; `ad9715bfa9b5 -> DES-03`; `235f4eba81d9 -> DES-03`; `86d15c022ff2 -> DES-03`; `c08ee2c84186 -> DES-03`; `bd3ee332d171 -> DES-03`; `ec88b585a24d -> DES-03`; `a9595a6486f1 -> DES-04`; `accb06cd6f3c -> DES-04`; `806001c2c365 -> DES-04`; `696587b33f1e -> DES-04`; `8678cdb975d0 -> NG`; `8ad2a4dc63d2 -> DES-05`; `33cc7540d89e -> DES-05`; `51a2b698ba14 -> DES-05`; `81085592cc91 -> DES-05`; `74b952cc1121 -> DES-05`; `da7551391a41 -> DES-05`; `02c93ec05a4a -> DES-06`; `6864967fd8a4 -> DES-06`; `84e9be719156 -> DES-06`; `7ed89c44264b -> DES-06`; `dc7ba56c1cd4 -> DES-06`; `57ccefb935bf -> DES-06`; `9d27238332b2 -> NG`; `a0c758ab26aa -> NG`; `0e17c1a2de0b -> DES-07`; `e9ea8625567c -> DES-07`; `908e710e7304 -> DES-07`; `38a0adf2dcd6 -> DES-07`; `16c2036990df -> DES-07`; `b23bbe0c4282 -> DES-07`; `71972778f6b8 -> DES-07`; `7f88caab1f38 -> DES-07`; `7eb6f3a2d666 -> DES-07`; `e7a364820674 -> DES-07`; `241de26a0b0b -> DES-07`; `9d7a898331a3 -> DES-07`; `686152516d78 -> DES-07`; `bd3ad56d6265 -> DES-08`; `a19d9c6d7b42 -> DES-08`; `3af5412588ba -> DES-08`; `a0f1c66507d0 -> DES-08`; `a97364c2ca8b -> DES-08`; `4725e333dea4 -> DES-07`; `595d3a64c0f4 -> DES-07`; `57923a130802 -> DES-07`; `7d8fdfb4ca6f -> NG`; `033fb711de49 -> NG`; `d30bb6464138 -> DES-08` |
225
225
  | `oat-project-design/references/selective-review-pass.md` | `d4956192b82e -> DES-06`; `7d6e1f926ecb -> DES-06`; `04f918a5fcac -> DES-07` |
226
- | `oat-project-plan/SKILL.md` | `5eb3949f32e1 -> NG`; `64a08153bb9e -> NG`; `655d61df0a8f -> NG`; `56b37486f09d -> PLAN-01`; `cf317c17c586 -> PLAN-02`; `781643b0f2c3 -> NG`; `01fd7cca8253 -> PLAN-04`; `7bc7fa3f2cbb -> NG`; `da28ce0a5f2e -> NG`; `e334f94c4d35 -> NG`; `1fa55762c038 -> NG`; `c0935b5484a2 -> NG`; `6008163054f8 -> PLAN-05`; `571271f4d71b -> PLAN-06`; `746b760289e4 -> PLAN-06`; `de195590ff83 -> NG`; `49640510829a -> PLAN-07`; `4bef7afa7a71 -> PLAN-08`; `e5886632533e -> PLAN-08`; `4cfe1df14372 -> NG`; `71d18f57db67 -> PLAN-10`; `9b6ef603b0b9 -> PLAN-10`; `bee4c4aa34c6 -> NG`; `3f0b53056edd -> PLAN-11`; `1734b2c85c5d -> NG` |
226
+ | `oat-project-plan/SKILL.md` | `5eb3949f32e1 -> NG`; `64a08153bb9e -> NG`; `655d61df0a8f -> NG`; `56b37486f09d -> PLAN-01`; `cf317c17c586 -> PLAN-02`; `781643b0f2c3 -> NG`; `01fd7cca8253 -> PLAN-04`; `7bc7fa3f2cbb -> NG`; `da28ce0a5f2e -> NG`; `e334f94c4d35 -> NG`; `1fa55762c038 -> NG`; `c0935b5484a2 -> NG`; `6008163054f8 -> PLAN-05`; `571271f4d71b -> PLAN-06`; `746b760289e4 -> PLAN-06`; `de195590ff83 -> NG`; `49640510829a -> PLAN-07`; `4bef7afa7a71 -> PLAN-08`; `e5886632533e -> PLAN-08`; `4cfe1df14372 -> NG`; `d116c97a500c -> PLAN-10`; `aa62facff547 -> PLAN-10`; `bee4c4aa34c6 -> NG`; `3f0b53056edd -> PLAN-11`; `1734b2c85c5d -> NG`; `b4af2220eb91 -> PLAN-11` |
227
227
  | `oat-project-import-plan/SKILL.md` | `f7ca8635452f -> NG`; `c2e5fa410069 -> NG`; `655d61df0a8f -> NG`; `b137f73db20c -> IMPORT-01`; `45b699c1c0b5 -> IMPORT-01`; `ba6d120791c1 -> IMPORT-01`; `070ebc5259af -> IMPORT-03`; `c11552696e2e -> IMPORT-03`; `cfe661966baf -> IMPORT-04`; `baa91c0a0bf8 -> NG`; `e364e84b2702 -> NG`; `39031985a945 -> IMPORT-06`; `f106aa29a217 -> IMPORT-07`; `65038450aee3 -> IMPORT-07`; `bee4c4aa34c6 -> NG`; `3f0b53056edd -> IMPORT-09` |
228
228
  | `oat-project-implement/SKILL.md` | `c6732295bc8c -> NG`; `ffb3af0ba8ef -> NG`; `e0355c7a05e9 -> IMPLEMENT-11+IMPLEMENT-13+IMPLEMENT-16`; `6296f41ae11c -> NG`; `a167d03559fa -> NG`; `cf317c17c586 -> IMPLEMENT-01`; `8ce8a09feca4 -> NG` |
229
229
  | `oat-project-implement/references/completion-and-closeout.md` | `105600fbd045 -> IMPLEMENT-11`; `3e6055aede6c -> IMPLEMENT-11`; `0705f7533039 -> IMPLEMENT-11`; `0c39746f3cb5 -> IMPLEMENT-11`; `14d89fe39c8c -> IMPLEMENT-11`; `378a75543a72 -> IMPLEMENT-11`; `c7b25627e674 -> IMPLEMENT-11`; `51ef9a453323 -> IMPLEMENT-11`; `c67145e3fb00 -> IMPLEMENT-11`; `64fbeac64811 -> IMPLEMENT-11`; `19b13c17bddb -> NG`; `f7dab9c1f96c -> IMPLEMENT-12`; `c69c17a069a8 -> IMPLEMENT-14`; `a97fa5634a68 -> IMPLEMENT-14`; `3af58881811c -> IMPLEMENT-14`; `4203e1f49d0f -> IMPLEMENT-14`; `c3bd2458a3d3 -> IMPLEMENT-13`; `95b5eafc070d -> IMPLEMENT-13`; `25ecbe9c998b -> IMPLEMENT-13+IMPLEMENT-14+IMPLEMENT-15+IMPLEMENT-16`; `f6f24fd71da4 -> IMPLEMENT-13+IMPLEMENT-14+IMPLEMENT-15+IMPLEMENT-16`; `f18283bc1cf9 -> IMPLEMENT-13+IMPLEMENT-14+IMPLEMENT-15+IMPLEMENT-16`; `2c1ffc4a82dd -> IMPLEMENT-13+IMPLEMENT-14+IMPLEMENT-15+IMPLEMENT-16`; `3454a07aa843 -> IMPLEMENT-16`; `0d86e2098cfb -> IMPLEMENT-13+IMPLEMENT-14+IMPLEMENT-15+IMPLEMENT-16`; `d5fe597d266f -> IMPLEMENT-13+IMPLEMENT-14+IMPLEMENT-15+IMPLEMENT-16`; `55a152e944c1 -> IMPLEMENT-16`; `effac7cbd573 -> IMPLEMENT-13+IMPLEMENT-14+IMPLEMENT-15+IMPLEMENT-16`; `9d2a34d8b148 -> IMPLEMENT-13+IMPLEMENT-14+IMPLEMENT-15+IMPLEMENT-16`; `d27462aaed26 -> IMPLEMENT-13+IMPLEMENT-14+IMPLEMENT-15+IMPLEMENT-16`; `9d52ecb17268 -> IMPLEMENT-13+IMPLEMENT-14+IMPLEMENT-15+IMPLEMENT-16`; `5b91aabe3757 -> IMPLEMENT-13+IMPLEMENT-14+IMPLEMENT-15+IMPLEMENT-16`; `fd0ad919f702 -> IMPLEMENT-13+IMPLEMENT-14+IMPLEMENT-15+IMPLEMENT-16`; `63bf28df1474 -> IMPLEMENT-13+IMPLEMENT-14+IMPLEMENT-15+IMPLEMENT-16`; `a4ed471dbc78 -> IMPLEMENT-16`; `6b7a64cec6e5 -> IMPLEMENT-16`; `0a4fdba0ebc0 -> IMPLEMENT-13+IMPLEMENT-14+IMPLEMENT-15+IMPLEMENT-16`; `a5033c2aada5 -> IMPLEMENT-13+IMPLEMENT-14+IMPLEMENT-15+IMPLEMENT-16`; `e77609eddba0 -> IMPLEMENT-13+IMPLEMENT-14+IMPLEMENT-15+IMPLEMENT-16`; `351156e8dde4 -> IMPLEMENT-13+IMPLEMENT-14+IMPLEMENT-15+IMPLEMENT-16`; `51d45bd2bbd1 -> IMPLEMENT-16`; `f7796ffcc804 -> IMPLEMENT-16`; `990d730cb494 -> IMPLEMENT-16`; `6ed28bb7d384 -> IMPLEMENT-16`; `8b7d4b5bcf1b -> IMPLEMENT-16`; `88aad500e6e9 -> IMPLEMENT-16`; `877e3e3f9eda -> IMPLEMENT-16`; `fc03c97f834e -> IMPLEMENT-16`; `12939a3da5e0 -> IMPLEMENT-16`; `bdb418335a88 -> IMPLEMENT-16`; `fba97e596ebd -> IMPLEMENT-16`; `3d0b5e2f14f0 -> IMPLEMENT-17`; `f56a9ce88461 -> IMPLEMENT-17`; `9ba67b50d0ba -> IMPLEMENT-17`; `39ff911760af -> IMPLEMENT-17`; `5b560b5bd6e3 -> IMPLEMENT-17`; `fa21df5e5e01 -> IMPLEMENT-17`; `0fed77bec55e -> IMPLEMENT-17`; `6d81cfb0483f -> IMPLEMENT-17`; `bee4c4aa34c6 -> NG`; `3f0b53056edd -> IMPLEMENT-18` |
package/assets/skills/oat-project-design/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: oat-project-design
3
- version: 2.2.0
3
+ version: 2.3.0
4
4
  description: Use when discovery is complete and implementation-ready decisions are needed. Runs a collaborative, selective collaborative, or draft-and-review design flow, confirms requirements and produces both `spec.md` and `design.md`, and commits artifacts before the user-review gate.
5
5
  disable-model-invocation: true
6
6
  user-invocable: true
@@ -619,79 +619,10 @@ Wait for user response:
619
619
  stop and report: "Design draft committed; awaiting HiLL approval."
620
620
  ```
621
621
 
622
- ### Step 7: Approval — Mark Design Complete and Update HiLL State
622
+ ### Step 7: Gate Execution
623
623
 
624
- On approval (either explicit user approval when HiLL gate fired, or automatic when no HiLL gate is configured):
625
-
626
- **Step 7a: Mark design.md complete**
627
-
628
- Update `design.md` frontmatter:
629
-
630
- ```yaml
631
- ---
632
- oat_status: complete
633
- oat_ready_for: oat-project-plan
634
- oat_blockers: []
635
- oat_last_updated: { today }
636
- ---
637
- ```
638
-
639
- **Step 7b: Update project state.md**
640
-
641
- Update `"$PROJECT_PATH/state.md"`:
642
-
643
- **Frontmatter updates:**
644
-
645
- - `oat_current_task: null`
646
- - `oat_last_commit: {commit_sha_from_step_6a_or_revision}`
647
- - `oat_blockers: []`
648
- - `oat_phase: design`
649
- - `oat_phase_status: complete`
650
- - `oat_project_state_updated: "{ISO 8601 UTC timestamp}"`
651
- - **If** `"design"` is in `oat_hill_checkpoints`: append `"design"` to `oat_hill_completed` array.
652
- - **If** `"spec"` is in `oat_hill_checkpoints` and not previously completed via the standalone spec skill: append `"spec"` too (folded HiLL — a single approval covers both).
653
-
654
- **Note:** Only append to `oat_hill_completed` when the phase is configured as a HiLL gate.
655
-
656
- Update content:
657
-
658
- ```markdown
659
- ## Current Phase
660
-
661
- Design - Ready for implementation planning
662
-
663
- ## Progress
664
-
665
- - ✓ Discovery complete
666
- - ✓ Specification complete (folded into design)
667
- - ✓ Design complete
668
- - ⧗ Awaiting implementation plan
669
- ```
670
-
671
- **Step 7c: Commit the approval-side metadata**
672
-
673
- ```bash
674
- git add "$PROJECT_PATH/design.md" "$PROJECT_PATH/state.md"
675
- git diff --cached --quiet || git commit -m "chore(oat): mark design complete for {project-name}"
676
- ```
677
-
678
- ### Step 8: Output Summary
679
-
680
- ```
681
- Design phase complete for {project-name}.
682
-
683
- Architecture:
684
- - {N} components defined
685
- - {N} data models specified
686
- - {N} API endpoints designed
687
-
688
- Next: Create implementation plan with the oat-project-plan skill
689
- ```
690
-
691
- ### Gate Execution
692
-
693
- Before reporting this skill as complete, run the configured gate as the final
694
- step:
624
+ After artifact finalization and any configured HiLL approval, run the configured
625
+ gate as the last check before the completion boundary:
695
626
 
696
627
  1. Resolve the gate for this skill:
697
628
 
@@ -699,8 +630,8 @@ step:
699
630
  oat gate resolve <this-skill> --json
700
631
  ```
701
632
 
702
- If the command returns JSON `null`, no gate is configured; the skill is
703
- complete.
633
+ If the command returns JSON `null`, no gate is configured; proceed directly
634
+ to the completion steps in Step 8 below.
704
635
 
705
636
  2. Export the resolved project path into the command shell:
706
637
 
@@ -766,6 +697,88 @@ setting; record the blocker and leave the project resumable. Important findings
766
697
  follow the configured gate policy. When autonomy is inactive, the interactive
767
698
  behavior above is unchanged.
768
699
 
700
+ A gate that ends in `block` after attempts are exhausted, or at an unresolved
701
+ `prompt` boundary, means the completion steps below MUST NOT run; the phase
702
+ stays `in_progress` and resumable.
703
+
704
+ ### Step 8: Approval — Mark Design Complete and Update HiLL State
705
+
706
+ Reach this completion boundary only after the configured gate passes or resolves
707
+ according to its `onFailure` policy.
708
+
709
+ On approval (either explicit user approval when HiLL gate fired, or automatic when no HiLL gate is configured):
710
+
711
+ **Step 8a: Mark design.md complete**
712
+
713
+ Update `design.md` frontmatter:
714
+
715
+ ```yaml
716
+ ---
717
+ oat_status: complete
718
+ oat_ready_for: oat-project-plan
719
+ oat_blockers: []
720
+ oat_last_updated: { today }
721
+ ---
722
+ ```
723
+
724
+ **Step 8b: Update project state.md**
725
+
726
+ Update `"$PROJECT_PATH/state.md"`:
727
+
728
+ **Frontmatter updates:**
729
+
730
+ - `oat_current_task: null`
731
+ - `oat_last_commit: {commit_sha_from_step_6a_or_revision}`
732
+ - `oat_blockers: []`
733
+ - `oat_phase: design`
734
+ - `oat_phase_status: complete`
735
+ - `oat_project_state_updated: "{ISO 8601 UTC timestamp}"`
736
+ - **If** `"design"` is in `oat_hill_checkpoints`: append `"design"` to `oat_hill_completed` array.
737
+ - **If** `"spec"` is in `oat_hill_checkpoints` and not previously completed via the standalone spec skill: append `"spec"` too (folded HiLL — a single approval covers both).
738
+
739
+ **Note:** Only append to `oat_hill_completed` when the phase is configured as a HiLL gate.
740
+
741
+ Update content:
742
+
743
+ ```markdown
744
+ ## Current Phase
745
+
746
+ Design - Ready for implementation planning
747
+
748
+ ## Progress
749
+
750
+ - ✓ Discovery complete
751
+ - ✓ Specification complete (folded into design)
752
+ - ✓ Design complete
753
+ - ⧗ Awaiting implementation plan
754
+ ```
755
+
756
+ **Step 8c: Commit the approval-side metadata**
757
+
758
+ Reach this commit step only after the configured gate passes or resolves
759
+ according to its `onFailure` policy.
760
+
761
+ ```bash
762
+ git add "$PROJECT_PATH/design.md" "$PROJECT_PATH/state.md"
763
+ git diff --cached --quiet || git commit -m "chore(oat): mark design complete for {project-name}"
764
+ ```
765
+
766
+ ### Step 9: Output Summary
767
+
768
+ Report completion only after the configured gate passes or resolves according to
769
+ its `onFailure` policy.
770
+
771
+ ```
772
+ Design phase complete for {project-name}.
773
+
774
+ Architecture:
775
+ - {N} components defined
776
+ - {N} data models specified
777
+ - {N} API endpoints designed
778
+
779
+ Next: Create implementation plan with the oat-project-plan skill
780
+ ```
781
+
769
782
  ## Success Criteria
770
783
 
771
784
  - Architecture aligns with existing patterns (from architecture.md)