docs(oat): harden HiLL prompts and artifact tracking

.agents/skills/oat-project-implement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-implement
-version: 1.2.0
+version: 1.2.1
 description: Use when plan.md is ready for execution. Implements plan tasks sequentially with TDD discipline and state tracking.
 disable-model-invocation: true
 user-invocable: true
@@ -142,22 +142,29 @@ Determine whether this is a first implementation run:
 
 Prompt behavior:
 
-- **If first run:** always present a brief phase summary and confirm checkpoint phases before any task execution. A missing `oat_plan_hill_phases` value is the normal unconfirmed state; if a value is already present, treat it as a provisional value to confirm rather than as final.
+- **If first run:** always present a complete phase-by-phase summary and confirm checkpoint phases before any task execution. A missing `oat_plan_hill_phases` value is the normal unconfirmed state; if a value is already present, treat it as a provisional value to confirm rather than as final.
 - **If resuming and `oat_plan_hill_phases` is valid:** do not re-ask; print active checkpoint config and continue.
 - **If resuming and `oat_plan_hill_phases` is missing/invalid:** treat this as bookkeeping drift, because implementation should already have written the confirmed value before prior task execution. Ask the user to repair the checkpoint configuration before continuing.
 
 Required prompt shape for first-run confirmation:
 
-1. Briefly summarize each plan phase:
+1. Open with plan framing:
+   - `This plan has {phase_count} phases. Final phase: {final_phase_id}.`
+2. Briefly summarize every plan phase in order:
    - `p01 — {short phase summary}`
    - `p02 — {short phase summary}`
    - ...
-2. Ask a simple checkpoint question:
-   - `Which checkpoints do you want: every phase, or specific checkpoints?`
-3. Offer concrete examples:
-   - `Every phase` -> `[]`
-   - `Final phase only` -> `["p07"]` (replace `p07` with the actual final phase ID for this plan)
-   - `Specific checkpoints` -> `["p02","p05"]`
+   - Never omit this summary, even if the plan has only one phase or `oat_plan_hill_phases` already contains a provisional value.
+3. Ask the checkpoint question using exactly three options:
+   - `Which checkpoint behavior do you want?`
+   - `1. Stop after each phase (default)`
+   - `2. Stop after specific phases, e.g. p02, p05`
+   - `3. Stop only after the final phase is completed`
+4. Map the options to stored values:
+   - `1` -> `[]`
+   - `2` -> user-specified array such as `["p02","p05"]`
+   - `3` -> `["p07"]` (replace `p07` with the actual final phase ID for this plan)
+5. If a provisional `oat_plan_hill_phases` value already exists, mention it after presenting the three options, but still require the user to choose or confirm one of them.
 
 When user confirms/changes:
 

.agents/skills/oat-project-quick-start/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-quick-start
-version: 1.3.0
+version: 1.3.1
 description: Use when a task is small enough for quick mode or rapid iteration is preferred. Scaffolds a lightweight OAT project from discovery directly to a runnable plan, with optional brainstorming and lightweight design.
 argument-hint: '<project-name>'
 disable-model-invocation: true
@@ -65,6 +65,12 @@ When executing this skill, provide lightweight progress feedback so the user can
   - `[6/6] Refreshing dashboard…`
   - _(If lightweight design is chosen, insert design steps between 3 and 4)_
 
+## Artifact Persistence (Required)
+
+- 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.
+- 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.
+- Quick-start handoff is not complete until the changed project artifacts and regenerated `.oat/state.md` dashboard have been committed.
+
 ## Process
 
 ### Step 0: Resolve Active Project
@@ -146,6 +152,15 @@ Whether well-understood or exploratory, backfill `discovery.md` with the discuss
 
 Keep this concise and outcome-oriented.
 
+### Step 2d: Persist Discovery Before Any Decision Pause
+
+If discovery/state artifacts were updated and the skill is about to pause for the Step 2.5 design-depth decision, commit those artifact changes first so the project can be resumed cleanly.
+
+```bash
+git add "$PROJECT_PATH/discovery.md" "$PROJECT_PATH/state.md"
+git diff --cached --quiet || git commit -m "chore(oat): capture quick-start discovery for {project-name}"
+```
+
 ### Step 2.5: Decision Point — Design Depth
 
 **Auto-advance rule:** If the request was classified as **well-understood** in Step 2a and discovery surfaced no architecture decisions, component boundary questions, or unexpected complexity, skip this decision point entirely and continue directly to Step 3. This preserves the minimal-ceremony contract for straightforward requests.
@@ -182,6 +197,13 @@ Use `AskUserQuestion` to present this choice.
   - `oat_phase_status: complete`
   - `oat_project_state_updated: "{ISO 8601 UTC timestamp}"`
 - Refresh repo dashboard: `oat state refresh`
+- Commit the promoted discovery/state artifacts before stopping:
+
+```bash
+git add "$PROJECT_PATH/discovery.md" "$PROJECT_PATH/state.md" ".oat/state.md"
+git diff --cached --quiet || git commit -m "chore(oat): promote quick-start discovery for {project-name}"
+```
+
 - Inform the user: "Discovery is complete. Run `oat-project-spec` next to formalize requirements."
 - Stop here. Do not generate a plan.
 
@@ -222,6 +244,8 @@ Copy template: `.oat/templates/design.md` → `"$PROJECT_PATH/design.md"`
 
 After each chunk, ask: "Does this look right, or should we adjust before continuing?"
 
+If `design.md` or `state.md` was updated before one of these validation pauses, commit those artifact changes before waiting for the user response.
+
 Update `design.md` frontmatter:
 
 ```yaml
@@ -240,6 +264,13 @@ Update `"$PROJECT_PATH/state.md"` to reflect the design phase:
 - `oat_phase_status: complete`
 - `oat_project_state_updated: "{ISO 8601 UTC timestamp}"`
 
+Before proceeding to plan generation or pausing for validation, persist the design bookkeeping:
+
+```bash
+git add "$PROJECT_PATH/design.md" "$PROJECT_PATH/state.md"
+git diff --cached --quiet || git commit -m "chore(oat): capture quick-start design for {project-name}"
+```
+
 ### Step 3: Generate Plan Directly
 
 Create/update `"$PROJECT_PATH/plan.md"` from `.oat/templates/plan.md`.
@@ -293,6 +324,23 @@ Always regenerate the repo dashboard after quick-start updates (including resume
 oat state refresh
 ```
 
+### Step 6.5: Commit Quick-Start Artifacts
+
+After dashboard refresh, stage and commit the changed quick-start artifacts before handing off to implementation or stopping.
+
+```bash
+for path in \
+  "$PROJECT_PATH/discovery.md" \
+  "$PROJECT_PATH/design.md" \
+  "$PROJECT_PATH/plan.md" \
+  "$PROJECT_PATH/implementation.md" \
+  "$PROJECT_PATH/state.md" \
+  ".oat/state.md"; do
+  [ -e "$path" ] && git add "$path"
+done
+git diff --cached --quiet || git commit -m "chore(oat): update quick-start artifacts for {project-name}"
+```
+
 ### Step 7: Output Next Action
 
 Report:
@@ -312,3 +360,4 @@ Report:
 - ✅ `discovery.md` contains synthesized or backfilled quick discovery decisions from the session context.
 - ✅ `plan.md` is complete and executable (`oat_ready_for: oat-project-implement`).
 - ✅ `implementation.md` is initialized for resumable execution.
+- ✅ Changed quick-start artifacts and refreshed `.oat/state.md` are committed before handoff or pause.

.claude/skills/oat-pjm-add-backlog-item

@@ -0,0 +1 @@
+../../.agents/skills/oat-pjm-add-backlog-item

.claude/skills/oat-pjm-review-backlog

@@ -0,0 +1 @@
+../../.agents/skills/oat-pjm-review-backlog

.claude/skills/oat-pjm-update-repo-reference

@@ -0,0 +1 @@
+../../.agents/skills/oat-pjm-update-repo-reference

.cursor/skills/oat-pjm-add-backlog-item

@@ -0,0 +1 @@
+../../.agents/skills/oat-pjm-add-backlog-item

.cursor/skills/oat-pjm-review-backlog

@@ -0,0 +1 @@
+../../.agents/skills/oat-pjm-review-backlog

.cursor/skills/oat-pjm-update-repo-reference

@@ -0,0 +1 @@
+../../.agents/skills/oat-pjm-update-repo-reference

.oat/sync/manifest.json

@@ -1121,7 +1121,67 @@
       "contentHash": null,
       "isFile": false,
       "lastSynced": "2026-03-16T17:37:53.299Z"
+    },
+    {
+      "canonicalPath": ".agents/skills/oat-pjm-add-backlog-item",
+      "providerPath": ".claude/skills/oat-pjm-add-backlog-item",
+      "provider": "claude",
+      "contentType": "skill",
+      "strategy": "symlink",
+      "contentHash": null,
+      "isFile": false,
+      "lastSynced": "2026-03-21T14:51:12.220Z"
+    },
+    {
+      "canonicalPath": ".agents/skills/oat-pjm-review-backlog",
+      "providerPath": ".claude/skills/oat-pjm-review-backlog",
+      "provider": "claude",
+      "contentType": "skill",
+      "strategy": "symlink",
+      "contentHash": null,
+      "isFile": false,
+      "lastSynced": "2026-03-21T14:51:12.221Z"
+    },
+    {
+      "canonicalPath": ".agents/skills/oat-pjm-update-repo-reference",
+      "providerPath": ".claude/skills/oat-pjm-update-repo-reference",
+      "provider": "claude",
+      "contentType": "skill",
+      "strategy": "symlink",
+      "contentHash": null,
+      "isFile": false,
+      "lastSynced": "2026-03-21T14:51:12.221Z"
+    },
+    {
+      "canonicalPath": ".agents/skills/oat-pjm-add-backlog-item",
+      "providerPath": ".cursor/skills/oat-pjm-add-backlog-item",
+      "provider": "cursor",
+      "contentType": "skill",
+      "strategy": "symlink",
+      "contentHash": null,
+      "isFile": false,
+      "lastSynced": "2026-03-21T14:51:12.221Z"
+    },
+    {
+      "canonicalPath": ".agents/skills/oat-pjm-review-backlog",
+      "providerPath": ".cursor/skills/oat-pjm-review-backlog",
+      "provider": "cursor",
+      "contentType": "skill",
+      "strategy": "symlink",
+      "contentHash": null,
+      "isFile": false,
+      "lastSynced": "2026-03-21T14:51:12.222Z"
+    },
+    {
+      "canonicalPath": ".agents/skills/oat-pjm-update-repo-reference",
+      "providerPath": ".cursor/skills/oat-pjm-update-repo-reference",
+      "provider": "cursor",
+      "contentType": "skill",
+      "strategy": "symlink",
+      "contentHash": null,
+      "isFile": false,
+      "lastSynced": "2026-03-21T14:51:12.222Z"
     }
   ],
-  "lastUpdated": "2026-03-16T17:37:53.299Z"
+  "lastUpdated": "2026-03-21T14:51:12.222Z"
 }

apps/oat-docs/docs/guide/workflow/hill-checkpoints.md

@@ -36,7 +36,13 @@ Semantics:
 - Empty list: checkpoint after every phase boundary, but only after implementation has confirmed the choice and written `oat_plan_hill_phases: []` into `plan.md`.
 - Explicit list: checkpoint only after completing the named phases (`p01`, `p04`, etc).
 
-On the first implementation run, `oat-project-implement` presents a brief phase summary and asks a simple checkpoint question such as "every phase or specific checkpoints?" It then writes the confirmed value into `plan.md`. If the field is later missing during a resumed implementation run, treat that as bookkeeping drift rather than as an implicit default.
+On the first implementation run, `oat-project-implement` must summarize every plan phase, state the total phase count and final phase ID, and then ask an explicit three-option checkpoint question:
+
+- Stop after each phase
+- Stop after specific phases
+- Stop only after the final phase is completed
+
+It then writes the confirmed value into `plan.md`. If the field is later missing during a resumed implementation run, treat that as bookkeeping drift rather than as an implicit default.
 
 Listed phases are where you stop **after completing them**, not before. `["p03"]` means "complete p03, then pause" — not "pause before starting p03." Setting the last phase ID (e.g., `["p03"]` when p03 is final) means "stop only at the end of implementation."
 

packages/cli/src/validation/skills.test.ts

@@ -607,7 +607,7 @@ describe('validateOatSkills', () => {
     );
     const content = await readFile(skillPath, 'utf8');
 
-    expect(content.match(/^version:\s*(.+)$/m)?.[1]?.trim()).toBe('1.3.0');
+    expect(content.match(/^version:\s*(.+)$/m)?.[1]?.trim()).toBe('1.3.1');
   });
 
   it('reports missing quick-start-specific discovery guidance', async () => {