fix(goal-draft): keep drafts concise and verifiable

docs/users/features/goals.md

@@ -52,6 +52,8 @@ Put these into the objective, in this order:
 
 Keep it to one objective. `/goal set` and `/goal edit` accept any length, but stay roughly under 1,200 characters: the objective is re-sent on every Goal turn. An objective the model proposes through `propose_goal` is capped at 1,500 characters. Both commands collapse newlines to spaces, so number the items rather than relying on line breaks.
 
+`Budget` is an instruction to the model about when to stop and report a blocker. Writing a turn count or time limit in the objective does not configure a runtime timer or change the Goal's token budget.
+
 | Weak                       | Why it fails                                                | Stronger                                                                                                                                                                                                                                |
 | -------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | make checkout faster       | No threshold, no check.                                     | `Outcome: checkout p95 is below 250 ms. Done when: 1) npm run bench:checkout exits 0 and prints p95 < 250 (paste the line); 2) npm test exits 0. Must not: change the benchmark or skip tests. Budget: stop as blocked after 20 turns.` |
@@ -61,9 +63,15 @@ Keep it to one objective. `/goal set` and `/goal edit` accept any length, but st
 
 ## Let `/goal-draft` write it
 
-`/goal-draft <what you want done>` is a bundled skill that does the above for you. It checks whether the request is a Goal at all, reads the workspace for the real test and lint commands instead of guessing, asks at most one round of multiple-choice questions when the answer changes the check or the scope, drafts the objective in the format above, runs the self-check, and hands it over: in an interactive session it proposes the objective through the `propose_goal` approval dialog described below, otherwise it prints a `/goal set …` line you can run as-is. It never starts the work itself, and nothing is set without your approval.
+`/goal-draft <what you want done>` is a bundled skill that does the above for you. It reads only enough of the workspace to establish the scope and real verification commands, without running tests, building, installing dependencies, or starting services. It asks at most one round of questions when essential choices are unclear, then writes a compact objective, usually with 3–5 completion checks (fewer when enough). Explicit requirements are preserved; it does not add checks just to reach a count.
+
+For an audit, completion means covering the agreed scenarios and reporting evidence, including reproduction steps for confirmed defects. Finding no defects is a valid result. The draft should not invent a minimum number of scenarios, evidence files, exploration rounds, or defects.
+
+If a success criterion, command, input path, or essential decision cannot be established, the skill returns a draft marked "Needs clarification" with `<TODO: …>` items. It does not offer that draft for approval or print a runnable `/goal set` or `/goal edit` command. Nonessential defaults are marked `[ASSUMPTION]`; they do not stand in for missing success criteria.
+
+Once the objective is ready, an interactive terminal session can show the `propose_goal` approval dialog described below. Web Shell and other ACP clients, headless runs, sessions with the tool disabled, and sessions with an active Goal receive a command to run manually instead. The hand-off says that the draft has not been applied. The skill never starts the work itself, and nothing is set without your approval.
 
-Pass an existing objective to tighten it: `/goal-draft all tests pass and the lint is clean`.
+Pass an existing objective to tighten it: `/goal-draft all tests pass and the lint is clean`. For an active Goal, an explicit request to tighten it produces `/goal edit`; a replacement uses `/goal set`. If the intended operation is unclear, the skill includes that choice in its single round of questions.
 
 ### Approve a Goal the model proposes
 

packages/core/src/skills/bundled/goal-draft/SKILL.md

@@ -13,7 +13,7 @@ allowedTools:
 
 You are already inside the loaded `goal-draft` skill — do not call the `skill` tool to invoke it again; start with Step 0.
 
-You are drafting the text for `/goal set`. You are NOT doing the work the goal describes. Do not edit files, do not run the checks, do not start on the task. The only deliverable is the objective text and the `/goal set` line the user can run.
+You are drafting the text for `/goal set`. You are NOT doing the work the goal describes. Do not edit files, do not run the checks, do not start on the task. Deliver a concise objective for approval or a command the user can run; if essential information is missing, deliver only a draft marked "Needs clarification".
 
 ## How Goals are judged (why the format below matters)
 
@@ -32,12 +32,14 @@ Say no, briefly, when the request is a normal one-shot task, needs a design or p
 
 ## Step 1 — check the active Goal
 
-Call `get_goal`. If a Goal is active, ask whether to edit it (same goal, tighter wording → `/goal edit`) or replace it (`/goal set`). Never draft a second concurrent goal.
+Call `get_goal`. If a Goal is active, preserve the user's explicit choice to edit it (same goal, tighter wording → `/goal edit`) or replace it (`/goal set`). If that choice is unclear, include it in Step 3's single round of questions; do not choose on the user's behalf. Never draft a second concurrent goal.
 
 ## Step 2 — ground the draft in the workspace
 
 Before asking anything, verify what you can with `read_file`, `glob`, and `grep_search`: that named files and packages exist, and what the real check commands are (`package.json` scripts, `Makefile`, CI workflow, test config). Use those exact commands in "Done when". Never invent paths, IDs, or commands; write `<TODO: …>` for anything you cannot confirm.
 
+Read only what is needed to establish the scope and verification path. Stop exploring once those are grounded; do not audit the implementation, reproduce failures, run builds or tests, install dependencies, or start services while drafting. A requested new output file is a proposed destination, not evidence that the file already exists.
+
 ## Step 3 — at most one round of questions
 
 Ask with `ask_user_question`, 1–3 questions in one call, each with options and a recommended default. Ask only when the answer changes the check, the scope, or the budget. Typical questions:
@@ -54,7 +56,7 @@ Rules for the questions:
 - Only ask things only the user can answer: what counts as done, what is off limits, how long to try.
 - If you cannot find a concrete way to verify the outcome, you MUST ask, offering 2–3 candidate checks. Do not skip this and do not invent one.
 
-If you cannot ask (headless, or a client without prompts), take the recommended default and mark it `[ASSUMPTION]` in Context.
+If you cannot ask (headless, or a client without prompts), use a recommended default only for nonessential choices and mark it `[ASSUMPTION]` in Context. An unknown success criterion, unverified command or input path, or unresolved edit-versus-replace choice stays `<TODO: …>`; do not invent an answer just to finish the hand-off. If essential information is still missing after the single question round, keep the draft incomplete rather than starting another round.
 
 ## Step 4 — draft the objective
 
@@ -64,27 +66,32 @@ Use exactly these labels, in this order. Keep the whole objective on one line wh
 Outcome: <one sentence: what is true when done>
 Done when: 1) <command> exits 0 and its output shows <…> (paste that line); 2) <file/state assertion provable via read or grep>; 3) …
 Must not: <files not to touch; tests/thresholds not to weaken; irreversible actions not to take>
-Budget: stop as blocked after <N> turns (default 20) or <M> minutes without measurable progress
+Budget: <user's stopping agreement; otherwise stop as blocked after 20 turns, and mark that default [ASSUMPTION] in Context>
 On block: propose blocked with the exact blocker and the decision a human must make; never claim completion without evidence for every Done-when item
 Context: <only facts the agent cannot derive: paths, branch, environment, earlier decisions>
 ```
 
 Rules of thumb:
 
 - One Outcome. Several outcomes = several goals, or a checklist file plus a single "every item in `<file>` is checked" goal.
+- Usually 3–5 Done-when checks suffice; use fewer when enough. Do not add checks just to reach a count, and preserve explicit user requirements.
 - Every Done-when item is binary, and at least one is tool-observable (a command with an exit code or output line, a file that exists, a grep that matches).
+- For audits and exploratory work, agree on bounded coverage and require evidence for each conclusion. Zero defects is a valid result: never require a positive defect count. Do not invent minimum scenario counts, evidence-file counts, or exploration-round quotas; include them only when the user requested them.
 - Prefer "the smallest safe change in `<scope>`" over open-ended refactors.
 - Put anything that must not change on the way into Must not — this is what stops the loop from deleting a failing test to "pass".
 - Keep it short: everything the agent can derive from the workspace stays out. Aim for under ~1200 characters.
+- `Budget` is a stopping agreement for the model, not a runtime-enforced turn or wall-clock limit. Do not claim that writing it configures a timer or changes the Goal token budget. Preserve a user-specified budget; otherwise mark the default `[ASSUMPTION]` in Context.
+
+For example, an audit's Done-when checks can require a report covering the agreed scenarios, observed results and evidence for each scenario, and reproduction steps for each confirmed defect (or an explicit "no confirmed defects" result). Ground the scenarios and report destination before offering the objective for use.
 
 ### Weak → strong
 
-| Weak                          | Strong                                                                                                                                                                                                                                                                                                                                                                                           |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| make checkout faster          | Outcome: checkout API p95 is below 250 ms on the documented slow path. Done when: 1) `npm run bench:checkout` exits 0 and prints a p95 below 250 (paste the line); 2) `npm test` exits 0. Must not: change the benchmark, skip tests, touch files outside `src/checkout`. Budget: stop as blocked after 20 turns. On block: report the measured p95 and what blocks it.                          |
-| keep handling the PR comments | Outcome: every unresolved review thread on PR #123 is fixed or answered. Done when: 1) the review-threads query shows zero unresolved threads (paste the count); 2) CI on the head commit is green (paste the check summary). Must not: force-push, resolve a thread without replying to it. Budget: stop as blocked after 30 turns. On block: list the threads that need a maintainer decision. |
-| clean up the auth module      | Not a goal — "clean" has no check. Ask what would be observable (zero lint warnings in `src/auth`? a file count? a coverage threshold?) or offer a refactor plan instead.                                                                                                                                                                                                                        |
-| get the release out           | Not a goal as written — publishing is irreversible. Either narrow it to a checkable pre-release state (tag exists, changelog entry present, `npm run release:dry-run` exits 0) and put "do not publish" in Must not, or leave publishing to a human.                                                                                                                                             |
+| Weak                          | Strong                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| make checkout faster          | Outcome: checkout API p95 is below 250 ms on the documented slow path. Done when: 1) `npm run bench:checkout` exits 0 and prints a p95 below 250 (paste the line); 2) `npm test` exits 0. Must not: change the benchmark, skip tests, touch files outside `src/checkout`. Budget: stop as blocked after 20 turns. On block: report the measured p95 and what blocks it. Context: [ASSUMPTION] the 20-turn budget is the drafter's default, not the user's. |
+| keep handling the PR comments | Outcome: every unresolved review thread on PR #123 is fixed or answered. Done when: 1) the review-threads query shows zero unresolved threads (paste the count); 2) CI on the head commit is green (paste the check summary). Must not: force-push, resolve a thread without replying to it. Budget: stop as blocked after 30 turns. On block: list the threads that need a maintainer decision.                                                           |
+| clean up the auth module      | Not a goal — "clean" has no check. Ask what would be observable (zero lint warnings in `src/auth`? a file count? a coverage threshold?) or offer a refactor plan instead.                                                                                                                                                                                                                                                                                  |
+| get the release out           | Not a goal as written — publishing is irreversible. Either narrow it to a checkable pre-release state (tag exists, changelog entry present, `npm run release:dry-run` exits 0) and put "do not publish" in Must not, or leave publishing to a human.                                                                                                                                                                                                       |
 
 ## Step 5 — self-check, then hand off
 
@@ -96,18 +103,21 @@ Check every line before printing:
 4. No "after the user confirms/approves" as a completion condition — that belongs in On block as a decision a human must make.
 5. Budget or On block is present.
 6. Exactly one Outcome.
-7. Every path and command in Context was verified in the workspace or is marked `<TODO>`.
+7. Every path and command in Context was verified in the workspace; an unverified path or command is essential and stays `<TODO: …>`.
 8. Under ~1200 characters.
 9. Irreversible actions (push, delete, publish) are listed in Must not, or the user explicitly allowed them.
+10. No invented coverage quotas, required defect findings, or claims that a prose budget is enforced by the runtime; an unrequested default Budget is marked `[ASSUMPTION]` in Context.
+
+**If an essential item remains unresolved — an unknown success criterion, an unverified command or input path, or an unresolved edit-versus-replace choice (each written as `<TODO: …>`) —**, print only a draft marked "Needs clarification" (in the user's language) and briefly list what is missing. Do not call `propose_goal` or print a runnable `/goal set` or `/goal edit` line. Stop here; the ready-objective hand-off below does not apply.
 
 Then hand off, and nothing else:
 
 **If the `propose_goal` tool is available and no Goal is active**, call it with the objective on one line. The user approves or declines it in a dialog; only their approval sets the Goal. If they decline you will not be told why: stop, do not ask about it, and do not propose the same or a reworded objective again. After approval, acknowledge it in one sentence and end the turn — the Goal runtime starts the first Goal turn on its own.
 
-**Otherwise** (headless, the tool is disabled, or a Goal is active), print:
+**Otherwise** (Web Shell or another ACP client, headless, the tool is disabled, or a Goal is active), print:
 
 1. The objective in a fenced code block.
 2. One line the user can run as-is: `/goal set <objective on one line>` (or `/goal edit …` when tightening the active goal). Print it as plain text with no code markers, so it can be copied verbatim.
-3. One sentence on what you assumed (`[ASSUMPTION]` / `<TODO>` items), if any.
+3. One sentence explaining that the draft has not been applied and the user must run the command to apply it; include any `[ASSUMPTION]` items. Do not promise a dialog in Web Shell or other ACP sessions.
 
 Do not run /goal yourself. Do not begin the task. Stop and wait for the user.