@cat-factory/agents 0.94.0 → 0.96.0

package/dist/agents/kinds/registry.d.ts

@@ -4,6 +4,7 @@ import { normalizeSkillRefs, normalizeToolRefs } from './capabilities.js';
 import type { AgentPresentation } from '@cat-factory/contracts';
 import type { AgentTrait, AgentTraitDefinition } from './traits.js';
 import type { AgentTuning } from './tuning.js';
+import type { AgentKindVariantDefinition } from './variants.js';
 import type { StructuredOutput } from './structured-output.js';
 export interface AgentKindDefinition {
     /** The free-form agent-kind id used in pipelines and steps (e.g. `security-auditor`). */
@@ -178,6 +179,7 @@ export declare class AgentKindRegistry {
     private readonly toolServerDefinitions;
     private readonly assignedSkills;
     private readonly assignedToolServers;
+    private readonly variantDefinitions;
     constructor();
     /** Register a custom agent kind. A later registration of the same id replaces the earlier one. */
     register(definition: AgentKindDefinition): void;
@@ -295,6 +297,29 @@ export declare class AgentKindRegistry {
      * not thrown on (see {@link skillsFor}).
      */
     toolServersFor(kind: AgentKind): ReturnType<typeof normalizeToolRefs>;
+    /**
+     * Register a VARIATION of an existing agent kind — an alternate prompt a pipeline step selects
+     * by id, running the base kind in every other respect. A later registration of the same id
+     * replaces the earlier one, which is also how a deployment RE-WORDS a variant an installed
+     * package shipped without forking it — safe for Kaizen because a step is keyed by a fingerprint
+     * of the text its variant contributed, not by the id alone (see `AppliedAgentVariant`).
+     *
+     * Nothing is validated here (an id may legitimately be registered before its base kind is):
+     * `validateRegistrations` reports an unknown base, a collision with a kind id, and a variant
+     * that changes no text, as startup errors.
+     */
+    registerVariant(definition: AgentKindVariantDefinition): void;
+    /** Register several variants at once. */
+    registerVariants(definitions: Iterable<AgentKindVariantDefinition>): void;
+    /** A registered variant, or undefined when the id is unknown. */
+    variant(id: string): AgentKindVariantDefinition | undefined;
+    /** All registered variants (registration order). */
+    variants(): AgentKindVariantDefinition[];
+    /**
+     * The variants registered for one kind — what the pipeline builder offers on a step of that
+     * kind. Empty when the kind has none, which is every kind on the stock product.
+     */
+    variantsForKind(kind: AgentKind): AgentKindVariantDefinition[];
 }
 /**
  * A fresh registry pre-loaded with the built-in agent kinds. This is the single place the

package/dist/agents/kinds/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/agents/kinds/registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/agents/kinds/registry.ts"],"names":[],"mappings":"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"}

package/dist/agents/kinds/registry.js

@@ -58,6 +58,11 @@ export class AgentKindRegistry {
     // its house playbook or its issue-tracker MCP server without redefining the kind's prompt.
     assignedSkills = new Map();
     assignedToolServers = new Map();
+    // VARIANTS of existing kinds (id → definition) — an alternate prompt a step selects through
+    // `stepOptions.agentVariantId`. They live here beside the kinds and their capabilities for the
+    // same reason those do, but they are deliberately NOT kinds: a variant never appears in
+    // `all()`, never answers `get()`, and never changes a behavioural answer. See ./variants.
+    variantDefinitions = new Map();
     constructor() {
         for (const definition of STANDARD_TRAIT_DEFINITIONS) {
             this.traitDefinitions.set(definition.id, definition);
@@ -271,6 +276,40 @@ export class AgentKindRegistry {
             return EMPTY_TOOL_REFS;
         return normalizeToolRefs([...own, ...assigned], (id) => this.toolServerDefinitions.get(id));
     }
+    /**
+     * Register a VARIATION of an existing agent kind — an alternate prompt a pipeline step selects
+     * by id, running the base kind in every other respect. A later registration of the same id
+     * replaces the earlier one, which is also how a deployment RE-WORDS a variant an installed
+     * package shipped without forking it — safe for Kaizen because a step is keyed by a fingerprint
+     * of the text its variant contributed, not by the id alone (see `AppliedAgentVariant`).
+     *
+     * Nothing is validated here (an id may legitimately be registered before its base kind is):
+     * `validateRegistrations` reports an unknown base, a collision with a kind id, and a variant
+     * that changes no text, as startup errors.
+     */
+    registerVariant(definition) {
+        this.variantDefinitions.set(definition.id, definition);
+    }
+    /** Register several variants at once. */
+    registerVariants(definitions) {
+        for (const definition of definitions)
+            this.registerVariant(definition);
+    }
+    /** A registered variant, or undefined when the id is unknown. */
+    variant(id) {
+        return this.variantDefinitions.get(id);
+    }
+    /** All registered variants (registration order). */
+    variants() {
+        return [...this.variantDefinitions.values()];
+    }
+    /**
+     * The variants registered for one kind — what the pipeline builder offers on a step of that
+     * kind. Empty when the kind has none, which is every kind on the stock product.
+     */
+    variantsForKind(kind) {
+        return this.variants().filter((variant) => variant.baseKind === kind);
+    }
 }
 /** Shared empty set so `assignedTraitsFor` allocates nothing on the common no-assignment path. */
 const EMPTY_TRAIT_SET = new Set();

package/dist/agents/kinds/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/agents/kinds/registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/agents/kinds/registry.ts"],"names":[],"mappings":"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"}

package/dist/agents/kinds/traits.d.ts

@@ -59,6 +59,28 @@ export declare const INTERVIEW_GATE_TRAIT: AgentTrait;
  * so the trait only affects kinds whose standards are folded into the prompt.
  */
 export declare const BRIEF_STANDARDS_TRAIT: AgentTrait;
+/**
+ * DESIGN-time kinds that choose which shared FOUNDATIONAL SERVICES a solution consumes. The
+ * engine injects the workspace's catalog (identity + capabilities + operation names, never a
+ * contract document) as `.cat-context/foundational-services/catalog.md`, and the guidance below
+ * requires the kind to declare the ids it designed against in a machine-readable block. That
+ * declaration is what the downstream `foundational-contracts` kinds' lazy read keys off — the
+ * whole point of splitting the two traits is that a design step pays for the cheap catalog and
+ * only the services it actually picked cost anyone a document.
+ */
+export declare const FOUNDATIONAL_CATALOG_TRAIT: AgentTrait;
+/**
+ * CONSUMER kinds that need the API details of the services the design declared. The engine
+ * resolves those ids to their full contract documents and injects one file per service. The
+ * guidance points at the index rather than restating the catalog: a consumer must not be
+ * choosing services, and handing it the whole catalog is how a coder ends up adopting a shared
+ * service the design deliberately rejected.
+ */
+export declare const FOUNDATIONAL_CONTRACTS_TRAIT: AgentTrait;
+/** The guidance a design-time kind gets: consult the catalog, then DECLARE what it used. */
+export declare const FOUNDATIONAL_CATALOG_GUIDANCE: string;
+/** The guidance a consumer kind gets: the contracts are files, and they are authoritative. */
+export declare const FOUNDATIONAL_CONTRACTS_GUIDANCE: string;
 /** The guidance appended to a spec-aware kind's system prompt — explains the spec format. */
 export declare const SPEC_AWARE_GUIDANCE: string;
 /**

package/dist/agents/kinds/traits.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"traits.d.ts","sourceRoot":"","sources":["../../../src/agents/kinds/traits.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,SAAS,EAGf,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAetD,yFAAyF;AACzF,MAAM,MAAM,UAAU,GAAG,MAAM,CAAA;AAE/B;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,UAAyB,CAAA;AAExD;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,UAAwB,CAAA;AAEtD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,UAAyB,CAAA;AAExD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,EAAE,UAA6B,CAAA;AAEhE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,EAAE,UAA6B,CAAA;AAEhE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,EAAE,UAA8B,CAAA;AAElE,6FAA6F;AAC7F,eAAO,MAAM,mBAAmB,QAWpB,CAAA;AAEZ;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,UAAU,EAAE,CAAC,CA6B1E,CAAA;AAED,kFAAkF;AAClF,MAAM,WAAW,oBAAoB;IACnC,mFAAmF;IACnF,EAAE,EAAE,UAAU,CAAA;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,SAAS,KAAK,MAAM,CAAC,CAAA;CAClD;AAED;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,oBAAoB,EAMrE,CAAA;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,iBAAiB,GAAG,GAAG,CAAC,UAAU,CAAC,CAKvF;AAED,sCAAsC;AACtC,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAEjG;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,iBAAiB,GAC1B,MAAM,GAAG,OAAO,CAElB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,iBAAiB,GAAG,MAAM,EAAE,CAQvF"}
+{"version":3,"file":"traits.d.ts","sourceRoot":"","sources":["../../../src/agents/kinds/traits.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,SAAS,EAOf,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAetD,yFAAyF;AACzF,MAAM,MAAM,UAAU,GAAG,MAAM,CAAA;AAE/B;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,UAAyB,CAAA;AAExD;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,UAAwB,CAAA;AAEtD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,UAAyB,CAAA;AAExD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,EAAE,UAA6B,CAAA;AAEhE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,EAAE,UAA6B,CAAA;AAEhE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,EAAE,UAA8B,CAAA;AAElE;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,EAAE,UAAmC,CAAA;AAE5E;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,EAAE,UAAqC,CAAA;AAEhF,4FAA4F;AAC5F,eAAO,MAAM,6BAA6B,QAK9B,CAAA;AAEZ,8FAA8F;AAC9F,eAAO,MAAM,+BAA+B,QAIhC,CAAA;AAEZ,6FAA6F;AAC7F,eAAO,MAAM,mBAAmB,QAWpB,CAAA;AAEZ;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,UAAU,EAAE,CAAC,CAmC1E,CAAA;AAED,kFAAkF;AAClF,MAAM,WAAW,oBAAoB;IACnC,mFAAmF;IACnF,EAAE,EAAE,UAAU,CAAA;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,SAAS,KAAK,MAAM,CAAC,CAAA;CAClD;AAED;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,oBAAoB,EAQrE,CAAA;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,iBAAiB,GAAG,GAAG,CAAC,UAAU,CAAC,CAKvF;AAED,sCAAsC;AACtC,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAEjG;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,iBAAiB,GAC1B,MAAM,GAAG,OAAO,CAElB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,iBAAiB,GAAG,MAAM,EAAE,CAQvF"}

package/dist/agents/kinds/traits.js

@@ -1,5 +1,5 @@
 import { SPEC_FEATURES_DIR, SPEC_MODULES_DIR, SPEC_OVERVIEW_PATH } from '@cat-factory/contracts';
-import { DOC_INTERVIEWER_AGENT_KIND, INITIATIVE_INTERVIEWER_AGENT_KIND, } from '@cat-factory/kernel';
+import { DOC_INTERVIEWER_AGENT_KIND, FOUNDATIONAL_CATALOG_FILE, FOUNDATIONAL_CONTEXT_DIR, FOUNDATIONAL_DECLARATION_TAG, FOUNDATIONAL_INDEX_FILE, INITIATIVE_INTERVIEWER_AGENT_KIND, } from '@cat-factory/kernel';
 /**
  * Code-aware kinds read and/or change the service's code. The service's selected
  * best-practice / guideline fragments (Node, Fastify, performance, …) are folded into
@@ -57,6 +57,37 @@ export const INTERVIEW_GATE_TRAIT = 'interview-gate';
  * so the trait only affects kinds whose standards are folded into the prompt.
  */
 export const BRIEF_STANDARDS_TRAIT = 'brief-standards';
+/**
+ * DESIGN-time kinds that choose which shared FOUNDATIONAL SERVICES a solution consumes. The
+ * engine injects the workspace's catalog (identity + capabilities + operation names, never a
+ * contract document) as `.cat-context/foundational-services/catalog.md`, and the guidance below
+ * requires the kind to declare the ids it designed against in a machine-readable block. That
+ * declaration is what the downstream `foundational-contracts` kinds' lazy read keys off — the
+ * whole point of splitting the two traits is that a design step pays for the cheap catalog and
+ * only the services it actually picked cost anyone a document.
+ */
+export const FOUNDATIONAL_CATALOG_TRAIT = 'foundational-catalog';
+/**
+ * CONSUMER kinds that need the API details of the services the design declared. The engine
+ * resolves those ids to their full contract documents and injects one file per service. The
+ * guidance points at the index rather than restating the catalog: a consumer must not be
+ * choosing services, and handing it the whole catalog is how a coder ends up adopting a shared
+ * service the design deliberately rejected.
+ */
+export const FOUNDATIONAL_CONTRACTS_TRAIT = 'foundational-contracts';
+/** The guidance a design-time kind gets: consult the catalog, then DECLARE what it used. */
+export const FOUNDATIONAL_CATALOG_GUIDANCE = [
+    `This deployment runs shared FOUNDATIONAL SERVICES — capabilities such as file storage, notifications or audit that already exist and that new systems are expected to CONSUME rather than rebuild. The catalog of what is available is provided to you as \`.cat-context/${FOUNDATIONAL_CATALOG_FILE}\`; read it before you settle on a design.`,
+    `Prefer an existing foundational service over designing your own equivalent. When you reject one that looks applicable, say why — "we already have this" is the single most common avoidable finding in a design review.`,
+    `The catalog lists each service's operations but NOT its full API documents. Design against the operations you can see; do not invent endpoints, fields or semantics the catalog does not show. The implementation steps get the full contracts.`,
+    `END your reply with a fenced \`\`\`${FOUNDATIONAL_DECLARATION_TAG} block listing the service ids your design consumes, one per line, and nothing else in the block. Write \`none\` when your design consumes no foundational service. This block is machine-read: the ids you list are what the later implementation steps are handed the API contracts for, so a service you omit is one nobody downstream will have the interface to, and an id you invent will be reported as unavailable.`,
+].join('\n');
+/** The guidance a consumer kind gets: the contracts are files, and they are authoritative. */
+export const FOUNDATIONAL_CONTRACTS_GUIDANCE = [
+    `The FOUNDATIONAL SERVICES the design chose for this task — shared capabilities such as file storage, notifications or audit — have their API contracts provided to you under \`.cat-context/${FOUNDATIONAL_CONTEXT_DIR}/\`. Start at \`.cat-context/${FOUNDATIONAL_INDEX_FILE}\`, which names each one and states anything the design asked for that could not be provided.`,
+    `Treat those contracts as the authoritative interface: call the operations they declare, with the shapes they declare. Do not invent an endpoint or a field, and do not reimplement a capability one of these services already provides.`,
+    `If the work needs something the provided contracts do not cover, say so in your report rather than guessing at the missing API.`,
+].join('\n');
 /** The guidance appended to a spec-aware kind's system prompt — explains the spec format. */
 export const SPEC_AWARE_GUIDANCE = [
     `This repository may contain a prescriptive SPECIFICATION for the service under the \`spec/\` directory — the source of truth for what the service must do. It is sharded by a module (domain) → feature (group) taxonomy. When it is present, read it before doing the work:`,
@@ -83,8 +114,14 @@ export const SPEC_AWARE_GUIDANCE = [
  *    `reviewer` companion is a built-in listed here while the coder declares its own).
  */
 export const STANDARD_AGENT_TRAITS = {
-    architect: [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT],
-    coder: [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT, BRIEF_STANDARDS_TRAIT],
+    // The architect DESIGNS, so it is the one built-in kind that chooses foundational services
+    // and declares them; `researcher` and `coder` CONSUME that declaration.
+    architect: [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT, FOUNDATIONAL_CATALOG_TRAIT],
+    coder: [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT, BRIEF_STANDARDS_TRAIT, FOUNDATIONAL_CONTRACTS_TRAIT],
+    // The researcher plans the solution against the design, so it needs the same contracts the
+    // coder will build to — investigating prior art for a capability the org already runs, from
+    // the catalog entry alone, is how a plan ends up proposing a library beside a shared service.
+    researcher: [FOUNDATIONAL_CONTRACTS_TRAIT],
     reviewer: [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT],
     'ci-fixer': [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT, BRIEF_STANDARDS_TRAIT],
     fixer: [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT, BRIEF_STANDARDS_TRAIT],
@@ -124,6 +161,8 @@ export const STANDARD_TRAIT_DEFINITIONS = [
     { id: SPEC_AWARE_TRAIT, guidance: SPEC_AWARE_GUIDANCE },
     { id: INTERVIEW_GATE_TRAIT },
     { id: BRIEF_STANDARDS_TRAIT },
+    { id: FOUNDATIONAL_CATALOG_TRAIT, guidance: FOUNDATIONAL_CATALOG_GUIDANCE },
+    { id: FOUNDATIONAL_CONTRACTS_TRAIT, guidance: FOUNDATIONAL_CONTRACTS_GUIDANCE },
 ];
 /**
  * The traits a kind carries: its built-in set ({@link STANDARD_AGENT_TRAITS}) unioned with a

package/dist/agents/kinds/traits.js.map

@@ -1 +1 @@
-{"version":3,"file":"traits.js","sourceRoot":"","sources":["../../../src/agents/kinds/traits.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"traits.js","sourceRoot":"","sources":["../../../src/agents/kinds/traits.ts"],"names":[],"mappings":"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"}

package/dist/agents/kinds/variants.d.ts

@@ -0,0 +1,115 @@
+import type { AgentKind } from '@cat-factory/kernel';
+/** How a variant is labelled wherever a step's agent kind is shown. */
+export interface AgentKindVariantPresentation {
+    /**
+     * Short distinguishing name, shown BESIDE the base kind's own label (`Coder · TDD-first`)
+     * rather than in place of it — the step really is a Coder step, and a label that hid that
+     * would make the run harder to read, not easier.
+     */
+    label: string;
+    /** One sentence on what this variant changes, for the step-option picker's tooltip. */
+    description?: string;
+}
+/**
+ * A registered variation of an existing agent kind: its alternate prompt plus the identity the
+ * pipeline builder and the run views show it under.
+ *
+ * At least one of {@link systemPrompt} / {@link promptAddition} must be set — a variant that
+ * changes no text is a step option with no effect, which boot validation reports rather than
+ * letting it run as a silently ordinary step.
+ */
+export interface AgentKindVariantDefinition {
+    /**
+     * The variant id named by a step's `stepOptions.agentVariantId`. Free-form; namespace it the
+     * way a deployment namespaces anything else it registers (`acme:coder-tdd`).
+     */
+    id: string;
+    /**
+     * The EXISTING agent kind this varies. The step runs as this kind in every respect; the
+     * variant supplies only its prompt. Boot validation refuses an unknown one.
+     *
+     * It must also be a kind the DISPATCH composes a prompt for. The inline ENGINE kinds
+     * (`INLINE_ENGINE_SYSTEM_PROMPTS` — the requirements + clarity reviewers, both brainstorm
+     * stages, their rework editors) are refused: `IterativeReviewService` composes their prompt from
+     * (workspace, kind) with no step in hand, so a variant selected on such a step could never reach
+     * the model, and a per-workspace prompt override is what varies them today. The bespoke
+     * CONTAINER kinds (`merger`, `on-call`) are fine — they dispatch through the engine like any
+     * other container kind, against their ROLE half.
+     */
+    baseKind: AgentKind;
+    /**
+     * REPLACES the kind's shipped track prompt outright — for a variant whose role is genuinely
+     * different prose, not a rider on the shipped one.
+     *
+     * Prefer {@link promptAddition} where it will do: a replacement is a copy of the shipped
+     * prompt that stops tracking it the day the product edits it, which is the same staleness a
+     * per-workspace override carries. What it CANNOT do is drop a platform invariant — those are
+     * re-applied on top (see the file header).
+     */
+    systemPrompt?: string;
+    /**
+     * APPENDED to whatever base prompt this dispatch runs under — the shipped one, this variant's
+     * {@link systemPrompt}, or the workspace's own override of it. That is what makes an addition
+     * the safe default: it steers the kind without forking its prompt, so both the product's edits
+     * and a workspace's keep applying underneath.
+     */
+    promptAddition?: string;
+    /** Display metadata. Omitted ⇒ the SPA shows the variant's raw id. */
+    presentation?: AgentKindVariantPresentation;
+}
+/**
+ * How much of what a selected variant declares actually reached the prompt a step ran under.
+ *
+ * A variant loses its `systemPrompt` to a workspace override, because the workspace is the
+ * narrower tier — so "a variant was selected" and "the variant shaped this prompt" are different
+ * facts, and a reader shown only the first would be told something untrue. The three losing
+ * cases are kept APART rather than collapsed into one "didn't apply", because they need
+ * different fixes: drop the workspace's edit, drop the variant's replacement in favour of an
+ * addition, or re-register the variant.
+ *
+ * - `full` — everything the variant declares is in the effective prompt.
+ * - `addition-only` — a workspace override displaced its `systemPrompt`; its `promptAddition`
+ *   still folded on top.
+ * - `superseded` — a workspace override displaced its `systemPrompt` and it had no addition, so
+ *   nothing of it survives.
+ * - `withdrawn` — the id the step names is not registered (resolved by the caller, which is the
+ *   only place that knows the lookup failed).
+ */
+export type AgentVariantApplication = 'full' | 'addition-only' | 'superseded' | 'withdrawn';
+/** The effective prompt for one dispatch plus what the variant contributed to it. */
+export interface AppliedAgentVariant {
+    /**
+     * The effective system-prompt override, or undefined to run the shipped prompt — so an
+     * unvaried, unedited step's dispatch is byte-for-byte what it always sent, the same
+     * "absent ⇒ shipped" contract `AgentRunContext.systemPromptOverride` already has.
+     */
+    prompt?: string;
+    /** How much of the variant survived into {@link prompt}. */
+    applied: AgentVariantApplication;
+    /**
+     * Fingerprint of the text the variant actually CONTRIBUTED, absent when it contributed none.
+     *
+     * This is what stops a re-worded variant from inheriting the verification its previous wording
+     * earned — the same hazard the workspace revision suffix (`wN`) exists for, which a bare id
+     * cannot express because re-registering an id is a supported way to re-word a variant. It
+     * fingerprints the CONTRIBUTION rather than the definition so the key describes the text that
+     * ran: a variant whose replacement was displaced is keyed by the addition that survived, and
+     * one that contributed nothing does not enter the key at all.
+     */
+    fingerprint?: string;
+}
+/**
+ * The effective system-prompt override for one dispatch: the variant's replacement (unless a
+ * workspace override already replaced the track prompt — the narrower tier wins, as it does for
+ * every other per-dispatch knob) plus the variant's addition folded onto whichever base survived.
+ *
+ * `shipped` is passed in rather than resolved here because the caller (the engine) is the one
+ * place that knows the kind actually being dispatched; see `shippedBasePromptFor`, which is what
+ * it resolves it with.
+ *
+ * Called with NO variant (an ordinary step, varied or not by the workspace alone) this is just
+ * the workspace override passed through, and `applied` is vacuously `full` — there is nothing to
+ * lose. Only a caller that named a variant id reads it.
+ */
+export declare function applyAgentVariant(shipped: string, variant: AgentKindVariantDefinition | undefined, workspaceOverride?: string): AppliedAgentVariant;
+//# sourceMappingURL=variants.d.ts.map

package/dist/agents/kinds/variants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variants.d.ts","sourceRoot":"","sources":["../../../src/agents/kinds/variants.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AA2BpD,uEAAuE;AACvE,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,uFAAuF;IACvF,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;;;;;;;;;;OAWG;IACH,QAAQ,EAAE,SAAS,CAAA;IACnB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,sEAAsE;IACtE,YAAY,CAAC,EAAE,4BAA4B,CAAA;CAC5C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,eAAe,GAAG,YAAY,GAAG,WAAW,CAAA;AAE3F,qFAAqF;AACrF,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,4DAA4D;IAC5D,OAAO,EAAE,uBAAuB,CAAA;IAChC;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,0BAA0B,GAAG,SAAS,EAC/C,iBAAiB,CAAC,EAAE,MAAM,GACzB,mBAAmB,CAqBrB"}

package/dist/agents/kinds/variants.js

@@ -0,0 +1,35 @@
+import { contentHash } from '@cat-factory/kernel';
+/**
+ * The effective system-prompt override for one dispatch: the variant's replacement (unless a
+ * workspace override already replaced the track prompt — the narrower tier wins, as it does for
+ * every other per-dispatch knob) plus the variant's addition folded onto whichever base survived.
+ *
+ * `shipped` is passed in rather than resolved here because the caller (the engine) is the one
+ * place that knows the kind actually being dispatched; see `shippedBasePromptFor`, which is what
+ * it resolves it with.
+ *
+ * Called with NO variant (an ordinary step, varied or not by the workspace alone) this is just
+ * the workspace override passed through, and `applied` is vacuously `full` — there is nothing to
+ * lose. Only a caller that named a variant id reads it.
+ */
+export function applyAgentVariant(shipped, variant, workspaceOverride) {
+    const replacement = variant?.systemPrompt;
+    const replaced = workspaceOverride ?? replacement;
+    const addition = variant?.promptAddition?.trim();
+    const displaced = Boolean(replacement) && workspaceOverride !== undefined;
+    if (!addition) {
+        return {
+            ...(replaced === undefined ? {} : { prompt: replaced }),
+            applied: displaced ? 'superseded' : 'full',
+            ...(displaced || !replacement ? {} : { fingerprint: contentHash(replacement) }),
+        };
+    }
+    return {
+        prompt: `${replaced ?? shipped}\n\n${addition}`,
+        applied: displaced ? 'addition-only' : 'full',
+        // The contribution, which is the addition alone once a workspace override displaced the
+        // replacement — see {@link AppliedAgentVariant.fingerprint}.
+        fingerprint: contentHash(displaced || !replacement ? addition : `${replacement}\n\n${addition}`),
+    };
+}
+//# sourceMappingURL=variants.js.map

package/dist/agents/kinds/variants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variants.js","sourceRoot":"","sources":["../../../src/agents/kinds/variants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAmIjD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAe,EACf,OAA+C,EAC/C,iBAA0B;IAE1B,MAAM,WAAW,GAAG,OAAO,EAAE,YAAY,CAAA;IACzC,MAAM,QAAQ,GAAG,iBAAiB,IAAI,WAAW,CAAA;IACjD,MAAM,QAAQ,GAAG,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,CAAA;IAChD,MAAM,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,IAAI,iBAAiB,KAAK,SAAS,CAAA;IACzE,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO;YACL,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;YACvD,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM;YAC1C,GAAG,CAAC,SAAS,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,WAAW,CAAC,WAAW,CAAC,EAAE,CAAC;SAChF,CAAA;IACH,CAAC;IACD,OAAO;QACL,MAAM,EAAE,GAAG,QAAQ,IAAI,OAAO,OAAO,QAAQ,EAAE;QAC/C,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,MAAM;QAC7C,wFAAwF;QACxF,6DAA6D;QAC7D,WAAW,EAAE,WAAW,CACtB,SAAS,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,WAAW,OAAO,QAAQ,EAAE,CACvE;KACF,CAAA;AACH,CAAC"}

package/dist/agents/prompts/bespoke-kinds.d.ts

@@ -0,0 +1,72 @@
+import type { AgentKind } from '@cat-factory/kernel';
+import type { AgentKindRegistry } from '../kinds/registry.js';
+import type { BespokeSystemPrompt } from './bespoke.js';
+/**
+ * The EDITABLE half of the `merger` prompt: what the agent is for. Replaced wholesale by a
+ * workspace override, so it must carry no invariant the engine depends on.
+ */
+export declare const MERGER_ROLE_PROMPT: string;
+/**
+ * The NON-EDITABLE half: the JSON contract `resolveMergerStep` parses, and the rule that keeps a
+ * reasoning model's answer out of its hidden channel. Re-appended on top of an override — an
+ * override that could drop these fails the run in exactly the ways they exist to prevent (an
+ * empty visible reply the harness reads as unusable; a merge decision with nothing to parse).
+ */
+export declare const MERGER_DIRECTIVES: string;
+/** Role prompt the `merger` step runs under (scores the PR; returns JSON only). */
+export declare const MERGER_SYSTEM_PROMPT: string;
+/**
+ * The EDITABLE half of the `on-call` prompt: what the agent is investigating and how to weigh
+ * it. Replaced wholesale by a workspace override — note that the read-only guardrail is
+ * deliberately NOT here, since an on-call agent that could be told to commit is the specific
+ * accident this split prevents.
+ */
+export declare const ON_CALL_ROLE_PROMPT: string;
+/**
+ * The NON-EDITABLE half: the read-only guardrail (this kind investigates, a human decides
+ * whether to revert — see `resolveOnCallStep`), the JSON contract the engine parses, and the
+ * answer-in-your-reply rule. Re-appended on top of an override.
+ */
+export declare const ON_CALL_DIRECTIVES: string;
+/** Role prompt the `on-call` step runs under (investigates a regression; returns JSON only). */
+export declare const ON_CALL_SYSTEM_PROMPT: string;
+/**
+ * Every kind whose prompt is a bespoke constant rather than a `systemPromptFor` composition,
+ * keyed by agent kind and SPLIT at the boundary a replacement may cross
+ * ({@link BespokeSystemPrompt}).
+ *
+ * Two families, for the same reason. The container kinds `merger` and `on-call` dispatch a
+ * bespoke constant (both return a strict JSON assessment whose contract is stated in that
+ * prompt); the inline ENGINE steps — the requirements + clarity reviewers, both brainstorm
+ * stages, their rework editors and the Requirement Writer — are driven by
+ * `IterativeReviewService` as bare inline calls. Neither family passes through `systemPromptFor`,
+ * so neither gets its override applied or its invariants re-appended by that seam.
+ *
+ * Collected here so the prompt EDITOR, the RUN and a code-registered VARIANT agree on what "the
+ * built-in prompt for this kind" is. With the constants only inlined, an editor built on
+ * `systemPromptFor` showed the merger's thin one-line role — and the requirements reviewer's
+ * `roles.ts` line — as the baseline while something else entirely ran: "restore the built-in"
+ * restored a prompt that was never running, and a diff against the baseline was noise.
+ *
+ * Adding another such kind means adding it here, SPLIT — a kind added with its directives inside
+ * `role` compiles and runs fine, and fails only later, as a workspace that edited it loses its
+ * guardrail or its JSON contract.
+ *
+ * The two container kind ids are bare literals: their canonical constants live in kernel
+ * (`ON_CALL_AGENT_KIND`) and orchestration (`MERGER_AGENT_KIND`), and this package sits below
+ * both. Pinned by `promptOverrides.spec.ts`, which resolves them through those constants.
+ */
+export declare const BESPOKE_SYSTEM_PROMPTS: Partial<Record<AgentKind, BespokeSystemPrompt>>;
+/**
+ * The SHIPPED prompt for a kind — the unit a per-workspace override or a registered variant
+ * REPLACES, and what the prompt editor shows as the baseline to diff against and restore to.
+ *
+ * It excludes the surface directives and trait guidance `systemPromptFor` layers on (and, for a
+ * bespoke kind, its `directives` half), because those are invariants of how the platform runs
+ * the kind (a read-only kind must not edit; a reasoning kind's answer must land in its visible
+ * reply) rather than editorial content. They are re-applied on top of a replacement, so handing
+ * them to an editor would only let someone delete something that comes back anyway — or, worse,
+ * duplicate it on save.
+ */
+export declare function shippedBasePromptFor(kind: AgentKind, registry: AgentKindRegistry): string;
+//# sourceMappingURL=bespoke-kinds.d.ts.map

package/dist/agents/prompts/bespoke-kinds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bespoke-kinds.d.ts","sourceRoot":"","sources":["../../../src/agents/prompts/bespoke-kinds.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAE7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAwBvD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,QAMmC,CAAA;AAElE;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,QAIP,CAAA;AAEvB,mFAAmF;AACnF,eAAO,MAAM,oBAAoB,QAAyC,CAAA;AAE1E;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,QAKsC,CAAA;AAEtE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAMR,CAAA;AAEvB,gGAAgG;AAChG,eAAO,MAAM,qBAAqB,QAA2C,CAAA;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,sBAAsB,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,mBAAmB,CAAC,CAIlF,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAEzF"}