crewly 1.11.6 → 1.12.1

package/dist/backend/backend/src/services/orchestrator/onboarding/materialize-team.d.ts

@@ -1,108 +1,129 @@
 /**
- * Materialize-Team Logic (Onboarding v3, v0)
+ * Materialize-Team Logic (Onboarding v3)
  *
- * v0 stub: writes a minimal team `config.json` under `<teamsDir>/<id>/`
- * and flips a project `onboardingComplete` flag. Real provisioning
- * (template-engine wiring, agent-soul generation, system-prompt
- * personalisation) lands Wed–Fri — Sam's brief explicitly says a
- * "logs + flips flag" stub is acceptable for the Mon 5/4 EOD demo.
+ * Turns a confirmed {@link TeamRecommendation} into a REAL, persisted team
+ * that the rest of the system can run hands-off:
  *
- * The function is async + injection-friendly: callers pass a
- * `teamsDir`, a `projectFlagPath`, a UUID generator, and a clock — so
- * tests exercise the real write path with tmp dirs and deterministic
- * IDs.
+ *   1. Provision a live, template-backed team via the proven
+ *      `TemplateService.createTeamFromTemplate` + `StorageService.saveTeam`
+ *      path — the same path `onboarding-provision.service.ts` uses. The
+ *      created members carry real system prompts, skill sets, hierarchy
+ *      (`hierarchyLevel` / `parentMemberId`) and `canDelegate` flags from the
+ *      template, so the orchestrator can immediately delegate into the team
+ *      and the agents auto-activate on first claim.
+ *   2. Flip the project `onboardingComplete` flag.
  *
- * Wired downstream: when this module is upgraded post-Mon, swap the
- * inline write for a delegation to
- * `backend/src/services/onboarding/onboarding-provision.service.ts`
- * (it already provisions teams via TemplateService — see that file's
- * `provisionFromOnboarding`).
+ * Fallback: if the recommendation's `templateId` is not a registered template
+ * (or provisioning throws — e.g. a tier-gated template on OSS), we write the
+ * legacy minimal `config.json` stub so the orc never dead-ends. That stub has
+ * inactive members with empty prompts and is clearly marked `provisioned:false`
+ * so callers can warn the user that a generic team was created.
+ *
+ * History: this was a "Mon EOD v0 stub" that only wrote a dead config and
+ * flipped a flag (members `agentStatus:'inactive'`, empty `systemPrompt`),
+ * which meant every new-team goal required a human to actually stand up
+ * agents. P0 of the autonomy roadmap wires it to real provisioning.
+ *
+ * The function stays injection-friendly: callers pass `teamsDir`,
+ * `projectFlagPath`, a UUID generator, a clock, and (for tests) a
+ * `provisionTeam` implementation — so unit tests run against tmp dirs with
+ * deterministic IDs and a fake provisioner, never touching the real
+ * `~/.crewly` tree or the singletons.
  *
  * @module services/orchestrator/onboarding/materialize-team
  */
 import type { TeamRecommendation } from './recommend-team.js';
+/** A live team produced by {@link MaterializeOptions.provisionTeam}. */
+export interface ProvisionedTeam {
+    /** Persisted team id (from StorageService). */
+    readonly teamId: string;
+    /** Number of members created from the template. */
+    readonly memberCount: number;
+}
 /**
  * Side-effects the materialize step needs. Injected so tests can run
- * against a tmp dir without touching the real `~/.crewly` tree.
+ * against a tmp dir + a fake provisioner without touching the real
+ * `~/.crewly` tree or the TemplateService/StorageService singletons.
  */
 export interface MaterializeOptions {
-    /** Root teams directory (e.g. `~/.crewly/teams`). */
+    /** Root teams directory for the FALLBACK stub write (e.g. `~/.crewly/teams`). */
     readonly teamsDir: string;
     /** File path for the project onboarding-complete flag. */
     readonly projectFlagPath: string;
-    /** UUID generator — defaults to {@link crypto.randomUUID} when omitted. */
+    /** UUID generator (fallback stub only) — defaults to {@link crypto.randomUUID}. */
     readonly uuid?: () => string;
     /** Clock — defaults to `() => new Date()` when omitted. */
     readonly now?: () => Date;
+    /** Optional logger sink — receives the materialize log lines. */
+    readonly log?: (message: string) => void;
+    /** Owner principal to attribute the created team to (multi-tenant). */
+    readonly ownerUserId?: string;
     /**
-     * Optional logger sink. When provided, the function writes the
-     * Mon-EOD-stub log lines through it (so tests can assert).
+     * Parent team id, set when this team is a CHILD in a nested hierarchy (P3).
+     * Links the created team to its parent so the parent TL coordinates it.
+     * Undefined for a standalone or top-level team.
      */
-    readonly log?: (message: string) => void;
+    readonly parentTeamId?: string;
+    /**
+     * Team provisioner. Defaults to {@link defaultProvisionTeam}, which creates
+     * a live, persisted, template-backed team. Returns `null` when the
+     * recommendation's `templateId` is not a registered template, signalling the
+     * caller to fall back to a minimal stub. Tests inject a fake.
+     */
+    readonly provisionTeam?: (recommendation: TeamRecommendation, teamName: string, ownerUserId: string | undefined, parentTeamId: string | undefined) => Promise<ProvisionedTeam | null>;
 }
 /**
  * Outcome of a successful materialize call.
  */
 export interface MaterializeResult {
-    /** Newly-generated team ID (UUID). */
+    /** Team ID — the persisted team id (live path) or the generated id (fallback). */
     readonly teamId: string;
-    /** Absolute path to the team's `config.json`. */
-    readonly teamConfigPath: string;
     /**
-     * Always `true` for a successful call — mirrors the brief's spec:
-     * "flips `onboardingComplete = true`".
+     * Absolute path to the team's fallback `config.json`. Empty string on the
+     * live path (the team is persisted via StorageService, not a flat file).
      */
+    readonly teamConfigPath: string;
+    /** Always `true` for a successful call — mirrors "flips `onboardingComplete = true`". */
     readonly onboardingComplete: true;
-    /** Echo of the recommendation that was materialized (for orc to summarise back to the user). */
+    /** Echo of the recommendation that was materialized (for the orc to summarise back). */
     readonly recommendation: TeamRecommendation;
+    /** Where the project flag was persisted. */
+    readonly projectFlagPath: string;
+    /** Number of members on the created team. */
+    readonly memberCount: number;
     /**
-     * Where the project flag was persisted. The flag is a tiny JSON file
-     * (`{ onboardingComplete: true, completedAt }`).
+     * `true` when a live, template-backed team was provisioned (real agents,
+     * prompts, hierarchy). `false` when provisioning was unavailable and a
+     * minimal stub config was written instead — the orc should tell the user a
+     * generic team was created and offer to refine it.
      */
-    readonly projectFlagPath: string;
+    readonly provisioned: boolean;
 }
 /**
- * Materialize a {@link TeamRecommendation} into a team config file +
- * project onboarding-complete flag.
- *
- * v0 (Mon 5/4 EOD) writes a minimal config:
- * ```json
- * {
- *   "id":   "<uuid>",
- *   "name": "<recommendation.templateId> Team",
- *   "createdAt": "...",
- *   "createdBy": "onboarding-v3",
- *   "templateId": "...",
- *   "members": [ ... ]
- * }
- * ```
- * No agent-soul personalisation, no project linkage, no goals.md
- * generation — those land Wed–Fri when this calls into
- * `onboarding-provision.service.ts`.
+ * Materialize a {@link TeamRecommendation} into a REAL team + project
+ * onboarding-complete flag.
  *
  * @param recommendation - Output of {@link recommendTeam} that the user confirmed.
- * @param opts - Side-effect injection (teamsDir, projectFlagPath, etc.).
- * @returns The team ID + config path + flag-path on success.
- * @throws If the team config write fails (filesystem error). Caller is
- *         expected to surface a brief, honest error to the user
- *         ("I couldn't create the team — error: …") rather than retry
- *         silently.
+ * @param opts - Side-effect injection (teamsDir, projectFlagPath, provisionTeam, …).
+ * @returns The team ID + member count + provisioned flag + flag-path on success.
+ * @throws If BOTH provisioning fails AND the fallback config write fails
+ *         (filesystem error). Caller surfaces a brief honest error rather than
+ *         retrying silently.
  *
  * @example
  * ```ts
  * import { getCrewlyHomePath } from '../../core/crewly-home.utils.js';
  *
- * const crewlyHome = getCrewlyHomePath(); // honours CREWLY_HOME env override
+ * const crewlyHome = getCrewlyHomePath();
  * const result = await materializeTeam(rec, {
  *   teamsDir: path.join(crewlyHome, 'teams'),
  *   projectFlagPath: path.join(crewlyHome, 'onboarding-complete.json'),
  * });
- * console.log(result.teamId, '→', result.teamConfigPath);
+ * // result.provisioned === true → live team `result.teamId` with `result.memberCount` agents
  * ```
  *
- * Do NOT inline `path.join(os.homedir(), '.crewly/teams')` — that
- * ignores CREWLY_HOME and breaks ESTestNode + dry-run-kit isolation
- * (see crewly-home.utils.ts for context).
+ * Do NOT inline `path.join(os.homedir(), '.crewly/teams')` — that ignores
+ * CREWLY_HOME and breaks ESTestNode + dry-run-kit isolation.
  */
 export declare function materializeTeam(recommendation: TeamRecommendation, opts: MaterializeOptions): Promise<MaterializeResult>;
 //# sourceMappingURL=materialize-team.d.ts.map

package/dist/backend/backend/src/services/orchestrator/onboarding/materialize-team.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"materialize-team.d.ts","sourceRoot":"","sources":["../../../../../../../backend/src/services/orchestrator/onboarding/materialize-team.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAM9D;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,MAAM,CAAC;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,EAAE,IAAI,CAAC;IAClC,gGAAgG;IAChG,QAAQ,CAAC,cAAc,EAAE,kBAAkB,CAAC;IAC5C;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAsB,eAAe,CACnC,cAAc,EAAE,kBAAkB,EAClC,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,iBAAiB,CAAC,CAqC5B"}
+{"version":3,"file":"materialize-team.d.ts","sourceRoot":"","sources":["../../../../../../../backend/src/services/orchestrator/onboarding/materialize-team.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAM9D,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,mFAAmF;IACnF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,MAAM,CAAC;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,uEAAuE;IACvE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,CACvB,cAAc,EAAE,kBAAkB,EAClC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,YAAY,EAAE,MAAM,GAAG,SAAS,KAC7B,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,yFAAyF;IACzF,QAAQ,CAAC,kBAAkB,EAAE,IAAI,CAAC;IAClC,wFAAwF;IACxF,QAAQ,CAAC,cAAc,EAAE,kBAAkB,CAAC;IAC5C,4CAA4C;IAC5C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,6CAA6C;IAC7C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,eAAe,CACnC,cAAc,EAAE,kBAAkB,EAClC,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,iBAAiB,CAAC,CAsE5B"}

package/dist/backend/backend/src/services/orchestrator/onboarding/materialize-team.js

@@ -1,22 +1,34 @@
 /**
- * Materialize-Team Logic (Onboarding v3, v0)
+ * Materialize-Team Logic (Onboarding v3)
  *
- * v0 stub: writes a minimal team `config.json` under `<teamsDir>/<id>/`
- * and flips a project `onboardingComplete` flag. Real provisioning
- * (template-engine wiring, agent-soul generation, system-prompt
- * personalisation) lands Wed–Fri — Sam's brief explicitly says a
- * "logs + flips flag" stub is acceptable for the Mon 5/4 EOD demo.
+ * Turns a confirmed {@link TeamRecommendation} into a REAL, persisted team
+ * that the rest of the system can run hands-off:
  *
- * The function is async + injection-friendly: callers pass a
- * `teamsDir`, a `projectFlagPath`, a UUID generator, and a clock — so
- * tests exercise the real write path with tmp dirs and deterministic
- * IDs.
+ *   1. Provision a live, template-backed team via the proven
+ *      `TemplateService.createTeamFromTemplate` + `StorageService.saveTeam`
+ *      path — the same path `onboarding-provision.service.ts` uses. The
+ *      created members carry real system prompts, skill sets, hierarchy
+ *      (`hierarchyLevel` / `parentMemberId`) and `canDelegate` flags from the
+ *      template, so the orchestrator can immediately delegate into the team
+ *      and the agents auto-activate on first claim.
+ *   2. Flip the project `onboardingComplete` flag.
  *
- * Wired downstream: when this module is upgraded post-Mon, swap the
- * inline write for a delegation to
- * `backend/src/services/onboarding/onboarding-provision.service.ts`
- * (it already provisions teams via TemplateService — see that file's
- * `provisionFromOnboarding`).
+ * Fallback: if the recommendation's `templateId` is not a registered template
+ * (or provisioning throws — e.g. a tier-gated template on OSS), we write the
+ * legacy minimal `config.json` stub so the orc never dead-ends. That stub has
+ * inactive members with empty prompts and is clearly marked `provisioned:false`
+ * so callers can warn the user that a generic team was created.
+ *
+ * History: this was a "Mon EOD v0 stub" that only wrote a dead config and
+ * flipped a flag (members `agentStatus:'inactive'`, empty `systemPrompt`),
+ * which meant every new-team goal required a human to actually stand up
+ * agents. P0 of the autonomy roadmap wires it to real provisioning.
+ *
+ * The function stays injection-friendly: callers pass `teamsDir`,
+ * `projectFlagPath`, a UUID generator, a clock, and (for tests) a
+ * `provisionTeam` implementation — so unit tests run against tmp dirs with
+ * deterministic IDs and a fake provisioner, never touching the real
+ * `~/.crewly` tree or the singletons.
  *
  * @module services/orchestrator/onboarding/materialize-team
  */
@@ -26,63 +38,76 @@ import * as path from 'node:path';
 // Public API
 // =============================================================================
 /**
- * Materialize a {@link TeamRecommendation} into a team config file +
- * project onboarding-complete flag.
- *
- * v0 (Mon 5/4 EOD) writes a minimal config:
- * ```json
- * {
- *   "id":   "<uuid>",
- *   "name": "<recommendation.templateId> Team",
- *   "createdAt": "...",
- *   "createdBy": "onboarding-v3",
- *   "templateId": "...",
- *   "members": [ ... ]
- * }
- * ```
- * No agent-soul personalisation, no project linkage, no goals.md
- * generation — those land Wed–Fri when this calls into
- * `onboarding-provision.service.ts`.
+ * Materialize a {@link TeamRecommendation} into a REAL team + project
+ * onboarding-complete flag.
  *
  * @param recommendation - Output of {@link recommendTeam} that the user confirmed.
- * @param opts - Side-effect injection (teamsDir, projectFlagPath, etc.).
- * @returns The team ID + config path + flag-path on success.
- * @throws If the team config write fails (filesystem error). Caller is
- *         expected to surface a brief, honest error to the user
- *         ("I couldn't create the team — error: …") rather than retry
- *         silently.
+ * @param opts - Side-effect injection (teamsDir, projectFlagPath, provisionTeam, …).
+ * @returns The team ID + member count + provisioned flag + flag-path on success.
+ * @throws If BOTH provisioning fails AND the fallback config write fails
+ *         (filesystem error). Caller surfaces a brief honest error rather than
+ *         retrying silently.
  *
  * @example
  * ```ts
  * import { getCrewlyHomePath } from '../../core/crewly-home.utils.js';
  *
- * const crewlyHome = getCrewlyHomePath(); // honours CREWLY_HOME env override
+ * const crewlyHome = getCrewlyHomePath();
  * const result = await materializeTeam(rec, {
  *   teamsDir: path.join(crewlyHome, 'teams'),
  *   projectFlagPath: path.join(crewlyHome, 'onboarding-complete.json'),
  * });
- * console.log(result.teamId, '→', result.teamConfigPath);
+ * // result.provisioned === true → live team `result.teamId` with `result.memberCount` agents
  * ```
  *
- * Do NOT inline `path.join(os.homedir(), '.crewly/teams')` — that
- * ignores CREWLY_HOME and breaks ESTestNode + dry-run-kit isolation
- * (see crewly-home.utils.ts for context).
+ * Do NOT inline `path.join(os.homedir(), '.crewly/teams')` — that ignores
+ * CREWLY_HOME and breaks ESTestNode + dry-run-kit isolation.
  */
 export async function materializeTeam(recommendation, opts) {
-    const uuid = opts.uuid ?? defaultUuid;
     const now = opts.now ?? defaultNow;
     const log = opts.log ?? noopLog;
-    const teamId = uuid();
-    const teamDir = path.join(opts.teamsDir, teamId);
-    const teamConfigPath = path.join(teamDir, 'config.json');
+    const provisionTeam = opts.provisionTeam ?? defaultProvisionTeam;
     const createdAt = now().toISOString();
-    log(`[materialize-team] would materialize team for template "${recommendation.templateId}" with ${recommendation.agents.length} agents (id=${teamId})`);
-    // 1. Write the team config.
-    const config = buildTeamConfig(recommendation, teamId, createdAt);
-    await fs.mkdir(teamDir, { recursive: true });
-    await fs.writeFile(teamConfigPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+    const teamName = humanizeTemplateName(recommendation.templateId);
+    log(`[materialize-team] materializing template "${recommendation.templateId}" (${recommendation.agents.length} recommended agents)`);
+    // 1. Provision a live, persisted, template-backed team when possible.
+    let teamId;
+    let memberCount;
+    let teamConfigPath = '';
+    let provisioned;
+    let live = null;
+    try {
+        live = await provisionTeam(recommendation, teamName, opts.ownerUserId, opts.parentTeamId);
+    }
+    catch (err) {
+        // Tier-gated template, missing registry, or storage error — don't dead-end
+        // the orc; drop to the minimal fallback with a warning.
+        log(`[materialize-team] WARN live provisioning failed for template "${recommendation.templateId}" ` +
+            `(${err instanceof Error ? err.message : String(err)}) — falling back to a minimal team`);
+    }
+    if (live) {
+        teamId = live.teamId;
+        memberCount = live.memberCount;
+        provisioned = true;
+        log(`[materialize-team] provisioned LIVE team id=${teamId} (${memberCount} members) from template "${recommendation.templateId}"`);
+    }
+    else {
+        // Fallback: template not registered / provisioning unavailable. Write a
+        // minimal stub config so the orc still has a team to talk about.
+        const uuid = opts.uuid ?? defaultUuid;
+        teamId = uuid();
+        const teamDir = path.join(opts.teamsDir, teamId);
+        teamConfigPath = path.join(teamDir, 'config.json');
+        const config = buildTeamConfig(recommendation, teamId, createdAt);
+        memberCount = recommendation.agents.length;
+        provisioned = false;
+        await fs.mkdir(teamDir, { recursive: true });
+        await fs.writeFile(teamConfigPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+        log(`[materialize-team] wrote MINIMAL fallback config id=${teamId} ` +
+            `(template "${recommendation.templateId}" not provisionable)`);
+    }
     // 2. Flip the project onboarding-complete flag.
-    const flag = { onboardingComplete: true, completedAt: createdAt };
+    const flag = { onboardingComplete: true, completedAt: createdAt, teamId };
     await fs.mkdir(path.dirname(opts.projectFlagPath), { recursive: true });
     await fs.writeFile(opts.projectFlagPath, JSON.stringify(flag, null, 2) + '\n', 'utf8');
     log(`[materialize-team] flipped onboardingComplete = true at ${opts.projectFlagPath}`);
@@ -92,14 +117,54 @@ export async function materializeTeam(recommendation, opts) {
         onboardingComplete: true,
         recommendation,
         projectFlagPath: opts.projectFlagPath,
+        memberCount,
+        provisioned,
     };
 }
 // =============================================================================
 // Internals
 // =============================================================================
 /**
- * Build the minimal v0 team config. Members are derived 1:1 from the
- * recommendation's agents list.
+ * Default team provisioner: create a live, persisted team from the
+ * recommendation's template via the same path `onboarding-provision.service.ts`
+ * uses. Lazy-imports the singletons so this module stays dependency-light and
+ * unit-testable (callers inject a fake `provisionTeam` instead).
+ *
+ * @param recommendation - The confirmed recommendation (carries `templateId`).
+ * @param teamName - Human-readable team name to assign.
+ * @param ownerUserId - Owner principal, or undefined for OSS single-user mode.
+ * @returns The persisted team id + member count, or `null` when the template
+ *          is not registered (caller falls back to a minimal stub).
+ * @throws Propagates a tier-gating error from `createTeamFromTemplate` (the
+ *         caller catches it and falls back).
+ */
+async function defaultProvisionTeam(recommendation, teamName, ownerUserId, parentTeamId) {
+    const { TemplateService } = await import('../../template/template.service.js');
+    const { StorageService } = await import('../../core/storage.service.js');
+    const result = TemplateService.getInstance().createTeamFromTemplate(recommendation.templateId, teamName);
+    if (!result)
+        return null;
+    // Attribute to the authenticated principal (multi-tenant). Undefined in OSS
+    // single-user mode leaves the team unscoped (legacy behaviour).
+    if (ownerUserId !== undefined) {
+        result.team.ownerUserId = ownerUserId;
+    }
+    // Link to the parent team when this is a child in a nested hierarchy (P3).
+    if (parentTeamId !== undefined) {
+        result.team.parentTeamId = parentTeamId;
+    }
+    await StorageService.getInstance().saveTeam(result.team);
+    return { teamId: result.team.id, memberCount: result.memberCount };
+}
+/**
+ * Build the minimal FALLBACK team config. Members are derived 1:1 from the
+ * recommendation's agents list, inactive with empty prompts. Only used when
+ * live provisioning is unavailable.
+ *
+ * @param rec - The recommendation to materialize.
+ * @param teamId - The generated team id.
+ * @param createdAt - ISO creation timestamp.
+ * @returns A plain config object ready to JSON-serialize.
  */
 function buildTeamConfig(rec, teamId, createdAt) {
     return {
@@ -124,10 +189,10 @@ function buildTeamConfig(rec, teamId, createdAt) {
 }
 /**
  * Convert a kebab-case template id → human team name
- * (`"dtc-viral-content-team"` → `"Dtc Viral Content Team"`). The full
- * personalisation pass happens post-Mon when we wire into
- * `onboarding-provision.service.ts` — that service already builds
- * proper names.
+ * (`"dtc-viral-content-team"` → `"Dtc Viral Content Team"`).
+ *
+ * @param templateId - The kebab-case template id.
+ * @returns A title-cased, space-separated name.
  */
 function humanizeTemplateName(templateId) {
     return templateId
@@ -137,6 +202,9 @@ function humanizeTemplateName(templateId) {
 }
 /**
  * Convert a kebab-case role → human display name.
+ *
+ * @param role - The kebab-case role id.
+ * @returns A title-cased, space-separated name.
  */
 function humanizeRoleName(role) {
     return role
@@ -145,20 +213,27 @@ function humanizeRoleName(role) {
         .join(' ');
 }
 /**
- * Default UUID generator. Uses Node's `crypto.randomUUID` so we don't
- * pull in a dep, and so the output is deterministic-shaped.
+ * Default UUID generator (fallback stub only).
+ *
+ * @returns A random UUID string.
  */
 function defaultUuid() {
-    // Lazy require to keep the import surface minimal and avoid loading
-    // `node:crypto` at module load.
     const { randomUUID } = require('node:crypto');
     return randomUUID();
 }
-/** Default clock — wall-clock time. */
+/**
+ * Default clock — wall-clock time.
+ *
+ * @returns The current Date.
+ */
 function defaultNow() {
     return new Date();
 }
-/** Default log sink — drops the message on the floor. */
+/**
+ * Default log sink — drops the message on the floor.
+ *
+ * @param _message - Ignored.
+ */
 function noopLog(_message) {
     /* intentional no-op */
 }

package/dist/backend/backend/src/services/orchestrator/onboarding/materialize-team.js.map

@@ -1 +1 @@
-{"version":3,"file":"materialize-team.js","sourceRoot":"","sources":["../../../../../../../backend/src/services/orchestrator/onboarding/materialize-team.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"materialize-team.js","sourceRoot":"","sources":["../../../../../../../backend/src/services/orchestrator/onboarding/materialize-team.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/services/orchestrator/onboarding/synthesize-hierarchy.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Nested sub-team synthesis (Autonomy roadmap P3).
+ *
+ * When a goal needs PARALLEL work-streams (e.g. "build a SaaS with a frontend,
+ * a backend, and DevOps"), a single flat team is the wrong shape — you want a
+ * top coordination team whose lead (TL) delegates to per-stream CHILD teams,
+ * each with its own TL who decomposes + verifies its slice and reports up.
+ * The data model already supports this (`Team.parentTeamId`,
+ * `TeamMember.parentMemberId`/`hierarchyLevel`) but nothing DECIDED the shape
+ * or instantiated it — complex goals had to be wired by hand.
+ *
+ * This module adds that decision + instantiation:
+ *   1. {@link detectStreams} — heuristically find the parallel streams in a goal.
+ *   2. {@link synthesizeHierarchyPlan} — turn them into a parent + child-team
+ *      plan (or a single flat team when <2 streams), capped by a branching
+ *      limit aligned with fission-guard's `maxBranchingFactor`.
+ *   3. {@link materializeHierarchy} — instantiate the parent then each child via
+ *      the P0 {@link materializeTeam} path, linking children to the parent.
+ *
+ * The stream detection is heuristic (v1) — same spirit as the hardcoded
+ * `recommendTeam` mappings; a semantic/LLM planner is a later upgrade. The
+ * STRUCTURE (parent + linked children, real provisioning) is the deliverable.
+ *
+ * @module services/orchestrator/onboarding/synthesize-hierarchy
+ */
+import { type BusinessContext, type TeamRecommendation } from './recommend-team.js';
+import { type MaterializeOptions } from './materialize-team.js';
+/**
+ * Default cap on child teams in a single hierarchy. Aligned with fission-guard's
+ * `maxBranchingFactor` so the synthesized shape never exceeds the runtime's
+ * fan-out guardrail.
+ */
+export declare const DEFAULT_MAX_SUBTEAMS = 5;
+/**
+ * Detect the parallel work-streams named in a goal context.
+ *
+ * @param ctx - The business context (goal/industry + tasks).
+ * @returns Stream keys (e.g. `['frontend','backend','infra']`) in canonical order.
+ */
+export declare function detectStreams(ctx: BusinessContext): string[];
+/** One child team in a synthesized hierarchy. */
+export interface HierarchyNode {
+    /** The stream this child team owns (e.g. `frontend`). */
+    readonly stream: string;
+    /** The team recommendation for this child. */
+    readonly recommendation: TeamRecommendation;
+}
+/** A synthesized team hierarchy: a parent coordination team + child teams. */
+export interface HierarchyPlan {
+    /** Top coordination team (its TL delegates to + accepts from the children). */
+    readonly parent: TeamRecommendation;
+    /** Per-stream child teams. Empty → a single flat team is sufficient. */
+    readonly children: readonly HierarchyNode[];
+    /** Human-readable rationale for the shape. */
+    readonly rationale: string;
+}
+/** Options for {@link synthesizeHierarchyPlan}. */
+export interface SynthesizeOptions {
+    /** Max child teams (default {@link DEFAULT_MAX_SUBTEAMS}). */
+    readonly maxSubteams?: number;
+}
+/**
+ * Synthesize a (possibly nested) team plan for a goal.
+ *
+ * If fewer than 2 parallel streams are detected, returns a single flat team
+ * (no children) — nesting would be overhead. Otherwise returns a parent
+ * coordination team plus one child team per detected stream, capped at
+ * `maxSubteams`.
+ *
+ * @param ctx - The goal/business context.
+ * @param opts - Synthesis options (branching cap).
+ * @returns The hierarchy plan.
+ *
+ * @example
+ * ```ts
+ * const plan = synthesizeHierarchyPlan({
+ *   industry: 'build a SaaS with a React frontend, a Node API backend, and DevOps',
+ *   scale: 'small-team',
+ *   tasks: [],
+ * });
+ * // plan.children → frontend / backend / infra child teams under a parent
+ * ```
+ */
+export declare function synthesizeHierarchyPlan(ctx: BusinessContext, opts?: SynthesizeOptions): HierarchyPlan;
+/** A child team that was instantiated as part of a hierarchy. */
+export interface MaterializedChild {
+    readonly stream: string;
+    readonly teamId: string;
+    readonly memberCount: number;
+    readonly parentTeamId: string;
+    readonly provisioned: boolean;
+}
+/** Result of {@link materializeHierarchy}. */
+export interface MaterializedHierarchy {
+    readonly parentTeamId: string;
+    readonly parentMemberCount: number;
+    readonly parentProvisioned: boolean;
+    readonly children: readonly MaterializedChild[];
+}
+/**
+ * Instantiate a {@link HierarchyPlan}: materialize the parent team, then each
+ * child team linked to the parent via `parentTeamId`. Reuses the P0
+ * {@link materializeTeam} path (real, persisted, template-backed teams).
+ *
+ * The same `opts` (teamsDir, projectFlagPath, ownerUserId, provisionTeam, …)
+ * is used for every team; the per-child `parentTeamId` is injected by this
+ * function. When the plan has no children, only the parent is created (this is
+ * equivalent to a single {@link materializeTeam} call).
+ *
+ * @param plan - The hierarchy plan from {@link synthesizeHierarchyPlan}.
+ * @param opts - Materialize options shared across all teams.
+ * @returns The created parent + children team ids with parent links.
+ * @throws If the PARENT materialize fails (a child failure is surfaced via its
+ *         `provisioned` flag, not thrown — partial hierarchies are usable).
+ */
+export declare function materializeHierarchy(plan: HierarchyPlan, opts: MaterializeOptions): Promise<MaterializedHierarchy>;
+//# sourceMappingURL=synthesize-hierarchy.d.ts.map

package/dist/backend/backend/src/services/orchestrator/onboarding/synthesize-hierarchy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesize-hierarchy.d.ts","sourceRoot":"","sources":["../../../../../../../backend/src/services/orchestrator/onboarding/synthesize-hierarchy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAM/B;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AA8BtC;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,EAAE,CAK5D;AAqBD,iDAAiD;AACjD,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,cAAc,EAAE,kBAAkB,CAAC;CAC7C;AAED,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IAC5C,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,mDAAmD;AACnD,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAeD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,eAAe,EACpB,IAAI,GAAE,iBAAsB,GAC3B,aAAa,CA2Bf;AAMD,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAED,8CAA8C;AAC9C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACjD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,qBAAqB,CAAC,CA0BhC"}