gsd-pi 2.79.0-dev.ece5fd8ba → 2.80.0-dev.4ea7d80e7

package/dist/resources/extensions/gsd/prompts/triage-captures.md

@@ -2,7 +2,7 @@ You are triaging user-captured thoughts during a GSD session.
 
 ## UNIT: Triage Captures
 
-The user captured thoughts during execution using `/gsd capture`. Your job is to classify each capture, present your proposals, get user confirmation, and update CAPTURES.md with the final classifications.
+The user captured thoughts with `/gsd capture`. Classify each capture, present proposals, get needed confirmation, and update CAPTURES.md with final classifications.
 
 ## Pending Captures
 
@@ -18,24 +18,24 @@ The user captured thoughts during execution using `/gsd capture`. Your job is to
 
 ## Classification Criteria
 
-For each capture, classify it as one of:
+Classify each capture as one of:
 
-- **stop**: User directive to halt auto-mode immediately. Use when the user says "stop", "halt", "abort", "don't continue", "pause", or otherwise wants execution to cease. Auto-mode will pause after the current unit completes. Examples: "stop running", "halt execution", "don't continue".
-- **backtrack**: User directive to abandon the current milestone and return to a previous one. The user believes earlier milestones missed critical features or need rework. Include the target milestone ID (e.g., M003) in the Resolution field. Auto-mode will pause and write a regression marker. Examples: "restart from M003", "go back to milestone 3", "M004 and M005 failed, restart from M003".
-- **quick-task**: Small, self-contained, no downstream impact. Can be done in minutes without modifying the plan. Examples: fix a typo, add a missing import, tweak a config value.
-- **inject**: Belongs in the current slice but wasn't planned. Needs a new task added to the slice plan. Examples: add error handling to a module being built, add a missing test case for current work.
-- **defer**: Belongs in a future slice or milestone. Not urgent for current work. Examples: performance optimization, feature that depends on unbuilt infrastructure, nice-to-have enhancement.
-- **replan**: Changes the shape of remaining work in the current slice. Existing incomplete tasks may need rewriting. Examples: "the approach is wrong, we need to use X instead of Y", discovering a fundamental constraint.
-- **note**: Informational only. No action needed right now. Good context for future reference. Examples: "remember that the API has a rate limit", observations about code quality.
+- **stop**: Halt/pause auto-mode immediately after the current unit. Examples: "stop", "halt", "abort", "don't continue".
+- **backtrack**: Abandon current milestone and return to an earlier one. Include target milestone ID (e.g., M003) in Resolution. Auto-mode pauses and writes a regression marker.
+- **quick-task**: Small, self-contained, no downstream impact; minutes of work without plan changes.
+- **inject**: Belongs in current slice but was not planned; needs a new task.
+- **defer**: Belongs in a future slice/milestone; not urgent for current work.
+- **replan**: Changes remaining work shape in the current slice; incomplete tasks may need rewriting.
+- **note**: Informational only; useful future context with no immediate action.
 
 ## Decision Guidelines
 
-- **ALWAYS classify as stop** when the user explicitly says "stop", "halt", "abort", or "don't continue". Never shoe-horn a stop directive into "replan" or "note".
-- **ALWAYS classify as backtrack** when the user references returning to a previous milestone, restarting from an earlier point, or abandoning current milestone work. Include the target milestone ID in the Resolution field (e.g., "Backtrack to M003").
+- **ALWAYS classify as stop** when the user says "stop", "halt", "abort", or "don't continue". Never shoe-horn stop into "replan" or "note".
+- **ALWAYS classify as backtrack** when the user references returning to a previous milestone, restarting earlier, or abandoning current milestone work. Include target milestone ID in Resolution (e.g., "Backtrack to M003").
 - Prefer **quick-task** when the work is clearly small and self-contained.
 - Prefer **inject** over **replan** when only a new task is needed, not rewriting existing ones.
 - Prefer **defer** over **inject** when the work doesn't belong in the current slice's scope.
-- Use **replan** only when remaining incomplete tasks in the *current slice* need to change — not for cross-milestone issues.
+- Use **replan** only when remaining incomplete tasks in the *current slice* need to change, not for cross-milestone issues.
 - Use **note** for observations that don't require action.
 - When unsure between quick-task and inject, consider: will this take more than 10 minutes? If yes, inject.
 
@@ -49,8 +49,8 @@ For each capture, classify it as one of:
    - Your rationale
    - If applicable, which files would be affected
    
-   For captures classified as **note** or **defer**, auto-confirm without asking — these are low-impact.
-   For captures classified as **stop** or **backtrack**, auto-confirm without asking — these are urgent user directives that must be honored immediately.
+   Auto-confirm **note** and **defer** because they are low-impact.
+   Auto-confirm **stop** and **backtrack** because they are urgent user directives.
    For captures classified as **quick-task**, **inject**, or **replan**, ask the user to confirm or choose a different classification. **Non-bypassable:** If `ask_user_questions` fails, errors, or the user does not respond, you MUST re-ask — never auto-confirm these classifications without explicit user approval.
 
 3. **Update** `.gsd/CAPTURES.md` — for each capture, update its section with the confirmed classification:
@@ -61,7 +61,7 @@ For each capture, classify it as one of:
    - Add `**Resolved:** <current ISO timestamp>`
    - Add `**Milestone:** <current milestone ID>` (e.g., `**Milestone:** M003`)
 
-4. **Summarize** what was triaged: how many captures, what classifications were assigned, and what actions are pending (e.g., "2 quick-tasks ready for execution, 1 deferred to S03").
+4. **Summarize** count, assigned classifications, and pending actions (e.g., "2 quick-tasks ready, 1 deferred to S03").
 
 **Important:** Do NOT execute any resolutions. Only classify and update CAPTURES.md. Resolution execution happens separately (in auto-mode dispatch or manually by the user).
 

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

@@ -1,20 +1,20 @@
-# Milestone Validation — Parallel Review
+# Milestone Validation - Parallel Review
 
-You are the validation orchestrator for **{{milestoneId}} — {{milestoneTitle}}**.
+You are the validation orchestrator for **{{milestoneId}} - {{milestoneTitle}}**.
 
 ## Working Directory
 
-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.
+Work in `{{workingDirectory}}`. All reads, writes, and shell commands MUST stay relative to it. Do NOT `cd` elsewhere.
 
 ## Mission
 
-Dispatch 3 independent parallel reviewers, then synthesize their findings into the final VALIDATION verdict.
+Dispatch 3 independent parallel reviewers, then synthesize the final VALIDATION verdict.
 
-This is remediation round {{remediationRound}}. If this is round 0, this is the first validation pass. If > 0, prior validation found issues and remediation slices were added and executed — verify those remediation slices resolved the issues.
+Remediation round: {{remediationRound}}. Round 0 is the first pass; later rounds must verify remediation slices resolved prior findings.
 
 ## Context
 
-All relevant context has been preloaded below — the roadmap, all slice summaries, assessment results, requirements, decisions, and project context are inlined. Start working immediately without re-reading these files.
+Roadmap, slice summaries, assessments, requirements, decisions, and project context are inlined. Start immediately.
 
 {{inlinedContext}}
 
@@ -22,29 +22,29 @@ All relevant context has been preloaded below — the roadmap, all slice summari
 
 ## Execution Protocol
 
-### Step 1 — Dispatch Parallel Reviewers
+### Step 1 - Dispatch Parallel Reviewers
 
 Call `subagent` with `tasks: [...]` containing ALL THREE reviewers simultaneously:
 
-**Reviewer A — Requirements Coverage**
-Prompt: "Review milestone {{milestoneId}} requirements coverage. Working directory: {{workingDirectory}}. Read `.gsd/{{milestoneId}}/REQUIREMENTS.md` (or equivalent requirements file). For each requirement, check the slice SUMMARY files in `.gsd/{{milestoneId}}/` to determine if it is: COVERED (clearly demonstrated), PARTIAL (mentioned but not fully demonstrated), or MISSING (no evidence). Output a markdown table with columns: Requirement | Status | Evidence. End with a one-line verdict: PASS if all covered, NEEDS-ATTENTION if partials exist, FAIL if any missing."
+**Reviewer A - Requirements Coverage**
+Prompt: "Review milestone {{milestoneId}} requirements coverage. Working directory: {{workingDirectory}}. Read `.gsd/{{milestoneId}}/REQUIREMENTS.md` or equivalent. For each requirement, check slice SUMMARY files in `.gsd/{{milestoneId}}/` and mark COVERED, PARTIAL, or MISSING. Output table: Requirement | Status | Evidence. End with one-line verdict: PASS if all covered, NEEDS-ATTENTION if partials exist, FAIL if any missing."
 
-**Reviewer B — Cross-Slice Integration**
-Prompt: "Review milestone {{milestoneId}} cross-slice integration. Working directory: {{workingDirectory}}. Read `{{roadmapPath}}` and find the boundary map (produces/consumes contracts). For each boundary, check that the producing slice's SUMMARY confirms it produced the artifact, and the consuming slice's SUMMARY confirms it consumed it. Output a markdown table: Boundary | Producer Summary | Consumer Summary | Status. End with a one-line verdict: PASS if all boundaries honored, NEEDS-ATTENTION if any gaps."
+**Reviewer B - Cross-Slice Integration**
+Prompt: "Review milestone {{milestoneId}} cross-slice integration. Working directory: {{workingDirectory}}. Read `{{roadmapPath}}` and find the boundary map (produces/consumes contracts). For each boundary, confirm producer SUMMARY produced the artifact and consumer SUMMARY consumed it. Output table: Boundary | Producer Summary | Consumer Summary | Status. End with one-line verdict: PASS if all boundaries honored, NEEDS-ATTENTION if any gaps."
 
-**Reviewer C — Assessment & Acceptance Criteria**
-Prompt: "Review milestone {{milestoneId}} assessment evidence and acceptance criteria. Working directory: {{workingDirectory}}. Read `.gsd/{{milestoneId}}/CONTEXT.md` for acceptance criteria. Check for ASSESSMENT files in each slice directory. Verify each acceptance criterion maps to either a passing assessment result or clear SUMMARY evidence. Then review the inlined milestone verification classes from planning. For each non-empty planned class, output a markdown table: Class | Planned Check | Evidence | Verdict. Use the exact class names `Contract`, `Integration`, `Operational`, and `UAT` whenever those classes are present. If no verification classes were planned, say that explicitly. Output two sections: `Acceptance Criteria` with a checklist `[ ] Criterion | Evidence`, and `Verification Classes` with the table. End with a one-line verdict: PASS if all criteria and verification classes are covered, NEEDS-ATTENTION if gaps exist."
+**Reviewer C - Assessment & Acceptance Criteria**
+Prompt: "Review milestone {{milestoneId}} assessment evidence and acceptance criteria. Working directory: {{workingDirectory}}. Read `.gsd/{{milestoneId}}/CONTEXT.md` for criteria. Check slice ASSESSMENT files. Verify each criterion maps to a passing assessment or clear SUMMARY evidence. Then review inlined milestone verification classes. For each non-empty planned class, output table: Class | Planned Check | Evidence | Verdict. Use the exact class names `Contract`, `Integration`, `Operational`, and `UAT` whenever those classes are present. If no verification classes were planned, say that explicitly. Output sections `Acceptance Criteria` with checklist `[ ] Criterion | Evidence`, and `Verification Classes` with the table. End with one-line verdict: PASS if all criteria and classes are covered, NEEDS-ATTENTION if gaps exist."
 
-### Step 2 — Synthesize Findings
+### Step 2 - Synthesize Findings
 
-After all reviewers complete, aggregate their verdicts:
-- If ALL reviewers say PASS → overall verdict: `pass`
-- If any reviewer says NEEDS-ATTENTION → overall verdict: `needs-attention`
-- If any reviewer says FAIL → overall verdict: `needs-remediation`
+Aggregate reviewer verdicts:
+- ALL PASS -> `pass`
+- Any NEEDS-ATTENTION -> `needs-attention`
+- Any FAIL -> `needs-remediation`
 
-### Step 3 — Persist Validation
+### Step 3 - Persist Validation
 
-Prepare the validation content you will pass to `gsd_validate_milestone`. Do **not** manually write `{{validationPath}}` — the DB-backed tool is the canonical write path and renders the validation file for you.
+Prepare validation content for `gsd_validate_milestone`. Do **not** manually write `{{validationPath}}` - the DB-backed tool is the canonical write path and renders the file.
 
 ```markdown
 ---
@@ -65,7 +65,7 @@ reviewers: 3
 <paste Reviewer C output>
 
 ## Synthesis
-<2-3 sentences summarizing overall findings and verdict rationale>
+<2-3 sentence verdict rationale>
 
 ## Remediation Plan
 <if verdict is not pass: specific actions required>
@@ -74,14 +74,14 @@ reviewers: 3
 Call `gsd_validate_milestone` with the camelCase fields `milestoneId`, `verdict`, `remediationRound`, `successCriteriaChecklist`, `sliceDeliveryAudit`, `crossSliceIntegration`, `requirementCoverage`, `verdictRationale`, and `remediationPlan` when needed. If you include verification-class analysis, pass it in `verificationClasses`.
 Extract the `Verification Classes` subsection from Reviewer C and pass it verbatim in `verificationClasses` so the persisted validation output uses the canonical class names `Contract`, `Integration`, `Operational`, and `UAT`.
 
-**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. Direct DB access corrupts the WAL and bypasses tool-level validation.
+**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` for milestone and slice state. Data is already inlined or available via `gsd_*` tools. Direct DB access risks WAL corruption and bypasses validation.
 
 If verdict is `needs-remediation`:
-- Use `gsd_reassess_roadmap` to add the remediation slices instead of editing `{{roadmapPath}}` manually
+- Use `gsd_reassess_roadmap` to add remediation slices instead of editing `{{roadmapPath}}` manually.
 - Those slices will be planned and executed before validation re-runs
 
 **You MUST call `gsd_validate_milestone` before finishing. Do not manually write `{{validationPath}}`.**
 
-**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, use `ls` or `find` first. Never pass a directory path such as `tasks/` or `slices/` directly to `read`; it only accepts files.
 
 When done, say: "Milestone {{milestoneId}} validation complete — verdict: <verdict>."

package/dist/resources/extensions/gsd/prompts/worktree-merge.md

@@ -1,16 +1,16 @@
-You are merging changes from worktree **{{worktreeName}}** (branch `{{worktreeBranch}}`) into target branch `{{mainBranch}}`.
+You are merging worktree **{{worktreeName}}** (branch `{{worktreeBranch}}`) into target branch `{{mainBranch}}`.
 
 ## Working Directory
 
-Your current working directory has been set to the **main project tree** at `{{mainTreePath}}`. You are on the `{{mainBranch}}` branch. All git and file commands run from here.
+Your CWD is the **main project tree** at `{{mainTreePath}}` on `{{mainBranch}}`. Run all git and file commands here.
 
-- **Main tree (CWD):** `{{mainTreePath}}` — this is where you run `git merge`, read main-branch files, and commit
-- **Worktree directory:** `{{worktreePath}}` — the worktree's working copy; read files here to inspect worktree versions before merging
+- **Main tree (CWD):** `{{mainTreePath}}` — run `git merge`, read main files, commit.
+- **Worktree directory:** `{{worktreePath}}` — inspect worktree versions before merging.
 - **Worktree branch:** `{{worktreeBranch}}`
 
 ## Context
 
-The worktree was created as a parallel workspace. It may contain code changes, new milestones, updated roadmaps, new plans, research, decisions, or other artifacts that need to be merged into the target branch.
+The worktree may contain code, milestones, roadmaps, plans, research, decisions, requirements, or other artifacts to merge.
 
 ### Commit History (worktree)
 
@@ -43,50 +43,50 @@ The worktree was created as a parallel workspace. It may contain code changes, n
 
 ## Your Task
 
-Analyze the changes and guide the merge. Follow these steps exactly:
+Analyze and guide the merge exactly:
 
 ### Step 1: Categorize Changes
 
-Classify each changed file:
+Classify each changed file.
 
 **Code changes:**
-- **New source files** — new modules, components, utilities, tests
-- **Modified source files** — changes to existing code
+- **New source files** — modules, components, utilities, tests.
+- **Modified source files** — existing code changes.
 - **Config changes** — package.json, tsconfig, build config, etc.
-- **Deleted files** — removed source or config files
+- **Deleted files** — removed source/config.
 
 **GSD artifact changes:**
-- **New milestones** — entirely new M###/ directories with roadmaps
-- **New slices/tasks** — new planning artifacts within existing milestones
-- **Updated roadmaps** — modifications to existing M###-ROADMAP.md files
-- **Updated plans** — modifications to existing slice or task plans
-- **Research/context** — new or updated RESEARCH.md, CONTEXT.md files
+- **New milestones** — new M###/ directories with roadmaps.
+- **New slices/tasks** — planning artifacts inside existing milestones.
+- **Updated roadmaps** — changed M###-ROADMAP.md files.
+- **Updated plans** — changed slice/task plans.
+- **Research/context** — new or updated RESEARCH.md, CONTEXT.md.
 - **Decisions** — changes to DECISIONS.md
 - **Requirements** — changes to REQUIREMENTS.md
 - **Other** — anything else
 
 ### Step 2: Conflict Assessment
 
-For each **modified** file, check whether the main branch version has also changed since the worktree branched off. Flag any files where both branches have diverged — these need manual reconciliation.
+For each **modified** file, check whether main also changed since the worktree branched. Flag diverged files for manual reconciliation.
 
 To compare versions:
-- **Main-branch version:** read the file at its normal path (your CWD is the main tree)
-- **Worktree version:** read the file at `{{worktreePath}}/<relative-path>`
-- Use `git merge-base {{mainBranch}} {{worktreeBranch}}` to find the common ancestor if needed
+- **Main version:** read normal path from CWD.
+- **Worktree version:** read `{{worktreePath}}/<relative-path>`.
+- Use `git merge-base {{mainBranch}} {{worktreeBranch}}` if needed.
 
 Classify each modified file:
-- **Clean merges** — main hasn't changed, worktree changes can apply directly
-- **Conflicts** — both branches changed the same file; needs reconciliation
-- **Stale changes** — worktree modified a file that main has since replaced or removed
+- **Clean merges** — main unchanged; apply worktree changes directly.
+- **Conflicts** — both changed same file; reconcile.
+- **Stale changes** — main replaced/removed a file the worktree modified.
 
 ### Step 3: Merge Strategy
 
-Present a merge plan to the user:
+Present a merge plan:
 
-1. For **clean merges**: list files that will merge without conflict
-2. For **conflicts**: show both versions side-by-side and propose a reconciled version
-3. For **new files**: confirm they should be added to the main branch
-4. For **removed files**: confirm the removals are intentional
+1. **Clean merges:** files expected to merge without conflict.
+2. **Conflicts:** show both versions side-by-side and propose reconciliation.
+3. **New files:** confirm they should be added.
+4. **Removed files:** confirm removals are intentional.
 
 Ask the user to confirm the merge plan before proceeding.
 
@@ -97,17 +97,17 @@ Ask the user to confirm the merge plan before proceeding.
 Once the user has explicitly confirmed, run all commands from `{{mainTreePath}}` (your CWD):
 
 1. Ensure you are on the target branch: `git checkout {{mainBranch}}`
-2. If there are conflicts requiring manual reconciliation, apply the reconciled versions first
+2. If conflicts require manual reconciliation, apply reconciled versions first
 3. Run `git merge --squash {{worktreeBranch}}` to bring in all changes
-4. Review the staged changes — if any reconciled files need adjustment, apply them now
+4. Review staged changes; adjust reconciled files if needed
 5. Commit with message: `merge(worktree/{{worktreeName}}): <summary of what was merged>`
 6. Report what was merged
 
 ### Step 5: Cleanup Prompt
 
 After a successful merge, ask the user whether to:
-- **Remove the worktree** — delete the worktree directory and the `{{worktreeBranch}}` branch
-- **Keep the worktree** — leave it for continued parallel work
+- **Remove the worktree** — delete the worktree directory and `{{worktreeBranch}}`.
+- **Keep the worktree** — leave it for continued parallel work.
 
 If the user chooses to remove it, run these commands from `{{mainTreePath}}`:
 ```
@@ -119,7 +119,7 @@ git branch -D {{worktreeBranch}}
 
 ## Important
 
-- Never silently discard changes from either branch
-- When in doubt about a conflict, show both versions and ask the user
-- Preserve all GSD artifact formatting conventions (frontmatter, section structure, checkbox states)
-- If the worktree introduced new milestone IDs that conflict with main, flag this immediately
+- Never silently discard changes from either branch.
+- When in doubt, show both versions and ask.
+- Preserve GSD artifact formatting: frontmatter, sections, checkbox states.
+- If new milestone IDs conflict with main, flag immediately.

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

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Runtime state derivation from GSD workflow database and legacy files.
 // GSD Extension — State Derivation
 // DB-authoritative runtime derivation with explicit legacy filesystem fallback.
 // Pure TypeScript, zero Pi dependencies.
@@ -15,6 +17,7 @@ import { logWarning } from './workflow-logger.js';
 import { extractVerdict } from './verdict-parser.js';
 import { detectPendingEscalation } from './escalation.js';
 import { isTerminalMilestoneSummaryContent } from './milestone-summary-classifier.js';
+import { incrementLegacyTelemetry } from './legacy-telemetry.js';
 import { isDbAvailable, wasDbOpenAttempted, getAllMilestones, getMilestone, getMilestoneSlices, getSliceTasks, getReplanHistory, getSlice, getRequirementCounts, getLatestAssessmentByScope, getPendingGateCountForTurn, } from './gsd-db.js';
 /**
  * A "ghost" milestone directory contains only META.json (and no substantive
@@ -239,6 +242,7 @@ export async function deriveState(basePath, opts) {
         }
         result = await _deriveStateImpl(basePath, opts);
         _telemetry.markdownDeriveCount++;
+        incrementLegacyTelemetry("legacy.markdownFallbackUsed");
     }
     else {
         if (wasDbOpenAttempted()) {

package/dist/resources/extensions/gsd/tools/complete-milestone.js

@@ -1,3 +1,4 @@
+// GSD2 complete-milestone tool handler
 /**
  * complete-milestone handler — the core operation behind gsd_complete_milestone.
  *
@@ -89,6 +90,7 @@ export async function handleCompleteMilestone(params, basePath) {
     // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
     const completedAt = new Date().toISOString();
     let guardError = null;
+    let alreadyComplete = false;
     transaction(() => {
         // State machine preconditions (inside txn for atomicity)
         const milestone = getMilestone(params.milestoneId);
@@ -97,7 +99,7 @@ export async function handleCompleteMilestone(params, basePath) {
             return;
         }
         if (isClosedStatus(milestone.status)) {
-            guardError = `milestone ${params.milestoneId} is already complete`;
+            alreadyComplete = true;
             return;
         }
         // Verify all slices are complete
@@ -177,14 +179,16 @@ export async function handleCompleteMilestone(params, basePath) {
         logWarning("tool", `complete-milestone manifest warning: ${mfErr.message}`);
     }
     try {
-        appendEvent(basePath, {
-            cmd: "complete-milestone",
-            params: { milestoneId: params.milestoneId },
-            ts: new Date().toISOString(),
-            actor: "agent",
-            actor_name: params.actorName,
-            trigger_reason: params.triggerReason,
-        });
+        if (!alreadyComplete) {
+            appendEvent(basePath, {
+                cmd: "complete-milestone",
+                params: { milestoneId: params.milestoneId },
+                ts: new Date().toISOString(),
+                actor: "agent",
+                actor_name: params.actorName,
+                trigger_reason: params.triggerReason,
+            });
+        }
     }
     catch (eventErr) {
         logError("tool", `complete-milestone event log FAILED — completion invisible to reconciliation`, { error: eventErr.message });
@@ -193,5 +197,6 @@ export async function handleCompleteMilestone(params, basePath) {
         milestoneId: params.milestoneId,
         summaryPath,
         ...(projectionStale ? { stale: true } : {}),
+        ...(alreadyComplete ? { alreadyComplete: true } : {}),
     };
 }

package/dist/resources/extensions/gsd/tools/complete-task.js

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Complete-task tool handler for GSD workflow state and summaries.
 /**
  * complete-task handler — the core operation behind gsd_complete_task.
  *

package/dist/resources/extensions/gsd/tools/workflow-tool-executors.js

@@ -376,12 +376,17 @@ export async function executeCompleteMilestone(params, basePath = process.cwd())
                 isError: true,
             };
         }
+        const message = result.alreadyComplete
+            ? `Milestone ${result.milestoneId} is already complete. Summary available at ${result.summaryPath}`
+            : `Completed milestone ${result.milestoneId}. Summary written to ${result.summaryPath}`;
         return {
-            content: [{ type: "text", text: `Completed milestone ${result.milestoneId}. Summary written to ${result.summaryPath}` }],
+            content: [{ type: "text", text: message }],
             details: {
                 operation: "complete_milestone",
                 milestoneId: result.milestoneId,
                 summaryPath: result.summaryPath,
+                ...(result.alreadyComplete ? { alreadyComplete: true } : {}),
+                ...(result.stale ? { stale: true } : {}),
             },
         };
     }

package/dist/resources/extensions/gsd/unit-context-composer.js

@@ -80,7 +80,7 @@ const CONTEXT_MODE_LANE_LABELS = {
     orchestration: "orchestration",
     docs: "documentation",
 };
-const CONTEXT_MODE_GUIDANCE = "Use `gsd_exec` for noisy scans, builds, and tests so full output stays out of prompt context; call `gsd_exec_search` before repeating prior runs; call `gsd_resume` after compaction or resume to recover stored execution context.";
+const CONTEXT_MODE_GUIDANCE = "Use `gsd_exec` for noisy commands, `gsd_exec_search` before reruns, and `gsd_resume` after compaction or resume.";
 /**
  * Render the Context Mode instruction lane for a unit type. Unknown unit
  * types, disabled config, and explicit `contextMode: "none"` all omit the

package/dist/resources/extensions/gsd/uok/kernel.js

@@ -5,6 +5,7 @@ import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
 import { setUnifiedAuditEnabled } from "./audit-toggle.js";
 import { resolveUokFlags } from "./flags.js";
 import { createTurnObserver } from "./loop-adapter.js";
+import { incrementLegacyTelemetry } from "../legacy-telemetry.js";
 function parityLogPath(basePath) {
     return join(gsdRoot(basePath), "runtime", "uok-parity.jsonl");
 }
@@ -27,9 +28,13 @@ export async function runAutoLoopWithUok(args) {
     const prefs = deps.loadEffectiveGSDPreferences()?.preferences;
     const flags = resolveUokFlags(prefs);
     setUnifiedAuditEnabled(flags.auditUnified);
+    const pathLabel = resolveKernelPathLabel(flags);
+    if (pathLabel !== "uok-kernel") {
+        incrementLegacyTelemetry("legacy.uokFallbackUsed");
+    }
     writeParityEvent(s.basePath, {
         ts: new Date().toISOString(),
-        path: resolveKernelPathLabel(flags),
+        path: pathLabel,
         flags,
         phase: "enter",
     });
@@ -65,7 +70,7 @@ export async function runAutoLoopWithUok(args) {
         }
         writeParityEvent(s.basePath, {
             ts: new Date().toISOString(),
-            path: resolveKernelPathLabel(flags),
+            path: pathLabel,
             flags,
             phase: "exit",
             status: "ok",
@@ -74,7 +79,7 @@ export async function runAutoLoopWithUok(args) {
     catch (err) {
         writeParityEvent(s.basePath, {
             ts: new Date().toISOString(),
-            path: resolveKernelPathLabel(flags),
+            path: pathLabel,
             flags,
             phase: "exit",
             status: "error",

package/dist/resources/extensions/gsd/uok/plan-v2.js

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: UOK plan v2 graph compilation from GSD workflow state.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot, resolveMilestoneFile, resolveSliceFile } from "../paths.js";

package/dist/resources/extensions/gsd/workflow-logger.js

@@ -3,13 +3,12 @@
 // Captures structured entries that the auto-loop can drain after each unit
 // to surface root causes for stuck loops, silent degradation, and blocked writes.
 // Error-severity entries are persisted to .gsd/audit-log.jsonl (sanitized) for
-// post-mortem analysis. Warnings are ephemeral (stderr + buffer only) to avoid
-// log amplification from expected-control-flow catch paths.
+// post-mortem analysis. Warnings persist to notifications and remain available
+// in the in-memory buffer, but are not printed to stderr.
 //
-// Stderr policy: every logWarning/logError call writes immediately to stderr
-// for terminal visibility. This is intentional — unlike debug-logger (which is
-// opt-in and zero-overhead when disabled), workflow-logger covers operational
-// warnings/errors that should always be visible. There is no disable flag.
+// Stderr policy: logError writes immediately to stderr for terminal visibility.
+// logWarning stays out of the TUI/stdout stream and is surfaced through the
+// notification store plus the auto-loop issue buffer.
 //
 // Singleton safety: _buffer is module-level and shared across all calls within
 // a process. The auto-loop must call _resetLogs() (or drainAndSummarize()) at
@@ -45,7 +44,8 @@ export function setStderrLoggingEnabled(enabled) {
 }
 // ─── Public API ─────────────────────────────────────────────────────────
 /**
- * Record a warning. Also writes to stderr for terminal visibility.
+ * Record a warning. Warnings are persisted to notifications and buffered for
+ * auto-loop issue summaries, but they are intentionally not written to stderr.
  */
 export function logWarning(component, message, context) {
     _push("warn", component, message, context);
@@ -189,10 +189,10 @@ function _push(severity, component, message, context) {
         message,
         ...(context ? { context } : {}),
     };
-    // Always forward to stderr so terminal watchers see it (see module header for policy)
-    const prefix = severity === "error" ? "ERROR" : "WARN";
-    const ctxStr = context ? ` ${JSON.stringify(context)}` : "";
-    _writeStderr(`[gsd:${component}] ${prefix}: ${message}${ctxStr}\n`);
+    if (severity === "error") {
+        const ctxStr = context ? ` ${JSON.stringify(context)}` : "";
+        _writeStderr(`[gsd:${component}] ERROR: ${message}${ctxStr}\n`);
+    }
     // Persist to notification store (both warnings and errors)
     try {
         appendNotification(`[${component}] ${message}`, severity === "error" ? "error" : "warning", "workflow-logger");
@@ -226,8 +226,8 @@ function _push(severity, component, message, context) {
         }
     }
     // Persist errors to .gsd/audit-log.jsonl so they survive context resets.
-    // Only error-severity entries are persisted — warnings are ephemeral (stderr + buffer)
-    // to avoid log amplification from expected-control-flow catch paths.
+    // Warnings are already persisted to notifications and buffered for the
+    // current auto-loop unit.
     if (_auditBasePath && severity === "error") {
         try {
             const auditDir = join(_auditBasePath, ".gsd");

package/dist/resources/extensions/gsd/workflow-manifest.js

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: State manifest snapshot and restore orchestration for GSD workflow data.
 import { _getAdapter, readTransaction, restoreManifest, } from "./gsd-db.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { readFileSync, existsSync, mkdirSync } from "node:fs";

package/dist/resources/extensions/gsd/workflow-projections.js

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Projection renderers for GSD workflow database rows.
 // GSD Extension — Projection Renderers (DB -> Markdown)
 // Renders PLAN.md, ROADMAP.md, SUMMARY.md, and STATE.md from database rows.
 // Projections are read-only views of engine state (Layer 3 of the architecture).

package/dist/resources/extensions/gsd/workflow-templates.js

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Workflow template registry loading, matching, and display helpers.
 /**
  * GSD Workflow Templates — Registry & Resolution
  *
@@ -8,6 +10,7 @@ import { readFileSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { gsdHome } from "./gsd-home.js";
+import { formatRecommendedProcessPaths } from "./process-task-path.js";
 const __extensionDir = resolveGsdExtensionDir();
 const registryPath = join(__extensionDir, "workflow-templates", "registry.json");
 /** Resolve the GSD extension dir with fallback to ~/.gsd/agent/extensions/gsd/. */
@@ -20,6 +23,9 @@ function resolveGsdExtensionDir() {
         return agentGsdDir;
     return moduleDir;
 }
+export function isLegacyWorkflowMode(mode) {
+    return (mode ?? "markdown-phase") !== "auto-milestone";
+}
 // ─── Registry Cache ──────────────────────────────────────────────────────────
 let cachedRegistry = null;
 /**
@@ -159,6 +165,9 @@ export function listTemplates() {
     }
     lines.push("Usage: /gsd start <template> [description]");
     lines.push("       /gsd templates info <name>");
+    lines.push("");
+    lines.push("Recommended Task Paths:");
+    lines.push(formatRecommendedProcessPaths());
     return lines.join("\n");
 }
 /**