gsd-pi 2.77.0-dev.58d3d4d6c → 2.77.0-dev.cfd69e714

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/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/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/src/resources/extensions/gsd/gate-registry.ts

@@ -60,9 +60,9 @@ export const GATE_REGISTRY = {
     id: "Q4",
     scope: "slice",
     ownerTurn: "gate-evaluate",
-    question: "What existing promises does this break?",
+    question: "Which existing requirements (R-IDs) does this slice touch, and which must be re-tested?",
     guidance: [
-      "List which existing requirements (R001, R003, etc.) are touched by this slice.",
+      "List the R-IDs (e.g. R001, R003) touched by this slice; see the milestone requirements artifact at .gsd/milestones/<id>/REQUIREMENTS.md.",
       "Identify what must be re-tested after shipping.",
       "Flag decisions that should be revisited given the new scope.",
       "If no existing requirements are affected, return verdict 'omitted'.",

package/src/resources/extensions/gsd/git-constants.ts

@@ -2,9 +2,38 @@
  * Shared git constants used across git-service and native-git-bridge.
  */
 
+/**
+ * Parent process env vars that, if leaked into a git child process, can
+ * silently redirect every operation to a different repo or index.
+ *
+ * Stripped from GIT_NO_PROMPT_ENV so a GSD invoked from inside a git hook,
+ * a different worktree's terminal, or any context that pre-set these vars
+ * cannot redirect GSD's git operations to the wrong target.
+ * (Issue #4980 NEW-1)
+ */
+const LEAKING_GIT_ENV_VARS = [
+  "GIT_DIR",
+  "GIT_WORK_TREE",
+  "GIT_INDEX_FILE",
+  "GIT_OBJECT_DIRECTORY",
+  "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+  "GIT_COMMON_DIR",
+  "GIT_NAMESPACE",
+] as const;
+
+function buildSafeParentEnv(): NodeJS.ProcessEnv {
+  const safe: NodeJS.ProcessEnv = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (!LEAKING_GIT_ENV_VARS.includes(k as (typeof LEAKING_GIT_ENV_VARS)[number])) {
+      safe[k] = v;
+    }
+  }
+  return safe;
+}
+
 /** Env overlay that suppresses interactive git credential prompts and git-svn noise. */
 export const GIT_NO_PROMPT_ENV = {
-  ...process.env,
+  ...buildSafeParentEnv(),
   GIT_TERMINAL_PROMPT: "0",
   GIT_ASKPASS: "",
   GIT_SVN_ID: "",

package/src/resources/extensions/gsd/git-self-heal.ts

@@ -10,6 +10,7 @@
  * user-friendly messages suggesting `/gsd doctor`.
  */
 
+import { execFileSync } from "node:child_process";
 import { existsSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { MergeConflictError } from "./git-service.js";
@@ -24,6 +25,18 @@ export interface AbortAndResetResult {
   cleaned: string[];
 }
 
+function hasWorkingTreeChanges(cwd: string): boolean {
+  try {
+    return execFileSync("git", ["status", "--porcelain"], {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    }).trim().length > 0;
+  } catch {
+    return true;
+  }
+}
+
 /**
  * Detect and clean up leftover merge/rebase state, then hard-reset.
  *
@@ -70,6 +83,24 @@ export function abortAndReset(cwd: string): AbortAndResetResult {
     }
   }
 
+  // Preserve any staged or untracked user work before the hard reset.
+  // Reset --hard discards staged changes (reflog only covers committed
+  // state), so a labeled stash gives the user a recovery handle if their
+  // in-flight inspection work would otherwise be silently lost.
+  // (Issue #4980 HIGH-5)
+  if (hasWorkingTreeChanges(cwd)) {
+    try {
+      execFileSync(
+        "git",
+        ["stash", "push", "--include-untracked", "-m", `gsd: pre-self-heal-reset ${new Date().toISOString()}`],
+        { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
+      );
+      cleaned.push("stashed working tree before reset");
+    } catch {
+      /* nothing to stash, or stash refused (e.g. unresolved conflicts) — proceed */
+    }
+  }
+
   // Always hard-reset to HEAD
   try {
     nativeResetHard(cwd);