gsd-pi 2.49.0 → 2.50.0-dev.d210a87

package/dist/resources/extensions/gsd/observability-validator.js

@@ -0,0 +1,422 @@
+import { loadFile } from "./files.js";
+import { resolveSliceFile, resolveTaskFile, resolveTasksDir, resolveTaskFiles } from "./paths.js";
+function getSection(content, heading, level = 2) {
+    const prefix = "#".repeat(level) + " ";
+    const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const regex = new RegExp(`^${prefix}${escaped}\\s*$`, "m");
+    const match = regex.exec(content);
+    if (!match)
+        return null;
+    const start = match.index + match[0].length;
+    const rest = content.slice(start);
+    const nextHeading = rest.match(new RegExp(`^#{1,${level}} `, "m"));
+    const end = nextHeading ? nextHeading.index : rest.length;
+    return rest.slice(0, end).trim();
+}
+function getFrontmatter(content) {
+    const trimmed = content.trimStart();
+    if (!trimmed.startsWith("---"))
+        return null;
+    const afterFirst = trimmed.indexOf("\n");
+    if (afterFirst === -1)
+        return null;
+    const rest = trimmed.slice(afterFirst + 1);
+    const endIdx = rest.indexOf("\n---");
+    if (endIdx === -1)
+        return null;
+    return rest.slice(0, endIdx);
+}
+function hasFrontmatterKey(content, key) {
+    const fm = getFrontmatter(content);
+    if (!fm)
+        return false;
+    return new RegExp(`^${key}:`, "m").test(fm);
+}
+function normalizeMeaningfulLines(text) {
+    return text
+        .split("\n")
+        .map(line => line.trim())
+        .filter(line => line.length > 0)
+        .filter(line => !line.startsWith("<!--"))
+        .filter(line => !line.endsWith("-->"))
+        .filter(line => !/^[-*]\s*\{\{.+\}\}$/.test(line))
+        .filter(line => !/^\{\{.+\}\}$/.test(line));
+}
+function sectionLooksPlaceholderOnly(text) {
+    if (!text)
+        return true;
+    const lines = normalizeMeaningfulLines(text)
+        .map(line => line.replace(/^[-*]\s+/, "").trim())
+        .filter(line => line.length > 0);
+    if (lines.length === 0)
+        return true;
+    return lines.every(line => {
+        const lower = line.toLowerCase();
+        return lower === "none" ||
+            lower.endsWith(": none") ||
+            lower.includes("{{") ||
+            lower.includes("}}") ||
+            lower.startsWith("required for non-trivial") ||
+            lower.startsWith("describe how a future agent") ||
+            lower.startsWith("prefer:") ||
+            lower.startsWith("keep this section concise");
+    });
+}
+function textSuggestsObservabilityRelevant(content) {
+    const lower = content.toLowerCase();
+    const needles = [
+        " api", "route", "server", "worker", "queue", "job", "sync", "import",
+        "webhook", "auth", "db", "database", "migration", "cache", "background",
+        "polling", "realtime", "socket", "stateful", "integration", "ui", "form",
+        "submit", "status", "service", "pipeline", "health endpoint", "error path"
+    ];
+    return needles.some(needle => lower.includes(needle));
+}
+function verificationMentionsDiagnostics(section) {
+    if (!section)
+        return false;
+    const lower = section.toLowerCase();
+    const needles = [
+        "error", "failure", "diagnostic", "status", "health", "inspect", "log",
+        "network", "console", "retry", "last error", "correlation", "readiness"
+    ];
+    return needles.some(needle => lower.includes(needle));
+}
+export function validateSlicePlanContent(file, content) {
+    const issues = [];
+    // ── Plan quality rules (always run, not gated by runtime relevance) ──
+    const tasksSection = getSection(content, "Tasks", 2);
+    if (tasksSection) {
+        const lines = tasksSection.split("\n");
+        const taskLinePattern = /^- \[[ x]\] \*\*T\d+:/;
+        const taskLineIndices = [];
+        for (let i = 0; i < lines.length; i++) {
+            if (taskLinePattern.test(lines[i]))
+                taskLineIndices.push(i);
+        }
+        for (let t = 0; t < taskLineIndices.length; t++) {
+            const start = taskLineIndices[t];
+            const end = t + 1 < taskLineIndices.length ? taskLineIndices[t + 1] : lines.length;
+            // Check lines between this task header and the next (or section end)
+            const bodyLines = lines.slice(start + 1, end);
+            const meaningful = bodyLines.filter(l => l.trim().length > 0);
+            if (meaningful.length === 0) {
+                issues.push({
+                    severity: "warning",
+                    scope: "slice-plan",
+                    file,
+                    ruleId: "empty_task_entry",
+                    message: "Inline task entry has no description content beneath the checkbox line.",
+                    suggestion: "Add at least a Why/Files/Do/Verify summary so the task is self-describing.",
+                });
+            }
+        }
+    }
+    // ── Observability rules (gated by runtime relevance) ──
+    const relevant = textSuggestsObservabilityRelevant(content);
+    if (!relevant)
+        return issues;
+    const obs = getSection(content, "Observability / Diagnostics", 2);
+    const verification = getSection(content, "Verification", 2);
+    if (!obs) {
+        issues.push({
+            severity: "warning",
+            scope: "slice-plan",
+            file,
+            ruleId: "missing_observability_section",
+            message: "Slice plan appears non-trivial but is missing `## Observability / Diagnostics`.",
+            suggestion: "Add runtime signals, inspection surfaces, failure visibility, and redaction constraints.",
+        });
+    }
+    else if (sectionLooksPlaceholderOnly(obs)) {
+        issues.push({
+            severity: "warning",
+            scope: "slice-plan",
+            file,
+            ruleId: "observability_section_placeholder_only",
+            message: "Slice plan has `## Observability / Diagnostics` but it still looks like placeholder text.",
+            suggestion: "Replace placeholders with concrete signals and inspection surfaces a future agent should trust.",
+        });
+    }
+    if (!verificationMentionsDiagnostics(verification)) {
+        issues.push({
+            severity: "warning",
+            scope: "slice-plan",
+            file,
+            ruleId: "verification_missing_diagnostic_check",
+            message: "Slice verification does not appear to include any diagnostic or failure-path check.",
+            suggestion: "Add at least one verification step for inspectable failure state, structured error output, status surface, or equivalent.",
+        });
+    }
+    return issues;
+}
+export function validateTaskPlanContent(file, content) {
+    const issues = [];
+    // ── Plan quality rules (always run, not gated by runtime relevance) ──
+    // Rule: empty or missing Steps section
+    const stepsSection = getSection(content, "Steps", 2);
+    if (stepsSection === null || sectionLooksPlaceholderOnly(stepsSection)) {
+        issues.push({
+            severity: "warning",
+            scope: "task-plan",
+            file,
+            ruleId: "empty_steps_section",
+            message: "Task plan has an empty or missing `## Steps` section.",
+            suggestion: "Add concrete numbered implementation steps so execution has a clear sequence.",
+        });
+    }
+    // Rule: placeholder-only Verification section
+    const verificationSection = getSection(content, "Verification", 2);
+    if (verificationSection !== null && sectionLooksPlaceholderOnly(verificationSection)) {
+        issues.push({
+            severity: "warning",
+            scope: "task-plan",
+            file,
+            ruleId: "placeholder_verification",
+            message: "Task plan has `## Verification` but it still looks like placeholder text.",
+            suggestion: "Replace placeholders with concrete verification commands, test runs, or observable checks.",
+        });
+    }
+    // Rule: scope estimate thresholds
+    const fm = getFrontmatter(content);
+    if (fm) {
+        const stepsMatch = fm.match(/^estimated_steps:\s*(\d+)/m);
+        const filesMatch = fm.match(/^estimated_files:\s*(\d+)/m);
+        if (stepsMatch) {
+            const estimatedSteps = parseInt(stepsMatch[1], 10);
+            if (estimatedSteps >= 10) {
+                issues.push({
+                    severity: "warning",
+                    scope: "task-plan",
+                    file,
+                    ruleId: "scope_estimate_steps_high",
+                    message: `Task plan estimates ${estimatedSteps} steps (threshold: 10). Consider splitting into smaller tasks.`,
+                    suggestion: "Break the task into sub-tasks or reduce scope so each task stays focused and completable in one pass.",
+                });
+            }
+        }
+        if (filesMatch) {
+            const estimatedFiles = parseInt(filesMatch[1], 10);
+            if (estimatedFiles >= 12) {
+                issues.push({
+                    severity: "warning",
+                    scope: "task-plan",
+                    file,
+                    ruleId: "scope_estimate_files_high",
+                    message: `Task plan estimates ${estimatedFiles} files (threshold: 12). Consider splitting into smaller tasks.`,
+                    suggestion: "Break the task into sub-tasks or reduce scope to keep the change footprint manageable.",
+                });
+            }
+        }
+    }
+    // Rule: Inputs and Expected Output should contain backtick-wrapped file paths
+    const inputsSection = getSection(content, "Inputs", 2);
+    const outputSection = getSection(content, "Expected Output", 2);
+    const backtickPathPattern = /`[^`]*[./][^`]*`/;
+    if (outputSection === null || !backtickPathPattern.test(outputSection)) {
+        issues.push({
+            severity: "warning",
+            scope: "task-plan",
+            file,
+            ruleId: "missing_output_file_paths",
+            message: "Task plan `## Expected Output` is missing or has no backtick-wrapped file paths.",
+            suggestion: "List concrete output file paths in backticks (e.g. `src/types.ts`). These are machine-parsed to derive task dependencies.",
+        });
+    }
+    if (inputsSection !== null && inputsSection.trim().length > 0 && !backtickPathPattern.test(inputsSection)) {
+        issues.push({
+            severity: "info",
+            scope: "task-plan",
+            file,
+            ruleId: "missing_input_file_paths",
+            message: "Task plan `## Inputs` has content but no backtick-wrapped file paths.",
+            suggestion: "List input file paths in backticks (e.g. `src/config.json`). These are machine-parsed to derive task dependencies.",
+        });
+    }
+    // ── Observability rules (gated by runtime relevance) ──
+    const relevant = textSuggestsObservabilityRelevant(content);
+    if (!relevant)
+        return issues;
+    const obs = getSection(content, "Observability Impact", 2);
+    if (!obs) {
+        issues.push({
+            severity: "warning",
+            scope: "task-plan",
+            file,
+            ruleId: "missing_observability_impact",
+            message: "Task plan appears runtime-relevant but is missing `## Observability Impact`.",
+            suggestion: "Explain what signals change, how a future agent inspects this task, and what failure state becomes visible.",
+        });
+    }
+    else if (sectionLooksPlaceholderOnly(obs)) {
+        issues.push({
+            severity: "warning",
+            scope: "task-plan",
+            file,
+            ruleId: "observability_impact_placeholder_only",
+            message: "Task plan has `## Observability Impact` but it still looks empty or placeholder-only.",
+            suggestion: "Fill in concrete inspection surfaces or explicitly justify why observability is not applicable.",
+        });
+    }
+    return issues;
+}
+export function validateTaskSummaryContent(file, content) {
+    const issues = [];
+    if (!hasFrontmatterKey(content, "observability_surfaces")) {
+        issues.push({
+            severity: "warning",
+            scope: "task-summary",
+            file,
+            ruleId: "missing_observability_frontmatter",
+            message: "Task summary is missing `observability_surfaces` in frontmatter.",
+            suggestion: "List the durable status/log/error surfaces a future agent should use.",
+        });
+    }
+    const diagnostics = getSection(content, "Diagnostics", 2);
+    if (!diagnostics) {
+        issues.push({
+            severity: "warning",
+            scope: "task-summary",
+            file,
+            ruleId: "missing_diagnostics_section",
+            message: "Task summary is missing `## Diagnostics`.",
+            suggestion: "Document how to inspect what this task built later.",
+        });
+    }
+    else if (sectionLooksPlaceholderOnly(diagnostics)) {
+        issues.push({
+            severity: "warning",
+            scope: "task-summary",
+            file,
+            ruleId: "diagnostics_placeholder_only",
+            message: "Task summary diagnostics section still looks like placeholder text.",
+            suggestion: "Replace placeholders with concrete commands, endpoints, logs, error shapes, or failure artifacts.",
+        });
+    }
+    const evidence = getSection(content, "Verification Evidence", 2);
+    if (!evidence) {
+        issues.push({
+            severity: "warning",
+            scope: "task-summary",
+            file,
+            ruleId: "evidence_block_missing",
+            message: "Task summary is missing `## Verification Evidence`.",
+            suggestion: "Add a verification evidence table showing gate check results (command, exit code, verdict, duration).",
+        });
+    }
+    else if (sectionLooksPlaceholderOnly(evidence)) {
+        issues.push({
+            severity: "warning",
+            scope: "task-summary",
+            file,
+            ruleId: "evidence_block_placeholder",
+            message: "Task summary verification evidence section still looks like placeholder text.",
+            suggestion: "Replace placeholders with actual gate results or note that no verification commands were discovered.",
+        });
+    }
+    return issues;
+}
+export function validateSliceSummaryContent(file, content) {
+    const issues = [];
+    if (!hasFrontmatterKey(content, "observability_surfaces")) {
+        issues.push({
+            severity: "warning",
+            scope: "slice-summary",
+            file,
+            ruleId: "missing_observability_frontmatter",
+            message: "Slice summary is missing `observability_surfaces` in frontmatter.",
+            suggestion: "List the authoritative diagnostics and durable inspection surfaces for this slice.",
+        });
+    }
+    const diagnostics = getSection(content, "Authoritative diagnostics", 3);
+    if (!diagnostics) {
+        issues.push({
+            severity: "warning",
+            scope: "slice-summary",
+            file,
+            ruleId: "missing_authoritative_diagnostics",
+            message: "Slice summary is missing `### Authoritative diagnostics` in Forward Intelligence.",
+            suggestion: "Tell future agents where to look first and why that signal is trustworthy.",
+        });
+    }
+    else if (sectionLooksPlaceholderOnly(diagnostics)) {
+        issues.push({
+            severity: "warning",
+            scope: "slice-summary",
+            file,
+            ruleId: "authoritative_diagnostics_placeholder_only",
+            message: "Slice summary includes authoritative diagnostics but it still looks like placeholder text.",
+            suggestion: "Replace placeholders with the real first-stop diagnostic surface for this slice.",
+        });
+    }
+    return issues;
+}
+export async function validatePlanBoundary(basePath, milestoneId, sliceId) {
+    const issues = [];
+    const slicePlan = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN");
+    if (slicePlan) {
+        const content = await loadFile(slicePlan);
+        if (content)
+            issues.push(...validateSlicePlanContent(slicePlan, content));
+    }
+    const tasksDir = resolveTasksDir(basePath, milestoneId, sliceId);
+    const taskPlans = tasksDir ? resolveTaskFiles(tasksDir, "PLAN") : [];
+    for (const file of taskPlans) {
+        const taskId = file.split("-")[0];
+        const taskPlan = resolveTaskFile(basePath, milestoneId, sliceId, taskId, "PLAN");
+        if (!taskPlan)
+            continue;
+        const content = await loadFile(taskPlan);
+        if (content)
+            issues.push(...validateTaskPlanContent(taskPlan, content));
+    }
+    return issues;
+}
+export async function validateExecuteBoundary(basePath, milestoneId, sliceId, taskId) {
+    const issues = [];
+    const slicePlan = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN");
+    if (slicePlan) {
+        const content = await loadFile(slicePlan);
+        if (content)
+            issues.push(...validateSlicePlanContent(slicePlan, content));
+    }
+    const taskPlan = resolveTaskFile(basePath, milestoneId, sliceId, taskId, "PLAN");
+    if (taskPlan) {
+        const content = await loadFile(taskPlan);
+        if (content)
+            issues.push(...validateTaskPlanContent(taskPlan, content));
+    }
+    return issues;
+}
+export async function validateCompleteBoundary(basePath, milestoneId, sliceId) {
+    const issues = [];
+    const tasksDir = resolveTasksDir(basePath, milestoneId, sliceId);
+    const taskSummaries = tasksDir ? resolveTaskFiles(tasksDir, "SUMMARY") : [];
+    for (const file of taskSummaries) {
+        const taskId = file.split("-")[0];
+        const taskSummary = resolveTaskFile(basePath, milestoneId, sliceId, taskId, "SUMMARY");
+        if (!taskSummary)
+            continue;
+        const content = await loadFile(taskSummary);
+        if (content)
+            issues.push(...validateTaskSummaryContent(taskSummary, content));
+    }
+    const sliceSummary = resolveSliceFile(basePath, milestoneId, sliceId, "SUMMARY");
+    if (sliceSummary) {
+        const content = await loadFile(sliceSummary);
+        if (content)
+            issues.push(...validateSliceSummaryContent(sliceSummary, content));
+    }
+    return issues;
+}
+export function formatValidationIssues(issues, limit = 4) {
+    if (issues.length === 0)
+        return "";
+    const lines = issues.slice(0, limit).map(issue => {
+        const fileName = issue.file.split("/").pop() || issue.file;
+        return `- ${fileName}: ${issue.message}`;
+    });
+    if (issues.length > limit)
+        lines.push(`- ...and ${issues.length - limit} more`);
+    return lines.join("\n");
+}

package/dist/resources/extensions/gsd/preferences-skills.js

@@ -7,19 +7,25 @@
 import { existsSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
-import { getAgentDir } from "@gsd/pi-coding-agent";
 import { statSync } from "node:fs";
 import { validatePreferences } from "./preferences-validation.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 /**
  * Known skill directories, in priority order.
- * User skills (~/.gsd/agent/skills/) take precedence over project skills.
+ * Global skills (~/.agents/skills/) take precedence over project skills.
+ * Legacy ~/.gsd/agent/skills/ is included as a fallback for pre-migration installs.
  */
 export function getSkillSearchDirs(cwd) {
-    return [
-        { dir: join(getAgentDir(), "skills"), method: "user-skill" },
-        { dir: join(cwd, ".pi", "agent", "skills"), method: "project-skill" },
+    const dirs = [
+        { dir: join(homedir(), ".agents", "skills"), method: "user-skill" },
+        { dir: join(cwd, ".agents", "skills"), method: "project-skill" },
     ];
+    // Legacy fallback — read skills from old GSD directory only if migration hasn't completed
+    const legacyDir = join(homedir(), ".gsd", "agent", "skills");
+    if (existsSync(legacyDir) && !existsSync(join(legacyDir, ".migrated-to-agents"))) {
+        dirs.push({ dir: legacyDir, method: "user-skill" });
+    }
+    return dirs;
 }
 /**
  * Resolve a single skill reference to an absolute path.

package/dist/resources/extensions/gsd/preferences-types.js

@@ -65,15 +65,17 @@ export const KNOWN_PREFERENCE_KEYS = new Set([
     "context_selection",
     "widget_mode",
     "reactive_execution",
+    "gate_evaluation",
     "github",
     "service_tier",
     "forensics_dedup",
     "show_token_cost",
+    "experimental",
 ]);
 /** Canonical list of all dispatch unit types. */
 export const KNOWN_UNIT_TYPES = [
     "research-milestone", "plan-milestone", "research-slice", "plan-slice",
-    "execute-task", "reactive-execute", "complete-slice", "replan-slice", "reassess-roadmap",
+    "execute-task", "reactive-execute", "gate-evaluate", "complete-slice", "replan-slice", "reassess-roadmap",
     "run-uat", "complete-milestone",
 ];
 export const SKILL_ACTIONS = new Set(["use", "prefer", "avoid"]);

package/dist/resources/extensions/gsd/preferences-validation.js

@@ -542,6 +542,45 @@ export function validatePreferences(preferences) {
             errors.push("reactive_execution must be an object");
         }
     }
+    // ─── Gate Evaluation ─────────────────────────────────────────────────────
+    if (preferences.gate_evaluation !== undefined) {
+        if (typeof preferences.gate_evaluation === "object" && preferences.gate_evaluation !== null) {
+            const ge = preferences.gate_evaluation;
+            const validGe = {};
+            if (ge.enabled !== undefined) {
+                if (typeof ge.enabled === "boolean")
+                    validGe.enabled = ge.enabled;
+                else
+                    errors.push("gate_evaluation.enabled must be a boolean");
+            }
+            if (ge.slice_gates !== undefined) {
+                if (Array.isArray(ge.slice_gates) && ge.slice_gates.every((g) => typeof g === "string")) {
+                    validGe.slice_gates = ge.slice_gates;
+                }
+                else {
+                    errors.push("gate_evaluation.slice_gates must be an array of strings");
+                }
+            }
+            if (ge.task_gates !== undefined) {
+                if (typeof ge.task_gates === "boolean")
+                    validGe.task_gates = ge.task_gates;
+                else
+                    errors.push("gate_evaluation.task_gates must be a boolean");
+            }
+            const knownGeKeys = new Set(["enabled", "slice_gates", "task_gates"]);
+            for (const key of Object.keys(ge)) {
+                if (!knownGeKeys.has(key)) {
+                    warnings.push(`unknown gate_evaluation key "${key}" — ignored`);
+                }
+            }
+            if (Object.keys(validGe).length > 0) {
+                validated.gate_evaluation = validGe;
+            }
+        }
+        else {
+            errors.push("gate_evaluation must be an object");
+        }
+    }
     // ─── Verification Preferences ───────────────────────────────────────────
     if (preferences.verification_commands !== undefined) {
         if (Array.isArray(preferences.verification_commands)) {
@@ -784,5 +823,30 @@ export function validatePreferences(preferences) {
             errors.push("show_token_cost must be a boolean");
         }
     }
+    // ─── Experimental Features ────────────────────────────────────────
+    if (preferences.experimental !== undefined) {
+        if (typeof preferences.experimental === "object" && preferences.experimental !== null) {
+            const exp = preferences.experimental;
+            const validExp = {};
+            if (exp.rtk !== undefined) {
+                if (typeof exp.rtk === "boolean")
+                    validExp.rtk = exp.rtk;
+                else
+                    errors.push("experimental.rtk must be a boolean");
+            }
+            const knownExpKeys = new Set(["rtk"]);
+            for (const key of Object.keys(exp)) {
+                if (!knownExpKeys.has(key)) {
+                    warnings.push(`unknown experimental key "${key}" — ignored`);
+                }
+            }
+            if (Object.keys(validExp).length > 0) {
+                validated.experimental = validExp;
+            }
+        }
+        else {
+            errors.push("experimental must be an object");
+        }
+    }
     return { preferences: validated, errors, warnings };
 }

package/dist/resources/extensions/gsd/preferences.js

@@ -275,6 +275,9 @@ function mergePreferences(base, override) {
         service_tier: override.service_tier ?? base.service_tier,
         forensics_dedup: override.forensics_dedup ?? base.forensics_dedup,
         show_token_cost: override.show_token_cost ?? base.show_token_cost,
+        experimental: (base.experimental || override.experimental)
+            ? { ...(base.experimental ?? {}), ...(override.experimental ?? {}) }
+            : undefined,
     };
 }
 function mergeStringLists(base, override) {

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

@@ -20,11 +20,13 @@ Then:
 3. **Verify code changes exist.** Run `git diff --stat HEAD $(git merge-base HEAD main) -- ':!.gsd/'` (or the equivalent for the integration branch). If no non-`.gsd/` files appear in the diff, the milestone produced only planning artifacts and no actual code. Record this as a **verification failure**.
 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. 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.
+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.
 
 ### 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 7.**
+**If ANY verification failure was recorded in steps 3, 4, or 5, you MUST follow the failure path below. Do NOT proceed to step 9.**
 
 **Failure path** (verification failed):
 - Do NOT call `gsd_complete_milestone` — the milestone must not be marked as complete.
@@ -33,13 +35,30 @@ Then:
 - Write a clear summary of what failed and why to help the next attempt.
 - Say: "Milestone {{milestoneId}} verification FAILED — not complete." and stop.
 
-**Success path** (all verifications passed — continue with steps 7–11):
+**Success path** (all verifications passed — continue with steps 9–13):
 
-7. **Persist completion through `gsd_complete_milestone`.** Call it with: `milestoneId`, `title`, `oneLiner`, `narrative`, `successCriteriaResults`, `definitionOfDoneResults`, `requirementOutcomes`, `keyDecisions`, `keyFiles`, `lessonsLearned`, `followUps`, `deviations`, `verificationPassed: true`. The tool updates the milestone status in the DB, renders `{{milestoneSummaryPath}}`, and validates all slices are complete before proceeding.
-8. For each requirement whose status changed in step 6, call `gsd_requirement_update` with the requirement ID and updated `status` and `validation` fields — the tool regenerates `.gsd/REQUIREMENTS.md` automatically.
-9. Update `.gsd/PROJECT.md` to reflect milestone completion and current project state.
-10. Review all slice summaries for cross-cutting lessons, patterns, or gotchas that emerged during this milestone. Append any non-obvious, reusable insights to `.gsd/KNOWLEDGE.md`.
-11. Do not commit manually — the system auto-commits your changes after this unit completes.
+9. **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.
+
+   **Required parameters:**
+   - `milestoneId` (string) — Milestone ID (e.g. M001)
+   - `title` (string) — Milestone title
+   - `oneLiner` (string) — One-sentence summary of what the milestone achieved
+   - `narrative` (string) — Detailed narrative of what happened during the milestone
+   - `successCriteriaResults` (string) — Markdown detailing how each success criterion was met or not met
+   - `definitionOfDoneResults` (string) — Markdown detailing how each definition-of-done item was met
+   - `requirementOutcomes` (string) — Markdown detailing requirement status transitions with evidence
+   - `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
+
+   **Optional parameters:**
+   - `followUps` (string) — Follow-up items for future milestones
+   - `deviations` (string) — Deviations from the original plan
+10. 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.
+11. Update `.gsd/PROJECT.md` to reflect milestone completion and current project state.
+12. Review all slice summaries for cross-cutting lessons, patterns, or gotchas that emerged during this milestone. Append any non-obvious, reusable insights to `.gsd/KNOWLEDGE.md`.
+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.

package/dist/resources/extensions/gsd/prompts/complete-slice.md

@@ -23,14 +23,15 @@ Then:
 2. {{skillActivation}}
 3. Run all slice-level verification checks defined in the slice plan. All must pass before marking the slice done. If any fail, fix them first.
 4. If the slice plan includes observability/diagnostic surfaces, confirm they work. Skip this for simple slices that don't have observability sections.
-5. If this slice produced evidence that a requirement changed status (Active → Validated, Active → Deferred, etc.), call `gsd_save_decision` with scope="requirement", decision="{requirement-id}", choice="{new-status}", rationale="{evidence}". Do NOT write `.gsd/REQUIREMENTS.md` directly — the engine renders it from the database.
-6. Write `{{sliceSummaryPath}}` (compress all task summaries).
-7. Write `{{sliceUatPath}}` — a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built.
-8. Review task summaries for `key_decisions`. Append any significant decisions to `.gsd/DECISIONS.md` if missing.
-9. Review task summaries for patterns, gotchas, or non-obvious lessons learned. If any would save future agents from repeating investigation or hitting the same issues, append them to `.gsd/KNOWLEDGE.md`. Only add entries that are genuinely useful — don't pad with obvious observations.
-10. Call `gsd_complete_slice` with milestone_id, slice_id, the slice summary, and the UAT result. Do NOT manually mark the roadmap checkbox — the tool writes to the DB and renders the ROADMAP.md projection automatically.
-11. Do not run git commands — the system commits your changes and handles any merge after this unit succeeds.
-12. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed.
+5. If the slice involved runtime behavior, fill the **Operational Readiness** section (Q8) in the slice summary: health signal, failure signal, recovery procedure, and monitoring gaps. Omit entirely for simple slices with no runtime concerns.
+6. If this slice produced evidence that a requirement changed status (Active → Validated, Active → Deferred, etc.), call `gsd_save_decision` with scope="requirement", decision="{requirement-id}", choice="{new-status}", rationale="{evidence}". Do NOT write `.gsd/REQUIREMENTS.md` directly — the engine renders it from the database.
+7. Write `{{sliceSummaryPath}}` (compress all task summaries).
+8. Write `{{sliceUatPath}}` — a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built.
+9. Review task summaries for `key_decisions`. Append any significant decisions to `.gsd/DECISIONS.md` if missing.
+10. Review task summaries for patterns, gotchas, or non-obvious lessons learned. If any would save future agents from repeating investigation or hitting the same issues, append them to `.gsd/KNOWLEDGE.md`. Only add entries that are genuinely useful — don't pad with obvious observations.
+11. Call `gsd_complete_slice` with milestone_id, slice_id, the slice summary, and the UAT result. Do NOT manually mark the roadmap checkbox — the tool writes to the DB and renders the ROADMAP.md projection automatically.
+12. Do not run git commands — the system commits your changes and handles any merge after this unit succeeds.
+13. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed.
 
 **You MUST call `gsd_complete_slice` with the slice summary and UAT content before finishing. The tool persists to both DB and disk and renders `{{sliceSummaryPath}}` and `{{sliceUatPath}}` automatically.**