gsd-pi 2.77.0 → 2.78.0-dev.aeeb2ca00

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

@@ -0,0 +1,362 @@
+/**
+ * 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.
+ */
+
+// ============================================================================
+// Component Kind
+// ============================================================================
+
+/** All supported component types for the first component-system slice. */
+export type ComponentKind = 'skill' | 'agent';
+
+/** API version for component.yaml spec */
+export type ComponentApiVersion = 'gsd/v1';
+
+// ============================================================================
+// Component Metadata
+// ============================================================================
+
+export interface ComponentAuthor {
+	name: string;
+	email?: string;
+	url?: string;
+}
+
+export interface ComponentMetadata {
+	/** Component name (lowercase a-z, 0-9, hyphens). Required. */
+	name: string;
+
+	/** Human-readable description. Required. */
+	description: string;
+
+	/** Namespace for plugin-sourced components (e.g., "my-plugin"). */
+	namespace?: string;
+
+	/** Semver version string. */
+	version?: string;
+
+	/** Author information. */
+	author?: ComponentAuthor;
+
+	/** Searchable tags. */
+	tags?: string[];
+
+	/** SPDX license identifier. */
+	license?: string;
+}
+
+// ============================================================================
+// Skill Spec
+// ============================================================================
+
+export interface SkillSpec {
+	/** Path to the prompt content file (relative to component dir). */
+	prompt: string;
+
+	/** If true, skill is excluded from LLM system prompt (invoke-only). */
+	disableModelInvocation?: boolean;
+}
+
+// ============================================================================
+// Agent Spec
+// ============================================================================
+
+export interface AgentToolConfig {
+	/** Tools the agent is allowed to use. If set, only these tools are available. */
+	allow?: string[];
+
+	/** Tools the agent is explicitly denied. Applied after allow. */
+	deny?: string[];
+}
+
+export interface AgentContextConfig {
+	/** Files to always include in the agent's context. */
+	alwaysInclude?: string[];
+
+	/** Whether to inject project context (project files, structure). */
+	injectProjectContext?: boolean;
+
+	/** Whether to inject current git status. */
+	injectGitStatus?: boolean;
+}
+
+export interface AgentOutputSchema {
+	type: 'object' | 'string';
+	properties?: Record<string, { type: string; items?: { type: string }; description?: string }>;
+	required?: string[];
+}
+
+export interface AgentSpec {
+	/** Path to the system prompt file (relative to component dir). */
+	systemPrompt: string;
+
+	/** Model override (e.g., "claude-sonnet-4-6"). */
+	model?: string;
+
+	/** Fallback models to try if primary fails. */
+	modelFallbacks?: string[];
+
+	/** Tool access configuration. */
+	tools?: AgentToolConfig | string[];
+
+	/** Maximum number of turns before the agent is stopped. */
+	maxTurns?: number;
+
+	/** Maximum tokens budget per invocation. */
+	maxTokens?: number;
+
+	/** Hard timeout in minutes. */
+	timeoutMinutes?: number;
+
+	/** Temperature override. */
+	temperature?: number;
+
+	/** Thinking level override. */
+	thinking?: 'off' | 'minimal' | 'standard' | 'full';
+
+	/** Output format preference. */
+	outputFormat?: 'text' | 'structured' | 'markdown';
+
+	/** Context injection configuration. */
+	context?: AgentContextConfig;
+
+	/** Isolation mode for execution. */
+	isolation?: 'none' | 'worktree';
+
+	/** Merge strategy when isolation is used. */
+	mergeStrategy?: 'patch' | 'squash' | 'manual';
+
+	/** Whether the agent accepts {previous} input from chain mode. */
+	acceptsInput?: boolean;
+
+	/** Structured output contract. */
+	outputSchema?: AgentOutputSchema;
+
+	/** Name of another agent to inherit configuration from. */
+	extends?: string;
+}
+
+// ============================================================================
+// Dependency & Compatibility
+// ============================================================================
+
+export interface ComponentDependencies {
+	/** Required skills that must be installed. */
+	skills?: string[];
+
+	/** Required agents that must be installed. */
+	agents?: string[];
+
+	/** Required MCP servers. */
+	mcpServers?: string[];
+}
+
+export interface ComponentCompatibility {
+	/** Minimum GSD version (semver range). */
+	gsd?: string;
+
+	/** Minimum Node.js version (semver range). */
+	node?: string;
+}
+
+// ============================================================================
+// Agent Routing
+// ============================================================================
+
+export interface AgentRoutingRule {
+	/** Natural-language condition for when this agent should be used. */
+	when: string;
+
+	/** Confidence level for this rule. */
+	confidence?: 'low' | 'medium' | 'high';
+}
+
+export type ComponentSpec = SkillSpec | AgentSpec;
+
+// ============================================================================
+// Full Component Definition
+// ============================================================================
+
+/**
+ * Complete component.yaml definition.
+ * This is the parsed representation of a component.yaml file.
+ */
+export interface ComponentDefinition {
+	apiVersion: ComponentApiVersion;
+	kind: ComponentKind;
+	metadata: ComponentMetadata;
+	spec: ComponentSpec;
+
+	/** Dependencies on other components. */
+	requires?: ComponentDependencies;
+
+	/** Version compatibility constraints. */
+	compatibility?: ComponentCompatibility;
+
+	/** Agent routing rules (only for kind: agent). */
+	routing?: AgentRoutingRule[];
+}
+
+// ============================================================================
+// Resolved Component (Runtime)
+// ============================================================================
+
+/** Source of a loaded component */
+export type ComponentSource = 'user' | 'project' | 'builtin' | 'plugin' | 'path';
+
+/**
+ * A fully resolved component at runtime.
+ * Combines the definition with resolution metadata.
+ */
+export interface Component {
+	/** Unique identifier: `${namespace}:${name}` or bare `name`. */
+	id: string;
+
+	/** Component kind. */
+	kind: ComponentKind;
+
+	/** Component metadata. */
+	metadata: ComponentMetadata;
+
+	/** Kind-specific specification. */
+	spec: ComponentSpec;
+
+	/** Dependencies. */
+	requires?: ComponentDependencies;
+
+	/** Compatibility constraints. */
+	compatibility?: ComponentCompatibility;
+
+	/** Routing rules (agents only). */
+	routing?: AgentRoutingRule[];
+
+	/** Absolute path to the component directory. */
+	dirPath: string;
+
+	/** Absolute path to the definition file (component.yaml or SKILL.md or agent.md). */
+	filePath: string;
+
+	/** How this component was discovered. */
+	source: ComponentSource;
+
+	/** Format of the original definition. */
+	format: 'component-yaml' | 'skill-md' | 'agent-md';
+
+	/** Whether the component is currently enabled. */
+	enabled: boolean;
+}
+
+// ============================================================================
+// Registry Types
+// ============================================================================
+
+export interface ComponentFilter {
+	/** Filter by kind. */
+	kind?: ComponentKind | ComponentKind[];
+
+	/** Filter by source. */
+	source?: ComponentSource | ComponentSource[];
+
+	/** Filter by namespace. */
+	namespace?: string;
+
+	/** Filter by tags (any match). */
+	tags?: string[];
+
+	/** Text search across name and description. */
+	search?: string;
+
+	/** Only enabled components. Default: true. */
+	enabledOnly?: boolean;
+}
+
+export interface ComponentDiagnostic {
+	type: 'warning' | 'error' | 'collision';
+	message: string;
+	componentId?: string;
+	path?: string;
+	collision?: {
+		name: string;
+		winnerPath: string;
+		loserPath: string;
+		winnerSource?: string;
+		loserSource?: string;
+	};
+}
+
+// ============================================================================
+// 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: string): string[] {
+	const errors: string[] = [];
+
+	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: string | undefined): string[] {
+	const errors: string[] = [];
+
+	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: string, namespace?: string): string {
+	return namespace ? `${namespace}:${name}` : name;
+}

package/src/resources/extensions/gsd/context-store.ts

@@ -211,7 +211,13 @@ export function queryProject(): string | null {
 
 /**
  * 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)
  *
@@ -220,7 +226,7 @@ export function queryProject(): string | null {
  *
  * @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: string, keywords: string[]): Promise<string> {
   if (!content || keywords.length === 0) return '';
@@ -228,11 +234,23 @@ export async function queryKnowledge(content: string, keywords: string[]): Promi
   // 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 '';
+  const prefix = useH3 ? '###' : '##';
 
-  // Normalize keywords for case-insensitive matching
-  const normalizedKeywords = keywords.map(k => k.toLowerCase());
+  // 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: string[] = [];
 
@@ -240,16 +258,15 @@ export async function queryKnowledge(content: string, keywords: string[]): Promi
     // 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)
+      headerLower.includes(kw) || paragraphLower.includes(kw),
     );
 
     if (matches) {
-      matchingSections.push(`## ${header}\n\n${body}`);
+      matchingSections.push(`${prefix} ${header}\n\n${body}`);
     }
   }
 

package/src/resources/extensions/gsd/detection.ts

@@ -7,7 +7,7 @@
  */
 
 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";
 
@@ -1120,6 +1120,63 @@ function resolveVersionCatalogAccessors(
   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: string,
+  existsFn: (p: string) => boolean = existsSync,
+): boolean {
+  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: string,
+  existsFn: (p: string) => boolean = existsSync,
+): boolean {
+  return (
+    existsFn(gsdPath) &&
+    (existsFn(join(gsdPath, "PREFERENCES.md")) ||
+      existsFn(join(gsdPath, "preferences.md")) ||
+      existsFn(join(gsdPath, "milestones")))
+  );
+}
+
 export function scanProjectFiles(basePath: string): string[] {
   const files: string[] = [];
   const queue: Array<{ path: string; depth: number }> = [{ path: basePath, depth: 0 }];

package/src/resources/extensions/gsd/dispatch-guard.ts

@@ -3,9 +3,10 @@
 import { resolveMilestoneFile } from "./paths.js";
 import { findMilestoneIds } from "./guided-flow.js";
 import { parseUnitId } from "./unit-id.js";
-import { isDbAvailable, getMilestoneSlices } from "./gsd-db.js";
+import { isDbAvailable, getMilestoneSlices, getMilestone } from "./gsd-db.js";
 import { parseRoadmap } from "./parsers-legacy.js";
 import { isClosedStatus } from "./status-guards.js";
+import { classifyMilestoneSummaryContent } from "./milestone-summary-classifier.js";
 import { readFileSync } from "node:fs";
 
 const SLICE_DISPATCH_TYPES = new Set([
@@ -47,7 +48,30 @@ export function getPriorSliceCompletionBlocker(
 
   for (const mid of milestoneIds) {
     if (resolveMilestoneFile(base, mid, "PARKED")) continue;
-    if (resolveMilestoneFile(base, mid, "SUMMARY")) continue;
+
+    // DB/SUMMARY completion check (#4663 sibling to #4658).
+    // Prior behavior treated any SUMMARY file on disk as proof of milestone
+    // completion, which is wrong when the SUMMARY is a failure-path report
+    // (verification FAILED, blocker placeholder, etc.). Resolve as follows:
+    //   1. When DB is available and status is closed → skip (authoritative).
+    //   2. When SUMMARY exists but looks like a failure/blocker report →
+    //      do not short-circuit; fall through to the slice-level check so
+    //      the guard can still block dependents of an active milestone.
+    //   3. Otherwise (SUMMARY without failure markers) → skip. Preserves
+    //      the #1716 contract where a completed milestone with unchecked
+    //      remediation slices is still treated as done.
+    const summaryPath = resolveMilestoneFile(base, mid, "SUMMARY");
+    if (isDbAvailable()) {
+      const milestoneRow = getMilestone(mid);
+      if (milestoneRow && isClosedStatus(milestoneRow.status)) continue;
+    }
+    if (summaryPath) {
+      let summaryContent: string | null = null;
+      try { summaryContent = readFileSync(summaryPath, "utf-8"); } catch { /* ignore */ }
+      if (!summaryContent || classifyMilestoneSummaryContent(summaryContent) !== "failure") {
+        continue;
+      }
+    }
 
     // Normalised slice list from DB or file fallback
     type NormSlice = { id: string; done: boolean; depends: string[] };

package/src/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`.