gsd-pi 2.76.0 → 2.77.0-dev.1d17f366c

package/README.md

@@ -27,47 +27,49 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.75
+## What's New in v2.77
 
-### Knowledge Graph & Learning Extraction
+### Context Mode & Execution
 
-- **Knowledge graph system** — GSD now builds a structured knowledge graph from project artifacts. Learnings, decisions, and patterns are parsed into queryable graph nodes.
-- **`/gsd extract-learnings`** — new command extracts decisions, lessons, patterns, and surprises from completed phase artifacts into `LEARNINGS.md`, which feeds the knowledge graph automatically.
+- **Context Mode** — a dispatch behavior that builds task-ready context automatically: it pulls in the most relevant project artifacts, prior session state, milestone/slice signals, and execution metadata before the model runs. This reduces manual prompt assembly, improves continuity across turns, and helps tasks start with the right files and constraints from the first dispatch. Enabled by default for new projects (opt out with `enabled: false`).
+- **Sandboxed execution tools** — added `gsd_exec_search`, `gsd_resume`, and sandboxed tool-output execution paths for context-mode flows, so search/resume and follow-up execution can run with tighter boundaries and more predictable runtime behavior.
+- **Preflight hardening** — milestone completion now performs stricter clean-root preflight checks and can auto-stash when needed, reducing accidental dirty-tree transitions and helping completion flows fail fast with clearer remediation.
 
-### Unified Orchestration Kernel (UOK)
+### Memory Architecture (ADR-013)
 
-- **UOK is now the default** — the unified orchestration kernel replaces the legacy execution path. Plan-v2 compile gates, unified audit envelopes, turn-level git transaction modes, reactive/parallel scheduling via execution graph, and model policy filtering are all enforced by default. Legacy fallback remains as an emergency escape.
+- **Memories table is now authoritative** — all memory reads and writes now flow through the `memories` table as the single source of truth. By removing split legacy paths, memory state stays consistent across agents, tools, and UI surfaces, with fewer reconciliation edge cases and less sync drift.
+- **Structured memory fields** — `structured_fields` adds typed metadata (instead of only free-form text), so memories can carry machine-usable attributes for more accurate retrieval, stronger filtering, and more dependable downstream automation and tooling.
+- **Dual-write migration completed** — the staged migration that wrote to both old and new paths is now fully landed, including decisions backfill and parity wiring across agents, MCP tools, and extract-learnings flows. That gives a safer upgrade path while preserving historical data and reducing cutover risk.
 
-### Extension API
+### Skills, Tooling, and UX
 
-- **GSD Extension API** — third-party extensions can now be loaded from `.gsd/extensions/`, with a formal API surface for hooking into the GSD lifecycle (#3338).
+- **Skill coverage expanded** — 9 gap-closing skills landed and 6 planning/design skills were surfaced, improving end-to-end workflow coverage and making specialized guidance easier to discover at the point of use.
+- **Hook stack upgrades** — Layer 0 shell hooks and additional Layer 2 events were added to widen extension integration points: hooks can act earlier in command execution, and lifecycle consumers now receive richer event signals for orchestration, policy checks, and observability.
+- **TUI polish** — skill invocations now render in a dedicated chat-frame style for clearer scanability, and active-row overflow handling was fixed to prevent terminal layout breakage during long outputs.
 
-### v1 Command Parity
+### Reliability & Safety
 
-- **12 missing commands added** — GSD v2 now covers all v1 commands, closing the migration gap.
+- **Worktree and dispatch resilience** — crash-recovery dispatch is more robust, path derivation is safer, and worktree context fallback is improved, reducing stuck states and misrouted artifact operations after interruptions.
+- **DB/schema guardrails** — migration/index ordering and schema version stamping were tightened so upgrades apply deterministically and avoid index/version drift across mixed or legacy states.
+- **Security and validation fixes** — multiple hardening fixes landed across redaction paths, file/path checks, and pre-execution validation, closing false-positive/false-negative gaps while improving safety boundaries.
 
-### TUI Improvements
-
-- **Chat frame redesign** — compaction notices, tool execution cards, and the chat frame now share a unified styling with timestamps and model headers.
-- **Inline tool calls** — assistant tool calls render inline with text instead of grouped at the end.
-- **Compaction and success fixes** — tool cards no longer stick after compaction; success notifications are properly promoted.
-
-### Auto-Mode & Reliability
-
-- **Session timeout recovery** — auto-resume timer handles session creation timeouts; timeout counter resets on resume.
-- **Compaction checkpoint fix** — all session phases are checkpointed during compaction, not just the executing phase.
-- **MCP worktree routing** — tool writes are routed to the active worktree when a milestone has one; worktree paths are accepted in the project root guard.
-- **Single-writer DB invariant** — the engine database now enforces a single-writer invariant, preventing corruption from concurrent access.
-
-### Providers & CI
+See the full [Changelog](./CHANGELOG.md) for details on every release.
 
-- **Alibaba DashScope** — added as a standalone provider (#3891).
-- **Persistent language preference** — `/gsd language` sets a persistent language preference.
-- **Flat-rate provider detection** — extended to custom and externalCli providers.
-- **Thinking level as effort** — Claude Code now passes thinking level as an effort parameter.
-- **Hardened release pipeline** — workspace versions synced in release commits, package-lock.json regenerated during bumps, incremental build cache issues resolved.
+<details>
+<summary>v2.75 highlights</summary>
+
+- **Knowledge graph system** — structured knowledge graph built from project artifacts
+- **`/gsd extract-learnings`** — extracts decisions, lessons, patterns, and surprises into `LEARNINGS.md`
+- **Unified Orchestration Kernel (UOK)** — now the default execution path with plan-v2 compile gates and reactive/parallel scheduling
+- **GSD Extension API** — third-party extensions loadable from `.gsd/extensions/` (#3338)
+- **v1 command parity** — 12 missing commands added, closing the migration gap
+- **Chat frame redesign** — unified styling for compaction notices, tool cards, and chat frame with timestamps and model headers
+- **Single-writer DB invariant** — engine database enforces single-writer to prevent corruption
+- **MCP worktree routing** — tool writes routed to active worktree; worktree paths accepted in project root guard
+- **Alibaba DashScope** — added as a standalone provider (#3891)
+- **Persistent language preference** — `/gsd language`
 
-See the full [Changelog](./CHANGELOG.md) for details on every release.
+</details>
 
 <details>
 <summary>v2.74 highlights</summary>

package/dist/claude-cli-check.js

@@ -12,12 +12,41 @@ import { execFileSync } from 'node:child_process';
  * `src/resources/extensions/gsd/pre-execution-checks.ts`.
  */
 export const CLAUDE_COMMAND = process.platform === 'win32' ? 'claude.cmd' : 'claude';
+/**
+ * Ordered list of binary names to probe for the Claude Code CLI.
+ *
+ * Windows installs vary: npm-global installs produce a `claude.cmd` shim,
+ * direct binary installs produce `claude.exe`, and Git Bash wrappers may
+ * expose a bare `claude` shim. Try all three so no valid install is missed.
+ */
+const CLAUDE_COMMAND_CANDIDATES = process.platform === 'win32' ? [CLAUDE_COMMAND, 'claude.exe', 'claude'] : [CLAUDE_COMMAND];
+/**
+ * Try to run `args` against each candidate binary.
+ * Returns the output buffer on first success, throws the last error if all fail.
+ */
+function execClaudeCheck(args) {
+    let lastError;
+    for (const command of CLAUDE_COMMAND_CANDIDATES) {
+        try {
+            return execFileSync(command, args, { timeout: 5_000, stdio: 'pipe' });
+        }
+        catch (error) {
+            lastError = error;
+            const code = error?.code;
+            // EINVAL can surface on Windows Git Bash for .cmd spawn failures.
+            if (code === 'ENOENT' || code === 'EINVAL')
+                continue;
+            throw error;
+        }
+    }
+    throw lastError ?? new Error(`Claude CLI not found (tried: ${CLAUDE_COMMAND_CANDIDATES.join(', ')})`);
+}
 /**
  * Check if the `claude` binary is installed (regardless of auth state).
  */
 export function isClaudeBinaryInstalled() {
     try {
-        execFileSync(CLAUDE_COMMAND, ['--version'], { timeout: 5_000, stdio: 'pipe' });
+        execClaudeCheck(['--version']);
         return true;
     }
     catch {
@@ -29,13 +58,13 @@ export function isClaudeBinaryInstalled() {
  */
 export function isClaudeCliReady() {
     try {
-        execFileSync(CLAUDE_COMMAND, ['--version'], { timeout: 5_000, stdio: 'pipe' });
+        execClaudeCheck(['--version']);
     }
     catch {
         return false;
     }
     try {
-        const output = execFileSync(CLAUDE_COMMAND, ['auth', 'status'], { timeout: 5_000, stdio: 'pipe' })
+        const output = execClaudeCheck(['auth', 'status'])
             .toString()
             .toLowerCase();
         return !(/not logged in|no credentials|unauthenticated|not authenticated/i.test(output));

package/dist/cli-web-branch.d.ts

@@ -34,6 +34,7 @@ export interface RunWebCliBranchDeps {
     webPreferencesPath?: string;
 }
 export declare function parseCliArgs(argv: string[]): CliFlags;
+export declare function buildHeadlessAutoArgs(flags: Pick<CliFlags, 'messages' | 'model'>): string[];
 export { getProjectSessionsDir } from './project-sessions.js';
 export declare function migrateLegacyFlatSessions(baseSessionsDir: string, projectSessionsDir: string): void;
 /**

package/dist/cli-web-branch.js

@@ -73,6 +73,9 @@ export function parseCliArgs(argv) {
     }
     return flags;
 }
+export function buildHeadlessAutoArgs(flags) {
+    return flags.model ? ['--model', flags.model, ...flags.messages] : [...flags.messages];
+}
 export { getProjectSessionsDir } from './project-sessions.js';
 export function migrateLegacyFlatSessions(baseSessionsDir, projectSessionsDir) {
     if (!existsSync(baseSessionsDir))

package/dist/cli.js

@@ -12,7 +12,8 @@ import { checkForUpdates } from './update-check.js';
 import { printHelp, printSubcommandHelp } from './help-text.js';
 import { applySecurityOverrides } from './security-overrides.js';
 import { validateConfiguredModel } from './startup-model-validation.js';
-import { parseCliArgs, runWebCliBranch, migrateLegacyFlatSessions, } from './cli-web-branch.js';
+import { migrateAnthropicDefaultToClaudeCode } from './provider-migrations.js';
+import { buildHeadlessAutoArgs, parseCliArgs, runWebCliBranch, migrateLegacyFlatSessions, } from './cli-web-branch.js';
 import { stopWebMode } from './web-mode.js';
 import { getProjectSessionsDir } from './project-sessions.js';
 import { markStartup, printStartupTimings } from './startup-timings.js';
@@ -74,6 +75,18 @@ function printExtensionErrors(errors) {
         process.stderr.write(`[gsd] ${prefix}: ${err.error}\n`);
     }
 }
+/**
+ * Print extension load warnings (non-fatal, e.g. missing declared deps from
+ * the topological sort). Complements printExtensionErrors — fatal errors go
+ * there, advisory warnings go here.
+ */
+function printExtensionWarnings(warnings) {
+    if (!warnings)
+        return;
+    for (const w of warnings) {
+        process.stderr.write(`[gsd] Extension warning: ${w.message}\n`);
+    }
+}
 /**
  * Re-apply the validated model to the session when `createAgentSession()`
  * reports that it had to use a fallback. Prevents silently overriding the
@@ -354,11 +367,18 @@ async function runHeadlessFromAuto(headlessArgs) {
     await runHeadless(parseHeadlessArgs(argv));
     process.exit(0);
 }
+function flushPendingProviderRegistrations(resourceLoader, modelRegistry) {
+    const { runtime } = resourceLoader.getExtensions();
+    for (const { name, config } of runtime.pendingProviderRegistrations) {
+        modelRegistry.registerProvider(name, config);
+    }
+    runtime.pendingProviderRegistrations = [];
+}
 // `gsd auto [args...]` — shorthand for `gsd headless auto [args...]` (#2732)
 // Without this, `gsd auto` falls through to the interactive TUI which hangs
 // when stdin/stdout are piped (non-TTY environments).
 if (cliFlags.messages[0] === 'auto') {
-    await runHeadlessFromAuto(cliFlags.messages);
+    await runHeadlessFromAuto(buildHeadlessAutoArgs(cliFlags));
 }
 // Pi's tool bootstrap can mis-detect already-installed fd/rg on some systems
 // because spawnSync(..., ["--version"]) returns EPERM despite a zero exit code.
@@ -492,6 +512,13 @@ if (isPrintMode) {
     });
     await resourceLoader.reload();
     markStartup('resourceLoader.reload');
+    flushPendingProviderRegistrations(resourceLoader, modelRegistry);
+    migrateAnthropicDefaultToClaudeCode({
+        authStorage,
+        isClaudeCodeReady: modelRegistry.isProviderRequestReady('claude-code'),
+        settingsManager,
+        modelRegistry,
+    });
     const { session, extensionsResult, modelFallbackMessage } = await createAgentSession({
         authStorage,
         modelRegistry,
@@ -507,6 +534,7 @@ if (isPrintMode) {
     validateConfiguredModel(modelRegistry, settingsManager);
     await reapplyValidatedModelOnFallback(session, modelRegistry, settingsManager, modelFallbackMessage);
     printExtensionErrors(extensionsResult.errors);
+    printExtensionWarnings(extensionsResult.warnings);
     // Apply --model override if specified
     if (cliFlags.model) {
         const available = modelRegistry.getAvailable();
@@ -629,6 +657,13 @@ const resourceLoadPromise = resourceLoader.reload();
 // Then await the resource promise before creating the agent session.
 await resourceLoadPromise;
 markStartup('resourceLoader.reload');
+flushPendingProviderRegistrations(resourceLoader, modelRegistry);
+migrateAnthropicDefaultToClaudeCode({
+    authStorage,
+    isClaudeCodeReady: modelRegistry.isProviderRequestReady('claude-code'),
+    settingsManager,
+    modelRegistry,
+});
 const { session, extensionsResult, modelFallbackMessage: interactiveFallbackMsg } = await createAgentSession({
     authStorage,
     modelRegistry,
@@ -644,6 +679,7 @@ markStartup('createAgentSession');
 validateConfiguredModel(modelRegistry, settingsManager);
 await reapplyValidatedModelOnFallback(session, modelRegistry, settingsManager, interactiveFallbackMsg);
 printExtensionErrors(extensionsResult.errors);
+printExtensionWarnings(extensionsResult.warnings);
 // Restore scoped models from settings on startup.
 // The upstream InteractiveMode reads enabledModels from settings when /scoped-models is opened,
 // but doesn't apply them to the session at startup — so Ctrl+P cycles all models instead of

package/dist/extension-discovery.d.ts

@@ -16,3 +16,9 @@ export declare function resolveExtensionEntries(dir: string): string[];
  *   pi.extensions, then index.ts/index.js fallback).
  */
 export declare function discoverExtensionEntryPaths(extensionsDir: string): string[];
+/**
+ * Merge bundled and installed extension entry paths.
+ * Installed extensions with the same manifest ID as a bundled extension take precedence (D-14).
+ * Loader stays dumb — receives a pre-merged path list (D-15).
+ */
+export declare function mergeExtensionEntryPaths(bundledPaths: string[], installedExtDir: string): string[];

package/dist/extension-discovery.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { readManifest, readManifestFromEntryPath } from './extension-registry.js';
 function isExtensionFile(name) {
     return name.endsWith('.ts') || name.endsWith('.js');
 }
@@ -69,3 +70,39 @@ export function discoverExtensionEntryPaths(extensionsDir) {
     }
     return discovered;
 }
+/**
+ * Merge bundled and installed extension entry paths.
+ * Installed extensions with the same manifest ID as a bundled extension take precedence (D-14).
+ * Loader stays dumb — receives a pre-merged path list (D-15).
+ */
+export function mergeExtensionEntryPaths(bundledPaths, installedExtDir) {
+    if (!existsSync(installedExtDir))
+        return bundledPaths;
+    // Build map: manifest ID → entry paths for installed extensions
+    const installedById = new Map();
+    for (const entry of readdirSync(installedExtDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = join(installedExtDir, entry.name);
+        const manifest = readManifest(dir);
+        const entries = resolveExtensionEntries(dir);
+        if (manifest && entries.length > 0) {
+            installedById.set(manifest.id, entries);
+        }
+    }
+    if (installedById.size === 0)
+        return bundledPaths;
+    // Filter bundled paths: skip any whose manifest id is shadowed by installed
+    const merged = [];
+    for (const entryPath of bundledPaths) {
+        const manifest = readManifestFromEntryPath(entryPath);
+        if (manifest && installedById.has(manifest.id))
+            continue; // shadowed by installed
+        merged.push(entryPath);
+    }
+    // Append all installed entries
+    for (const entries of installedById.values()) {
+        merged.push(...entries);
+    }
+    return merged;
+}

package/dist/extension-registry.d.ts

@@ -31,6 +31,9 @@ export interface ExtensionRegistryEntry {
     source: "bundled" | "user" | "project";
     disabledAt?: string;
     disabledReason?: string;
+    version?: string;
+    installedFrom?: string;
+    installType?: "npm" | "git" | "local";
 }
 export interface ExtensionRegistry {
     version: 1;

package/dist/extension-sort.d.ts

@@ -0,0 +1,18 @@
+export interface SortWarning {
+    declaringId: string;
+    missingId: string;
+    message: string;
+}
+export interface SortResult {
+    sortedPaths: string[];
+    warnings: SortWarning[];
+}
+/**
+ * Sort extension entry paths in topological dependency-first order using Kahn's BFS algorithm.
+ *
+ * - Extensions without manifests are prepended in input order.
+ * - Missing dependencies produce a structured warning but do not block loading.
+ * - Cycles produce warnings; cycle participants are appended alphabetically.
+ * - Self-dependencies are silently ignored.
+ */
+export declare function sortExtensionPaths(paths: string[]): SortResult;

package/dist/extension-sort.js

@@ -0,0 +1,114 @@
+// GSD-2 — Extension Sort: Topological dependency ordering
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+import { readManifestFromEntryPath } from './extension-registry.js';
+/**
+ * Sort extension entry paths in topological dependency-first order using Kahn's BFS algorithm.
+ *
+ * - Extensions without manifests are prepended in input order.
+ * - Missing dependencies produce a structured warning but do not block loading.
+ * - Cycles produce warnings; cycle participants are appended alphabetically.
+ * - Self-dependencies are silently ignored.
+ */
+export function sortExtensionPaths(paths) {
+    const warnings = [];
+    const pathsWithoutId = [];
+    const idToPath = new Map();
+    // Step 1: Build ID map
+    for (const path of paths) {
+        const manifest = readManifestFromEntryPath(path);
+        if (!manifest) {
+            pathsWithoutId.push(path);
+        }
+        else {
+            idToPath.set(manifest.id, path);
+        }
+    }
+    // Step 2: Build graph — inDegree and dependents adjacency
+    const inDegree = new Map();
+    const dependents = new Map(); // dep → [ids that depend on dep]
+    for (const id of idToPath.keys()) {
+        if (!inDegree.has(id))
+            inDegree.set(id, 0);
+        if (!dependents.has(id))
+            dependents.set(id, []);
+    }
+    for (const [id, path] of idToPath) {
+        const manifest = readManifestFromEntryPath(path);
+        const rawDeps = manifest?.dependencies?.extensions ?? [];
+        const deps = Array.isArray(rawDeps) ? rawDeps : [];
+        for (const depId of deps) {
+            // Silently ignore self-deps
+            if (depId === id)
+                continue;
+            if (!idToPath.has(depId)) {
+                // Missing dependency — warn and skip edge
+                warnings.push({
+                    declaringId: id,
+                    missingId: depId,
+                    message: `Extension '${id}' declares dependency '${depId}' which is not installed — loading anyway`,
+                });
+                continue;
+            }
+            // Valid edge: id depends on depId → increment inDegree[id], add id to dependents[depId]
+            inDegree.set(id, (inDegree.get(id) ?? 0) + 1);
+            const depDependents = dependents.get(depId) ?? [];
+            depDependents.push(id);
+            dependents.set(depId, depDependents);
+        }
+    }
+    // Step 3: Kahn's algorithm — start with nodes that have inDegree 0
+    const sorted = [];
+    // Ready queue: IDs with inDegree 0, maintained in alphabetical order
+    const ready = [...idToPath.keys()]
+        .filter(id => inDegree.get(id) === 0)
+        .sort();
+    while (ready.length > 0) {
+        const id = ready.shift();
+        sorted.push(idToPath.get(id));
+        const deps = dependents.get(id) ?? [];
+        for (const depId of deps) {
+            const newDegree = (inDegree.get(depId) ?? 0) - 1;
+            inDegree.set(depId, newDegree);
+            if (newDegree === 0) {
+                // Insert into ready queue maintaining alphabetical order
+                const insertIdx = ready.findIndex(r => r > depId);
+                if (insertIdx === -1) {
+                    ready.push(depId);
+                }
+                else {
+                    ready.splice(insertIdx, 0, depId);
+                }
+            }
+        }
+    }
+    // Step 4: Cycle handling — any remaining IDs with inDegree > 0
+    const cycleIds = [...idToPath.keys()]
+        .filter(id => (inDegree.get(id) ?? 0) > 0)
+        .sort();
+    if (cycleIds.length > 0) {
+        const cycleSet = new Set(cycleIds);
+        for (const id of cycleIds) {
+            const path = idToPath.get(id);
+            const manifest = readManifestFromEntryPath(path);
+            const rawDeps = manifest?.dependencies?.extensions ?? [];
+            const deps = Array.isArray(rawDeps) ? rawDeps : [];
+            for (const depId of deps) {
+                if (depId === id)
+                    continue;
+                if (!cycleSet.has(depId))
+                    continue;
+                // Both id and depId are in cycle — emit warning
+                warnings.push({
+                    declaringId: id,
+                    missingId: depId,
+                    message: `Extension '${id}' and '${depId}' form a dependency cycle — loading both anyway (alphabetical order)`,
+                });
+            }
+            sorted.push(path);
+        }
+    }
+    return {
+        sortedPaths: [...pathsWithoutId, ...sorted],
+        warnings,
+    };
+}

package/dist/extension-validator.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Install-time validator for GSD extension packages. Called by the install command
+ * (Phase 8) before writing files. Not called on bundled extensions — they are
+ * discovered at load time, not installed.
+ */
+export interface ValidationError {
+    code: string;
+    message: string;
+    field?: string;
+}
+export interface ValidationWarning {
+    code: string;
+    message: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+}
+export interface ValidationOptions {
+    allowGsdNamespace?: boolean;
+    extensionId?: string;
+}
+/**
+ * Per D-03: Check that pkg.gsd.extension === true with STRICT equality (not truthiness).
+ * Packages without this marker are not recognized as GSD extensions.
+ */
+export declare function checkInstallDiscriminator(pkg: unknown): ValidationError | null;
+/**
+ * Per D-04/D-05: Check that the extension ID does not use the reserved gsd.* namespace,
+ * unless allowGsdNamespace is explicitly set to true.
+ * Per D-06: Only checks extension manifest ID — not pkg.name.
+ */
+export declare function checkNamespaceReservation(extensionId: string, opts: ValidationOptions): ValidationError | null;
+/**
+ * Per D-07/D-08/D-09/D-10: Scan both `dependencies` and `devDependencies` for @gsd/* packages.
+ * peerDependencies is the correct placement and is NOT flagged.
+ * Returns an error per violation naming the exact field and package.
+ */
+export declare function checkDependencyPlacement(pkg: unknown): ValidationError[];
+/**
+ * Run all validation checks for a GSD extension package.json.
+ * - If opts.extensionId is provided, runs namespace reservation check.
+ * - If opts.extensionId is not provided, skips namespace check and adds a warning.
+ * - valid is ALWAYS derived as errors.length === 0.
+ */
+export declare function validateExtensionPackage(pkg: unknown, opts?: ValidationOptions): ValidationResult;

package/dist/extension-validator.js

@@ -0,0 +1,127 @@
+// GSD-2 — Extension Package Format Validator
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+// ─── Individual Check Functions ───────────────────────────────────────────────
+/**
+ * Per D-03: Check that pkg.gsd.extension === true with STRICT equality (not truthiness).
+ * Packages without this marker are not recognized as GSD extensions.
+ */
+export function checkInstallDiscriminator(pkg) {
+    if (typeof pkg !== 'object' || pkg === null) {
+        return {
+            code: 'MISSING_GSD_MARKER',
+            message: 'package.json must declare "gsd": { "extension": true } to be recognized as a GSD extension.',
+            field: 'gsd.extension',
+        };
+    }
+    const obj = pkg;
+    const gsd = obj.gsd;
+    if (typeof gsd !== 'object' || gsd === null) {
+        return {
+            code: 'MISSING_GSD_MARKER',
+            message: 'package.json must declare "gsd": { "extension": true } to be recognized as a GSD extension.',
+            field: 'gsd.extension',
+        };
+    }
+    const gsdObj = gsd;
+    if (gsdObj.extension !== true) {
+        return {
+            code: 'MISSING_GSD_MARKER',
+            message: 'package.json must declare "gsd": { "extension": true } to be recognized as a GSD extension.',
+            field: 'gsd.extension',
+        };
+    }
+    return null;
+}
+/**
+ * Per D-04/D-05: Check that the extension ID does not use the reserved gsd.* namespace,
+ * unless allowGsdNamespace is explicitly set to true.
+ * Per D-06: Only checks extension manifest ID — not pkg.name.
+ */
+export function checkNamespaceReservation(extensionId, opts) {
+    if (opts.allowGsdNamespace === true) {
+        return null;
+    }
+    if (extensionId.startsWith('gsd.')) {
+        return {
+            code: 'RESERVED_NAMESPACE',
+            message: `Extension ID "${extensionId}" is reserved for GSD core extensions. Use a different namespace for community extensions (e.g., "my-tool" or "acme.my-tool"). To override: pass --allow-gsd-namespace (maintainers only).`,
+            field: 'extensionId',
+        };
+    }
+    return null;
+}
+/**
+ * Per D-07/D-08/D-09/D-10: Scan both `dependencies` and `devDependencies` for @gsd/* packages.
+ * peerDependencies is the correct placement and is NOT flagged.
+ * Returns an error per violation naming the exact field and package.
+ */
+export function checkDependencyPlacement(pkg) {
+    const errors = [];
+    if (typeof pkg !== 'object' || pkg === null) {
+        return errors;
+    }
+    const obj = pkg;
+    const fieldsToCheck = [
+        {
+            field: 'dependencies',
+            reason: 'Extensions must not bundle GSD host packages — the host provides them at runtime.',
+        },
+        {
+            field: 'devDependencies',
+            reason: 'GSD host packages are provided by the host at runtime; listing them in devDependencies misrepresents the runtime contract.',
+        },
+    ];
+    for (const { field, reason } of fieldsToCheck) {
+        const deps = obj[field];
+        if (typeof deps !== 'object' || deps === null)
+            continue;
+        const depsObj = deps;
+        for (const pkgName of Object.keys(depsObj)) {
+            if (pkgName.startsWith('@gsd/')) {
+                errors.push({
+                    code: 'WRONG_DEP_FIELD',
+                    message: `"${pkgName}" must not appear in "${field}". Move it to "peerDependencies". ${reason}`,
+                    field,
+                });
+            }
+        }
+    }
+    return errors;
+}
+// ─── Composite Validation ─────────────────────────────────────────────────────
+/**
+ * Run all validation checks for a GSD extension package.json.
+ * - If opts.extensionId is provided, runs namespace reservation check.
+ * - If opts.extensionId is not provided, skips namespace check and adds a warning.
+ * - valid is ALWAYS derived as errors.length === 0.
+ */
+export function validateExtensionPackage(pkg, opts = {}) {
+    const errors = [];
+    const warnings = [];
+    // Check 1: Install discriminator
+    const discriminatorError = checkInstallDiscriminator(pkg);
+    if (discriminatorError) {
+        errors.push(discriminatorError);
+    }
+    // Check 2: Namespace reservation (only if extensionId provided)
+    if (opts.extensionId !== undefined) {
+        const namespaceError = checkNamespaceReservation(opts.extensionId, opts);
+        if (namespaceError) {
+            errors.push(namespaceError);
+        }
+    }
+    else {
+        warnings.push({
+            code: 'NAMESPACE_CHECK_SKIPPED',
+            message: 'No extensionId provided — namespace reservation check was skipped.',
+        });
+    }
+    // Check 3: Dependency placement
+    const depErrors = checkDependencyPlacement(pkg);
+    errors.push(...depErrors);
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}