gsd-pi 2.79.0 → 2.80.0-dev.0aaa4fc17

package/src/resources/extensions/gsd/planning-path-scope.ts

@@ -0,0 +1,35 @@
+import { isAbsolute, relative, resolve } from "node:path";
+import { normalizePlannedFileReference } from "./files.js";
+
+export interface PlanningPathScopeField {
+  field: string;
+  values: string[];
+}
+
+function isInsideBase(basePath: string, candidate: string): boolean {
+  const base = resolve(basePath);
+  const abs = resolve(candidate);
+  const rel = relative(base, abs);
+  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
+}
+
+/**
+ * Planning IO fields are execution contracts. Absolute paths are only safe when
+ * they stay inside the active working directory; in worktree mode, an absolute
+ * path to the original checkout makes executors edit the wrong tree.
+ */
+export function validatePlanningPathScope(
+  basePath: string,
+  fields: PlanningPathScopeField[],
+): string | null {
+  for (const { field, values } of fields) {
+    for (const raw of values) {
+      const candidate = normalizePlannedFileReference(raw);
+      if (!isAbsolute(candidate)) continue;
+      if (isInsideBase(basePath, candidate)) continue;
+      return `${field} contains absolute path outside working directory: ${candidate}. Use a path relative to ${basePath}.`;
+    }
+  }
+
+  return null;
+}

package/src/resources/extensions/gsd/post-execution-checks.ts

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Post-execution validation checks for completed GSD task output.
+
 /**
  * Post-Execution Checks — Validate task output after execution completes.
  *
@@ -15,7 +18,7 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { resolve, dirname, join, extname } from "node:path";
-import type { TaskRow } from "./gsd-db.ts";
+import type { TaskRow } from "./db-task-slice-rows.js";
 
 // ─── Result Types ────────────────────────────────────────────────────────────
 
@@ -144,12 +147,30 @@ export function resolveImportPath(
     if (existsSync(directPath)) {
       return { exists: true, resolvedPath: directPath };
     }
-    // Only .js/.jsx/.mjs/.cjs imports legitimately fall through for the TS
-    // ESM convention (.js → .ts). Any other explicit extension (.css, .json,
-    // .svg, images, fonts, .ts, .tsx, …) must stay unresolved when the direct
-    // path is missing — otherwise a stray `./missing.css.ts` could shadow a
-    // genuinely missing `./missing.css` import.
-    if (![".js", ".jsx", ".mjs", ".cjs"].includes(explicitExt)) {
+
+    // Known concrete extensions that should NOT fall through to code-shadow
+    // probing when missing. This preserves the "missing.css must stay missing"
+    // guarantee while still allowing dotted module stems like ./route.server
+    // to resolve as ./route.server.ts.
+    const nonFallbackExtensions = new Set([
+      ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+      ".json", ".css", ".scss", ".sass", ".less", ".styl",
+      ".svg", ".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".ico", ".bmp",
+      ".woff", ".woff2", ".ttf", ".otf", ".eot",
+    ]);
+    const runtimeFallbackExtensions = new Set([".js", ".jsx", ".mjs", ".cjs"]);
+    const dottedStemFallbackExtensions = new Set([".server", ".client", ".webhook"]);
+
+    if (
+      explicitExt !== "" &&
+      !runtimeFallbackExtensions.has(explicitExt) &&
+      !nonFallbackExtensions.has(explicitExt) &&
+      !dottedStemFallbackExtensions.has(explicitExt)
+    ) {
+      return { exists: false, resolvedPath: null };
+    }
+
+    if (nonFallbackExtensions.has(explicitExt) && !runtimeFallbackExtensions.has(explicitExt)) {
       return { exists: false, resolvedPath: null };
     }
   }
@@ -222,6 +243,13 @@ export function checkImportResolution(
     const imports = extractRelativeImports(source);
 
     for (const { importPath, lineNum } of imports) {
+      // React Router generated +types modules may not exist on disk during
+      // post-exec checks (generated during framework build). Don't block task
+      // completion on these imports.
+      if (/^\.{1,2}\/\+types\//.test(importPath)) {
+        continue;
+      }
+
       const resolution = resolveImportPath(importPath, file, basePath);
 
       if (!resolution.exists) {

package/src/resources/extensions/gsd/pr-evidence.ts

@@ -0,0 +1,182 @@
+// Project/App: GSD-2
+// File Purpose: Shared pull request evidence generator for GSD shipping paths.
+
+export type PrChangeType = "feat" | "fix" | "refactor" | "test" | "docs" | "chore";
+
+export interface PrEvidenceInput {
+  milestoneId: string;
+  subjectId?: string;
+  subjectKind?: "milestone" | "slice" | "workflow";
+  milestoneTitle?: string;
+  changeType?: PrChangeType;
+  linkedIssue?: string;
+  summaries?: string[];
+  blockers?: string[];
+  roadmapItems?: string[];
+  metrics?: string[];
+  testsRun?: string[];
+  why?: string;
+  how?: string;
+  rollbackNotes?: string[];
+  aiAssisted?: boolean;
+}
+
+export interface PrEvidence {
+  title: string;
+  body: string;
+}
+
+const CHANGE_TYPE_LABELS: Record<PrChangeType, string> = {
+  feat: "New feature or capability",
+  fix: "Bug fix",
+  refactor: "Code restructuring",
+  test: "Adding or updating tests",
+  docs: "Documentation only",
+  chore: "Build, CI, or tooling changes",
+};
+
+// Per-item cap for user-supplied content. 2 KB gives slice titles plus
+// descriptions room while still bounding malicious DoS-via-PR-body input.
+const USER_CONTENT_CAP_BYTES = 2048;
+const TRUNCATION_SUFFIX = " … [truncated]";
+
+// Strips HTML comments, fake commit trailers (Co-Authored-By, Signed-off-by —
+// case-insensitive on the trailer name), and caps total length. Designed to
+// be a no-op for well-formed input; golden fixtures must remain byte-stable.
+// Trailer lines are removed (not rejected) so that a single bad line in an
+// otherwise legitimate description does not block the entire PR.
+function sanitizeUserContent(s: string): string {
+  if (!s) return s;
+  // Strip HTML comments greedily across newlines.
+  let out = s.replace(/<!--[\s\S]*?-->/g, "");
+  // Drop lines that look like commit trailers we do not want forged.
+  out = out
+    .split("\n")
+    .filter((line) => !/^\s*(co-authored-by|signed-off-by)\s*:/i.test(line))
+    .join("\n");
+  if (Buffer.byteLength(out, "utf8") > USER_CONTENT_CAP_BYTES) {
+    const budget = USER_CONTENT_CAP_BYTES - Buffer.byteLength(TRUNCATION_SUFFIX, "utf8");
+    // Truncate by code units to stay safely under the byte budget for ASCII;
+    // for multibyte content we conservatively walk back until under budget.
+    let sliced = out.slice(0, Math.max(0, budget));
+    while (Buffer.byteLength(sliced, "utf8") > budget && sliced.length > 0) {
+      sliced = sliced.slice(0, -1);
+    }
+    out = sliced + TRUNCATION_SUFFIX;
+  }
+  return out;
+}
+
+// Strips HTML comments and fake trailers without applying the length cap.
+// Used for short fields like linkedIssue where truncation would be confusing.
+function sanitizeIssueRef(s: string): string {
+  if (!s) return s;
+  let out = s.replace(/<!--[\s\S]*?-->/g, "");
+  out = out
+    .split("\n")
+    .filter((line) => !/^\s*(co-authored-by|signed-off-by)\s*:/i.test(line))
+    .join("\n");
+  return out;
+}
+
+function normalizeList(values: readonly string[] | undefined): string[] {
+  return (values ?? [])
+    .map((value) => sanitizeUserContent(value).trim())
+    .filter(Boolean);
+}
+
+function changeTypeChecklist(selected: PrChangeType): string[] {
+  return (Object.keys(CHANGE_TYPE_LABELS) as PrChangeType[]).map((type) => {
+    const checked = type === selected ? "x" : " ";
+    return `- [${checked}] \`${type}\` - ${CHANGE_TYPE_LABELS[type]}`;
+  });
+}
+
+function bulletList(values: readonly string[], fallback: string): string {
+  if (values.length === 0) return `- ${fallback}`;
+  return values.map((value) => `- ${value}`).join("\n");
+}
+
+export function buildPrEvidence(input: PrEvidenceInput): PrEvidence {
+  const subjectId = input.subjectId?.trim() || input.milestoneId;
+  const subjectKind = input.subjectKind ?? "milestone";
+  const subjectTitle = input.milestoneTitle?.trim() || subjectId;
+  const changeType = input.changeType ?? "feat";
+  const summaries = normalizeList(input.summaries);
+  const blockers = normalizeList(input.blockers);
+  const roadmapItems = normalizeList(input.roadmapItems);
+  const metrics = normalizeList(input.metrics);
+  const testsRun = normalizeList(input.testsRun);
+  const rollbackNotes = normalizeList(input.rollbackNotes);
+  // linkedIssue is sanitized but not length-capped: legitimate issue refs
+  // are short by nature, and truncating "Closes #123" would be unhelpful.
+  const linkedIssueRaw = input.linkedIssue ? sanitizeIssueRef(input.linkedIssue).trim() : "";
+  const linkedIssue = linkedIssueRaw || "Not specified. Add an issue link before marking this PR ready if CONTRIBUTING.md requires one.";
+  const why = (input.why ? sanitizeUserContent(input.why).trim() : "") || `${capitalize(subjectKind)} work is complete and ready for review.`;
+  const how = (input.how ? sanitizeUserContent(input.how).trim() : "") || "Generated from GSD evidence and local workflow artifacts.";
+  const title = `${changeType}: ${subjectTitle}`;
+
+  const sections: string[] = [
+    "## TL;DR",
+    "",
+    `**What:** Ship ${subjectKind} ${subjectId} - ${subjectTitle}`,
+    `**Why:** ${why}`,
+    `**How:** ${how}`,
+    "",
+    "## What",
+    "",
+    summaries.length > 0 ? summaries.join("\n\n") : `${capitalize(subjectKind)} ${subjectId} completed.`,
+  ];
+
+  if (blockers.length > 0) {
+    sections.push("", "## Blockers", "", blockers.map((blocker) => `- ${blocker}`).join("\n"));
+  }
+
+  sections.push(
+    "",
+    "## Why",
+    "",
+    why,
+    "",
+    "## How",
+    "",
+    how,
+    "",
+    "## Linked Issue",
+    "",
+    linkedIssue,
+  );
+
+  if (roadmapItems.length > 0) {
+    sections.push("", "## Roadmap", "", roadmapItems.join("\n"));
+  }
+
+  if (metrics.length > 0) {
+    sections.push("", "## Metrics", "", bulletList(metrics, "No metrics recorded."));
+  }
+
+  sections.push(
+    "",
+    "## Tests Run",
+    "",
+    bulletList(testsRun, "Not specified. Add exact verification commands before requesting review."),
+    "",
+    "## Change Type",
+    "",
+    ...changeTypeChecklist(changeType),
+    "",
+    "## Rollback And Compatibility",
+    "",
+    bulletList(rollbackNotes, "No behavior-changing rollback notes recorded."),
+  );
+
+  if (input.aiAssisted !== false) {
+    sections.push("", "## AI Assistance Disclosure", "", "This PR was prepared with AI assistance.");
+  }
+
+  return { title, body: sections.join("\n") };
+}
+
+function capitalize(value: string): string {
+  return value.slice(0, 1).toUpperCase() + value.slice(1);
+}

package/src/resources/extensions/gsd/pre-execution-checks.ts

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Pre-execution validation checks for GSD task plans.
+
 /**
  * Pre-Execution Checks — Validate task plans before execution begins.
  *
@@ -18,7 +21,7 @@ import { existsSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
-import type { TaskRow } from "./gsd-db.ts";
+import type { TaskRow } from "./db-task-slice-rows.js";
 import type { PreExecutionCheckJSON } from "./verification-evidence.ts";
 
 const NPM_COMMAND = process.platform === "win32" ? "npm.cmd" : "npm";

package/src/resources/extensions/gsd/preferences-types.ts

@@ -154,8 +154,26 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "planning_depth",
 ]);
 
-/** Canonical list of all dispatch unit types. */
-export const KNOWN_UNIT_TYPES = [
+/**
+ * Broad union of every recognized unit-type *label* used across the codebase.
+ *
+ * This intentionally covers more than the manifest-tracked dispatch units in
+ * `unit-context-manifest.ts:KNOWN_UNIT_TYPES`. Examples that live here but not
+ * in the manifest:
+ * - `discuss-slice` — dispatched by `guided-flow.ts` rather than auto-mode;
+ *   composer falls through to default behavior via `resolveManifest()` null path.
+ * - `worktree-merge` — used as a model-routing case, prompt-template name, and
+ *   commit-message label, not as an LLM-dispatched unit.
+ *
+ * Used by `preferences-validation.ts` to validate user-provided unit-type
+ * references in preferences (model overrides, skill rules, etc.) — preferences
+ * may legitimately reference any label, including non-dispatched ones.
+ *
+ * The manifest-strict subset lives in `unit-context-manifest.ts:KNOWN_UNIT_TYPES`
+ * and is enforced 1:1 against `UNIT_MANIFESTS` by the parity test in
+ * `tests/unit-context-manifest.test.ts`.
+ */
+export const KNOWN_UNIT_LABELS = [
   "research-milestone", "plan-milestone", "research-slice", "plan-slice", "refine-slice",
   "execute-task", "reactive-execute", "gate-evaluate", "complete-slice", "replan-slice", "reassess-roadmap",
   "run-uat", "complete-milestone", "validate-milestone", "rewrite-docs",
@@ -164,7 +182,7 @@ export const KNOWN_UNIT_TYPES = [
   "workflow-preferences", "discuss-project", "discuss-requirements",
   "research-decision", "research-project",
 ] as const;
-export type UnitType = (typeof KNOWN_UNIT_TYPES)[number];
+export type UnitLabel = (typeof KNOWN_UNIT_LABELS)[number];
 
 
 export const SKILL_ACTIONS = new Set(["use", "prefer", "avoid"]);
@@ -343,7 +361,8 @@ export interface GSDPreferences {
   /**
    * Tool-output sandboxing via gsd_exec. Keeps sub-session context windows
    * clean by running scripts in a subprocess and only surfacing a short
-   * digest. See `ContextModeConfig`. Default: disabled.
+   * digest. See `ContextModeConfig`. Default: enabled unless explicitly
+   * disabled with `context_mode.enabled: false`.
    */
   context_mode?: ContextModeConfig;
   token_profile?: TokenProfile;

package/src/resources/extensions/gsd/preferences-validation.ts

@@ -14,7 +14,7 @@ import { normalizeStringArray } from "../shared/format-utils.js";
 
 import {
   KNOWN_PREFERENCE_KEYS,
-  KNOWN_UNIT_TYPES,
+  KNOWN_UNIT_LABELS,
 
   SKILL_ACTIONS,
   type WorkflowMode,
@@ -441,7 +441,7 @@ export function validatePreferences(preferences: GSDPreferences): {
   if (preferences.post_unit_hooks && Array.isArray(preferences.post_unit_hooks)) {
     const validHooks: PostUnitHookConfig[] = [];
     const seenNames = new Set<string>();
-    const knownUnitTypes = new Set<string>(KNOWN_UNIT_TYPES);
+    const knownUnitTypes = new Set<string>(KNOWN_UNIT_LABELS);
     for (const hook of preferences.post_unit_hooks) {
       if (!hook || typeof hook !== "object") {
         errors.push("post_unit_hooks entry must be an object");
@@ -503,7 +503,7 @@ export function validatePreferences(preferences: GSDPreferences): {
   if (preferences.pre_dispatch_hooks && Array.isArray(preferences.pre_dispatch_hooks)) {
     const validPreHooks: PreDispatchHookConfig[] = [];
     const seenPreNames = new Set<string>();
-    const knownUnitTypes = new Set<string>(KNOWN_UNIT_TYPES);
+    const knownUnitTypes = new Set<string>(KNOWN_UNIT_LABELS);
     const validActions = new Set(["modify", "skip", "replace"]);
     for (const hook of preferences.pre_dispatch_hooks) {
       if (!hook || typeof hook !== "object") {

package/src/resources/extensions/gsd/process-task-path.ts

@@ -0,0 +1,81 @@
+// Project/App: GSD-2
+// File Purpose: Canonical process recommendations for routing work by task size.
+
+export type ProcessTaskSize =
+  | "hotfix"
+  | "bugfix"
+  | "small-feature"
+  | "large-feature"
+  | "architecture-change";
+
+export interface ProcessTaskPath {
+  taskSize: ProcessTaskSize;
+  label: string;
+  templateId: string;
+  command: string;
+  phases: string[];
+  guidance: string;
+}
+
+const TASK_PATHS: Record<ProcessTaskSize, ProcessTaskPath> = {
+  hotfix: {
+    taskSize: "hotfix",
+    label: "Hotfix",
+    templateId: "hotfix",
+    command: "/gsd start hotfix <description>",
+    phases: ["fix", "ship"],
+    guidance: "Use for urgent production fixes that need minimal ceremony and fast verification.",
+  },
+  bugfix: {
+    taskSize: "bugfix",
+    label: "Bugfix",
+    templateId: "bugfix",
+    command: "/gsd start bugfix <description> --issue <ref>",
+    phases: ["triage", "fix", "verify", "ship"],
+    guidance: "Use for reproducible defects where a linked issue and regression test are expected.",
+  },
+  "small-feature": {
+    taskSize: "small-feature",
+    label: "Small Feature",
+    templateId: "small-feature",
+    command: "/gsd start small-feature <description>",
+    phases: ["scope", "plan", "implement", "verify"],
+    guidance: "Use for contained feature work that does not need the full milestone machinery.",
+  },
+  "large-feature": {
+    taskSize: "large-feature",
+    label: "Large Feature",
+    templateId: "full-project",
+    command: "/gsd discuss <description>, then /gsd auto",
+    phases: ["discuss", "plan", "execute", "verify"],
+    guidance: "Use for multi-slice work that should run through the DB-backed milestone flow.",
+  },
+  "architecture-change": {
+    taskSize: "architecture-change",
+    label: "Architecture Change",
+    templateId: "refactor",
+    command: "/gsd start refactor <description>",
+    phases: ["inventory", "plan", "migrate", "verify"],
+    guidance: "Use for structural changes that require inventory, compatibility notes, and staged verification.",
+  },
+};
+
+export function recommendProcessPath(taskSize: ProcessTaskSize): ProcessTaskPath {
+  return TASK_PATHS[taskSize];
+}
+
+export function listRecommendedProcessPaths(): ProcessTaskPath[] {
+  return [
+    TASK_PATHS.hotfix,
+    TASK_PATHS.bugfix,
+    TASK_PATHS["small-feature"],
+    TASK_PATHS["large-feature"],
+    TASK_PATHS["architecture-change"],
+  ];
+}
+
+export function formatRecommendedProcessPaths(): string {
+  return listRecommendedProcessPaths()
+    .map((path) => `  ${path.taskSize.padEnd(19)} ${path.command}`)
+    .join("\n");
+}

package/src/resources/extensions/gsd/prompt-loader.ts

@@ -10,7 +10,7 @@
  * Templates are snapshotted shortly after module init via warmCache().
  * This keeps import/extension-registration fast while still preventing a
  * running session from being invalidated when another `gsd` launch overwrites
- * ~/.gsd/agent/ with newer templates via initResources(). Without caching, the
+ * the user-local agent tree with newer templates via initResources(). Without caching, the
  * in-memory extension code (which knows variable set A) can read a newer
  * template from disk (which expects variable set B), causing a
  * "template declares {{X}} but no value was provided" crash mid-session.
@@ -57,9 +57,9 @@ export function resolveExtensionDirFromCandidates(
  *
  * `import.meta.url` resolves to whichever copy of this module is executing.
  * On Windows (npm global install via MSYS2 / Git Bash) this can resolve to
- * the npm-global `AppData/Roaming/npm/…` path, which does NOT contain the
- * prompts/ and templates/ subtrees that initResources() copies to
- * `~/.gsd/agent/extensions/gsd/`. Detect the mismatch and fall back to
+ * the npm-global package path, which does NOT contain the prompts/ and
+ * templates/ subtrees that initResources() copies to the user-local agent
+ * extension directory. Detect the mismatch and fall back to
  * the user-local agent directory.
  */
 function resolveExtensionDir(): string {
@@ -74,7 +74,7 @@ const templatesDir = join(__extensionDir, "templates");
 
 /**
  * Return the resolved templates directory path for use in prompts.
- * Avoids hardcoding `~/.gsd/agent/extensions/gsd/templates/` in templates. (#3575)
+ * Avoids hardcoding the user-local templates directory in templates. (#3575)
  */
 export function getTemplatesDir(): string {
   return templatesDir;
@@ -155,6 +155,10 @@ export function loadPrompt(name: string, vars: Record<string, string> = {}): str
   }
 
   const effectiveVars = {
+    templatesDir: getTemplatesDir(),
+    planTemplatePath: join(getTemplatesDir(), "plan.md"),
+    taskPlanTemplatePath: join(getTemplatesDir(), "task-plan.md"),
+    taskSummaryTemplatePath: join(getTemplatesDir(), "task-summary.md"),
     skillActivation: "If a `GSD Skill Preferences` block is present in system context, use it and the `<available_skills>` catalog in your system prompt to decide which skills to load and follow for this unit, without relaxing required verification or artifact rules.",
     ...vars,
   };

package/src/resources/extensions/gsd/prompts/complete-milestone.md

@@ -6,55 +6,60 @@ You are executing GSD auto-mode.
 
 Your working directory is `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` to any other directory.
 
-## Your Role in the Pipeline
+## Mission
 
-All slices are done. You are closing out the milestone — verifying that the assembled work actually delivers the promised outcome, writing the milestone summary, and updating project state. The milestone summary is the final record. After you finish, the system merges the worktree back to the integration branch. If there are queued milestones, the next one starts its own research → plan → execute cycle from a clean slate — the milestone summary is how it learns what was already built.
+All slices are complete. Verify the integrated work, persist milestone completion, refresh project state, and write the final record future milestones will rely on.
 
-Preloaded context below — the roadmap, compact slice-summary excerpts, requirements, decisions, and project context. **Slice summaries are excerpts, not full files.** They include frontmatter fields, section heads (deviations, known limitations, follow-ups), and short narrative only. When drafting LEARNINGS, the Decision Re-evaluation table, or cross-slice narrative, Read the full slice SUMMARY.md files listed under "On-demand Slice Summaries" — do that selectively as needed, not preemptively.
+Preloaded context includes roadmap, requirements, decisions, project context, and compact slice-summary excerpts. Slice summaries are excerpts, not full files: use them first, then selectively read full SUMMARY.md files listed under "On-demand Slice Summaries" only when section headings indicate needed evidence for LEARNINGS, Decision Re-evaluation, deviations, limitations, or cross-slice narrative.
 
 Start with what the excerpts give you. Read full files when the section heads signal richer context you need.
 
-**On-demand Read ordering:** Complete all slice SUMMARY Reads you need for cross-slice synthesis, the Decision Re-evaluation table, and LEARNINGS **before** calling `gsd_complete_milestone` (step 10). Once that tool runs, the milestone is marked complete in the DB — running out of tool budget between step 10 and the LEARNINGS write (step 12) leaves the milestone committed without its LEARNINGS artifact.
+**On-demand Read ordering:** Complete all slice SUMMARY Reads you need for cross-slice synthesis, the Decision Re-evaluation table, and LEARNINGS **before** calling `gsd_complete_milestone` (step 12). Once that tool runs, the milestone is marked complete in the DB, so it must be the final persistent milestone-closeout write.
 
-### Delegate Review Work
+### Closeout Review Mode
 
-This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate review work that benefits from a fresh context window. For non-trivial milestones, delegate before drafting LEARNINGS:
+The inlined context includes a validation status block.
 
-- **Cross-slice integrations or new public APIs** → dispatch the **reviewer** agent with the milestone diff and roadmap; treat its findings as input to your Decision Re-evaluation and LEARNINGS sections.
-- **Touched auth, network, parsing, file IO, shell exec, or crypto** → dispatch the **security** agent for an OWASP-style audit across the merged slices.
-- **Significant test surface added or changed** → dispatch the **tester** agent to assess coverage gaps relative to the milestone success criteria.
+- If it says a passing validation artifact is present, treat that artifact as authoritative for success criteria, requirement coverage, verification classes, and cross-slice integration. Do not delegate fresh reviewer/security/tester audits unless the validation artifact is internally inconsistent with the inlined summaries.
+- If validation is missing, stale, non-pass, or internally inconsistent, use `subagent` for review work needing fresh context before drafting LEARNINGS: cross-slice integrations or new public APIs -> **reviewer**; auth, network, parsing, file IO, shell exec, or crypto -> **security**; significant tests added or changed -> **tester**.
 
-Subagents read the diff and report findings — they do **not** write user source. Apply their feedback into the milestone summary and any captured decisions before calling `gsd_complete_milestone`.
+Subagents report only; they do not write user source. Fold any findings into Decision Re-evaluation and LEARNINGS before completion.
 
 {{inlinedContext}}
 
-Then:
+## Steps
+
 1. Use the **Milestone Summary** output template from the inlined context above
 2. {{skillActivation}}
-3. **Verify code changes exist.** Compare the milestone against its integration branch (usually `main`, `master`, or the recorded integration branch), using the merge-base as the older revision and `HEAD` as the newer revision. If that branch diff lists non-`.gsd/` files, code-change verification passes. If `HEAD` is already the same commit as the integration branch/merge-base (a retry-on-main self-diff), do **not** treat the empty branch diff as proof of missing code. Instead, inspect milestone-scoped commit evidence such as recent commits with `GSD-Unit: {{milestoneId}}` or production `GSD-Task: Sxx/Tyy` trailers whose diff also touches `.gsd/milestones/{{milestoneId}}/`, then check those commits for non-`.gsd/` files. Only record a **verification failure** when neither the branch diff nor milestone-scoped commit evidence shows implementation files.
-4. Verify each **success criterion** from the milestone definition in `{{roadmapPath}}`. For each criterion, confirm it was met with specific evidence from slice summaries, test results, or observable behavior. Record any criterion that was NOT met as a **verification failure**.
-5. Verify the milestone's **definition of done** — all slices are `[x]`, all slice summaries exist, and any cross-slice integration points work correctly. Record any unmet items as a **verification failure**.
-6. If the roadmap includes a **Horizontal Checklist**, verify each item was addressed during the milestone. Note unchecked items in the milestone summary.
-7. Fill the **Decision Re-evaluation** table in the milestone summary. For each key decision from `.gsd/DECISIONS.md` made during this milestone, evaluate whether it is still valid given what was actually built. Flag decisions that should be revisited next milestone.
-8. Validate **requirement status transitions**. For each requirement that changed status during this milestone, confirm the transition is supported by evidence. Requirements can move between Active, Validated, Deferred, Blocked, or Out of Scope — but only with proof.
+3. **Verify code changes exist.** Compare milestone work against the integration branch (`main`, `master`, or recorded branch), using merge-base as older revision and `HEAD` as newer. If the diff lists non-`.gsd/` files, pass. If `HEAD` equals the integration branch/merge-base, treat it as a self-diff retry: inspect milestone-scoped commit evidence (`GSD-Unit: {{milestoneId}}` or production `GSD-Task: Sxx/Tyy` trailers touching `.gsd/milestones/{{milestoneId}}/`) and verify those commits touched non-`.gsd/` files. Record **verification failure** only when neither source shows implementation files.
+4. Verify every **success criterion** from `{{roadmapPath}}`. If passing validation is present, summarize the validation evidence instead of re-auditing it; otherwise verify with evidence from summaries, tests, or observable behavior. Record unmet criteria as **verification failure**.
+5. Verify **definition of done**: all slices `[x]`, summaries exist, and integrations work. If passing validation is present, trust its integration/verification verdict unless inconsistent with current artifacts. Record unmet items as **verification failure**.
+6. If the roadmap includes a **Horizontal Checklist**, verify each item and note unchecked items in the summary.
+7. Fill the **Decision Re-evaluation** table: compare each key `.gsd/DECISIONS.md` decision from this milestone with what shipped, and flag decisions to revisit.
+8. Validate **requirement status transitions**. For each changed requirement, confirm evidence supports the new status. Requirements may move between Active, Validated, Deferred, Blocked, or Out of Scope only with proof.
 
-**DB access safety:** Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` — the engine owns the WAL connection. Use `gsd_milestone_status` to read milestone and slice state. All data you need is already inlined in the context above or accessible via the `gsd_*` tools — never via direct SQL.
+**DB access safety:** Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')`; the engine owns the WAL connection. Use `gsd_milestone_status`, inlined context, or `gsd_*` tools; never direct SQL.
 
 ### Verification Gate — STOP if verification failed
 
-**If ANY verification failure was recorded in steps 3, 4, or 5, you MUST follow the failure path below. Do NOT proceed to step 10.**
+**If ANY verification failure was recorded in steps 3, 4, or 5, you MUST follow the failure path below. Do NOT proceed with steps 9–13.**
 
 **Failure path** (verification failed):
-- Do NOT call `gsd_complete_milestone` — the milestone must not be marked as complete.
+- Do NOT call `gsd_complete_milestone`.
 - Do NOT update `.gsd/PROJECT.md` to reflect completion.
-- Do NOT update `.gsd/REQUIREMENTS.md` to mark requirements as validated.
-- Write a clear summary of what failed and why to help the next attempt.
+- Do NOT update `.gsd/REQUIREMENTS.md` to mark requirements validated.
+- Write a clear failed-verification summary for the next attempt.
 - Say: "Milestone {{milestoneId}} verification FAILED — not complete." and stop.
 
-**Success path** (all verifications passed — continue with steps 9–13):
+**Success path** (all verifications passed):
 
 9. For each requirement whose status changed in step 8, call `gsd_requirement_update` with the requirement ID and updated `status` and `validation` fields — the tool regenerates `.gsd/REQUIREMENTS.md` automatically. Do this BEFORE completing the milestone so requirement updates are persisted.
-10. **Persist completion through `gsd_complete_milestone`.** Call it with the parameters below. The tool updates the milestone status in the DB, renders `{{milestoneSummaryPath}}`, and validates all slices are complete before proceeding.
+10. Update `.gsd/PROJECT.md`: use the `write` tool with `path: ".gsd/PROJECT.md"` and `content` containing the full updated document reflecting milestone completion and current project state. Do NOT use the `edit` tool for this — PROJECT.md is a full-document refresh.
+11. Extract structured learnings from this milestone and persist them to the GSD memory store. Follow the procedure block immediately below — it writes `{{milestoneId}}-LEARNINGS.md` as the audit trail and persists Patterns, Lessons, and Decisions via `capture_thought` (categories: pattern, gotcha/convention, architecture). The memory store is the single source of truth for cross-session durable knowledge (ADR-013).
+
+{{extractLearningsSteps}}
+
+12. **Persist completion through `gsd_complete_milestone`.** Call it with the parameters below. This must be the final persistent write in the unit. The tool updates the milestone status in the DB, renders `{{milestoneSummaryPath}}`, and validates all slices are complete.
 
    **Required parameters:**
    - `milestoneId` (string) — Milestone ID (e.g. M001)
@@ -67,19 +72,15 @@ Then:
    - `keyDecisions` (array of strings) — Key architectural/pattern decisions made during the milestone
    - `keyFiles` (array of strings) — Key files created or modified during the milestone
    - `lessonsLearned` (array of strings) — Lessons learned during the milestone
-   - `verificationPassed` (boolean) — Must be `true` — confirms that code change verification, success criteria, and definition of done checks all passed before completion
+   - `verificationPassed` (boolean) — Must be `true`; confirms code-change verification, success criteria, and definition-of-done checks all passed
 
    **Optional parameters:**
    - `followUps` (string) — Follow-up items for future milestones
    - `deviations` (string) — Deviations from the original plan
-11. Update `.gsd/PROJECT.md`: use the `write` tool with `path: ".gsd/PROJECT.md"` and `content` containing the full updated document reflecting milestone completion and current project state. Do NOT use the `edit` tool for this — PROJECT.md is a full-document refresh.
-12. Extract structured learnings from this milestone and persist them to the GSD memory store. Follow the procedure block immediately below — it writes `{{milestoneId}}-LEARNINGS.md` as the audit trail and persists Patterns, Lessons, and Decisions via `capture_thought` (categories: pattern, gotcha/convention, architecture). The memory store is the single source of truth for cross-session durable knowledge (ADR-013).
-
-{{extractLearningsSteps}}
 
 13. Do not commit manually — the system auto-commits your changes after this unit completes.
 - Say: "Milestone {{milestoneId}} complete."
 
-**Important:** Do NOT skip the code change verification, success criteria, or definition of done verification (steps 3-5). The milestone summary must reflect actual verified outcomes, not assumed success. Verification failures BLOCK completion — there is no override. The milestone stays in its current state until issues are resolved and verification is re-run. **If a verification tool itself fails, errors, or returns unexpected output, treat it as a verification failure** — never rationalize past a tool error ("tool didn't respond, assuming success" is forbidden). A tool that cannot verify is a tool that did not verify.
+**Important:** Do NOT skip code-change, success-criteria, or definition-of-done verification (steps 3-5). The summary must reflect verified outcomes. Verification failures block completion; there is no override. If a verification tool fails, errors, or returns unexpected output, treat it as failure.
 
-**File system safety:** When scanning milestone directories for evidence, use `ls` or `find` to list directory contents first — never pass a directory path (e.g. `tasks/`, `slices/`) directly to the `read` tool. The `read` tool only accepts file paths, not directories.
+**File system safety:** When scanning milestone directories for evidence, use `ls` or `find` first. Never pass a directory path (e.g. `tasks/`, `slices/`) to `read`; it only accepts file paths.