@lumenflow/cli 5.0.3 → 5.2.0

package/packs/sidekick/src/ports/channel-bridge.port.ts

@@ -2,8 +2,17 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 
 /**
- * WU-2735 (INIT-060 WU-7a, ADR-013 §ChannelBridge):
- * ChannelBridge port.
+ * WU-2735 (INIT-060 WU-7a, ADR-013 §ChannelBridge) + WU-2831 (INIT-062 WU-E):
+ *
+ * Sidekick-pack ChannelBridge port.
+ *
+ * As of WU-2831 the canonical neutral port lives in `@lumenflow/conductor-sdk`
+ * under Apache-2.0 — consumers that need an AGPL-free surface (e.g. the
+ * cloud phone bridge) MUST import from there. The sidekick port below reuses
+ * the conductor-sdk identity / config / result types (no parallel drift) but
+ * keeps the pack-internal wire-format envelope (`ChannelEnvelope` with
+ * `kind: 'ephemeral' | 'queue'`) for on-disk and control-plane compatibility
+ * of existing adapters.
  *
  * Port contract — load-bearing across adapters (ADR-013 §ChannelBridge):
  *
@@ -11,14 +20,12 @@
  *   `ephemeral` envelopes (ADR-013 §4 backpressure split).
  * - `receive` yields envelopes in emit order on a single channel (§3). No
  *   cross-channel ordering guarantee.
- * - `register` is idempotent on `BridgeConfig` identity — same
- *   `(provider, name)` returns the same `ChannelId`.
+ * - `connect` (alias: `register`) is idempotent on `BridgeConfig` identity —
+ *   same `(provider, name)` returns the same `ChannelId`.
  * - `disconnect` flushes queued envelopes before closing; in-flight ephemerals
  *   may drop.
  *
- * The port MUST NOT leak filesystem- or network-specific types. Both the
- * filesystem adapter (this WU) and the cloud adapter (WU-2737) implement this
- * interface unmodified.
+ * The port MUST NOT leak filesystem- or network-specific types.
  */
 
 import type {
@@ -29,6 +36,21 @@ import type {
 } from '../domain/channel.types.js';
 
 export interface ChannelBridge {
+  /**
+   * Open (or reuse) a channel. Idempotent on `(provider, name)`.
+   *
+   * Canonical method name per the neutral conductor-sdk port (WU-2831).
+   */
+  connect(bridgeConfig: BridgeConfig): Promise<ChannelId>;
+
+  /**
+   * Legacy alias for `connect`. Retained for pack-internal call sites that
+   * predate WU-2831.
+   *
+   * @deprecated Use `connect` instead (WU-2831 port-contract alignment).
+   */
+  register(bridgeConfig: BridgeConfig): Promise<ChannelId>;
+
   /**
    * Send an envelope on a registered channel.
    *
@@ -42,11 +64,6 @@ export interface ChannelBridge {
    */
   receive(channelId: ChannelId): AsyncIterable<ChannelEnvelope>;
 
-  /**
-   * Register a channel and return its id. Idempotent on `(provider, name)`.
-   */
-  register(bridgeConfig: BridgeConfig): Promise<ChannelId>;
-
   /**
    * Close the channel. Queued envelopes flush before this resolves; ephemerals
    * in flight may be dropped.

package/packs/sidekick/tool-impl/channel-tools.ts

@@ -22,7 +22,6 @@ import {
   buildChannelMessageReceivedEvent,
   buildChannelMessageSentEvent,
   emitSidekickEvent,
-  serializeLocalChannelMessage,
 } from '../sidekick-events.js';
 
 // ---------------------------------------------------------------------------
@@ -300,16 +299,18 @@ async function channelSendViaTransport(
     };
   }
 
-  await emitSidekickEvent(
-    buildChannelMessageSentEvent({
-      provider,
-      channel,
-      content,
-      ...(transportResult.externalMessageId !== undefined
-        ? { external_message_id: transportResult.externalMessageId }
-        : {}),
-    }),
-  );
+  // WU-2830 (INIT-062 WU-D): ChannelMessageSentEvent.message is a typed
+  // ChannelMessageRecord. Provider sends do not have a local storage row,
+  // so we synthesize a record using the external id when available.
+  const providerSentMessage: ChannelMessageRecord = {
+    id: transportResult.externalMessageId ?? createId('msg'),
+    channel_id: `${provider}:${channel}`,
+    sender: 'assistant',
+    content,
+    created_at: nowIso(),
+  };
+
+  await emitSidekickEvent(buildChannelMessageSentEvent(providerSentMessage));
 
   return success(outputData);
 }
@@ -389,9 +390,8 @@ async function channelSendTool(input: unknown, context?: ToolContextLike): Promi
     );
   });
 
-  await emitSidekickEvent(
-    buildChannelMessageSentEvent(serializeLocalChannelMessage(resolvedMessage, channelName)),
-  );
+  // WU-2830: pass the typed ChannelMessageRecord directly.
+  await emitSidekickEvent(buildChannelMessageSentEvent(resolvedMessage));
 
   return success({ message: resolvedMessage as unknown as Record<string, unknown> });
 }
@@ -462,17 +462,47 @@ async function channelReceiveViaTransport(
     };
   }
 
+  // WU-2830: ChannelMessageReceivedEvent now carries typed
+  // ChannelMessageRecord[] (symmetric with the sent event). Coerce
+  // provider-opaque records into the canonical shape before emission.
+  const receivedRecords = (transportResult.records ?? []).map((record) =>
+    coerceProviderRecordToMessageRecord(record, `${provider}:${channel}`),
+  );
+
   await emitSidekickEvent(
     buildChannelMessageReceivedEvent({
       provider,
       channel,
-      count: transportResult.records?.length ?? 0,
+      messages: receivedRecords,
     }),
   );
 
   return success(outputData);
 }
 
+function coerceProviderRecordToMessageRecord(
+  record: unknown,
+  fallbackChannelId: string,
+): ChannelMessageRecord {
+  // WU-2830: provider transports declare `records?: unknown[]`. Type-narrow
+  // to build a ChannelMessageRecord without unsafe casts; missing fields
+  // fall back to sensible defaults so downstream consumers always see a
+  // complete, typed payload.
+  const source = record && typeof record === 'object' ? (record as Record<string, unknown>) : {};
+  const now = nowIso();
+  const id = typeof source.id === 'string' && source.id.length > 0 ? source.id : createId('msg');
+  const channel_id =
+    typeof source.channel_id === 'string' && source.channel_id.length > 0
+      ? source.channel_id
+      : fallbackChannelId;
+  const sender =
+    typeof source.sender === 'string' && source.sender.length > 0 ? source.sender : 'external';
+  const content = typeof source.content === 'string' ? source.content : '';
+  const created_at =
+    typeof source.created_at === 'string' && source.created_at.length > 0 ? source.created_at : now;
+  return { id, channel_id, sender, content, created_at };
+}
+
 async function channelReceiveTool(input: unknown, _context?: ToolContextLike): Promise<ToolOutput> {
   const parsed = toRecord(input);
   const channelName = asNonEmptyString(parsed.channel);
@@ -511,7 +541,8 @@ async function channelReceiveTool(input: unknown, _context?: ToolContextLike): P
   await emitSidekickEvent(
     buildChannelMessageReceivedEvent({
       channel: channelName ?? DEFAULT_CHANNEL_NAME,
-      count: items.length,
+      // WU-2830: carry the full typed ChannelMessageRecord[] payload.
+      messages: items,
     }),
   );
 

package/packs/sidekick/tool-impl/system-tools.ts

@@ -12,11 +12,7 @@ import {
   type ToolContextLike,
   type ToolOutput,
 } from './shared.js';
-import {
-  buildStateRehydratedEvent,
-  emitSidekickEvent,
-  snapshotSidekickState,
-} from '../sidekick-events.js';
+import { emitSidekickStateRehydration, snapshotSidekickState } from '../sidekick-events.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -51,7 +47,9 @@ async function initTool(context?: ToolContextLike): Promise<ToolOutput> {
     }),
   );
 
-  await emitSidekickEvent(buildStateRehydratedEvent(await snapshotSidekickState()));
+  // WU-2830 (INIT-062 WU-D): chunked rehydration replaces the monolithic
+  // `state_rehydrated` emission — unbounded snapshots cannot stream.
+  await emitSidekickStateRehydration(await snapshotSidekickState());
 
   return success({
     initialized: true,

package/packs/software-delivery/manifest.ts

@@ -31,6 +31,25 @@ export type {
 } from './manifest-schema.js';
 
 const FULL_WORKSPACE_SCOPE_PATTERN = '**';
+// WU-2833 (INIT-062 WU-G): the canonical read-only workspace scope used by
+// validation runners like gates / gates:docs. Exposed so remote callers
+// cannot mis-declare a read-only runner with a broader write scope.
+export const SOFTWARE_DELIVERY_READ_SCOPE_PATTERN = FULL_WORKSPACE_SCOPE_PATTERN;
+/**
+ * WU-2833 (INIT-062 WU-G): tools whose runtime handlers perform only
+ * read-side inspection (no filesystem mutation, no git mutation). Any
+ * attempt to re-declare these tools with permission: write or admin MUST
+ * fail the pack:validate gate so the security posture established by
+ * WU-2810/2811/2816 cannot drift without an explicit ADR.
+ */
+export const SOFTWARE_DELIVERY_READ_ONLY_RUNNER_TOOLS = ['gates', 'gates:docs'] as const;
+export type SoftwareDeliveryReadOnlyRunnerTool =
+  (typeof SOFTWARE_DELIVERY_READ_ONLY_RUNNER_TOOLS)[number];
+// WU-2833: metrics:snapshot reads the workspace to compute DORA metrics
+// but writes the computed snapshot back into workspace state. This narrow
+// write scope keeps mobile/cloud tokens for metrics:snapshot from leaking
+// full-tree write access (principle of least privilege).
+const SOFTWARE_DELIVERY_WORKSPACE_STATE_WRITE_PATTERN = '.lumenflow/state/**';
 const SOFTWARE_DELIVERY_WRITE_DIRECTORY_PATTERNS = [
   '.changeset/**',
   '.claude/**',
@@ -99,6 +118,10 @@ const WU_UNBLOCK_TOOL_ENTRY = 'tool-impl/wu-lifecycle-tools.ts#wuUnblockTool';
 const WU_RELEASE_TOOL_ENTRY = 'tool-impl/wu-lifecycle-tools.ts#wuReleaseTool';
 const WU_RECOVER_TOOL_ENTRY = 'tool-impl/wu-lifecycle-tools.ts#wuRecoverTool';
 const WU_REPAIR_TOOL_ENTRY = 'tool-impl/wu-lifecycle-tools.ts#wuRepairTool';
+// WU-2833 (INIT-062 WU-G): admin-mode wu:repair wrapper that forces the
+// `--admin` flag; exposed as a separate manifest tool so approvals can
+// be attached to the privileged surface independently of wu:repair.
+const WU_REPAIR_ADMIN_TOOL_ENTRY = 'tool-impl/wu-lifecycle-tools.ts#wuRepairAdminTool';
 const GATES_TOOL_ENTRY = 'tool-impl/wu-lifecycle-tools.ts#gatesTool';
 // WU-2729 (INIT-060 Phase 2): gates:docs exposes docs-only gate runs via a
 // dedicated manifest entry so remote callers can request the docs gate
@@ -210,6 +233,11 @@ const TOOL_PERMISSIONS = {
   'wu:recover': 'write',
   'wu:release': 'write',
   'wu:repair': 'write',
+  // WU-2833 (INIT-062 WU-G): privileged recovery surface for cloud-team
+  // phone UX. Distinct tool name so an approval gate + admin permission
+  // can be declared without widening the scope of the default wu:repair
+  // implementer tool.
+  'wu:repair:admin': 'admin',
   'wu:sandbox': 'write',
   'wu:status': 'read',
   'wu:unblock': 'write',
@@ -241,8 +269,12 @@ const TOOL_PERMISSIONS = {
   'lane:suggest': 'write',
   'flow:bottlenecks': 'read',
   'flow:report': 'read',
-  gates: 'write',
-  'gates:docs': 'write',
+  // WU-2833 (INIT-062 WU-G): gates and gates:docs are read-only validation
+  // runners. Mobile/cloud tokens for these tools must not carry workspace
+  // write access (principle of least privilege; matches the security
+  // posture established by WU-2810/2811/2816).
+  gates: 'read',
+  'gates:docs': 'read',
   'file:delete': 'write',
   'file:edit': 'write',
   'file:read': 'read',
@@ -278,7 +310,11 @@ const TOOL_PERMISSIONS = {
   'lumenflow:release': 'write',
   'lumenflow:upgrade': 'write',
   metrics: 'read',
-  'metrics:snapshot': 'read',
+  // WU-2833 (INIT-062 WU-G): metrics:snapshot reads the workspace and
+  // writes a DORA snapshot back into .lumenflow/state/. Permission role
+  // is "write" because it mutates state; the explicit SCOPE_OVERRIDE
+  // narrows the write path to .lumenflow/state/** (no full-tree write).
+  'metrics:snapshot': 'write',
   'lumenflow:metrics': 'read',
   'signal:cleanup': 'write',
   'sync:templates': 'write',
@@ -320,6 +356,7 @@ const TOOL_ENTRY_OVERRIDES: Partial<Record<ToolName, string>> = {
   'wu:release': WU_RELEASE_TOOL_ENTRY,
   'wu:recover': WU_RECOVER_TOOL_ENTRY,
   'wu:repair': WU_REPAIR_TOOL_ENTRY,
+  'wu:repair:admin': WU_REPAIR_ADMIN_TOOL_ENTRY,
   'wu:infer-lane': WU_INFER_LANE_TOOL_ENTRY,
   gates: GATES_TOOL_ENTRY,
   'gates:docs': GATES_DOCS_TOOL_ENTRY,
@@ -415,9 +452,36 @@ function requiredScopesForPermission(permission: ToolPermission): PathScope[] {
     return createPathScopes([FULL_WORKSPACE_SCOPE_PATTERN], TOOL_SCOPE_ACCESS.READ);
   }
 
+  // WU-2833: admin permission inherits the same constrained write-scope
+  // set as write permission. The admin distinction is carried by the
+  // required_approvals gate, not by broader path access.
   return createPathScopes(SOFTWARE_DELIVERY_WRITE_SCOPE_PATTERNS, TOOL_SCOPE_ACCESS.WRITE);
 }
 
+/**
+ * WU-2833 (INIT-062 WU-G): per-tool scope overrides for tools whose
+ * runtime semantics do not match the default read/write scope set. Used
+ * sparingly — only when a tool legitimately needs both read and a narrow
+ * write scope (or vice versa).
+ */
+const SCOPE_OVERRIDES: Partial<Record<string, PathScope[]>> = {
+  // metrics:snapshot reads the full workspace to compute DORA metrics,
+  // then writes the snapshot back into workspace state. The narrow write
+  // scope prevents mobile/cloud tokens from leaking full-tree write.
+  'metrics:snapshot': [
+    {
+      type: TOOL_SCOPE_TYPES.PATH,
+      pattern: FULL_WORKSPACE_SCOPE_PATTERN,
+      access: TOOL_SCOPE_ACCESS.READ,
+    },
+    {
+      type: TOOL_SCOPE_TYPES.PATH,
+      pattern: SOFTWARE_DELIVERY_WORKSPACE_STATE_WRITE_PATTERN,
+      access: TOOL_SCOPE_ACCESS.WRITE,
+    },
+  ],
+};
+
 /**
  * WU-2729 (INIT-060 Phase 2): the 10 software-delivery pack tools that are
  * callable remotely via POST /tools/:name. The HTTP surface uses this list
@@ -460,17 +524,23 @@ const APPROVAL_OVERRIDES: Partial<Record<ToolName, readonly string[]>> = {
   'plan:promote': [SOFTWARE_DELIVERY_APPROVAL_IDS.REMOTE_MUTATION],
   'initiative:create': [SOFTWARE_DELIVERY_APPROVAL_IDS.REMOTE_MUTATION],
   'initiative:add-wu': [SOFTWARE_DELIVERY_APPROVAL_IDS.REMOTE_MUTATION],
+  // WU-2833: privileged recovery MUST present an explicit approval gate
+  // to conductor/phone UX before dispatch. Without this the admin tool
+  // is indistinguishable from wu:repair from an authorisation standpoint.
+  'wu:repair:admin': [SOFTWARE_DELIVERY_APPROVAL_IDS.REMOTE_MUTATION],
 };
 
 function requiredApprovalsForTool(name: ToolName): string[] | undefined {
-  // WU-2729: only the 10 remote-callable tools carry explicit
+  // WU-2729: the 10 remote-callable tools carry explicit
   // required_approvals metadata (even if empty). Other tools leave the
   // field undefined so the manifest stays minimally descriptive.
+  // WU-2833: admin-permission tools also carry explicit approvals so the
+  // privileged surface cannot be invoked without a visible approval gate.
   const isRemoteCallable = (REMOTE_CALLABLE_TOOLS as readonly string[]).includes(name);
-  if (!isRemoteCallable) {
+  const override = APPROVAL_OVERRIDES[name];
+  if (!isRemoteCallable && override === undefined) {
     return undefined;
   }
-  const override = APPROVAL_OVERRIDES[name];
   return override ? [...override] : [];
 }
 
@@ -487,11 +557,15 @@ function createManifestTools(): SoftwareDeliveryManifestTool[] {
   return (Object.keys(TOOL_PERMISSIONS) as ToolName[]).map((name) => {
     const permission = TOOL_PERMISSIONS[name];
     const approvals = requiredApprovalsForTool(name);
+    // WU-2833: per-tool scope overrides take priority over the default
+    // permission-derived scope set so read-plus-narrow-write tools like
+    // metrics:snapshot can declare both accesses on a single entry.
+    const scopeOverride = SCOPE_OVERRIDES[name];
     const entry: SoftwareDeliveryManifestTool = {
       name,
       entry: resolveToolEntry(name),
       permission,
-      required_scopes: requiredScopesForPermission(permission),
+      required_scopes: scopeOverride ? [...scopeOverride] : requiredScopesForPermission(permission),
     };
     if (approvals !== undefined) {
       entry.required_approvals = approvals;
@@ -543,6 +617,19 @@ const SOFTWARE_DELIVERY_EMITTED_EVENT_KINDS = [
   'software-delivery:plan_created',
   'software-delivery:plan_linked',
   'software-delivery:plan_promoted',
+  // WU-2832 (INIT-062 WU-F): close the cloud-team polling gap with 9
+  // additional ephemeral kinds. Validation pair (validated/invalid),
+  // recovery, preflight, escalation, ratchet, bottleneck, DORA snapshot,
+  // and replay-artifact addressable by event_id.
+  'software-delivery:wu_spec_validated',
+  'software-delivery:wu_spec_invalid',
+  'software-delivery:wu_recovered',
+  'software-delivery:wu_preflight_failed',
+  'software-delivery:wu_escalation_resolved',
+  'software-delivery:test_ratchet_adjusted',
+  'software-delivery:flow_bottleneck_detected',
+  'software-delivery:dora_metric_snapshot',
+  'software-delivery:replay_artifact_published',
 ] as const;
 const SOFTWARE_DELIVERY_REQUIRED_SURFACES = ['http'] as const;
 

package/packs/software-delivery/manifest.yaml

@@ -200,6 +200,15 @@ tools:
     entry: tool-impl/wu-lifecycle-tools.ts#wuRepairTool
     permission: write
     required_scopes: *softwareDeliveryWriteScopes
+  # WU-2833 (INIT-062 WU-G): privileged wu:repair surface for cloud-team
+  # phone UX. Distinct tool name so approval gate + admin permission can
+  # be declared without widening the default wu:repair surface.
+  - name: wu:repair:admin
+    entry: tool-impl/wu-lifecycle-tools.ts#wuRepairAdminTool
+    permission: admin
+    required_scopes: *softwareDeliveryWriteScopes
+    required_approvals:
+      - software-delivery:remote_mutation
   - name: wu:sandbox
     entry: tool-impl/wu-lifecycle-tools.ts#wuSandboxTool
     permission: write
@@ -377,15 +386,26 @@ tools:
         access: read
     required_approvals: []
   # gate:*
+  # WU-2833 (INIT-062 WU-G): gates / gates:docs are read-only validation
+  # runners. Declaring them permission: write would grant mobile/cloud
+  # tokens full-tree write access via required_scopes (the security model
+  # hardened by WU-2810/2811/2816). Re-declare as permission: read and
+  # scope them to SOFTWARE_DELIVERY_READ_SCOPE (wildcard path, read).
   - name: gates
     entry: tool-impl/wu-lifecycle-tools.ts#gatesTool
-    permission: write
-    required_scopes: *softwareDeliveryWriteScopes
+    permission: read
+    required_scopes:
+      - type: path
+        pattern: '**'
+        access: read
     required_approvals: []
   - name: gates:docs
     entry: tool-impl/wu-lifecycle-tools.ts#gatesDocsTool
-    permission: write
-    required_scopes: *softwareDeliveryWriteScopes
+    permission: read
+    required_scopes:
+      - type: path
+        pattern: '**'
+        access: read
     required_approvals: []
   # file:*
   - name: file:delete
@@ -577,13 +597,20 @@ tools:
       - type: path
         pattern: '**'
         access: read
+  # WU-2833 (INIT-062 WU-G): metrics:snapshot reads the workspace and
+  # writes a DORA snapshot to .lumenflow/state/. Declared permission:
+  # write with narrow write scope + full-read scope (principle of least
+  # privilege — no full-tree write).
   - name: metrics:snapshot
     entry: tool-impl/flow-metrics-tools.ts#metricsSnapshotTool
-    permission: read
+    permission: write
     required_scopes:
       - type: path
         pattern: '**'
         access: read
+      - type: path
+        pattern: .lumenflow/state/**
+        access: write
   - name: lumenflow:metrics
     entry: tool-impl/runtime-native-tools.ts#lumenflowMetricsTool
     permission: read
@@ -686,6 +713,16 @@ emitted_event_kinds:
   - software-delivery:plan_created
   - software-delivery:plan_linked
   - software-delivery:plan_promoted
+  # WU-2832 (INIT-062 WU-F): close the cloud-team polling gap.
+  - software-delivery:wu_spec_validated
+  - software-delivery:wu_spec_invalid
+  - software-delivery:wu_recovered
+  - software-delivery:wu_preflight_failed
+  - software-delivery:wu_escalation_resolved
+  - software-delivery:test_ratchet_adjusted
+  - software-delivery:flow_bottleneck_detected
+  - software-delivery:dora_metric_snapshot
+  - software-delivery:replay_artifact_published
 subscribed_event_kinds: []
 required_approvals: []
 surfaces_required:

package/packs/software-delivery/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/packs-software-delivery",
-  "version": "5.0.3",
+  "version": "5.2.0",
   "description": "Software delivery pack for LumenFlow — work units, gates, lanes, initiatives, and agent coordination",
   "keywords": [
     "lumenflow",

package/packs/software-delivery/src/config/schemas/lumenflow-config-schema-types.ts

@@ -29,6 +29,11 @@ import {
   DEFAULT_MAX_ESLINT_WARNINGS,
   DEFAULT_MIN_COVERAGE,
 } from '../../constants/gate-constants.js';
+import {
+  AGENT_NAMES,
+  MANDATORY_AGENT_NAMES,
+  MANDATORY_TRIGGERS,
+} from '../../domain/orchestration.constants.js';
 
 const DEFAULT_LAYOUT = DOCS_LAYOUT_PRESETS.simple;
 
@@ -76,7 +81,7 @@ export const DIRECTORIES_DEFAULTS: DirectoriesConfig = {
   initiativesDir: `${DEFAULT_LAYOUT.tasks}/initiatives`,
   backlogPath: `${DEFAULT_LAYOUT.tasks}/backlog.md`,
   statusPath: `${DEFAULT_LAYOUT.tasks}/status.md`,
-  skillsDir: '.claude/skills',
+  skillsDir: '.lumenflow/skills',
   agentsDir: '.claude/agents',
   adrDir: DEFAULT_LAYOUT.adrDir,
   plansDir: `${DEFAULT_LAYOUT.operations}/plans`,
@@ -342,16 +347,35 @@ export const MEMORY_DEFAULTS: MemoryConfig = {
 };
 
 // ---------------------------------------------------------------------------
-// Agents (narrow — only defaultClient, which many cohorts need)
+// Agents
 // ---------------------------------------------------------------------------
 
+export interface MandatoryAgentsConfig {
+  names: string[];
+  triggers: Record<string, string[]>;
+  [extra: string]: unknown;
+}
+
 export interface AgentsConfig {
   defaultClient: string;
+  roster: string[];
+  mandatory: MandatoryAgentsConfig;
   [extra: string]: unknown;
 }
 
+function cloneMandatoryTriggersDefaults(): Record<string, string[]> {
+  return Object.fromEntries(
+    Object.entries(MANDATORY_TRIGGERS).map(([agentName, patterns]) => [agentName, [...patterns]]),
+  );
+}
+
 export const AGENTS_DEFAULTS: AgentsConfig = {
   defaultClient: LUMENFLOW_CLIENT_IDS.CLAUDE_CODE,
+  roster: [...AGENT_NAMES],
+  mandatory: {
+    names: [...MANDATORY_AGENT_NAMES],
+    triggers: cloneMandatoryTriggersDefaults(),
+  },
 };
 
 // ---------------------------------------------------------------------------

package/packs/software-delivery/src/config/workspace-reader.ts

@@ -172,6 +172,30 @@ function mergeSimple<T>(defaults: T, overrides: unknown): T {
   return { ...defaults };
 }
 
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+
+function cloneStringArrayRecord(record: Record<string, string[]>): Record<string, string[]> {
+  return Object.fromEntries(Object.entries(record).map(([key, values]) => [key, [...values]]));
+}
+
+function readStringArrayRecord(value: unknown): Record<string, string[]> {
+  if (!isObjectRecord(value)) {
+    return {};
+  }
+
+  return Object.fromEntries(
+    Object.entries(value).flatMap(([key, entryValue]) =>
+      isStringArray(entryValue) ? [[key, [...entryValue]]] : [],
+    ),
+  );
+}
+
 function mergeTelemetry(overrides: Partial<TelemetryConfig> | undefined): TelemetryConfig {
   if (!overrides) {
     return { methodology: { ...TELEMETRY_DEFAULTS.methodology } };
@@ -189,6 +213,47 @@ function pickEnum<T extends string>(value: unknown, allowed: readonly T[], fallb
     : fallback;
 }
 
+function cloneAgentsDefaults(): AgentsConfig {
+  return {
+    ...AGENTS_DEFAULTS,
+    roster: [...AGENTS_DEFAULTS.roster],
+    mandatory: {
+      ...AGENTS_DEFAULTS.mandatory,
+      names: [...AGENTS_DEFAULTS.mandatory.names],
+      triggers: cloneStringArrayRecord(AGENTS_DEFAULTS.mandatory.triggers),
+    },
+  };
+}
+
+function mergeAgents(overrides: unknown): AgentsConfig {
+  if (!isObjectRecord(overrides)) {
+    return cloneAgentsDefaults();
+  }
+
+  const defaults = cloneAgentsDefaults();
+  const { defaultClient, roster, mandatory: overrideMandatory, ...flatOverrides } = overrides;
+  const mandatoryOverrides = isObjectRecord(overrideMandatory) ? overrideMandatory : {};
+
+  return {
+    ...defaults,
+    ...flatOverrides,
+    defaultClient:
+      typeof defaultClient === 'string' ? defaultClient : AGENTS_DEFAULTS.defaultClient,
+    roster: isStringArray(roster) ? [...roster] : [...AGENTS_DEFAULTS.roster],
+    mandatory: {
+      ...defaults.mandatory,
+      ...mandatoryOverrides,
+      names: isStringArray(mandatoryOverrides['names'])
+        ? [...mandatoryOverrides['names']]
+        : [...AGENTS_DEFAULTS.mandatory.names],
+      triggers: {
+        ...cloneStringArrayRecord(AGENTS_DEFAULTS.mandatory.triggers),
+        ...readStringArrayRecord(mandatoryOverrides['triggers']),
+      },
+    },
+  };
+}
+
 /**
  * Return the fully-typed pack-local `LumenflowConfig` for the workspace rooted
  * at `cwd`.
@@ -230,7 +295,7 @@ export function getConfig(cwd: string): LumenflowConfig {
     memory: mergeSimple<MemoryConfig>(MEMORY_DEFAULTS, section['memory']),
     ui: mergeSimple<UiConfig>(UI_DEFAULTS, section['ui']),
     yaml: mergeSimple<YamlConfig>(YAML_DEFAULTS, section['yaml']),
-    agents: mergeSimple<AgentsConfig>(AGENTS_DEFAULTS, section['agents']),
+    agents: mergeAgents(section['agents']),
     experimental: mergeSimple<ExperimentalConfig>(EXPERIMENTAL_DEFAULTS, section['experimental']),
     cleanup: mergeSimple<CleanupConfig>(CLEANUP_DEFAULTS, section['cleanup']),
     telemetry: mergeTelemetry(section['telemetry'] as Partial<TelemetryConfig> | undefined),
@@ -275,7 +340,7 @@ function cloneDefaults(): LumenflowConfig {
     memory: { ...MEMORY_DEFAULTS },
     ui: { ...UI_DEFAULTS },
     yaml: { ...YAML_DEFAULTS },
-    agents: { ...AGENTS_DEFAULTS },
+    agents: cloneAgentsDefaults(),
     experimental: { ...EXPERIMENTAL_DEFAULTS },
     cleanup: { ...CLEANUP_DEFAULTS },
     telemetry: { methodology: { ...TELEMETRY_DEFAULTS.methodology } },

package/packs/software-delivery/src/constants/wu-paths-constants.ts

@@ -82,6 +82,32 @@ export const DIRECTORIES = {
   STATUS_PATH: `${DEFAULT_DOCS_PATHS.tasks}/status.md`,
 };
 
+/**
+ * Shared agent/client surface paths.
+ *
+ * Keeps vendor overlay and shared projection roots centralized so runtime code
+ * does not scatter hardcoded path literals through CLI/core packages.
+ */
+export const AGENT_SURFACES = {
+  /** Claude-projected skills directory */
+  CLAUDE_SKILLS_DIR: '.claude/skills',
+
+  /** Claude agent overlay directory */
+  CLAUDE_AGENTS_DIR: '.claude/agents',
+
+  /** Shared cross-vendor projected skills directory */
+  SHARED_SKILLS_DIR: '.agents/skills',
+
+  /** Codex agent overlay directory */
+  CODEX_AGENTS_DIR: '.codex/agents',
+
+  /** Gemini projected skills directory */
+  GEMINI_SKILLS_DIR: '.gemini/skills',
+
+  /** Gemini agent overlay directory */
+  GEMINI_AGENTS_DIR: '.gemini/agents',
+};
+
 /**
  * Build artifact cleanup globs
  *