@yaawn/workflow 0.4.0 → 0.5.0

package/agents/skills/yaawn-implement-plan/scripts/worktrees.ts

@@ -1,19 +1,25 @@
 import { execFile, execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
 import path from "node:path";
 import { promisify } from "node:util";
 import { uncommittedChangesAsync } from "./targets.js";
 
 // Shared by yaawn-implement-plan (creates one git worktree per issue) and
-// yaawn-verify-executed-plan (checks it verifies in the issue's worktree).
+// yaawn-verify-executed-plan (resolves the issue's worktree to verify in).
 //
 // Layout: the project root holds a bare `.git` repository, the main working
 // copy is a normal checkout at `<project>/main`, and every issue worktree is
-// a sibling of it at `<project>/yaawn-<issue>-<slug>`.
+// a sibling of it at `<project>/yaawn-<issue>-<slug>`. A prototype issue
+// (labelled `Yaawn: Prototype`) gets its worktree at
+// `<project>/prototype/yaawn-<issue>-<slug>` on branch
+// `prototype/yaawn-<issue>-<slug>`, which is never merged.
 
 export type WorktreeCheckStatus = "ok" | "warn" | "fail";
 
+// `path` is the worktree to verify in; null only when the check fails.
 export interface WorktreeCheck {
   status: WorktreeCheckStatus;
+  path: string | null;
   message: string;
 }
 
@@ -21,16 +27,20 @@ export interface WorktreeLayout {
   issue: number;
   mainCopy: string;
   registered: Iterable<string>;
-  currentToplevel: string;
-  // Resolved by branch (yaawn/<issue>), not by the title slug — the slug in
-  // the directory name is for humans only.
+  // Resolved by branch (yaawn/<issue>, or prototype/yaawn-<issue>-*), not by
+  // the title-derived path.
   ownWorktree?: string | null;
+  locked?: Iterable<string>;
+  // Registered, but git marks them prunable or their directory is gone.
+  stale?: Iterable<string>;
 }
 
 export interface WorktreeEntry {
   path: string;
   branch: string | null;
   bare: boolean;
+  locked: boolean;
+  prunable: boolean;
 }
 
 export interface AheadBehind {
@@ -58,12 +68,14 @@ const branchPrefix = "branch refs/heads/";
 const maxSlugLength = 40;
 const fallbackMainCopyName = "main";
 const fallbackDefaultBranches = ["main", "master"];
+const prototypeDir = "prototype";
+const fallbackPrototypeSlug = "prototype";
+
+export const prototypeLabel = "Yaawn: Prototype";
 
 const aheadBehindPattern = /^(\d+)\s+(\d+)$/;
 const execFileAsync = promisify(execFile);
 
-export const branchName = (issue: number): string => `yaawn/${issue}`;
-
 export function git(args: string[]): string {
   return execFileSync("git", args, {
     encoding: "utf-8",
@@ -92,9 +104,37 @@ export function titleSlug(title: string): string {
     .replace(/-+$/, "");
 }
 
-export function worktreeName(issue: number, title: string): string {
+// Exact label-name match only: a look-alike label never makes a prototype.
+export const isPrototype = (labels: readonly string[]): boolean =>
+  labels.includes(prototypeLabel);
+
+// A prototype branch always carries a slug, so `prototype/yaawn-<issue>-*`
+// finds it.
+const prototypeSlug = (title: string): string =>
+  titleSlug(title) || fallbackPrototypeSlug;
+
+export function prototypeBranchPrefix(issue: number): string {
   assertIssueNumber(issue);
-  const slug = titleSlug(title);
+  return `${prototypeDir}/yaawn-${issue}-`;
+}
+
+export function branchName(
+  issue: number,
+  labels: readonly string[] = [],
+  title = "",
+): string {
+  return isPrototype(labels)
+    ? `${prototypeBranchPrefix(issue)}${prototypeSlug(title)}`
+    : `yaawn/${issue}`;
+}
+
+export function worktreeName(
+  issue: number,
+  title: string,
+  labels: readonly string[] = [],
+): string {
+  assertIssueNumber(issue);
+  const slug = isPrototype(labels) ? prototypeSlug(title) : titleSlug(title);
   return slug ? `yaawn-${issue}-${slug}` : `yaawn-${issue}`;
 }
 
@@ -109,6 +149,8 @@ function entryFromBlock(lines: string[]): WorktreeEntry | null {
     branch:
       branchLine === undefined ? null : branchLine.slice(branchPrefix.length),
     bare: lines.includes("bare"),
+    locked: lines.some((line) => line === "locked" || line.startsWith("locked ")),
+    prunable: lines.some((line) => line === "prunable" || line.startsWith("prunable ")),
   };
 }
 
@@ -163,12 +205,56 @@ export function branchWorktreeFromPorcelain(
   return checkout?.path ?? null;
 }
 
+// A prototype's checkout on any `prototype/yaawn-<issue>-*` branch counts, so
+// a relaunch resumes it even after the issue was renamed.
+export function issueWorktreeFromPorcelain(
+  porcelain: string,
+  issue: number,
+  labels: readonly string[] = [],
+  title = "",
+): string | null {
+  const exact = branchWorktreeFromPorcelain(
+    porcelain,
+    branchName(issue, labels, title),
+  );
+  if (exact !== null || !isPrototype(labels)) return exact;
+  const prefix = prototypeBranchPrefix(issue);
+  const checkout = entriesFromPorcelain(porcelain).find(
+    (entry) => !entry.bare && entry.branch?.startsWith(prefix) === true,
+  );
+  return checkout?.path ?? null;
+}
+
+// Both the worktree path and its actual branch, so a relaunch after a
+// rename keeps reporting the branch that is really checked out.
+export function issueWorktreeAndBranchFromPorcelain(
+  porcelain: string,
+  issue: number,
+  labels: readonly string[] = [],
+  title = "",
+): { path: string; branch: string } | null {
+  const entry = entriesFromPorcelain(porcelain).find((candidate) => {
+    if (candidate.bare || candidate.branch === null) return false;
+    if (candidate.branch === branchName(issue, labels, title)) return true;
+    return (
+      isPrototype(labels) &&
+      candidate.branch.startsWith(prototypeBranchPrefix(issue))
+    );
+  });
+  if (entry === undefined || entry.branch === null) return null;
+  return { path: entry.path, branch: entry.branch };
+}
+
 export function worktreePathFor(
   projectRoot: string,
   issue: number,
   title: string,
+  labels: readonly string[] = [],
 ): string {
-  return path.join(projectRoot, worktreeName(issue, title));
+  const name = worktreeName(issue, title, labels);
+  return isPrototype(labels)
+    ? path.join(projectRoot, prototypeDir, name)
+    : path.join(projectRoot, name);
 }
 
 // --- git
@@ -209,22 +295,58 @@ export function usesBareLayout(): boolean {
   return isBareLayout(listPorcelain());
 }
 
-export function worktreePath(issue: number, title: string): string {
+export function worktreePath(
+  issue: number,
+  title: string,
+  labels: readonly string[] = [],
+): string {
   return worktreePathFor(
     projectRootFromPorcelain(listPorcelain()),
     issue,
     title,
+    labels,
   );
 }
 
 // The branch's existing checkout wins over the title-derived path, so a
 // relaunch resumes the earlier worktree even after the issue was renamed.
-export function laneWorktreePath(issue: number, title: string): string {
+export function laneWorktreePath(
+  issue: number,
+  title: string,
+  labels: readonly string[] = [],
+): string {
   const porcelain = listPorcelain();
   return (
-    branchWorktreeFromPorcelain(porcelain, branchName(issue)) ??
-    worktreePathFor(projectRootFromPorcelain(porcelain), issue, title)
+    issueWorktreeFromPorcelain(porcelain, issue, labels, title) ??
+    worktreePathFor(projectRootFromPorcelain(porcelain), issue, title, labels)
+  );
+}
+
+// Resolves both the worktree path and branch for a lane: the existing
+// checkout's actual branch when the worktree is reused, otherwise the
+// title-derived values for a fresh worktree.
+export function laneWorktreeAndBranch(
+  issue: number,
+  title: string,
+  labels: readonly string[] = [],
+): { path: string; branch: string } {
+  const porcelain = listPorcelain();
+  const existing = issueWorktreeAndBranchFromPorcelain(
+    porcelain,
+    issue,
+    labels,
+    title,
   );
+  if (existing !== null) return existing;
+  return {
+    path: worktreePathFor(
+      projectRootFromPorcelain(porcelain),
+      issue,
+      title,
+      labels,
+    ),
+    branch: branchName(issue, labels, title),
+  };
 }
 
 export function registeredWorktrees(): Set<string> {
@@ -236,58 +358,96 @@ const normalized = (worktree: string): string => path.resolve(worktree);
 const samePath = (left: string, right: string): boolean =>
   normalized(left) === normalized(right);
 
-export function runsInOwnWorktree(issue: number, title: string): boolean {
-  return samePath(worktreePath(issue, title), currentToplevel());
+export function runsInOwnWorktree(
+  issue: number,
+  title: string,
+  labels: readonly string[] = [],
+): boolean {
+  return samePath(worktreePath(issue, title, labels), currentToplevel());
 }
 
 // --- classification
 
-function checkOwnWorktree(own: string, toplevel: string): WorktreeCheck {
-  return samePath(own, toplevel)
-    ? { status: "ok", message: `verifying in the issue's worktree ${own}` }
-    : {
-        status: "fail",
-        message: `run verification in the issue's worktree ${own}, not in ${toplevel}`,
-      };
+const includesPath = (paths: Iterable<string> = [], target: string): boolean =>
+  [...paths].some((candidate) => samePath(candidate, target));
+
+const failedCheck = (message: string): WorktreeCheck => ({
+  status: "fail",
+  path: null,
+  message,
+});
+
+function checkOwnWorktree(layout: WorktreeLayout, own: string): WorktreeCheck {
+  const { issue, locked, stale } = layout;
+  if (includesPath(stale, own)) {
+    return failedCheck(
+      `#${issue}'s worktree ${own} is stale — its directory is missing; restore it or run \`git worktree prune\``,
+    );
+  }
+  if (includesPath(locked, own)) {
+    return failedCheck(
+      `#${issue}'s worktree ${own} is locked — unlock it with \`git worktree unlock\` first`,
+    );
+  }
+  return { status: "ok", path: own, message: `verifying in the issue's worktree ${own}` };
 }
 
-function checkMainCopy(
-  issue: number,
-  mainCopy: string,
-  toplevel: string,
-): WorktreeCheck {
-  return samePath(mainCopy, toplevel)
-    ? {
-        status: "warn",
-        message: `#${issue} has no git worktree of its own — verifying the main copy`,
-      }
-    : {
-        status: "fail",
-        message: `#${issue} has no git worktree of its own — run verification in the main copy ${mainCopy}, not in ${toplevel}`,
-      };
+function checkMainCopy(layout: WorktreeLayout): WorktreeCheck {
+  const { issue, mainCopy, registered, stale } = layout;
+  if (!includesPath(registered, mainCopy) || includesPath(stale, mainCopy)) {
+    return failedCheck(
+      `#${issue} has no git worktree of its own, and the main copy ${mainCopy} is missing`,
+    );
+  }
+  return {
+    status: "warn",
+    path: mainCopy,
+    message: `#${issue} has no git worktree of its own — verifying the main copy`,
+  };
 }
 
+// Resolves where to verify, wherever the session runs.
 export function classifyWorktree(layout: WorktreeLayout): WorktreeCheck {
-  const { issue, mainCopy, registered, ownWorktree, currentToplevel } = layout;
-  const own =
-    ownWorktree != null &&
-    [...registered].some((worktree) => samePath(worktree, ownWorktree))
-      ? ownWorktree
-      : null;
-  return own !== null
-    ? checkOwnWorktree(own, currentToplevel)
-    : checkMainCopy(issue, mainCopy, currentToplevel);
+  const { registered, ownWorktree } = layout;
+  return ownWorktree != null && includesPath(registered, ownWorktree)
+    ? checkOwnWorktree(layout, ownWorktree)
+    : checkMainCopy(layout);
+}
+
+function staleWorktrees(entries: WorktreeEntry[]): string[] {
+  return entries
+    .filter((entry) => entry.prunable || !existsSync(entry.path))
+    .map((entry) => entry.path);
 }
 
-export function checkWorktree(issue: number): WorktreeCheck {
+function layoutFromGit(
+  issue: number,
+  labels: readonly string[],
+  title: string,
+): WorktreeLayout {
   const porcelain = listPorcelain();
-  return classifyWorktree({
+  const entries = entriesFromPorcelain(porcelain);
+  return {
     issue,
     mainCopy: mainCopyFromPorcelain(porcelain, defaultBranches()),
-    registered: worktreesFromPorcelain(porcelain),
-    currentToplevel: currentToplevel(),
-    ownWorktree: branchWorktreeFromPorcelain(porcelain, branchName(issue)),
-  });
+    registered: entries.map((entry) => entry.path),
+    ownWorktree: issueWorktreeFromPorcelain(porcelain, issue, labels, title),
+    locked: entries.filter((entry) => entry.locked).map((entry) => entry.path),
+    stale: staleWorktrees(entries),
+  };
+}
+
+// Never throws: a git failure becomes a failed check.
+export function checkWorktree(
+  issue: number,
+  labels: readonly string[] = [],
+  title = "",
+): WorktreeCheck {
+  try {
+    return classifyWorktree(layoutFromGit(issue, labels, title));
+  } catch (error) {
+    return failedCheck(`could not resolve the worktree: ${gitErrorReason(error)}`);
+  }
 }
 
 // --- main copy sync
@@ -338,6 +498,13 @@ function redactedGitError(error: unknown): string {
   return line ? `: ${line.replace(/\/\/[^/\s@]+@/g, "//***@")}` : "";
 }
 
+function gitErrorReason(error: unknown): string {
+  const stderr = redactedGitError(error);
+  if (stderr) return stderr.slice(": ".length);
+  const message = error instanceof Error ? error.message : String(error);
+  return message.split("\n")[0];
+}
+
 // Never waits for a credential prompt: an unattended launch would hang.
 async function gitAsync(args: string[]): Promise<string> {
   const { stdout } = await execFileAsync("git", args, {

package/agents/skills/yaawn-prepare-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yaawn-prepare-plan
-description: "Turn a new idea or an existing GitHub issue into an approved work item — a story, refactor, spike, bug report, or other change — pick or confirm its type, draft or reconsider it, grill it, and save it to the issue — ready for /yaawn-create-plan (spikes go to a human instead). Use when: preparing work for planning, new idea, refine issue #N, write and grill a story, write a refactor, write a spike, write a bug report, write an other change, check if a story needs splitting, get a work item ready for planning."
+description: "Turn a new idea or an existing GitHub issue into an approved work item — a story, refactor, spike, bug report, prototype, or other change — pick or confirm its type, draft or reconsider it, grill it, and save it to the issue — ready for /yaawn-create-plan (spikes go to a human instead). Use when: preparing work for planning, new idea, refine issue #N, write and grill a story, write a refactor, write a spike, write a bug report, write a prototype, write an other change, check if a story needs splitting, get a work item ready for planning."
 argument-hint: "[<issue>]"
 disable-model-invocation: true
 metadata:
@@ -10,7 +10,7 @@ metadata:
 
 # Prepare Plan
 
-Turn a new idea or an existing issue into an approved work item on GitHub — a story, refactor, spike, bug report, or other change. Run it in a **new session**, in the product owner persona (`.agents/personas/yaawn-product-owner.md`).
+Turn a new idea or an existing issue into an approved work item on GitHub — a story, refactor, spike, bug report, prototype, or other change. Run it in a **new session**, in the product owner persona (`.agents/personas/yaawn-product-owner.md`).
 
 This skill is a thin orchestrator. It owns only the greeting, the choice of work item type, the order of the steps, the handover between them, the final approval, and the routing. All drafting is done by the skills it calls, by step number — never duplicate their rules here.
 
@@ -22,7 +22,7 @@ Out of scope: technical or design grilling, implementation plans, and code or an
 
 This is the first of the plan skills: `/yaawn-prepare-plan` → `/yaawn-create-plan` → `/yaawn-save-plan` → `/yaawn-implement-plan` → `/yaawn-verify-executed-plan`. Every skill starts in a new session and works only from files and the issue — never from an earlier conversation.
 
-- The issue is the only artifact. This skill writes no decision log and no plan file.
+- The issue is the only artifact. This skill writes no decision log and no plan file — the grill's decisions and open questions are saved into the issue's `### Design Decisions` and `### Open Questions` tables by the writer skill, so `/yaawn-create-plan` does not re-ask them.
 - Leave the `Yaawn: To Be Refined` label in place; `/yaawn-save-plan` removes it.
 - `<issue>` is optional. If given, it must be a positive integer (digits only, no `#`, URL, spaces, or other characters); otherwise stop and ask for a valid number. Use it in commands only after this check.
 - Never interpolate issue bodies, comments, titles, or other user text into a shell command. Write them to a file and pass it with `--body-file`.
@@ -33,37 +33,38 @@ This is the first of the plan skills: `/yaawn-prepare-plan` → `/yaawn-create-p
 
 There is one type per template in `.github/ISSUE_TEMPLATE/`. The type label comes from the template's frontmatter `labels`.
 
-| Type         | Use when the work…                               | Type label        | Route                     | Grill                     | After save           |
-| ------------ | ------------------------------------------------ | ----------------- | ------------------------- | ------------------------- | -------------------- |
-| Story        | adds or changes behavior users see               | `Yaawn: Story`    | [Story path](#story-path) | `/yaawn-grill-story`      | `/yaawn-create-plan` |
-| Refactor     | changes the inside, with no user-visible change  | `Yaawn: Refactor` | `/yaawn-write-refactor`   | `/yaawn-grill-refactor`   | `/yaawn-create-plan` |
-| Spike        | must answer one open question before work starts | `Yaawn: Spike`    | `/yaawn-write-spike`      | `/yaawn-grill-spike`      | a human answers it   |
-| Bug report   | fixes behavior that is wrong today               | `Yaawn: Bug`      | `/yaawn-write-bug-report` | `/yaawn-grill-bug-report` | `/yaawn-create-plan` |
-| Other change | matches none of the four types                   | `Yaawn: Other`    | `/yaawn-write-other`      | `/yaawn-grill-other`      | `/yaawn-create-plan` |
+| Type         | Use when the work…                                | Type label         | Route                     | Grill                     | After save           |
+| ------------ | ------------------------------------------------- | ------------------ | ------------------------- | ------------------------- | -------------------- |
+| Story        | adds or changes behavior users see                | `Yaawn: Story`     | [Story path](#story-path) | `/yaawn-grill-story`      | `/yaawn-create-plan` |
+| Refactor     | changes the inside, with no user-visible change   | `Yaawn: Refactor`  | `/yaawn-write-refactor`   | `/yaawn-grill-refactor`   | `/yaawn-create-plan` |
+| Spike        | must answer one open question before work starts  | `Yaawn: Spike`     | `/yaawn-write-spike`      | `/yaawn-grill-spike`      | a human answers it   |
+| Bug report   | fixes behavior that is wrong today                | `Yaawn: Bug`       | `/yaawn-write-bug-report` | `/yaawn-grill-bug-report` | `/yaawn-create-plan` |
+| Prototype    | builds a throwaway version to test with customers | `Yaawn: Prototype` | `/yaawn-write-prototype`  | `/yaawn-grill-prototype`  | `/yaawn-create-plan` |
+| Other change | matches none of the five types                    | `Yaawn: Other`     | `/yaawn-write-other`      | `/yaawn-grill-other`      | `/yaawn-create-plan` |
 
 ## 1. Greet and choose the type
 
-- **New idea (no `<issue>`):** greet the user and offer the five types through the ask tool, each with its one-line "use when", plus a last option: **"Not sure / none of these"**.
+- **New idea (no `<issue>`):** greet the user and offer the six types through the ask tool, each with its one-line "use when" — for a prototype: "Prototype — build a throwaway version of a feature idea to test with customers and learn what works" — plus a last option: **"Not sure / none of these"**.
 - **Existing issue:** read it with `gh issue view <issue> --json title,body,labels,comments`. Infer the type from its type label (table above) and ask the user to confirm it.
   - **Confirmed:** continue with that type.
   - **Override:** warn that re-typing rewrites the issue's body to the new type's template — the current body's sections are replaced — and ask for explicit confirmation. Only after it, continue with the new type; content worth keeping is carried over only with the user's agreement. Without confirmation, keep the inferred type.
   - **No type label:** fall back to the picker, as for a new idea.
-- **"Not sure / none of these":** help find the right shape — ask what the work changes: behavior users see (story), the inside without user-visible change (refactor), wrong behavior today (bug report), or nothing yet because a question must be answered first (spike). Offer the matching type. If nothing fits, offer **other change** as the last resort; if the user declines it too, say so and stop — never save anything on this path.
+- **"Not sure / none of these":** help find the right shape — ask what the work changes: behavior users see (story), the inside without user-visible change (refactor), wrong behavior today (bug report), nothing yet because a question must be answered first (spike), or a throwaway version of a feature idea to test with customers before committing to it (prototype). Offer the matching type. If nothing fits, offer **other change** as the last resort; if the user declines it too, say so and stop — never save anything on this path.
 
 If a writer skill later finds the item is a different type (for example a refactor that changes user-visible behavior), return here and re-offer the type choice.
 
 ## 2. Route
 
 - **Story:** follow the [Story path](#story-path). For a confirmed re-type, tell `/yaawn-write-user-story` to draft the body from the story template as for a new story, and swap the type label after the save as in [Writer path](#writer-path) step 3.
-- **Refactor, spike, bug report, other change:** follow the [Writer path](#writer-path) with the routed writer and grill skills from the table.
+- **Refactor, spike, bug report, prototype, other change:** follow the [Writer path](#writer-path) with the routed writer and grill skills from the table.
 
 ## Writer path
 
-1. **Draft, grill, check:** run step 1 of the routed writer skill (draft or refine), then the routed type's `/yaawn-grill-*` skill from the table — tell it to skip its scope check and that this skill defines what happens when the grill ends: continue with the writer's step 3 (quality check). The grill replaces the writer's step 2 (light grill) in this session only. For an existing issue, the writer reads the issue itself; for a confirmed re-type, tell it to build the body from its own template as for a new issue.
-2. **Approve:** present the finished fields and ask the user to approve them through the ask tool. Wait for it — never create or edit the issue before.
-3. **Save:** run the writer's step 4 ("Saving the issue"). Tell it this approval is the one its saving step 1 asks for — do not ask again. It reads the template frontmatter and saves with `--body-file`. For a confirmed re-type, also swap the old type label for the new one: `gh issue edit <issue> --remove-label "<old type label>" --add-label "<new type label>"`, with both labels taken from the template frontmatters.
+1. **Draft, grill, check:** run step 1 of the routed writer skill (draft or refine), then the routed type's `/yaawn-grill-*` skill from the table — tell it to skip its scope check and that this skill defines what happens when the grill ends: continue with the writer's step 3 (quality check). The grill replaces the writer's step 2 (light grill) in this session only. When the grill ends, keep the `## Decisions` and `## Open questions` sections from its Result for the save. For an existing issue, the writer reads the issue itself; for a confirmed re-type, tell it to build the body from its own template as for a new issue.
+2. **Approve:** present the finished fields, together with the grill's decisions and open questions, and ask the user to approve them through the ask tool. Wait for it — never create or edit the issue before.
+3. **Save:** run the writer's step 4 ("Approve and save"), which follows its "Saving the issue". Tell it this approval is the one its saving step 1 asks for — do not ask again. Pass it the grill's `## Decisions` and `## Open questions` sections as they are, so it fills the issue's `### Design Decisions` and `### Open Questions` tables in the same save — except for a spike, whose template has neither table, so nothing is passed. It reads the template frontmatter and saves with `--body-file`. For a confirmed re-type, also swap the old type label for the new one: `gh issue edit <issue> --remove-label "<old type label>" --add-label "<new type label>"`, with both labels taken from the template frontmatters.
 4. **Hand off:**
-   - **Refactor, bug report, other change:** tell the user to start a **new session** and run `/yaawn-create-plan <issue>` there.
+   - **Refactor, bug report, prototype, other change:** tell the user to start a **new session** and run `/yaawn-create-plan <issue>` there. For a prototype, add that it is built on a never-merged `prototype/` branch and that `/yaawn-extract-learnings <issue>` replaces `/yaawn-verify-executed-plan` after `/yaawn-implement-plan`.
    - **Spike:** the session ends here — a human answers the spike. There is no handoff to `/yaawn-create-plan`; tell the user so.
 
 ## Story path
@@ -97,7 +98,7 @@ Then, in this session:
 
 ### 4. Grill the story
 
-Run `/yaawn-grill-story` on the story. Tell it to skip its scope check — the sprint-fit check or the split assessment already covered scope — and that this skill defines what happens when the grill ends: continue with step 5.
+Run `/yaawn-grill-story` on the story. Tell it to skip its scope check — the sprint-fit check or the split assessment already covered scope — and that this skill defines what happens when the grill ends: continue with step 5. Keep the `## Decisions` and `## Open questions` sections from its Result for step 6.
 
 ### 5. Quality check
 
@@ -105,6 +106,6 @@ Run the quality check from `/yaawn-write-user-story` step 6 on the grilled story
 
 ### 6. Approve and save
 
-Ask the user to approve the finished story, then create or update the issue with `/yaawn-write-user-story` step 8. Leave the `Yaawn: To Be Refined` label in place.
+Ask the user to approve the finished story, together with the grill's decisions and open questions, then create or update the issue with `/yaawn-write-user-story` step 8. Pass it the grill's `## Decisions` and `## Open questions` sections as they are, so it fills the issue's `### Design Decisions` and `### Open Questions` tables in the same save. Leave the `Yaawn: To Be Refined` label in place.
 
 End by telling the user to start a **new session** and run `/yaawn-create-plan <issue>` there.

package/agents/skills/yaawn-verify-executed-plan/SKILL.md

@@ -16,23 +16,38 @@ It takes the same issue number as `/yaawn-implement-plan` and resolves the same
 
 Out of scope: implementing or fixing anything, committing or pushing, writing or editing plans, editing the issue — step 7 is the only exception: it opens a pull request for the issue's branch and removes the issue's `Yaawn: Ready To Implement` and `Yaawn: implementation-group-<n>` labels. On failure, report and stop — fixing is `/yaawn-implement-plan`'s job.
 
-Ask for the issue number if it is not given. Run all commands from the repo root.
+Prototypes (label `Yaawn: Prototype`) are never verified or merged — after `/yaawn-implement-plan`, they go to `/yaawn-extract-learnings` instead; pre-flight stops on them.
+
+It works from any worktree of the project — like `/yaawn-save-plan`, the session does not have to run in the issue's worktree. The script resolves the issue's worktree itself and does all its work there.
+
+Ask for the issue number if it is not given. Run all commands from the root of the worktree the session runs in.
 
 ## 1. Pre-flight
 
+First — before any worktree or branch lookup or other work — read the issue's labels:
+
+```sh
+gh issue view <issue> --json labels --jq '.labels[].name'
+```
+
+- The labels include exactly `Yaawn: Prototype`: stop — `#<issue> is a prototype — prototypes are never verified or merged. Extract its learnings with /yaawn-extract-learnings <issue> instead.` Do not offer to continue anyway, and never open a pull request.
+- The labels cannot be read (`gh` fails, the issue is not found): stop and report the error — never continue without knowing the issue is not a prototype.
+
+Then run the pre-flight script:
+
 ```sh
 npx tsx .agents/skills/yaawn-verify-executed-plan/scripts/overnight.ts preflight <issue>
 ```
 
-It first checks where it runs. `/yaawn-implement-plan` runs every issue in its own git worktree inside the project (`<project>/yaawn-<issue>-<slug>`, branch `yaawn/<issue>`), next to the main copy `<project>/main` — the bare-repo layout described in [`.agents/yaawn-worktrees.md`](../../yaawn-worktrees.md):
+It first resolves where to verify, wherever the session runs, and moves there. `/yaawn-implement-plan` runs every issue in its own git worktree inside the project (`<project>/yaawn-<issue>-<slug>`, branch `yaawn/<issue>`), next to the main copy `<project>/main` — the bare-repo layout described in [`.agents/yaawn-worktrees.md`](../../yaawn-worktrees.md):
 
-- The issue has its own worktree and the session runs elsewhere: `FAIL` naming the worktree's path.
-- The issue has no worktree of its own and the session runs in another issue's worktree: `FAIL` pointing to the main copy `<project>/main`.
-- The issue has no worktree of its own (implemented before every run got one, or by hand) and the session runs in the main copy: `WARN #<issue> has no git worktree of its own — verifying the main copy`. Mention the warning to the developer and continue.
+- The issue has its own worktree: `worktree: verifying in the issue's worktree <path>`.
+- The issue has no worktree of its own (implemented before every run got one, or by hand): `WARN #<issue> has no git worktree of its own — verifying the main copy`. Mention the warning to the developer and continue.
+- The target cannot be resolved — the issue's worktree is locked or stale, the main copy is missing, or git fails: `FAIL` with the reason.
 
-It prints the target, the verification commands — or a note when none are configured — and checks `gh`, `caffeinate`, that no verification is already running for the issue, and that the target's plan is fully executed — every step in `.yaawn/plans/yaawn-<target>-progress.md` is `- [x]`. It also lists uncommitted changes (files under `.yaawn/plans/` are left out), because the suites run against the working tree.
+Everything after that — the progress log, uncommitted changes, the suites — is read and run in the resolved worktree. It prints the target, the verification commands — or a note when none are configured — and checks `gh`, `caffeinate`, that no verification is already running for the issue, and that the target's plan is fully executed — every step in `.yaawn/plans/yaawn-<target>-progress.md` is `- [x]`. It also lists uncommitted changes (files under `.yaawn/plans/` are left out), because the suites run against the working tree.
 
-- Any `FAIL` line: stop and report it. A worktree `FAIL` means: start a new session in the named directory and run this skill there. A plan that is not fully executed means `/yaawn-implement-plan` has not finished — finish it first.
+- Any `FAIL` line: stop and report it. A worktree `FAIL` means: fix what it names (unlock, restore, or prune the worktree), then run this skill again. A plan that is not fully executed means `/yaawn-implement-plan` has not finished — finish it first.
 - Uncommitted changes listed: show them and ask whether to continue.
 - No verification commands configured: skip steps 3 and 4 — the manual checks are the verification.
 
@@ -40,7 +55,7 @@ It prints the target, the verification commands — or a note when none are conf
 
 `.yaawn/yaawn-definition-of-done.md` is the single source of truth for the standard steps — never read Definition of Done steps from the llm-plan file or the issue. If the file is missing or lists no steps, there are no standard steps to assign.
 
-For each target, read `.yaawn/plans/yaawn-<target>-progress.md` to see which steps the overnight session already checked off or listed as manual checks.
+For each target, read `.yaawn/plans/yaawn-<target>-progress.md` in the worktree pre-flight resolved to see which steps the overnight session already checked off or listed as manual checks.
 
 Every standard Definition of Done step must, for every target, be accounted for in exactly one of three places:
 
@@ -109,17 +124,17 @@ Keep the Mac on power and the editor open. I will report the results here when t
 
 Then end your turn and wait. Do not poll the terminal or the summary file — the harness notifies you when the background process ends. Then continue with step 4.
 
-**When the developer asks about the verification later**, in this chat or a new one, check in this order and stop at the first match:
+**When the developer asks about the verification later**, in this chat or a new one, first resolve the issue's worktree: the path pre-flight printed, or — in a new chat — the entry on branch `yaawn/<issue>` in `git worktree list`, falling back to the main copy `<project>/main` when the issue has none. Read every file below from there, never from the session's worktree. Then check in this order and stop at the first match:
 
 1. `pgrep -f "yaawn-verify-executed-plan/scripts/overnight.ts run <issue>( |$)"` finds a process → say the verification is still running. Never report a summary while the run is active.
-2. `.yaawn/plans/yaawn-<issue>-verify-summary.md` exists → continue with step 4.
+2. `<resolved worktree>/.yaawn/plans/yaawn-<issue>-verify-summary.md` exists → continue with step 4.
 3. Otherwise → say the verification was stopped before it ended and that launching it again reruns it.
 
 ## 4. Report the results
 
 This step only applies when the overnight verification ran.
 
-Read `.yaawn/plans/yaawn-<issue>-verify-summary.md`. Report one line per suite — pass/fail and the failing specs only. Do not paste full logs; they are in the per-suite log files.
+Read `.yaawn/plans/yaawn-<issue>-verify-summary.md` in the resolved worktree. Report one line per suite — pass/fail and the failing specs only. Do not paste full logs; they are in the per-suite log files.
 
 If a suite failed: keep the working files, report the failures, and tell the developer to fix them (resuming `/yaawn-implement-plan` if a step has to be redone) and then start a new session and run this skill again. Do not continue to the manual checks.
 
@@ -144,11 +159,11 @@ Tell the developer to commit and push the issue's branch, then — once they con
 npx tsx .agents/skills/yaawn-verify-executed-plan/scripts/overnight.ts finish <issue>
 ```
 
-It repeats the worktree check, requires the summary's `Result: passed` when verification commands are configured, and requires a branch other than the default branch, no uncommitted changes outside `.yaawn/plans/`, an upstream, and nothing unpushed. Then it finds the branch's open pull request or opens one (`Closes #<issue>`, assigned to the developer), removes the issue's `Yaawn: Ready To Implement` label together with its `Yaawn: implementation-group-<n>` labels (through `/yaawn-implement-plan`'s shared group-label reset — a failed reset only warns), and prints the link. It never commits or pushes.
+It works from any worktree: it repeats the worktree check, moves into the issue's worktree (or the main copy), and checks the issue's branch there. It requires the summary's `Result: passed` when verification commands are configured, and requires a branch other than the default branch, no uncommitted changes outside `.yaawn/plans/`, an upstream, and nothing unpushed. Then it finds the open pull request for the issue's branch or opens one (`Closes #<issue>`, assigned to the developer), removes the issue's `Yaawn: Ready To Implement` label together with its `Yaawn: implementation-group-<n>` labels (through `/yaawn-implement-plan`'s shared group-label reset — a failed reset only warns), and prints the link. It never commits or pushes.
 
 Relay its output:
 
 - `pull request opened: <url>` or `pull request already open: <url>`: report the link. The issue closes when the pull request is merged.
-- Any `FAIL` line: report it and tell the developer what to do — commit and push, or switch to the issue's branch or worktree — and then run this step again.
+- Any `FAIL` line: report it and tell the developer what to do — commit and push in the issue's worktree, or fix the worktree the check names — and then run this step again.
 
 Never commit or push yourself, and never offer to close the issue.