@gaia-ai/core 0.9.2 → 0.11.0

package/dist/src/cli/load-gaia-config.d.ts

@@ -1,6 +1,20 @@
 import type { DropSHPlugin } from 'dropsh/plugin';
 import type { GaiaCommandHost } from './commands.js';
 import { type GaiaConfigSource } from './gaia-dir.js';
+/**
+ * A connection config that was RESOLVED but is not usable — a missing
+ * `site.base_url`, a missing `workspace_id`.
+ *
+ * It exists so a caller can tell "there is no config" from "the config is right
+ * there and says something wrong". `gaia dropsh` otherwise reports every load
+ * failure as `no connection config could be loaded`, which sends the reader
+ * hunting for a file that was found and read. Matched by `name` rather than
+ * `instanceof`, so a duplicated `@gaia-ai/core` in a pnpm tree cannot break the
+ * check.
+ */
+export declare class GaiaConnectionConfigError extends Error {
+    readonly name = "GaiaConnectionConfigError";
+}
 /** The resolved control-plane connection: site + constructed auth plugins. */
 export interface GaiaConnectionConfig {
     site: {
@@ -8,6 +22,11 @@ export interface GaiaConnectionConfig {
         jsonapi_prefix: string;
     };
     plugins: DropSHPlugin[];
+    /**
+     * GAIA-351: the uuid of the `gaia_workspace` this connection creates into.
+     * REQUIRED at the config's top level — see `loadGaiaConfig`.
+     */
+    workspace_id: string;
     /** Absolute path of the loaded connection config. */
     config_path: string;
     /** true when this is the shipped machine-context fallback. */
@@ -16,6 +35,28 @@ export interface GaiaConnectionConfig {
     source: GaiaConfigSource;
     /** true when the loaded file is a legacy `conductor.config.js` connection. */
     legacy: boolean;
+    /**
+     * GAIA-373: UI extension entry modules discovered from `addons[]`, as
+     * RESOLVED `file://` URLs (see `resolveUiEntries` for why resolution happens
+     * here rather than at the import).
+     *
+     * Nothing is imported — `gaia dropsh` loads this same connection and never
+     * renders a TUI, so the cost of a UI contribution must not be paid until
+     * `gaia ui`'s kernel actually boots (spec F2/D3).
+     */
+    ui_entries: string[];
+}
+/**
+ * The connection config's top-level values, handed to every contribution as its
+ * base options (GAIA-351). An addon entry's own `with`/`options` is merged over
+ * them, so an explicit per-entry value always wins.
+ *
+ * This exists because the ambient workspace is NOT configured per addon: the
+ * filler is a child of `@gaia-ai/addon-essentials`, which no config passes
+ * options to, so the uuid has to travel as a global rather than as a `with`.
+ */
+export interface GaiaConnectionGlobals {
+    workspace_id: string;
 }
 /**
  * Load the connection config for `gaia ui` / `gaia dropsh` / conductor-auth.

package/dist/src/cli/load-gaia-config.js

@@ -4,19 +4,44 @@ import { discoverAddons } from '../plugins/discover-addons.js';
 import { resolveGaiaConfigPath } from './gaia-dir.js';
 import { resolveMachineContextPath } from './machine-context.js';
 import { resolveModuleEslintStyle } from './resolve-module.js';
+// GAIA-201: the CONNECTION loader. It reads ONLY `{ site, plugins }` from a
+// `gaia.config.js` (or a legacy `conductor.config.js` — back-compat), and never
+// constructs the engine slots (remote/executor/agent/workspace). This is the
+// deepest AC-2 fix: `gaia dropsh …` used to call `loadConductorConfig`, which
+// eagerly built the whole engine plugin farm just to read the auth `plugins`.
+// dropsh + ui now use this lenient loader instead, so a JSON:API read (or a
+// home-rooted connection with no engine wiring at all) loads cleanly.
+/**
+ * A connection config that was RESOLVED but is not usable — a missing
+ * `site.base_url`, a missing `workspace_id`.
+ *
+ * It exists so a caller can tell "there is no config" from "the config is right
+ * there and says something wrong". `gaia dropsh` otherwise reports every load
+ * failure as `no connection config could be loaded`, which sends the reader
+ * hunting for a file that was found and read. Matched by `name` rather than
+ * `instanceof`, so a duplicated `@gaia-ai/core` in a pnpm tree cannot break the
+ * check.
+ */
+export class GaiaConnectionConfigError extends Error {
+    name = 'GaiaConnectionConfigError';
+}
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 function isPluginDescriptor(entry) {
     return isRecord(entry) && typeof entry.plugin === 'string';
 }
+/** Merge the config globals under an entry's own options; the entry wins. */
+function withGlobals(globals, own) {
+    return isRecord(own) ? { ...globals, ...own } : { ...globals };
+}
 /**
  * Construct a `{ plugin, export?, with?/options? }` descriptor. Resolution base
  * order: the config's own dir first (so a project config can name a locally
  * installed plugin), then the host's `resolveBases` (host install → cwd) for
  * pnpm-safe resolution of the shipped fallback's `@dropsh/plugin-*`.
  */
-async function loadDescriptor(entry, bases) {
+async function loadDescriptor(entry, bases, globals) {
     const resolved = resolveModuleEslintStyle(entry.plugin, bases);
     if (resolved === undefined) {
         throw new Error(`gaia.config.js cannot resolve plugin '${entry.plugin}'`);
@@ -41,15 +66,15 @@ async function loadDescriptor(entry, bases) {
             throw new Error(`plugin '${entry.plugin}' has no default export and ${fns.length} function exports (${fns.join(', ')}); specify "export"`);
         }
     }
-    return factory(entry.with ?? entry.options);
+    return factory(withGlobals(globals, entry.with ?? entry.options));
 }
 /** Resolve the `plugins[]` array: descriptors constructed, constructed entries
  *  passed through; a factory returning an array is flattened one level (dropsh
  *  `composePlugins` semantics), mirroring the engine loader. */
-async function resolvePlugins(raw, bases) {
+async function resolvePlugins(raw, bases, globals) {
     if (!Array.isArray(raw))
         return [];
-    const resolved = await Promise.all(raw.map((entry) => isPluginDescriptor(entry) ? loadDescriptor(entry, bases) : entry));
+    const resolved = await Promise.all(raw.map((entry) => isPluginDescriptor(entry) ? loadDescriptor(entry, bases, globals) : entry));
     return resolved.flat();
 }
 /**
@@ -87,11 +112,27 @@ export async function loadGaiaConfig(host, opts = {}) {
         const expected = resolution.fallback
             ? 'the shipped machine-context fallback resolved no base_url — run `gaia conductor init` or create ~/.gaia/gaia.config.js'
             : 'expected a gaia.config.js (project ./.gaia/gaia.config.js or home ~/.gaia/gaia.config.js) declaring site.base_url';
-        throw new Error(`gaia connection config requires site.base_url — resolved ${configPath}; ${expected}`);
+        throw new GaiaConnectionConfigError(`gaia connection config requires site.base_url — resolved ${configPath}; ${expected}`);
     }
     const jsonapiPrefix = typeof site.jsonapi_prefix === 'string' && site.jsonapi_prefix.trim() !== ''
         ? site.jsonapi_prefix
         : '/jsonapi';
+    // GAIA-351: `workspace_id` is REQUIRED, at the config's TOP LEVEL — a sibling
+    // of `site`, not a member of it and not an addon's `with`. The ambient-
+    // workspace filler ships inside `@gaia-ai/addon-essentials`, which every
+    // connection loads and which no config passes options to, so the uuid has
+    // nowhere else to come from. Required rather than optional because there is no
+    // longer a "leave the addon out" form: the filler is always present, and a
+    // connection that cannot say which workspace it creates into would fail later,
+    // on the wire, as an opaque 422 from the server's `GaiaWorkspaceScope`.
+    const workspaceId = typeof raw.workspace_id === 'string' ? raw.workspace_id.trim() : '';
+    if (workspaceId === '') {
+        throw new GaiaConnectionConfigError(`gaia connection config requires a top-level workspace_id — resolved ${configPath}; ` +
+            "add `workspace_id: '<gaia_workspace uuid>'` beside `site` (it is the workspace every create is bound to). " +
+            'Find the uuid on the control plane at /admin/gaia/workspace — not with `gaia dropsh`, ' +
+            'which reads this same config and would fail the same way.');
+    }
+    const globals = { workspace_id: workspaceId };
     // Config dir first, then the host bases (pnpm-safe for the shipped fallback).
     const bases = [
         pathToFileURL(`${dirname(configPath)}/`).href,
@@ -101,9 +142,11 @@ export async function loadGaiaConfig(host, opts = {}) {
     // the legacy `plugins:[]` descriptor array AND the Storybook-style `addons:[]`
     // discovered via the shared engine (connection surface = the auth/renderer
     // plugins). Concatenate legacy first, then discovered.
-    const legacy = await resolvePlugins(raw.plugins, bases);
+    const legacy = await resolvePlugins(raw.plugins, bases, globals);
     const discovered = Array.isArray(raw.addons)
-        ? await discoverAddons(raw.addons, 'connection', bases)
+        ? await discoverAddons(raw.addons, 'connection', bases, {
+            globals,
+        })
         : undefined;
     const plugins = discovered
         ? [...legacy, ...discovered.connectionPlugins]
@@ -111,9 +154,40 @@ export async function loadGaiaConfig(host, opts = {}) {
     return {
         site: { base_url: baseUrl, jsonapi_prefix: jsonapiPrefix },
         plugins,
+        workspace_id: workspaceId,
         config_path: configPath,
         fallback: resolution.fallback,
         source: resolution.source,
         legacy: resolution.legacy,
+        ui_entries: discovered ? resolveUiEntries(discovered.uiEntries, bases) : [],
     };
 }
+/**
+ * Resolve each UI entry specifier to an importable file URL — GAIA-373.
+ *
+ * Resolution belongs HERE, against the very bases that found the addon's
+ * `./preset`, and not in the renderer that eventually imports them. A preset
+ * names a package specifier (`@gaia-ai/addon-x/ui`) because that is what its
+ * author can honestly write; but the module that imports it is the TUI kernel,
+ * inside `@gaia-ai/addon-gaia-ui`, and a bare specifier there resolves against
+ * THAT package's dependencies. A contribution addon is its SIBLING, never its
+ * dependency — the layered DAG forbids the backwards edge — so the bare import
+ * fails, and it fails at cockpit boot rather than at config load.
+ *
+ * Measured, not reasoned: `gaia ui GAIA-373` with the addon listed reported
+ * `Cannot find module '@gaia-ai/addon-gaia-ui-artifacts/ui' from
+ * .../addons/gaia-ui/dist/src/Extension/load.js`.
+ *
+ * Still NOTHING IS IMPORTED here (F2): a resolve is a path lookup, and the
+ * megabytes behind the specifier stay unloaded until a TUI actually boots.
+ */
+function resolveUiEntries(entries, bases) {
+    return entries.map((entry) => {
+        const resolved = resolveModuleEslintStyle(entry, bases);
+        if (resolved === undefined) {
+            throw new Error(`gaia.config.js cannot resolve UI entry '${entry}' — the addon that ` +
+                'contributes it must be installed where the config can see it');
+        }
+        return pathToFileURL(resolved).href;
+    });
+}

package/dist/src/cli/machine-context.d.ts

@@ -9,6 +9,11 @@ export interface MachineContext {
     base_url: string;
     client_id: string;
     client_secret: string;
+    /**
+     * Host concurrent-run budget (GAIA-353). Optional; consumers default to 1.
+     * Source of truth for capacity — not the engine conductor.config.js.
+     */
+    max_parallel?: number;
 }
 /** Canonical machine-context path: `~/.gaia/machine.config.js` (GAIA-201). */
 export declare function machineContextPath(): string;

package/dist/src/index.d.ts

@@ -2,7 +2,7 @@ export type { GaiaCommandHost, GaiaCommandPlugin } from './cli/commands.js';
 export { declaresTopLevelKey, findDefaultExportObject, matchDelimiter, type PropEntry, readKey, scanTopLevelProperties, scanToTopLevelComma, skipBlockComment, skipLineComment, skipString, skipTrivia, } from './cli/config-source.js';
 export type { GaiaConfigResolution, GaiaConfigSource, } from './cli/gaia-dir.js';
 export { findGaiaConfig, findGaiaDir, findProjectGaiaDir, homeGaiaDir, resolveConfigPath, resolveGaiaConfigPath, stemForConfigFile, } from './cli/gaia-dir.js';
-export { type GaiaConnectionConfig, loadGaiaConfig, } from './cli/load-gaia-config.js';
+export { type GaiaConnectionConfig, GaiaConnectionConfigError, type GaiaConnectionGlobals, loadGaiaConfig, } from './cli/load-gaia-config.js';
 export { legacyMachineContextPath, type MachineContext, machineContextPath, readMachineContext, resolveMachineContextPath, } from './cli/machine-context.js';
 export { corePackageRoot, homeFallbackGaiaConfigPath, } from './cli/paths.js';
 export { resolveModuleEslintStyle } from './cli/resolve-module.js';
@@ -16,4 +16,4 @@ export { shellQuote } from './core/shell.js';
 export { DEFAULT_SLUG_MAX_LENGTH, slugify } from './core/slug.js';
 export { discoverAddons, type ResolvedConductorSlots, resolveConductorSlots, } from './plugins/discover-addons.js';
 export { type AddonEntry, type CommandDescriptor, type DiscoveredContributions, emptyContributions, type GaiaPreset, type GaiaSurface, type OpaqueAccumulator, PRESET_FUNCTION_KEYS, SURFACE_KEYS, } from './plugins/preset.js';
-export { type ExpandedLoad, expandLoad, type InputDecl, parseStepValues, readSkillWhen, type SkillContract, type SkillWhen, StepContractError, type StepValues, type Triple, validateLoad, type WhenValue, WORKFLOW_STEPS, type WorkflowStep, } from './workflow/step-contract.js';
+export { deriveProjectTriples, type EmptyLoaderShape, type ExpandedLoad, expandLoad, type IndentedLoadSite, type InputDecl, measureEmptyLoader, parseStepValues, readSkillWhen, type SkillContract, type SkillWhen, StepContractError, type StepContractErrorCode, type StepValues, type Triple, validateLoad, type WhenValue, WORKFLOW_CLAIMABLE_STATES, WORKFLOW_STEPS, type WorkflowStep, } from './workflow/step-contract.js';

package/dist/src/index.js

@@ -4,7 +4,7 @@
 // config source declare?" — core is layer 0 and cannot import the conductor's copy.
 export { declaresTopLevelKey, findDefaultExportObject, matchDelimiter, readKey, scanTopLevelProperties, scanToTopLevelComma, skipBlockComment, skipLineComment, skipString, skipTrivia, } from './cli/config-source.js';
 export { findGaiaConfig, findGaiaDir, findProjectGaiaDir, homeGaiaDir, resolveConfigPath, resolveGaiaConfigPath, stemForConfigFile, } from './cli/gaia-dir.js';
-export { loadGaiaConfig, } from './cli/load-gaia-config.js';
+export { GaiaConnectionConfigError, loadGaiaConfig, } from './cli/load-gaia-config.js';
 export { legacyMachineContextPath, machineContextPath, readMachineContext, resolveMachineContextPath, } from './cli/machine-context.js';
 export { corePackageRoot, homeFallbackGaiaConfigPath, } from './cli/paths.js';
 export { resolveModuleEslintStyle } from './cli/resolve-module.js';
@@ -32,4 +32,4 @@ export { emptyContributions, PRESET_FUNCTION_KEYS, SURFACE_KEYS, } from './plugi
 // GAIA-194 AC-2: the agent-host contract (`AgentLaunchHost` / `HostedAgent` /
 // `supportsAgentHost`) is likewise NOT here — it is the TUI renderer's own plugin
 // seam (`@gaia-ai/addon-gaia-ui`), and herdr types its impl locally.
-export { expandLoad, parseStepValues, readSkillWhen, StepContractError, validateLoad, WORKFLOW_STEPS, } from './workflow/step-contract.js';
+export { deriveProjectTriples, expandLoad, measureEmptyLoader, parseStepValues, readSkillWhen, StepContractError, validateLoad, WORKFLOW_CLAIMABLE_STATES, WORKFLOW_STEPS, } from './workflow/step-contract.js';

package/dist/src/plugins/discover-addons.d.ts

@@ -9,6 +9,7 @@ import { type AddonEntry, type DiscoveredContributions, type GaiaSurface } from
  */
 export declare function discoverAddons(entries: AddonEntry[] | undefined, surface: GaiaSurface, bases: string[], opts?: {
     logger?: ConductorLogger;
+    globals?: unknown;
 }): Promise<DiscoveredContributions>;
 /**
  * The resolved conductor slots (last-wins singletons + agent candidate list).

package/dist/src/plugins/discover-addons.js

@@ -135,6 +135,26 @@ async function loadPreset(spec, bases, warn) {
         return { preset: mod, key: mainPath };
     return { preset: adaptDefaultExport(mod, spec, warn), key: mainPath };
 }
+/**
+ * Merge the caller's global options under an entry's own `with` (GAIA-351).
+ *
+ * A preset normally reads only what its own config entry passed it. That breaks
+ * down for a value carried by a meta-addon's CHILD: a child is listed as a bare
+ * package name, so it has no `with` at all, and the config has no place to write
+ * one. `globals` is the config-level fallback — every preset sees it, an entry's
+ * own `with` overrides it key by key, and an entry that ignores the extra keys
+ * (all of them but one, today) is unaffected.
+ */
+function mergeGlobals(globals, own) {
+    if (globals === undefined)
+        return own;
+    const g = globals;
+    if (own === undefined)
+        return { ...g };
+    if (typeof own !== 'object' || own === null || Array.isArray(own))
+        return own;
+    return { ...g, ...own };
+}
 /** Run one preset's surface accumulators into `acc`, attaching `priority` to any
  *  newly appended agent candidates. */
 async function applyPreset(preset, opts, priority, surface, acc) {
@@ -186,7 +206,7 @@ export async function discoverAddons(entries, surface, bases, opts = {}) {
             if (Array.isArray(preset.addons) && preset.addons.length > 0) {
                 await walk(preset.addons);
             }
-            await applyPreset(preset, withOpts, priority, surface, acc);
+            await applyPreset(preset, mergeGlobals(opts.globals, withOpts), priority, surface, acc);
         }
     };
     await walk(entries);

package/dist/src/plugins/preset.d.ts

@@ -60,6 +60,18 @@ export interface DiscoveredContributions {
     /** Opaque: `AgentCandidate[]` on the conductor surface. */
     agents: unknown[];
     connectionPlugins: DropSHPlugin[];
+    /**
+     * GAIA-373: UI extension entry MODULES — specifiers, never constructed
+     * contributions.
+     *
+     * Storybook's `managerEntries` model, and load-bearing for a measured reason:
+     * `discoverAddons` runs on every connection load (`gaia dropsh` included), and
+     * `@opentui/core` is megabytes of native code that a preset returning objects
+     * would pull onto that path — the very import GAIA-326 had to make dynamic.
+     * Concretely typed rather than opaque: a specifier is a string, so the kernel
+     * needs no foreign type for it and stays surface-agnostic all the same.
+     */
+    uiEntries: string[];
 }
 /**
  * An OPAQUE per-surface accumulator. The kernel threads it without knowing its
@@ -87,6 +99,7 @@ export interface GaiaPreset<O = unknown> {
     workspaces?: OpaqueAccumulator<O>;
     agents?: OpaqueAccumulator<O>;
     connectionPlugins?: (acc: DropSHPlugin[], opts: O) => DropSHPlugin[] | Promise<DropSHPlugin[]>;
+    uiEntries?: (acc: string[], opts: O) => string[] | Promise<string[]>;
 }
 /** The preset function keys, for shape-detection during discovery. */
 export declare const PRESET_FUNCTION_KEYS: Array<keyof DiscoveredContributions>;

package/dist/src/plugins/preset.js

@@ -28,7 +28,7 @@
 export const SURFACE_KEYS = {
     command: ['commands'],
     conductor: ['remotes', 'executors', 'workspaces', 'agents'],
-    connection: ['connectionPlugins'],
+    connection: ['connectionPlugins', 'uiEntries'],
 };
 /** The preset function keys, for shape-detection during discovery. */
 export const PRESET_FUNCTION_KEYS = [
@@ -38,6 +38,7 @@ export const PRESET_FUNCTION_KEYS = [
     'workspaces',
     'agents',
     'connectionPlugins',
+    'uiEntries',
 ];
 /** An empty contributions accumulator. */
 export function emptyContributions() {
@@ -48,5 +49,6 @@ export function emptyContributions() {
         workspaces: [],
         agents: [],
         connectionPlugins: [],
+        uiEntries: [],
     };
 }

package/dist/src/workflow/step-contract.d.ts

@@ -1,9 +1,42 @@
 /** The workflow states an agent works — the legal `step` values. */
 export declare const WORKFLOW_STEPS: readonly ["qualification", "spec", "diagnose", "coding", "review", "pre_deployment", "post_deployment", "verifying", "summary"];
 export type WorkflowStep = (typeof WORKFLOW_STEPS)[number];
-/** Typed defect raised on the first contract violation. */
+/**
+ * The machine-readable classification of a contract defect, for consumers that
+ * must branch on *which* defect it is rather than on what it says.
+ *
+ * GAIA-436: `gaia validate` used to recover this from a regex over the message
+ * text (`/^loaded skill \`([^\`]+)\` not found\.$/`). That leaked twice — the
+ * sibling defect raised by the same `walk()` (`bundle \`x\` loads unknown skill
+ * \`y\`.`) is the same class of problem and matched nothing, so it got no remedy
+ * printed; and rewording any message would have broken the consumer across the
+ * package boundary without a single failing test to say so.
+ *
+ * Deliberately narrow: exactly the two codes a caller branches on **today**. Most
+ * throw sites in this module carry no code, and that is correct — a code is added
+ * when a consumer needs to distinguish that defect, never speculatively, because
+ * an unused code is a contract nobody validates.
+ */
+export type StepContractErrorCode = 'unresolved_skill' | 'empty_loader';
+/**
+ * Typed defect raised on the first contract violation.
+ *
+ * The single-argument form `new StepContractError(message)` is the norm and stays
+ * the norm; `details` is opt-in for the few defects a consumer classifies.
+ */
 export declare class StepContractError extends Error {
-    constructor(message: string);
+    /** The defect's classification, when it is one a consumer branches on. */
+    readonly code?: StepContractErrorCode;
+    /**
+     * For `unresolved_skill`: the skill name that could not be resolved — the root
+     * bullet's, or the bundle member's. Named `skill` rather than `name` because
+     * `Error.name` is already taken (and set to `StepContractError` below).
+     */
+    readonly skill?: string;
+    constructor(message: string, details?: {
+        code: StepContractErrorCode;
+        skill?: string;
+    });
 }
 /**
  * A normalized `when` clause value: a concrete list of allowed values, the
@@ -60,14 +93,50 @@ export interface Triple {
     workflow: string;
     step: WorkflowStep;
 }
-/** Per-skill values, keyed by skill `name` (the `@gaia/` prefix stripped). */
+/** Per-skill values, keyed by skill `name` (the namespace prefix stripped). */
 export type StepValues = Record<string, Record<string, string>>;
+/** One `- @…` line the indent-0 anchor read as value rather than as an address. */
+export interface IndentedLoadSite {
+    /** 1-based line number, so a report can point the author straight at it. */
+    line: number;
+    /** Width of the whitespace before the marker — a TAB counts as one. */
+    indent: number;
+    /** The line without its indent: the address the author meant to write. */
+    text: string;
+}
+/** What a `## Loaded skills` section that produced no load site actually holds. */
+export interface EmptyLoaderShape {
+    /** The indented address-shaped lines, in document order. */
+    indented: IndentedLoadSite[];
+    /** Non-blank lines in the section body; `0` means the section is empty. */
+    bodyLines: number;
+}
+/**
+ * Measure a `## Loaded skills` section that yielded no load site, so a consumer
+ * can say WHICH of the shapes behind `empty_loader` it is looking at.
+ *
+ * GAIA-436: that code covers three documents — a list that is wholly indented, a
+ * section whose lines are not address-shaped at all (a `*` marker, a `-@` with no
+ * space), and an empty section. Only the first is the "your list is indented" the
+ * single message can describe; the other two get a remedy pointing at whitespace
+ * that is already fine, which is the same misdirection the anchoring fixed.
+ *
+ * It lives HERE, not in the CLI that renders it: where the section starts and ends
+ * and what counts as an address are rules of this module, and a second copy of
+ * them in the host is exactly the drift this ticket is about. The host measures
+ * (in `runValidate`) and renders (in `formatReport`); the rule stays in core.
+ *
+ * Answers for any document — a section it cannot find simply holds nothing — so a
+ * caller need not pre-check. It classifies, never throws: the defect is already
+ * raised by `expandLoad` before this is reached.
+ */
+export declare function measureEmptyLoader(workflowMd: string): EmptyLoaderShape;
 /**
  * Read the per-skill value **overrides** from a `WORKFLOW.md`'s `## Loaded skills`
  * section. A project overrides a skill default **inline under that skill's bullet**
  * (indented `key: value` YAML, block scalars allowed), not in one global block.
- * Returns a map keyed by skill `name` (the `@gaia/` prefix stripped); a skill with no
- * overrides maps to `{}` (it runs on its declared defaults).
+ * Returns a map keyed by skill `name` (any `@<namespace>/` prefix stripped); a skill
+ * with no overrides maps to `{}` (it runs on its declared defaults).
  */
 export declare function parseStepValues(workflowMd: string): StepValues;
 /**
@@ -75,6 +144,47 @@ export declare function parseStepValues(workflowMd: string): StepValues;
  * present) and the declared `inputs`. Malformed frontmatter raises `StepContractError`.
  */
 export declare function readSkillWhen(skillMd: string): SkillContract;
+/**
+ * The **claimable states** of each GAIA workflow — the only `step` values a ticket
+ * in that workflow can ever present to a step owner.
+ *
+ * Source of truth: `web/modules/custom/gaia_core/gaia_core.workflows.yml`. It is
+ * transcribed here rather than read, because this module is a pure library with no
+ * filesystem and no Drupal access. A workflow added there must be added here too.
+ */
+export declare const WORKFLOW_CLAIMABLE_STATES: Record<string, readonly WorkflowStep[]>;
+/**
+ * Derive the `(work_type, workflow, step)` set a project can produce, from the
+ * skills it loads plus the fixed workflow/claimable-state table above — the input
+ * `validateLoad` needs, which until GAIA-436 only the contract test could build
+ * (from a hardcoded list) and therefore no shipped command could.
+ *
+ * A **work type** exists for the project because some loaded **owner** declares it;
+ * its participating steps are the union of `when.step` across every owner declaring
+ * it. Those steps are then crossed against **all five** workflows — not merely the
+ * ones the declaring skill happens to list — because that is what makes a coverage
+ * gap real rather than tautological: a project that can route `work:code` at
+ * `coding` must be able to route it at `coding` in every workflow that claims there.
+ *
+ * A step no work type participates in carries a `null` work type (qualification,
+ * the deployment and verification steps). An owner whose `when.work_type` is `*` or
+ * omitted is a non-work-typed owner: it contributes to the `null` side, never to a
+ * named work type. Helpers (no `when`) contribute nothing — they own no step.
+ *
+ * **Known blind spot: the work-type universe is derived from the load, not from the
+ * project.** Because a work type exists here only if some loaded owner declares it,
+ * deleting the last owner of a work type does not open a coverage gap — it shrinks
+ * the triple set, and the validation stays green. Removing `- @gaia/docs-authoring`
+ * from this repository's own `WORKFLOW.md` yields `9 → 8` owners and `24 → 16`
+ * triples, all covered, although every `work:docs` ticket would then reach `coding`
+ * with no owner at all. The set of work types a project's tickets can actually
+ * carry lives in the ticket store's `work:*` vocabulary, which this function cannot
+ * see; closing the gap means feeding that vocabulary in, which is its own change.
+ * What is validated here is therefore: *given what the project loads, is the load
+ * internally complete and unambiguous* — not *does the project load everything its
+ * tickets need*.
+ */
+export declare function deriveProjectTriples(skills: SkillContract[]): Triple[];
 /** What a load expands to: the flat leaf skills plus the values that reached them. */
 export interface ExpandedLoad {
     /** The leaf skills (step-owners + helpers), deduplicated, in first-seen order. */
@@ -114,6 +224,10 @@ export declare function expandLoad(workflowMd: string, byName: Map<string, Skill
  * resolve to a value: the `values` map (as resolved by `expandLoad`) or the input's
  * own declared `default`.
  *
+ * Finally (GAIA-436) every override the load resolved must reach a declared input:
+ * an override key no loaded skill declares is a defect, because it resolves to
+ * nothing at all and the skill silently runs on its default instead.
+ *
  * Reports the first defect as a typed `StepContractError`. Never dispatches or routes.
  */
 export declare function validateLoad(skills: SkillContract[], values: StepValues, projectTriples: Triple[]): void;

package/dist/src/workflow/step-contract.js

@@ -30,15 +30,62 @@ export const WORKFLOW_STEPS = [
     'verifying',
     'summary',
 ];
-/** Typed defect raised on the first contract violation. */
+/**
+ * Typed defect raised on the first contract violation.
+ *
+ * The single-argument form `new StepContractError(message)` is the norm and stays
+ * the norm; `details` is opt-in for the few defects a consumer classifies.
+ */
 export class StepContractError extends Error {
-    constructor(message) {
+    /** The defect's classification, when it is one a consumer branches on. */
+    code;
+    /**
+     * For `unresolved_skill`: the skill name that could not be resolved — the root
+     * bullet's, or the bundle member's. Named `skill` rather than `name` because
+     * `Error.name` is already taken (and set to `StepContractError` below).
+     */
+    skill;
+    constructor(message, details) {
         super(message);
         this.name = 'StepContractError';
+        // `exactOptionalPropertyTypes` is on: assign an optional property only when
+        // the value is actually defined, never `undefined`.
+        if (details !== undefined)
+            this.code = details.code;
+        if (details?.skill !== undefined)
+            this.skill = details.skill;
     }
 }
 const LOADED_SKILLS_HEADING = /^##\s+Loaded skills\s*$/;
-const BULLET = /^\s*-\s+@gaia\/([a-z0-9-]+)\s*$/;
+/**
+ * One loaded-skill bullet: `- @<namespace>/<skill-name>`, **at indent 0**.
+ *
+ * GAIA-436: the namespace is captured only to be discarded. A skill is addressed
+ * by NAME — the prefix says which plugin ships it, and a project may load a step
+ * owner from any plugin (`@designbook-gaia/debo-config-sync`), not just `@gaia/`.
+ * Hardcoding `@gaia/` here made every foreign bullet unmatched, and an unmatched
+ * bullet at indent 0 fell through to the "dedented prose" branch below — dropping
+ * its own overrides *and* flushing away the preceding bullet's, in silence.
+ *
+ * The indent-0 anchor is the second half of the same defect. A load site is a
+ * top-level list item — in `WORKFLOW.md` and in a bundle body alike — while an
+ * indented `- @…` line is *value*: `.prompt` block scalars are written as lists
+ * of required skills. Matching at any indent read such a line as an address,
+ * which truncated the block scalar mid-value and invented a phantom skill from
+ * the line, and `validateLoad` then reported that corrupted load as clean.
+ */
+const BULLET = /^-\s+@([a-z0-9-]+)\/([a-z0-9-]+)\s*$/;
+/**
+ * A line merely *shaped* like a bullet — a top-level list item whose content
+ * starts `@`. Inside `## Loaded skills` such a line is an address, never prose,
+ * so one that `BULLET` cannot parse is REPORTED (GAIA-436) instead of taking the
+ * prose branch. That report is what stops a malformed address from damaging its
+ * neighbour. It carries `BULLET`'s indent-0 anchor for the same reason: without
+ * it, a near-miss inside a block scalar — `- @gaia/read-ticket before anything
+ * else.` — failed a document that was correct, and the remedy the message
+ * prescribes steered the author onto the exact form, which is the silent case.
+ */
+const BULLET_SHAPED = /^-\s+@/;
 /**
  * Locate the `## Loaded skills` section in a markdown document: the `[start, end)`
  * line range of its body, or `null` when the document carries no such section.
@@ -60,12 +107,54 @@ function loadedSkillsRange(lines) {
     }
     return [start, end];
 }
+/**
+ * Measure a `## Loaded skills` section that yielded no load site, so a consumer
+ * can say WHICH of the shapes behind `empty_loader` it is looking at.
+ *
+ * GAIA-436: that code covers three documents — a list that is wholly indented, a
+ * section whose lines are not address-shaped at all (a `*` marker, a `-@` with no
+ * space), and an empty section. Only the first is the "your list is indented" the
+ * single message can describe; the other two get a remedy pointing at whitespace
+ * that is already fine, which is the same misdirection the anchoring fixed.
+ *
+ * It lives HERE, not in the CLI that renders it: where the section starts and ends
+ * and what counts as an address are rules of this module, and a second copy of
+ * them in the host is exactly the drift this ticket is about. The host measures
+ * (in `runValidate`) and renders (in `formatReport`); the rule stays in core.
+ *
+ * Answers for any document — a section it cannot find simply holds nothing — so a
+ * caller need not pre-check. It classifies, never throws: the defect is already
+ * raised by `expandLoad` before this is reached.
+ */
+export function measureEmptyLoader(workflowMd) {
+    const lines = workflowMd.split('\n');
+    const range = loadedSkillsRange(lines);
+    if (range === null)
+        return { indented: [], bodyLines: 0 };
+    const [start, end] = range;
+    const indented = [];
+    let bodyLines = 0;
+    for (let i = start + 1; i < end; i++) {
+        const raw = lines[i] ?? '';
+        if (raw.trim() === '')
+            continue;
+        bodyLines++;
+        const indent = raw.length - raw.trimStart().length;
+        // Asks `BULLET_SHAPED` about the DE-indented line rather than restating its
+        // body with a leading `\s+`: "address-shaped" keeps exactly one definition,
+        // so this measurement cannot drift from the anchor it is explaining.
+        if (indent > 0 && BULLET_SHAPED.test(raw.slice(indent))) {
+            indented.push({ line: i + 1, indent, text: raw.trim() });
+        }
+    }
+    return { indented, bodyLines };
+}
 /**
  * Read the per-skill value **overrides** from a `WORKFLOW.md`'s `## Loaded skills`
  * section. A project overrides a skill default **inline under that skill's bullet**
  * (indented `key: value` YAML, block scalars allowed), not in one global block.
- * Returns a map keyed by skill `name` (the `@gaia/` prefix stripped); a skill with no
- * overrides maps to `{}` (it runs on its declared defaults).
+ * Returns a map keyed by skill `name` (any `@<namespace>/` prefix stripped); a skill
+ * with no overrides maps to `{}` (it runs on its declared defaults).
  */
 export function parseStepValues(workflowMd) {
     return parseLoadedSection(workflowMd).values;
@@ -126,11 +215,16 @@ function parseLoadedSection(workflowMd) {
         const bullet = BULLET.exec(raw);
         if (bullet) {
             flush();
-            current = bullet[1] ?? null;
+            current = bullet[2] ?? null; // group 2 = the name; group 1 = the namespace
             if (current !== null)
                 names.push(current);
             continue;
         }
+        if (BULLET_SHAPED.test(raw)) {
+            // GAIA-436: a bullet the loader cannot read is a defect in the loader's
+            // input, not prose. Reporting it here is what keeps the neighbour intact.
+            throw new StepContractError(`\`## Loaded skills\` carries a bullet this loader cannot read: \`${raw.trim()}\` — write \`- @<namespace>/<skill-name>\`, lowercase with digits and \`-\` only.`);
+        }
         if (current === null)
             continue; // prose before the first bullet
         if (raw.trim() === '') {
@@ -320,6 +414,108 @@ function matchesTriple(when, triple) {
 function tripleLabel(triple) {
     return `(${triple.work_type ?? '—'}, ${triple.workflow}, ${triple.step})`;
 }
+/**
+ * The **claimable states** of each GAIA workflow — the only `step` values a ticket
+ * in that workflow can ever present to a step owner.
+ *
+ * Source of truth: `web/modules/custom/gaia_core/gaia_core.workflows.yml`. It is
+ * transcribed here rather than read, because this module is a pure library with no
+ * filesystem and no Drupal access. A workflow added there must be added here too.
+ */
+export const WORKFLOW_CLAIMABLE_STATES = {
+    gaia_feature: ['qualification', 'spec', 'coding', 'review'],
+    gaia_bug: ['qualification', 'diagnose', 'coding', 'review'],
+    gaia_chore: ['qualification', 'spec', 'coding', 'review'],
+    gaia_deployment: ['pre_deployment', 'post_deployment'],
+    gaia_verification: ['verifying', 'summary'],
+};
+/**
+ * Derive the `(work_type, workflow, step)` set a project can produce, from the
+ * skills it loads plus the fixed workflow/claimable-state table above — the input
+ * `validateLoad` needs, which until GAIA-436 only the contract test could build
+ * (from a hardcoded list) and therefore no shipped command could.
+ *
+ * A **work type** exists for the project because some loaded **owner** declares it;
+ * its participating steps are the union of `when.step` across every owner declaring
+ * it. Those steps are then crossed against **all five** workflows — not merely the
+ * ones the declaring skill happens to list — because that is what makes a coverage
+ * gap real rather than tautological: a project that can route `work:code` at
+ * `coding` must be able to route it at `coding` in every workflow that claims there.
+ *
+ * A step no work type participates in carries a `null` work type (qualification,
+ * the deployment and verification steps). An owner whose `when.work_type` is `*` or
+ * omitted is a non-work-typed owner: it contributes to the `null` side, never to a
+ * named work type. Helpers (no `when`) contribute nothing — they own no step.
+ *
+ * **Known blind spot: the work-type universe is derived from the load, not from the
+ * project.** Because a work type exists here only if some loaded owner declares it,
+ * deleting the last owner of a work type does not open a coverage gap — it shrinks
+ * the triple set, and the validation stays green. Removing `- @gaia/docs-authoring`
+ * from this repository's own `WORKFLOW.md` yields `9 → 8` owners and `24 → 16`
+ * triples, all covered, although every `work:docs` ticket would then reach `coding`
+ * with no owner at all. The set of work types a project's tickets can actually
+ * carry lives in the ticket store's `work:*` vocabulary, which this function cannot
+ * see; closing the gap means feeding that vocabulary in, which is its own change.
+ * What is validated here is therefore: *given what the project loads, is the load
+ * internally complete and unambiguous* — not *does the project load everything its
+ * tickets need*.
+ */
+export function deriveProjectTriples(skills) {
+    const stepsByWorkType = new Map();
+    for (const skill of skills) {
+        const when = skill.when;
+        if (when === undefined)
+            continue; // helper: owns no step
+        const workTypes = when.work_type;
+        if (workTypes === undefined || workTypes === '*')
+            continue; // non-work-typed
+        const steps = when.step === undefined || when.step === '*'
+            ? WORKFLOW_STEPS
+            : when.step;
+        for (const workType of workTypes) {
+            let set = stepsByWorkType.get(workType);
+            if (set === undefined) {
+                set = new Set();
+                stepsByWorkType.set(workType, set);
+            }
+            for (const step of steps)
+                set.add(step);
+        }
+    }
+    const workTypedSteps = new Set();
+    for (const set of stepsByWorkType.values())
+        for (const step of set)
+            workTypedSteps.add(step);
+    const triples = [];
+    const seen = new Set();
+    const push = (triple) => {
+        // JSON rather than a joined string: it keeps a `null` work type distinct from
+        // any string one without inventing a sentinel character that a work type could
+        // itself contain.
+        const key = JSON.stringify([
+            triple.work_type,
+            triple.workflow,
+            triple.step,
+        ]);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        triples.push(triple);
+    };
+    for (const [workflow, states] of Object.entries(WORKFLOW_CLAIMABLE_STATES)) {
+        for (const step of states) {
+            if (!workTypedSteps.has(step)) {
+                push({ work_type: null, workflow, step });
+                continue;
+            }
+            for (const [workType, steps] of stepsByWorkType) {
+                if (steps.has(step))
+                    push({ work_type: workType, workflow, step });
+            }
+        }
+    }
+    return triples;
+}
 /**
  * Read a `WORKFLOW.md` and expand what it loads into the flat, deduplicated list of
  * **leaf** skills (step-owners + helpers) the project effectively runs, together with
@@ -344,6 +540,19 @@ function tripleLabel(triple) {
  */
 export function expandLoad(workflowMd, byName) {
     const { names: rootNames, values: workflowValues } = parseLoadedSection(workflowMd);
+    // GAIA-436: a `## Loaded skills` section that yields no load site at all is its
+    // own defect and needs its own message. Expanding it into an empty skill set
+    // let the failure surface much later as `no skill matches triple (—,
+    // gaia_feature, qualification) — coverage gap`, which sends the author looking
+    // for a missing work-type skill when the real cause is almost always that their
+    // list is indented — the one shape the indent-0 anchor turns into nothing.
+    //
+    // Here rather than in `parseLoadedSection`, because a BUNDLE that lists nothing
+    // is reported by `readSkillWhen` with the bundle's own name in the message; a
+    // check in the parser would displace that more specific report.
+    if (rootNames.length === 0) {
+        throw new StepContractError('the `## Loaded skills` section carries no load site: write each skill as `- @<namespace>/<skill-name>` at indent 0. An indented `- @…` line is read as value, never as an address.', { code: 'empty_loader' });
+    }
     const skills = [];
     const emitted = new Set();
     const values = {};
@@ -362,7 +571,15 @@ export function expandLoad(workflowMd, byName) {
             const via = stack.length > 0
                 ? `bundle \`${stack[stack.length - 1]}\` loads unknown skill \`${name}\``
                 : `loaded skill \`${name}\` not found`;
-            throw new StepContractError(`${via}.`);
+            // GAIA-436: both halves are the same class of defect — a name that resolves
+            // to nothing — and a consumer's remedy for them is identical ("that skill is
+            // not vendored where the scan looked: pass `--skills`"). They are tagged
+            // alike, with the unresolved name as data, so the host stops recovering it
+            // from the message text and stops missing the bundle-member half entirely.
+            throw new StepContractError(`${via}.`, {
+                code: 'unresolved_skill',
+                skill: name,
+            });
         }
         if (skill.loads !== undefined) {
             if (stack.includes(name)) {
@@ -401,6 +618,10 @@ export function expandLoad(workflowMd, byName) {
  * resolve to a value: the `values` map (as resolved by `expandLoad`) or the input's
  * own declared `default`.
  *
+ * Finally (GAIA-436) every override the load resolved must reach a declared input:
+ * an override key no loaded skill declares is a defect, because it resolves to
+ * nothing at all and the skill silently runs on its default instead.
+ *
  * Reports the first defect as a typed `StepContractError`. Never dispatches or routes.
  */
 export function validateLoad(skills, values, projectTriples) {
@@ -427,4 +648,30 @@ export function validateLoad(skills, values, projectTriples) {
             }
         }
     }
+    // GAIA-436: the loop above reads overrides only through the DECLARED inputs of a
+    // matched owner (`overrides?.[input.key]`), so it never looks at an override key
+    // the skill does not declare. Such a key resolves to nothing — the skill runs on
+    // its default and the project's stated intent evaporates without a word. That is
+    // how a key rename silently degraded eleven overrides on a consumer project for
+    // six weeks. Sweep the loaded skills for it, and name both skill and key.
+    //
+    // Deliberately AFTER the triple loop, so a coverage gap or a collision is still
+    // reported first with its own message; and over the `skills` LIST rather than the
+    // `values` map, because `values` may legitimately carry entries for skills this
+    // load does not contain. Owners and helpers alike: a helper is loaded precisely
+    // for its inputs, so a dead override key on one is the same defect.
+    for (const skill of skills) {
+        const overrides = values[skill.name];
+        if (overrides === undefined)
+            continue;
+        const declared = new Set(skill.inputs.map((i) => i.key));
+        for (const key of Object.keys(overrides)) {
+            if (declared.has(key))
+                continue;
+            const known = declared.size === 0
+                ? 'the skill declares no inputs at all'
+                : `the skill declares \`${[...declared].join('`, `')}\``;
+            throw new StepContractError(`skill \`${skill.name}\` has no input \`${key}\`: the override resolves to nothing and the skill silently runs on its default — ${known}. Rename the override to a declared key rather than deleting it.`);
+        }
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaia-ai/core",
-  "version": "0.9.2",
+  "version": "0.11.0",
   "description": "GAIA surface-agnostic kernel: host contract, split-config helpers, addon preset/discovery machinery, shared primitives.",
   "type": "module",
   "license": "MIT",
@@ -27,10 +27,10 @@
     "directory": "gaia-cli/core"
   },
   "dependencies": {
-    "@dropsh/plugin-markdown": "^0.5.8",
-    "@dropsh/plugin-oauth2": "^0.5.7",
+    "@dropsh/plugin-markdown": "^0.6.1",
+    "@dropsh/plugin-oauth2": "^0.6.1",
     "commander": "^12.1.0",
-    "dropsh": "^0.5.8",
+    "dropsh": "^0.6.1",
     "pino": "^9.6.0",
     "pino-pretty": "^13.0.0",
     "semver": "^7.6.0",