gsd-pi 2.77.0-dev.1d17f366c → 2.77.0-dev.2daa994b6

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

@@ -0,0 +1,69 @@
+/**
+ * Unified Component Type Definitions
+ *
+ * Shared metadata for installable/discoverable skills and agents.
+ *
+ * Replaces the separate type systems in:
+ * - packages/pi-coding-agent/src/core/skills.ts (SkillFrontmatter, Skill)
+ * - src/resources/extensions/subagent/agents.ts (AgentConfig)
+ *
+ * Legacy skill and agent formats are supported via backward-compatible loading.
+ */
+// ============================================================================
+// Validation
+// ============================================================================
+/** Max name length per spec */
+export const MAX_NAME_LENGTH = 64;
+/** Max description length per spec */
+export const MAX_DESCRIPTION_LENGTH = 1024;
+/** Valid name pattern: lowercase a-z, 0-9, hyphens, no leading/trailing/consecutive hyphens */
+export const NAME_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+/**
+ * Validate a component name.
+ * @returns Array of error messages (empty if valid).
+ */
+export function validateComponentName(name) {
+    const errors = [];
+    if (!name || name.trim() === '') {
+        errors.push('name is required');
+        return errors;
+    }
+    if (name.length > MAX_NAME_LENGTH) {
+        errors.push(`name exceeds ${MAX_NAME_LENGTH} characters (${name.length})`);
+    }
+    if (name.includes('--')) {
+        errors.push('name must not contain consecutive hyphens');
+    }
+    if (!NAME_PATTERN.test(name)) {
+        if (/[A-Z]/.test(name)) {
+            errors.push('name must be lowercase');
+        }
+        else if (name.startsWith('-') || name.endsWith('-')) {
+            errors.push('name must not start or end with a hyphen');
+        }
+        else if (!name.includes('--')) {
+            errors.push('name must contain only lowercase a-z, 0-9, and hyphens');
+        }
+    }
+    return errors;
+}
+/**
+ * Validate a component description.
+ * @returns Array of error messages (empty if valid).
+ */
+export function validateComponentDescription(description) {
+    const errors = [];
+    if (!description || description.trim() === '') {
+        errors.push('description is required');
+    }
+    else if (description.length > MAX_DESCRIPTION_LENGTH) {
+        errors.push(`description exceeds ${MAX_DESCRIPTION_LENGTH} characters (${description.length})`);
+    }
+    return errors;
+}
+/**
+ * Compute the canonical ID for a component.
+ */
+export function computeComponentId(name, namespace) {
+    return namespace ? `${namespace}:${name}` : name;
+}

package/dist/resources/extensions/gsd/context-store.js

@@ -180,7 +180,13 @@ export function queryProject() {
 // ─── Knowledge Query ───────────────────────────────────────────────────────
 /**
  * Filter KNOWLEDGE.md sections by keyword matching.
- * Uses H2 sections, matches keywords case-insensitively against:
+ *
+ * Structure-adaptive (issue #4719): files that organise entries as H3 items
+ * under one or more H2 topics are filtered at H3 granularity. Files with only
+ * H2 topic headers (no H3) fall back to H2-level filtering for backwards
+ * compatibility.
+ *
+ * Matches keywords case-insensitively against:
  * 1. Section header text
  * 2. First paragraph of section content (up to first blank line or next heading)
  *
@@ -189,28 +195,38 @@ export function queryProject() {
  *
  * @param content - Full KNOWLEDGE.md content
  * @param keywords - Keywords to match (case-insensitive)
- * @returns Concatenated matching sections with H2 headers, or empty string
+ * @returns Concatenated matching sections with their original heading prefix, or empty string
  */
 export async function queryKnowledge(content, keywords) {
     if (!content || keywords.length === 0)
         return '';
     // Lazy import to avoid circular dependency
     const { extractAllSections } = await import('./files.js');
-    const sections = extractAllSections(content, 2);
+    // Prefer H3 granularity when available; fall back to H2 for H2-only files.
+    // This prevents single-H2-with-many-H3 layouts from returning the entire
+    // file on a keyword match against the H2 header or its first paragraph.
+    const h3Sections = extractAllSections(content, 3);
+    const useH3 = h3Sections.size > 0;
+    const sections = useH3 ? h3Sections : extractAllSections(content, 2);
     if (sections.size === 0)
         return '';
-    // Normalize keywords for case-insensitive matching
-    const normalizedKeywords = keywords.map(k => k.toLowerCase());
+    const prefix = useH3 ? '###' : '##';
+    // Trim, lowercase, drop empties, and de-dupe so callers can pass raw
+    // user-provided strings without risking empty-string / whitespace matches.
+    const normalizedKeywords = [...new Set(keywords
+            .map(k => k.trim().toLowerCase())
+            .filter(k => k.length > 0))];
+    if (normalizedKeywords.length === 0)
+        return '';
     const matchingSections = [];
     for (const [header, body] of sections) {
         // Extract first paragraph: everything up to first blank line or next heading
         const firstParagraph = body.split(/\n\s*\n|\n#/)[0] || '';
-        // Check if any keyword matches header or first paragraph
         const headerLower = header.toLowerCase();
         const paragraphLower = firstParagraph.toLowerCase();
         const matches = normalizedKeywords.some(kw => headerLower.includes(kw) || paragraphLower.includes(kw));
         if (matches) {
-            matchingSections.push(`## ${header}\n\n${body}`);
+            matchingSections.push(`${prefix} ${header}\n\n${body}`);
         }
     }
     return matchingSections.join('\n\n');

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

@@ -6,7 +6,7 @@
  * flow to show when entering a project directory.
  */
 import { existsSync, openSync, readSync, closeSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join, parse as parsePath } from "node:path";
 import { homedir } from "node:os";
 import { gsdRoot } from "./paths.js";
 const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
@@ -951,6 +951,54 @@ function resolveVersionCatalogAccessors(basePath, versionCatalogFiles, settingsF
     }
     return accessors;
 }
+/**
+ * Walk ancestor directories of `startDir` looking for any file in
+ * `PROJECT_FILES`. Stops at the filesystem root or at a `.git` boundary
+ * (so ancestors above a git repo root — e.g. `$HOME` or `/usr/local` —
+ * can't trigger false positives). Returns true if an ancestor contains
+ * one of the project markers.
+ *
+ * Used by the worktree health check (#2347) to avoid warning about
+ * monorepos where package.json / Cargo.toml / etc. live in a parent
+ * directory rather than in the worktree's own checkout.
+ *
+ * `existsFn` is injectable so this remains deterministically testable
+ * without touching the real filesystem; defaults to `fs.existsSync`.
+ */
+export function hasProjectFileInAncestor(startDir, existsFn = existsSync) {
+    let checkDir = dirname(startDir);
+    const { root } = parsePath(checkDir);
+    while (checkDir !== root) {
+        if (PROJECT_FILES.some((f) => existsFn(join(checkDir, f)))) {
+            return true;
+        }
+        // Stop at git repository boundary — ancestors above the repo root
+        // may contain unrelated project files. Check AFTER project-file scan
+        // so a repo root containing both .git and a marker is still recognized.
+        if (existsFn(join(checkDir, ".git")))
+            return false;
+        checkDir = dirname(checkDir);
+    }
+    return false;
+}
+/**
+ * Check whether a project's `.gsd/` directory contains the bootstrap artifacts
+ * (`PREFERENCES.md` or `milestones/`) that indicate a completed init run.
+ *
+ * A zombie `.gsd/` state — symlink exists but neither artifact is present —
+ * must be treated as "needs init wizard". The previous guard checked only
+ * `existsSync(gsdRoot(basePath))`, which accepted zombie states and skipped
+ * the wizard (#2942).
+ *
+ * `existsFn` is injectable so tests can run deterministically; defaults to
+ * `fs.existsSync`.
+ */
+export function hasGsdBootstrapArtifacts(gsdPath, existsFn = existsSync) {
+    return (existsFn(gsdPath) &&
+        (existsFn(join(gsdPath, "PREFERENCES.md")) ||
+            existsFn(join(gsdPath, "preferences.md")) ||
+            existsFn(join(gsdPath, "milestones"))));
+}
 export function scanProjectFiles(basePath) {
     const files = [];
     const queue = [{ path: basePath, depth: 0 }];

package/dist/resources/extensions/gsd/docs/preferences-reference.md

@@ -159,7 +159,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
 
 - `phases`: fine-grained control over which phases run. Usually set by `token_profile`, but can be overridden. Keys:
   - `skip_research`: boolean — skip milestone-level research. Default: `false`.
-  - `reassess_after_slice`: boolean — run roadmap reassessment after each completed slice. Default: `true`.
+  - `reassess_after_slice`: boolean — run a dedicated roadmap-reassessment unit after each completed slice. Default: `false` (per ADR-003 §4). The plan-slice agent for the next slice performs JIT reassessment via a prompt preamble at zero additional token cost; a dedicated reassess session is opt-in. Set to `true` (e.g. via the `burn-max` profile) if you want the explicit session.
   - `skip_reassess`: boolean — force-disable roadmap reassessment even if `reassess_after_slice` is enabled. Default: `false`.
   - `skip_slice_research`: boolean — skip per-slice research. Default: `false`.
 

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

@@ -29,6 +29,7 @@ import { getAutoWorktreePath } from "./auto-worktree.js";
 import { loadEffectiveGSDPreferences, loadGlobalGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js";
 import { showNextAction } from "../shared/tui.js";
 import { ensurePreferencesFile, serializePreferencesToFrontmatter } from "./commands-prefs-wizard.js";
+import { summarizeWorktreeTelemetry, percentile } from "./worktree-telemetry.js";
 // ─── Duplicate Detection ──────────────────────────────────────────────────────
 const DEDUP_PROMPT_SECTION = `
 ## Pre-Investigation: Duplicate Check (REQUIRED)
@@ -214,6 +215,16 @@ export async function buildForensicReport(basePath) {
     detectCrash(crashLock, anomalies);
     detectDoctorIssues(doctorIssues, anomalies);
     detectErrorTraces(unitTraces, anomalies);
+    // 11b. #4764 — worktree lifecycle telemetry
+    let worktreeTelemetry = null;
+    try {
+        worktreeTelemetry = summarizeWorktreeTelemetry(basePath);
+        detectWorktreeOrphans(worktreeTelemetry, anomalies);
+    }
+    catch {
+        // Telemetry is best-effort — do not let an aggregator failure block the
+        // rest of the forensic report.
+    }
     detectJournalAnomalies(journalSummary, anomalies);
     return {
         gsdVersion,
@@ -232,6 +243,7 @@ export async function buildForensicReport(basePath) {
         recentUnits,
         journalSummary,
         activityLogMeta,
+        worktreeTelemetry,
     };
 }
 // ─── Activity Log Scanner ─────────────────────────────────────────────────────
@@ -630,6 +642,45 @@ function detectMissingArtifacts(completedKeys, basePath, activeMilestone, anomal
         }
     }
 }
+/**
+ * #4764 — surface worktree lifecycle and orphan signals in the forensic report.
+ *
+ * Consumes only the aggregated summary (not raw journal events) to respect
+ * the forensics memory-bloat guard in forensics-journal.test.ts — per-event
+ * detail stays in the journal itself where the LLM can query it on demand.
+ */
+function detectWorktreeOrphans(summary, anomalies) {
+    // 1. Orphan aggregate — severity depends on reason. In-progress orphans are
+    // the #4761 consumer-side signal (live work sitting on an unmerged branch).
+    for (const [reason, count] of Object.entries(summary.orphansByReason)) {
+        if (count <= 0)
+            continue;
+        const severity = reason === "in-progress-unmerged" ? "warning" : "info";
+        anomalies.push({
+            type: "worktree-orphan",
+            severity,
+            summary: `${count} worktree orphan(s) detected (${reason})`,
+            details: reason === "in-progress-unmerged"
+                ? "Auto-mode exited without completing a milestone; live work sits on an unmerged milestone branch. Run `/gsd auto` to resume, or merge manually."
+                : reason === "complete-unmerged"
+                    ? "A completed milestone's branch was never merged back to main. Run `/gsd health --fix` to resolve."
+                    : `Reason: ${reason}.`,
+        });
+    }
+    // 2. Auto-exit producer signal — #4761's upstream cause.
+    if (summary.exitsWithUnmergedWork > 0) {
+        const reasonBreakdown = Object.entries(summary.exitsByReason)
+            .filter(([, n]) => n > 0)
+            .map(([r, n]) => `${r}=${n}`)
+            .join(", ");
+        anomalies.push({
+            type: "worktree-unmerged-exit",
+            severity: "warning",
+            summary: `${summary.exitsWithUnmergedWork} auto-exit(s) left milestone work unmerged`,
+            details: `Exit reasons: ${reasonBreakdown || "(none)"} · Producer-side signal for #4761-class orphans. Inspect .gsd/journal/*.jsonl with eventType:"auto-exit" for per-exit detail.`,
+        });
+    }
+}
 function detectCrash(crashLock, anomalies) {
     if (!crashLock)
         return;
@@ -808,6 +859,39 @@ function saveForensicReport(basePath, report, problemDescription) {
             sections.push(`- Newest: ${meta.newestFile}`);
         sections.push(``);
     }
+    // #4764 — Worktree telemetry summary
+    if (report.worktreeTelemetry) {
+        const t = report.worktreeTelemetry;
+        const p50 = percentile(t.mergeDurationsMs, 0.5);
+        const p95 = percentile(t.mergeDurationsMs, 0.95);
+        sections.push(`## Worktree Telemetry`, ``);
+        sections.push(`- Worktrees created: ${t.worktreesCreated}`);
+        sections.push(`- Worktrees merged: ${t.worktreesMerged}`);
+        sections.push(`- Orphans detected: ${t.orphansDetected}`);
+        if (t.orphansDetected > 0) {
+            const breakdown = Object.entries(t.orphansByReason)
+                .map(([r, n]) => `${r}=${n}`).join(", ");
+            sections.push(`  - By reason: ${breakdown}`);
+        }
+        sections.push(`- Merge conflicts: ${t.mergeConflicts}`);
+        if (t.mergeDurationsMs.length > 0) {
+            sections.push(`- Merge duration p50 / p95: ${p50 ?? "-"} / ${p95 ?? "-"} ms (n=${t.mergeDurationsMs.length})`);
+        }
+        sections.push(`- Auto-exits leaving unmerged work: ${t.exitsWithUnmergedWork}`);
+        if (Object.keys(t.exitsByReason).length > 0) {
+            const breakdown = Object.entries(t.exitsByReason)
+                .sort((a, b) => b[1] - a[1])
+                .map(([r, n]) => `${r}=${n}`).join(", ");
+            sections.push(`  - Exit reasons: ${breakdown}`);
+        }
+        sections.push(`- Canonical-root redirects (#4761 fix fired): ${t.canonicalRedirects}`);
+        // #4765 slice-cadence counters
+        if (t.slicesMerged + t.sliceMergeConflicts + t.milestoneResquashes > 0) {
+            sections.push(`- Slices merged: ${t.slicesMerged} · Slice merge conflicts: ${t.sliceMergeConflicts}`);
+            sections.push(`- Milestone re-squashes: ${t.milestoneResquashes}`);
+        }
+        sections.push(``);
+    }
     // Journal summary
     if (report.journalSummary) {
         const js = report.journalSummary;
@@ -940,6 +1024,28 @@ function formatReportForPrompt(report) {
         sections.push(`- Total duration: ${formatDuration(totals.duration)}`);
         sections.push("");
     }
+    // #4764 — worktree telemetry (compact prompt form)
+    if (report.worktreeTelemetry) {
+        const t = report.worktreeTelemetry;
+        const hasSignal = t.worktreesCreated + t.worktreesMerged + t.orphansDetected +
+            t.exitsWithUnmergedWork + t.canonicalRedirects +
+            t.slicesMerged + t.milestoneResquashes > 0;
+        if (hasSignal) {
+            sections.push("### Worktree Telemetry");
+            sections.push(`- Created: ${t.worktreesCreated} · Merged: ${t.worktreesMerged} · Conflicts: ${t.mergeConflicts}`);
+            sections.push(`- Orphans: ${t.orphansDetected} · Unmerged exits: ${t.exitsWithUnmergedWork} · Redirects (#4761): ${t.canonicalRedirects}`);
+            if (t.orphansDetected > 0) {
+                const breakdown = Object.entries(t.orphansByReason)
+                    .map(([r, n]) => `${r}=${n}`).join(", ");
+                sections.push(`- Orphan reasons: ${breakdown}`);
+            }
+            // #4765 — slice-cadence counters (only shown when the feature was exercised)
+            if (t.slicesMerged + t.sliceMergeConflicts + t.milestoneResquashes > 0) {
+                sections.push(`- Slices merged: ${t.slicesMerged} · Slice conflicts: ${t.sliceMergeConflicts} · Re-squashes: ${t.milestoneResquashes}`);
+            }
+            sections.push("");
+        }
+    }
     // Activity log metadata
     if (report.activityLogMeta) {
         const meta = report.activityLogMeta;

package/dist/resources/extensions/gsd/gsd-db.js

@@ -135,7 +135,7 @@ function openRawDb(path) {
     const Database = providerModule;
     return new Database(path);
 }
-const SCHEMA_VERSION = 22;
+export const SCHEMA_VERSION = 22;
 function indexExists(db, name) {
     return !!db.prepare("SELECT 1 as present FROM sqlite_master WHERE type = 'index' AND name = ?").get(name);
 }

package/dist/resources/extensions/gsd/guided-flow.js

@@ -28,7 +28,7 @@ import { ensureGitignore, ensurePreferences, untrackRuntimeFiles } from "./gitig
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { resolveUokFlags } from "./uok/flags.js";
 import { ensurePlanV2Graph, isMissingFinalizedContextResult } from "./uok/plan-v2.js";
-import { detectProjectState } from "./detection.js";
+import { detectProjectState, hasGsdBootstrapArtifacts } from "./detection.js";
 import { showProjectInit, offerMigration } from "./init-wizard.js";
 import { validateDirectory } from "./validate-directory.js";
 import { showConfirm } from "../shared/tui.js";
@@ -1244,9 +1244,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
     // A zombie .gsd/ state (symlink exists but missing PREFERENCES.md and
     // milestones/) must trigger the init wizard, not skip it (#2942).
     const gsdPath = gsdRoot(basePath);
-    const hasBootstrapArtifacts = existsSync(gsdPath)
-        && (existsSync(join(gsdPath, "PREFERENCES.md"))
-            || existsSync(join(gsdPath, "milestones")));
+    const hasBootstrapArtifacts = hasGsdBootstrapArtifacts(gsdPath);
     if (!hasBootstrapArtifacts) {
         const detection = detectProjectState(basePath);
         // v1 .planning/ detected — offer migration before anything else

package/dist/resources/extensions/gsd/memory-extractor.js

@@ -62,7 +62,9 @@ export function buildMemoryLLMCall(ctx) {
         // which returns undefined for OAuth users (Claude Max / Claude Pro).
         // See: https://github.com/gsd-build/gsd-2/issues/2959
         const resolvedKeyPromise = ctx.modelRegistry.getApiKey(selectedModel).catch(() => undefined);
-        return async (system, user) => {
+        // Expose on the returned fn so tests can await resolution deterministically
+        // (avoids arbitrary setTimeout polling for an internal microtask).
+        const llmCall = async (system, user) => {
             const { completeSimple } = await import('@gsd/pi-ai');
             const resolvedApiKey = await resolvedKeyPromise;
             const result = await completeSimple(selectedModel, {
@@ -79,6 +81,10 @@ export function buildMemoryLLMCall(ctx) {
                 .map(c => c.text);
             return textParts.join('');
         };
+        // Attach the in-flight API-key resolution so tests (and callers) can
+        // `await llmCall.apiKeyReady` rather than relying on setTimeout polling.
+        llmCall.apiKeyReady = resolvedKeyPromise;
+        return llmCall;
     }
     catch {
         return null;