gsd-pi 2.79.0 → 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

@@ -1,7 +1,7 @@
 import { ensureDbOpen } from "../bootstrap/dynamic-tools.js";
 import { sanitizeCompleteMilestoneParams } from "../bootstrap/sanitize-complete-milestone.js";
 import { loadWriteGateSnapshot, shouldBlockContextArtifactSaveInSnapshot, shouldBlockRootArtifactSaveInSnapshot } from "../bootstrap/write-gate.js";
-import { getActiveRequirements, getMilestone, getSliceStatusSummary, getSliceTaskCounts, readTransaction, saveGateResult, } from "../gsd-db.js";
+import { getActiveRequirements, insertMilestone, getMilestone, getSliceStatusSummary, getSliceTaskCounts, readTransaction, saveGateResult, } from "../gsd-db.js";
 import { GATE_REGISTRY } from "../gate-registry.js";
 import { generateRequirementsMd, saveArtifactToDb } from "../db-writer.js";
 import { resolveMilestoneFile, resolveSliceFile } from "../paths.js";
@@ -17,6 +17,7 @@ import { handleValidateMilestone } from "./validate-milestone.js";
 import { logError, logWarning } from "../workflow-logger.js";
 import { invalidateStateCache } from "../state.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { parseProject } from "../schemas/parsers.js";
 export const SUPPORTED_SUMMARY_ARTIFACT_TYPES = [
     "SUMMARY",
     "RESEARCH",
@@ -37,6 +38,19 @@ function isRootSummaryArtifactType(artifactType) {
         artifactType === "REQUIREMENTS" ||
         artifactType === "REQUIREMENTS-DRAFT";
 }
+function registerProjectMilestoneSequence(content) {
+    const parsed = parseProject(content);
+    const registered = [];
+    for (const milestone of parsed.milestones) {
+        insertMilestone({
+            id: milestone.id,
+            title: milestone.title,
+            status: milestone.done ? "complete" : "queued",
+        });
+        registered.push(milestone.id);
+    }
+    return registered;
+}
 export async function executeSummarySave(params, basePath = process.cwd()) {
     const dbAvailable = await ensureDbOpen(basePath);
     if (!dbAvailable) {
@@ -126,6 +140,66 @@ export async function executeSummarySave(params, basePath = process.cwd()) {
             slice_id: isRootArtifact ? undefined : params.slice_id,
             task_id: isRootArtifact ? undefined : params.task_id,
         }, basePath);
+        let registeredMilestones = [];
+        if (params.artifact_type === "PROJECT") {
+            try {
+                registeredMilestones = registerProjectMilestoneSequence(contentToSave);
+                if (registeredMilestones.length > 0)
+                    invalidateStateCache();
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                logError("tool", `gsd_summary_save: PROJECT artifact persisted but milestone registration threw: ${msg}`, {
+                    tool: "gsd_summary_save",
+                    error: String(err),
+                    stack: err instanceof Error ? err.stack ?? "" : "",
+                });
+                // PROJECT.md was persisted by saveArtifactToDb above; the artifacts row
+                // changed even though no milestones registered. Invalidate so subsequent
+                // /gsd reads see the persisted artifact instead of the pre-save cache.
+                invalidateStateCache();
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Error: PROJECT.md was saved to ${relativePath} but milestone registration failed: ${msg}. ` +
+                                `The DB has no milestone rows for this project, so /gsd will report "No Active Milestone". ` +
+                                `Re-call gsd_summary_save(PROJECT) once the underlying error is resolved — INSERT OR IGNORE makes registration idempotent.`,
+                        }],
+                    details: {
+                        operation: "save_summary",
+                        path: relativePath,
+                        artifact_type: params.artifact_type,
+                        error: "milestone_registration_threw",
+                        registration_error: msg,
+                    },
+                    isError: true,
+                };
+            }
+            if (registeredMilestones.length === 0) {
+                logError("tool", `gsd_summary_save: PROJECT.md saved to ${relativePath} but parsed zero milestones — registration produced no DB rows`, {
+                    tool: "gsd_summary_save",
+                });
+                // PROJECT.md was persisted; invalidate so subsequent reads see the new
+                // artifacts row even though no milestones registered.
+                invalidateStateCache();
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Error: PROJECT.md was saved to ${relativePath} but contains zero parseable milestone lines, ` +
+                                `so no milestones were registered in the DB. /gsd will report "No Active Milestone". ` +
+                                `Rewrite PROJECT.md so the "Milestone Sequence" section uses canonical lines: ` +
+                                `\`- [ ] M001: <Title> — <One-liner>\` (em-dash, double-dash \`--\`, or single-dash \`-\` separator), then re-call gsd_summary_save(PROJECT).`,
+                        }],
+                    details: {
+                        operation: "save_summary",
+                        path: relativePath,
+                        artifact_type: params.artifact_type,
+                        error: "milestone_registration_empty_parse",
+                    },
+                    isError: true,
+                };
+            }
+        }
         if (params.artifact_type === "CONTEXT" && !params.task_id) {
             try {
                 const draftFile = params.slice_id
@@ -140,7 +214,13 @@ export async function executeSummarySave(params, basePath = process.cwd()) {
         }
         return {
             content: [{ type: "text", text: `Saved ${params.artifact_type} artifact to ${relativePath}` }],
-            details: { operation: "save_summary", path: relativePath, artifact_type: params.artifact_type, content_source: contentSource },
+            details: {
+                operation: "save_summary",
+                path: relativePath,
+                artifact_type: params.artifact_type,
+                content_source: contentSource,
+                ...(registeredMilestones.length > 0 ? { registeredMilestones } : {}),
+            },
         };
     }
     catch (err) {
@@ -296,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

@@ -71,6 +71,38 @@ export function manifestBudgetChars(unitType) {
     const manifest = resolveManifest(unitType);
     return manifest ? manifest.maxSystemPromptChars : null;
 }
+const CONTEXT_MODE_LANE_LABELS = {
+    interview: "interview",
+    research: "research",
+    planning: "planning",
+    execution: "execution",
+    verification: "verification",
+    orchestration: "orchestration",
+    docs: "documentation",
+};
+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
+ * block so callers can prefix this safely without extra branching.
+ */
+export function composeContextModeInstructions(unitType, opts) {
+    if (!opts.enabled)
+        return "";
+    const manifest = resolveManifest(unitType);
+    if (!manifest || manifest.contextMode === "none")
+        return "";
+    const lane = CONTEXT_MODE_LANE_LABELS[manifest.contextMode];
+    if (opts.renderMode === "nested") {
+        return `Context Mode (${lane} lane): ${CONTEXT_MODE_GUIDANCE}`;
+    }
+    return [
+        "## Context Mode",
+        "",
+        `Lane: **${lane} lane**.`,
+        CONTEXT_MODE_GUIDANCE,
+    ].join("\n");
+}
 const SECTION_SEPARATOR = "\n\n---\n\n";
 /**
  * Compose all manifest-declared context for a unit type using the v2