feat(refresh): add Refresh Gate to interactive refresh

.agents/skills/forerunner-refresh/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: forerunner-refresh
-description: Scan repo, check all docs for staleness, then generate or update every stale or missing doc in one pass. Use when the user wants to update all docs, refresh docs, or sync documentation with the current codebase.
+description: Scan repo, check all docs for staleness, then ask which stale or missing docs to regenerate before updating them. Use when the user wants to update all docs, refresh docs, or sync documentation with the current codebase. Pass "auto" to skip the approval step and update everything stale.
 ---
 
 # forerunner-refresh
 
-Runs a full documentation refresh cycle: scan → check → generate/update all stale or missing docs.
+Runs a full documentation refresh cycle: scan → check → Refresh Gate → generate/update the approved stale or missing docs.
 
 ## Activate when
 
@@ -16,19 +16,22 @@ User asks to: update all docs, refresh documentation, sync docs with code, run a
 Run each step in order, processing the result before moving to the next:
 
 1. **Scan** — `forerunner doc scan` → capture YAML output as the scan result
-2. **Check** — `forerunner doc check` → identify every doc with `STALE` or `MISSING` status
-3. **For each stale/missing** — run the corresponding task in this order, passing the scan result:
+2. **Check** — `forerunner doc check` → classify every doc as `CURRENT`, `STALE`, `MISSING`, or `UNVERIFIABLE`
+3. **Refresh Gate** — present the check report (what is stale, what is current, what is missing, what is unverifiable), then ask the user **once**, as a multi-select with all options pre-selected, which of the `STALE` and `MISSING` docs to regenerate.
+   - `UNVERIFIABLE` docs appear in the report but are never offered for regeneration — note them as gaps.
+   - Skip the gate entirely when the user passed `auto` as an argument, or when the harness has no way to ask (headless/AFK run): proceed with the full stale set and say so in the summary.
+4. **For each approved doc** — run the corresponding task in this order, passing the scan result:
    - `forerunner doc readme`
    - `forerunner doc api-docs`
    - `forerunner doc stack-docs`
    - `forerunner doc diagrams`
    - `forerunner doc flows`
    - `forerunner doc version-audit`
    - `forerunner doc audit`
-   - Skip any task whose check status is `CURRENT`
+   - Run order follows this sequence regardless of selection order. Skip any task whose check status is `CURRENT` or that the user declined at the gate.
 
-`changelog` and `review` are on-demand tasks — exclude from automated refresh.
+`changelog` and `review` are on-demand tasks — exclude from automated refresh and never offer them at the gate.
 
 ## Output
 
-Write each artifact to its task-defined output path. Append `## Gaps` wherever evidence is insufficient. Report a summary of what was updated.
+Write each artifact to its task-defined output path. Append `## Gaps` wherever evidence is insufficient. Report a summary of what was updated, what was skipped as `CURRENT`, what was declined at the Refresh Gate, and any gaps found.

CONTEXT.md

@@ -36,6 +36,10 @@ _Avoid_: Release checklist, publish config
 A release validation module that checks the packed npm artifact before publish, including required files, executable entrypoints, skill payloads, lock metadata, and shim pins. It treats the package artifact as the test surface.
 _Avoid_: npm pack script, file list check
 
+**Refresh Gate**:
+The approval step in an interactive refresh where the agent presents the staleness check report and the user selects which STALE or MISSING docs to regenerate. UNVERIFIABLE docs are reported but never offered. The Refresh Gate is absent from batch refresh and skipped when `auto` is passed.
+_Avoid_: Confirmation prompt, review step, interactive mode
+
 **Agent Onboarding**:
 A task that creates or refreshes the instructions and domain vocabulary a coding agent needs before working in a repo. Agent Onboarding may create or update `CONTEXT.md` with conservative glossary terms inferred from stable repo evidence.
 _Avoid_: Init docs, setup docs
@@ -54,6 +58,10 @@ Dev: "Add a new prompt task."
 
 Domain expert: "Register it in the Task Registry so wrappers, skills, docs, and refresh policy read the same task identity."
 
+Dev: "Make refresh ask before it rewrites docs."
+
+Domain expert: "That is the Refresh Gate: after the staleness check, offer the STALE and MISSING docs for selection; batch refresh and `auto` runs bypass it."
+
 Dev: "Why does scan-first logic exist in both CLI and MCP?"
 
 Domain expert: "That rule belongs to a Prompt Session: adapters should ask the session whether a task can run."

plugins/codeforerunner/skills/forerunner-refresh/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: forerunner-refresh
-description: Scan repo, check all docs for staleness, then generate or update every stale or missing doc in one pass. Use when the user wants to update all docs, refresh docs, or sync documentation with the current codebase.
+description: Scan repo, check all docs for staleness, then ask which stale or missing docs to regenerate before updating them. Use when the user wants to update all docs, refresh docs, or sync documentation with the current codebase. Pass "auto" to skip the approval step and update everything stale.
 ---
 
 # forerunner-refresh
 
-Runs a full documentation refresh cycle: scan → check → generate/update all stale or missing docs.
+Runs a full documentation refresh cycle: scan → check → Refresh Gate → generate/update the approved stale or missing docs.
 
 ## Activate when
 
@@ -16,19 +16,22 @@ User asks to: update all docs, refresh documentation, sync docs with code, run a
 Run each step in order, processing the result before moving to the next:
 
 1. **Scan** — `forerunner doc scan` → capture YAML output as the scan result
-2. **Check** — `forerunner doc check` → identify every doc with `STALE` or `MISSING` status
-3. **For each stale/missing** — run the corresponding task in this order, passing the scan result:
+2. **Check** — `forerunner doc check` → classify every doc as `CURRENT`, `STALE`, `MISSING`, or `UNVERIFIABLE`
+3. **Refresh Gate** — present the check report (what is stale, what is current, what is missing, what is unverifiable), then ask the user **once**, as a multi-select with all options pre-selected, which of the `STALE` and `MISSING` docs to regenerate.
+   - `UNVERIFIABLE` docs appear in the report but are never offered for regeneration — note them as gaps.
+   - Skip the gate entirely when the user passed `auto` as an argument, or when the harness has no way to ask (headless/AFK run): proceed with the full stale set and say so in the summary.
+4. **For each approved doc** — run the corresponding task in this order, passing the scan result:
    - `forerunner doc readme`
    - `forerunner doc api-docs`
    - `forerunner doc stack-docs`
    - `forerunner doc diagrams`
    - `forerunner doc flows`
    - `forerunner doc version-audit`
    - `forerunner doc audit`
-   - Skip any task whose check status is `CURRENT`
+   - Run order follows this sequence regardless of selection order. Skip any task whose check status is `CURRENT` or that the user declined at the gate.
 
-`changelog` and `review` are on-demand tasks — exclude from automated refresh.
+`changelog` and `review` are on-demand tasks — exclude from automated refresh and never offer them at the gate.
 
 ## Output
 
-Write each artifact to its task-defined output path. Append `## Gaps` wherever evidence is insufficient. Report a summary of what was updated.
+Write each artifact to its task-defined output path. Append `## Gaps` wherever evidence is insufficient. Report a summary of what was updated, what was skipped as `CURRENT`, what was declined at the Refresh Gate, and any gaps found.

skills/forerunner-refresh/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: forerunner-refresh
-description: Scan repo, check all docs for staleness, then generate or update every stale or missing doc in one pass. Use when the user wants to update all docs, refresh docs, or sync documentation with the current codebase.
+description: Scan repo, check all docs for staleness, then ask which stale or missing docs to regenerate before updating them. Use when the user wants to update all docs, refresh docs, or sync documentation with the current codebase. Pass "auto" to skip the approval step and update everything stale.
 ---
 
 # forerunner-refresh
 
-Runs a full documentation refresh cycle: scan → check → generate/update all stale or missing docs.
+Runs a full documentation refresh cycle: scan → check → Refresh Gate → generate/update the approved stale or missing docs.
 
 ## Activate when
 
@@ -16,19 +16,22 @@ User asks to: update all docs, refresh documentation, sync docs with code, run a
 Run each step in order, processing the result before moving to the next:
 
 1. **Scan** — `forerunner doc scan` → capture YAML output as the scan result
-2. **Check** — `forerunner doc check` → identify every doc with `STALE` or `MISSING` status
-3. **For each stale/missing** — run the corresponding task in this order, passing the scan result:
+2. **Check** — `forerunner doc check` → classify every doc as `CURRENT`, `STALE`, `MISSING`, or `UNVERIFIABLE`
+3. **Refresh Gate** — present the check report (what is stale, what is current, what is missing, what is unverifiable), then ask the user **once**, as a multi-select with all options pre-selected, which of the `STALE` and `MISSING` docs to regenerate.
+   - `UNVERIFIABLE` docs appear in the report but are never offered for regeneration — note them as gaps.
+   - Skip the gate entirely when the user passed `auto` as an argument, or when the harness has no way to ask (headless/AFK run): proceed with the full stale set and say so in the summary.
+4. **For each approved doc** — run the corresponding task in this order, passing the scan result:
    - `forerunner doc readme`
    - `forerunner doc api-docs`
    - `forerunner doc stack-docs`
    - `forerunner doc diagrams`
    - `forerunner doc flows`
    - `forerunner doc version-audit`
    - `forerunner doc audit`
-   - Skip any task whose check status is `CURRENT`
+   - Run order follows this sequence regardless of selection order. Skip any task whose check status is `CURRENT` or that the user declined at the gate.
 
-`changelog` and `review` are on-demand tasks — exclude from automated refresh.
+`changelog` and `review` are on-demand tasks — exclude from automated refresh and never offer them at the gate.
 
 ## Output
 
-Write each artifact to its task-defined output path. Append `## Gaps` wherever evidence is insufficient. Report a summary of what was updated.
+Write each artifact to its task-defined output path. Append `## Gaps` wherever evidence is insufficient. Report a summary of what was updated, what was skipped as `CURRENT`, what was declined at the Refresh Gate, and any gaps found.

src/codeforerunner/prompts/tasks/refresh.md

@@ -2,7 +2,7 @@
 
 Runs a full documentation refresh cycle: scan, check staleness, then generate or update every stale or missing doc in one pass.
 
-This prompt is the batch form (all bundles concatenated). When running via the `/forerunner-refresh` skill, the agent calls `forerunner doc <task>` for each step individually so it can process each result before moving to the next.
+This prompt is the batch form (all bundles concatenated). When running via the `/forerunner-refresh` skill, the agent calls `forerunner doc <task>` for each step individually so it can process each result before moving to the next, and applies the Refresh Gate — asking the user which stale or missing docs to regenerate — between check and generate. The batch form has no gate.
 
 ## Steps (execute in order)