@autobe/agent 0.30.0-dev.20260315 → 0.30.0

package/src/orchestrate/analyze/structures/FixedAnalyzeTemplate.ts

@@ -1,961 +1,961 @@
-import { AutoBeAnalyze } from "@autobe/interface";
-
-/**
- * Fixed 6-category SRS document structure template.
- *
- * Defines the authoritative structure for all analysis documents. LLM is no
- * longer responsible for deciding file count, file names, or module/unit
- * layout. Instead, it focuses solely on content generation within this fixed
- * skeleton.
- *
- * Hierarchy: Category (file) -> Module (#) -> Unit (##) -> Section (###)
- *
- * @author Juntak
- */
-
-// ─────────────────────────────────────────────
-// Types
-// ─────────────────────────────────────────────
-
-export type FixedAnalyzeTemplateCategoryId =
-  | "00-toc"
-  | "01-actors-and-auth"
-  | "02-domain-model"
-  | "03-functional-requirements"
-  | "04-business-rules"
-  | "05-non-functional";
-
-export interface FixedAnalyzeTemplateFileTemplate {
-  categoryId: FixedAnalyzeTemplateCategoryId;
-  /** Currently equals categoryId; reserved for future per-category splits. */
-  fileId: string;
-  filename: `${string}.md`;
-  documentType: string;
-  description: string;
-  downstreamPhase: string;
-  modules: FixedAnalyzeTemplateModuleTemplate[];
-  /** Regex patterns that must NOT appear in this file's sections. */
-  forbiddenPatterns: RegExp[];
-}
-
-export interface FixedAnalyzeTemplateModuleTemplate {
-  index: number;
-  title: string;
-  purpose: string;
-  unitStrategy: FixedAnalyzeTemplateUnitStrategy;
-}
-
-export type FixedAnalyzeTemplateUnitStrategy =
-  | FixedAnalyzeTemplateFixedUnits
-  | FixedAnalyzeTemplatePerEntityUnits
-  | FixedAnalyzeTemplatePerActorUnits
-  | FixedAnalyzeTemplatePerEntityGroupUnits;
-
-export interface FixedAnalyzeTemplateFixedUnits {
-  type: "fixed";
-  units: FixedAnalyzeTemplateUnitTemplate[];
-}
-export interface FixedAnalyzeTemplatePerEntityUnits {
-  type: "perEntity";
-  unitTemplate: FixedAnalyzeTemplateUnitTemplate;
-}
-export interface FixedAnalyzeTemplatePerActorUnits {
-  type: "perActor";
-  unitTemplate: FixedAnalyzeTemplateUnitTemplate;
-}
-export interface FixedAnalyzeTemplatePerEntityGroupUnits {
-  type: "perEntityGroup";
-  unitTemplate: FixedAnalyzeTemplateUnitTemplate;
-}
-
-export interface FixedAnalyzeTemplateUnitTemplate {
-  titlePattern: string;
-  purposePattern: string;
-  keywords: string[];
-}
-
-// ─────────────────────────────────────────────
-// Feature types (conditional module activation)
-// ─────────────────────────────────────────────
-
-export type FixedAnalyzeTemplateFeatureId =
-  | "real-time"
-  | "external-integration"
-  | "file-storage";
-
-export interface FixedAnalyzeTemplateFeature {
-  id: FixedAnalyzeTemplateFeatureId;
-  /** Provider names for external-integration (e.g., ["stripe", "sendgrid"]) */
-  providers?: string[];
-}
-
-// ─────────────────────────────────────────────
-// Canonical source mapping
-// ─────────────────────────────────────────────
-
-export const FIXED_ANALYZE_TEMPLATE_CANONICAL_SOURCE: Record<
-  string,
-  FixedAnalyzeTemplateCategoryId
-> = {
-  "domain-concepts": "02-domain-model",
-  "error-conditions": "04-business-rules",
-  permissions: "01-actors-and-auth",
-};
-
-// ─────────────────────────────────────────────
-// 6-file template definition
-// ─────────────────────────────────────────────
-
-export const FIXED_ANALYZE_TEMPLATE: FixedAnalyzeTemplateFileTemplate[] = [
-  // ── 00-toc ──
-  {
-    categoryId: "00-toc",
-    fileId: "00-toc",
-    filename: "00-toc.md",
-    documentType: "overview",
-    description: "Project summary, scope, glossary, and assumptions",
-    downstreamPhase: "project-setup",
-    forbiddenPatterns: [],
-    modules: [
-      {
-        index: 0,
-        title: "Project Summary",
-        purpose: "High-level vision, goals, and scope of the project.",
-        unitStrategy: {
-          type: "fixed",
-          units: [
-            {
-              titlePattern: "Vision and Goals",
-              purposePattern:
-                "Define the project vision, business objectives, and success criteria.",
-              keywords: [
-                "vision",
-                "goals",
-                "objectives",
-                "success-criteria",
-                "business-value",
-              ],
-            },
-            {
-              titlePattern: "Scope Definition",
-              purposePattern:
-                "Define what is in-scope and out-of-scope for this project.",
-              keywords: [
-                "scope",
-                "boundaries",
-                "in-scope",
-                "out-of-scope",
-                "constraints",
-              ],
-            },
-          ],
-        },
-      },
-      {
-        index: 1,
-        title: "Document Map and Canonical Sources",
-        purpose:
-          "Navigation index and authoritative source declarations for cross-file references.",
-        unitStrategy: {
-          type: "fixed",
-          units: [
-            {
-              titlePattern: "Document Map",
-              purposePattern:
-                "Hyperlinked file index with role summaries and downstream phase mapping.",
-              keywords: [
-                "document-map",
-                "navigation",
-                "file-index",
-                "hyperlink",
-              ],
-            },
-            {
-              titlePattern: "Canonical Source Declaration",
-              purposePattern:
-                "Declare which file is the authoritative source for each data type and the required reference format.",
-              keywords: [
-                "canonical-source",
-                "reference-format",
-                "backtick",
-                "authority",
-              ],
-            },
-          ],
-        },
-      },
-      {
-        index: 2,
-        title: "Glossary and Assumptions",
-        purpose: "Domain terminology definitions and project assumptions.",
-        unitStrategy: {
-          type: "fixed",
-          units: [
-            {
-              titlePattern: "Domain Glossary",
-              purposePattern:
-                "Define domain-specific terms used throughout the documents.",
-              keywords: [
-                "glossary",
-                "terminology",
-                "definitions",
-                "domain-language",
-              ],
-            },
-            {
-              titlePattern: "Assumptions and Constraints",
-              purposePattern:
-                "List project assumptions and environmental constraints.",
-              keywords: [
-                "assumptions",
-                "constraints",
-                "prerequisites",
-                "limitations",
-              ],
-            },
-          ],
-        },
-      },
-    ],
-  },
-
-  // ── 01-actors-and-auth ──
-  {
-    categoryId: "01-actors-and-auth",
-    fileId: "01-actors-and-auth",
-    filename: "01-actors-and-auth.md",
-    documentType: "actors-and-auth",
-    description:
-      "Actor definitions, permission matrix, authentication, session, account lifecycle",
-    downstreamPhase: "auth-middleware",
-    forbiddenPatterns: [
-      /\|\s*(?:type|required|default|constraint)\s*\|/i, // Entity attribute tables → 02
-      /```yaml\s*\n\s*entity:/i, // Entity YAML specs → 02
-    ],
-    modules: [
-      {
-        index: 0,
-        title: "Actor Definitions",
-        purpose:
-          "Define all user actor types with their identity, permissions, and access boundaries.",
-        unitStrategy: {
-          type: "perActor",
-          unitTemplate: {
-            titlePattern: "{name} Actor",
-            purposePattern:
-              "Define the {name} actor's identity, permissions, and access boundaries. Do NOT describe specific operations (03), data isolation policies (05), or domain concepts (02).",
-            keywords: ["actor", "role", "permissions", "access-boundary"],
-          },
-        },
-      },
-      {
-        index: 1,
-        title: "Authentication Flows",
-        purpose:
-          "Registration, login, logout, and session management from a user perspective.",
-        unitStrategy: {
-          type: "fixed",
-          units: [
-            {
-              titlePattern: "Registration and Login",
-              purposePattern:
-                "Define user registration and login flows including validation and error handling.",
-              keywords: ["registration", "login", "authentication"],
-            },
-            {
-              titlePattern: "Session and Logout",
-              purposePattern:
-                "Define session behavior and logout from a user perspective.",
-              keywords: ["session", "logout", "account-security"],
-            },
-          ],
-        },
-      },
-      {
-        index: 2,
-        title: "Account Lifecycle",
-        purpose: "Account creation, deletion, and password management.",
-        unitStrategy: {
-          type: "fixed",
-          units: [
-            {
-              titlePattern: "Account Management",
-              purposePattern:
-                "Define how users create accounts, delete accounts, and change passwords.",
-              keywords: [
-                "account-creation",
-                "account-deletion",
-                "password-change",
-              ],
-            },
-          ],
-        },
-      },
-    ],
-  },
-
-  // ── 02-domain-model ──
-  {
-    categoryId: "02-domain-model",
-    fileId: "02-domain-model",
-    filename: "02-domain-model.md",
-    documentType: "domain-model",
-    description:
-      "Business concepts, relationships, and states from user perspective",
-    downstreamPhase: "database-design",
-    forbiddenPatterns: [
-      /\b(?:GET|POST|PUT|PATCH|DELETE)\s+\/\w+/i, // API endpoint defs → 03
-      /\bRequest\s+Body\b/i,
-      /\bResponse\s+(?:Body|Schema)\b/i,
-    ],
-    modules: [
-      {
-        index: 0,
-        title: "Domain Concepts",
-        purpose:
-          "Describe what each concept means in the business domain and its key attributes.",
-        unitStrategy: {
-          type: "perEntity",
-          unitTemplate: {
-            titlePattern: "{name} Concept",
-            purposePattern:
-              "Describe what {name} represents in the business domain and its key attributes. Do NOT describe operations or workflows — those belong in 03-functional-requirements.",
-            keywords: ["concept", "domain", "business-meaning", "attributes"],
-          },
-        },
-      },
-      {
-        index: 1,
-        title: "Domain Relationships",
-        purpose:
-          "Describe how concepts relate to each other from a business perspective.",
-        unitStrategy: {
-          type: "fixed",
-          units: [
-            {
-              titlePattern: "Conceptual Relationships",
-              purposePattern:
-                "Describe how concepts relate to each other in business terms.",
-              keywords: [
-                "relationship",
-                "association",
-                "belongs-to",
-                "has-many",
-                "ownership",
-              ],
-            },
-            {
-              titlePattern: "Lifecycle and Retention",
-              purposePattern:
-                "Describe concept lifecycle states and transitions only. Detailed retention/recovery policies belong in 05-non-functional. Operation details belong in 03-functional-requirements.",
-              keywords: [
-                "lifecycle",
-                "retention",
-                "archival",
-                "deletion-policy",
-                "recovery",
-              ],
-            },
-          ],
-        },
-      },
-      {
-        index: 2,
-        title: "Business Categories and State Flows",
-        purpose:
-          "Business category classifications and state flow definitions.",
-        unitStrategy: {
-          type: "fixed",
-          units: [
-            {
-              titlePattern: "Business Category Definitions",
-              purposePattern:
-                "Define all business category classifications with their allowed values and descriptions.",
-              keywords: [
-                "business-category",
-                "classification",
-                "allowed-values",
-                "status-type",
-              ],
-            },
-            {
-              titlePattern: "State Transitions",
-              purposePattern:
-                "Define valid state transition paths for stateful concepts.",
-              keywords: [
-                "state-flow",
-                "transition",
-                "workflow",
-                "status-change",
-              ],
-            },
-          ],
-        },
-      },
-    ],
-  },
-
-  // ── 03-functional-requirements ──
-  {
-    categoryId: "03-functional-requirements",
-    fileId: "03-functional-requirements",
-    filename: "03-functional-requirements.md",
-    documentType: "functional-requirements",
-    description:
-      "What operations users can perform, use cases, business workflows",
-    downstreamPhase: "interface-design",
-    forbiddenPatterns: [
-      /\b(?:GET|POST|PUT|PATCH|DELETE)\s+\/\w+/i, // API endpoint defs FORBIDDEN in requirements
-      /\bHTTP\s+[1-5]\d{2}\b/i, // HTTP status codes FORBIDDEN
-      /\bRequest\s+(?:Body|Example)\b/i, // Request schemas FORBIDDEN
-      /\bResponse\s+(?:Body|Example|Schema)\b/i, // Response schemas FORBIDDEN
-      /```json\s*\n\s*\{/i, // JSON examples FORBIDDEN
-      /\b(?:CREATE\s+)?(?:UNIQUE\s+)?INDEX\b/i, // Index defs → 02
-      /\bON\s+DELETE\s+(?:CASCADE|SET\s+NULL|RESTRICT)\b/i, // Cascade rules → 02
-      /```yaml\s*\n\s*errors:/i, // Error catalog YAML → 04
-    ],
-    modules: [
-      {
-        index: 0,
-        title: "Core Business Operations",
-        purpose: "What the system must do for each business concept.",
-        unitStrategy: {
-          type: "perEntity",
-          unitTemplate: {
-            titlePattern: "{name} Operations",
-            purposePattern:
-              "Define business operations for {name}: what create, read, update, delete, and list operations must accomplish from a business perspective.",
-            keywords: [
-              "operation",
-              "business-logic",
-              "use-case",
-              "requirement",
-              "behavior",
-              "functionality",
-            ],
-          },
-        },
-      },
-      {
-        index: 1,
-        title: "Error Scenarios and Edge Cases",
-        purpose:
-          "Business-level error scenarios, edge case coverage, and expected system behaviors for exceptional conditions.",
-        unitStrategy: {
-          type: "perEntity",
-          unitTemplate: {
-            titlePattern: "{name} Error Scenarios",
-            purposePattern:
-              "Define business error conditions, edge cases, and expected system behaviors for all {name} operations.",
-            keywords: [
-              "error-scenario",
-              "edge-case",
-              "validation-rule",
-              "conflict-resolution",
-              "boundary-condition",
-            ],
-          },
-        },
-      },
-      {
-        index: 2,
-        title: "End-to-End User Scenarios",
-        purpose:
-          "Cross-domain user scenarios that span multiple concepts, describing complete user journeys.",
-        unitStrategy: {
-          type: "fixed",
-          units: [
-            {
-              titlePattern: "Cross-Domain User Scenarios",
-              purposePattern:
-                "Define end-to-end user scenarios that span multiple concepts, describing complete user journeys from start to finish.",
-              keywords: [
-                "user-scenario",
-                "end-to-end",
-                "multi-step",
-                "user-journey",
-              ],
-            },
-          ],
-        },
-      },
-    ],
-  },
-
-  // ── 04-business-rules ──
-  {
-    categoryId: "04-business-rules",
-    fileId: "04-business-rules",
-    filename: "04-business-rules.md",
-    documentType: "business-rules",
-    description:
-      "Business rules, validation constraints, data browsing expectations, error scenarios",
-    downstreamPhase: "service-layer",
-    forbiddenPatterns: [
-      /```yaml\s*\n\s*entity:/i, // Entity YAML specs → 02
-      /\b(?:GET|POST|PUT|PATCH|DELETE)\s+\/\w+/i, // API endpoint defs → 03
-    ],
-    modules: [
-      {
-        index: 0,
-        title: "Domain Business Rules",
-        purpose:
-          "Per-concept business rules, validation logic, and domain constraints.",
-        unitStrategy: {
-          type: "perEntity",
-          unitTemplate: {
-            titlePattern: "{name} Rules",
-            purposePattern:
-              "Define validation rules and domain constraints for {name}. Do NOT repeat data isolation (05), lifecycle states (02), or operation flows (03).",
-            keywords: [
-              "business-rule",
-              "validation",
-              "constraint",
-              "domain-logic",
-            ],
-          },
-        },
-      },
-      {
-        index: 1,
-        title: "Data Browsing Expectations",
-        purpose:
-          "Business expectations for how users browse, find, and navigate through lists of data.",
-        unitStrategy: {
-          type: "fixed",
-          units: [
-            {
-              titlePattern: "List Browsing Expectations",
-              purposePattern:
-                "Define business expectations for how users find, filter, and browse lists.",
-              keywords: ["filtering", "sorting", "pagination"],
-            },
-          ],
-        },
-      },
-      {
-        index: 2,
-        title: "Error Conditions",
-        purpose: "Business error scenarios and how the system should respond.",
-        unitStrategy: {
-          type: "fixed",
-          units: [
-            {
-              titlePattern: "Error Scenarios",
-              purposePattern:
-                "Describe error conditions and expected system responses in natural language.",
-              keywords: [
-                "error-scenario",
-                "rejection",
-                "failure-case",
-                "exception",
-              ],
-            },
-          ],
-        },
-      },
-    ],
-  },
-
-  // ── 05-non-functional ──
-  {
-    categoryId: "05-non-functional",
-    fileId: "05-non-functional",
-    filename: "05-non-functional.md",
-    documentType: "non-functional",
-    description: "Data ownership, privacy, retention, and recovery policies",
-    downstreamPhase: "test-infra",
-    forbiddenPatterns: [
-      /\b(?:GET|POST|PUT|PATCH|DELETE)\s+\/\w+/i, // API endpoint defs → 03
-      /```yaml\s*\n\s*entity:/i, // Entity YAML specs → 02
-    ],
-    modules: [
-      {
-        index: 0,
-        title: "Data Policies",
-        purpose:
-          "Data ownership, privacy, retention, and recovery policies from a business perspective.",
-        unitStrategy: {
-          type: "fixed",
-          units: [
-            {
-              titlePattern: "Data Ownership and Privacy",
-              purposePattern:
-                "Define who owns what data, who can access it, and privacy boundaries between users.",
-              keywords: [
-                "data-isolation",
-                "ownership",
-                "access-control",
-                "privacy",
-              ],
-            },
-            {
-              titlePattern: "Data Retention and Recovery",
-              purposePattern:
-                "Define what happens to deleted data, how long it is retained, and how users can recover it.",
-              keywords: [
-                "soft-delete",
-                "retention",
-                "recovery",
-                "permanent-deletion",
-              ],
-            },
-          ],
-        },
-      },
-    ],
-  },
-];
-
-// ─────────────────────────────────────────────
-// Conditional modules (activated by features)
-// ─────────────────────────────────────────────
-
-export const FIXED_ANALYZE_TEMPLATE_CONDITIONAL_MODULES: Record<
-  FixedAnalyzeTemplateFeatureId,
-  Array<{
-    targetCategory: FixedAnalyzeTemplateCategoryId;
-    module: FixedAnalyzeTemplateModuleTemplate;
-  }>
-> = {
-  "real-time": [
-    {
-      targetCategory: "03-functional-requirements",
-      module: {
-        index: 100, // appended after base modules
-        title: "Real-time Events",
-        purpose:
-          "WebSocket/SSE event definitions and subscription specifications.",
-        unitStrategy: {
-          type: "perEntity",
-          unitTemplate: {
-            titlePattern: "{name} Events",
-            purposePattern:
-              "Define real-time events for {name} changes, including event payload and subscription rules.",
-            keywords: [
-              "websocket",
-              "sse",
-              "event",
-              "subscription",
-              "real-time",
-            ],
-          },
-        },
-      },
-    },
-    {
-      targetCategory: "05-non-functional",
-      module: {
-        index: 100,
-        title: "Real-time Communication",
-        purpose:
-          "WebSocket/SSE connection policies and performance requirements.",
-        unitStrategy: {
-          type: "fixed",
-          units: [
-            {
-              titlePattern: "WebSocket Security and Performance",
-              purposePattern:
-                "Define connection limits, heartbeat intervals, reconnection policies, and security requirements for real-time communication.",
-              keywords: [
-                "websocket-security",
-                "connection-limit",
-                "heartbeat",
-                "reconnection",
-              ],
-            },
-          ],
-        },
-      },
-    },
-  ],
-  "external-integration": [
-    {
-      targetCategory: "03-functional-requirements",
-      module: {
-        index: 101,
-        title: "External Integrations",
-        purpose:
-          "Third-party API contracts, webhook handlers, and integration specifications.",
-        unitStrategy: {
-          type: "fixed",
-          units: [
-            {
-              titlePattern: "Integration Contracts",
-              purposePattern:
-                "Define external API dependencies, authentication methods, request/response formats, and error handling for third-party integrations.",
-              keywords: [
-                "integration",
-                "third-party",
-                "webhook",
-                "oauth-provider",
-                "payment",
-              ],
-            },
-          ],
-        },
-      },
-    },
-    {
-      targetCategory: "04-business-rules",
-      module: {
-        index: 100,
-        title: "Integration Error Handling",
-        purpose: "Error handling and retry policies for external integrations.",
-        unitStrategy: {
-          type: "fixed",
-          units: [
-            {
-              titlePattern: "Integration Failure Policies",
-              purposePattern:
-                "Define retry strategies, circuit breaker policies, fallback behavior, and error escalation for external service failures.",
-              keywords: [
-                "retry",
-                "circuit-breaker",
-                "fallback",
-                "integration-error",
-              ],
-            },
-          ],
-        },
-      },
-    },
-    {
-      targetCategory: "05-non-functional",
-      module: {
-        index: 101,
-        title: "External Dependency SLOs",
-        purpose:
-          "Service level objectives for external dependency availability.",
-        unitStrategy: {
-          type: "fixed",
-          units: [
-            {
-              titlePattern: "External Dependency SLOs",
-              purposePattern:
-                "Define availability expectations, timeout thresholds, and degradation policies for external service dependencies.",
-              keywords: [
-                "dependency-slo",
-                "timeout",
-                "degradation",
-                "external-availability",
-              ],
-            },
-          ],
-        },
-      },
-    },
-  ],
-  "file-storage": [
-    {
-      targetCategory: "03-functional-requirements",
-      module: {
-        index: 103,
-        title: "File Storage",
-        purpose:
-          "File upload capabilities, media processing, and storage requirements.",
-        unitStrategy: {
-          type: "fixed",
-          units: [
-            {
-              titlePattern: "File Upload and Management",
-              purposePattern:
-                "Define file upload capabilities, supported formats, processing requirements, and access control for stored files.",
-              keywords: ["file-upload", "media", "storage", "attachment"],
-            },
-          ],
-        },
-      },
-    },
-    {
-      targetCategory: "04-business-rules",
-      module: {
-        index: 102,
-        title: "File Validation Rules",
-        purpose: "Validation rules and policies for file uploads and storage.",
-        unitStrategy: {
-          type: "fixed",
-          units: [
-            {
-              titlePattern: "File Validation and Policies",
-              purposePattern:
-                "Define file type restrictions, virus scanning requirements, content validation, and retention policies for uploaded files.",
-              keywords: [
-                "file-validation",
-                "virus-scan",
-                "content-type",
-                "retention",
-              ],
-            },
-          ],
-        },
-      },
-    },
-    {
-      targetCategory: "05-non-functional",
-      module: {
-        index: 103,
-        title: "Storage Capacity",
-        purpose: "Storage capacity planning and CDN requirements.",
-        unitStrategy: {
-          type: "fixed",
-          units: [
-            {
-              titlePattern: "Storage Capacity Requirements",
-              purposePattern:
-                "Define storage requirements and capacity planning for file storage.",
-              keywords: ["storage-capacity", "cdn", "capacity"],
-            },
-          ],
-        },
-      },
-    },
-  ],
-};
-
-// ─────────────────────────────────────────────
-// Helper functions
-// ─────────────────────────────────────────────
-
-/**
- * Expand a module's unit strategy into concrete unit templates based on the
- * domain's entities and actors.
- */
-export const expandFixedAnalyzeTemplateUnits = (
-  module: FixedAnalyzeTemplateModuleTemplate,
-  entities: Array<{ name: string }>,
-  actors: Array<{ name: string }>,
-): FixedAnalyzeTemplateUnitTemplate[] => {
-  const strategy = module.unitStrategy;
-  switch (strategy.type) {
-    case "fixed":
-      return strategy.units;
-    case "perEntity":
-      return entities.map((e) => ({
-        titlePattern: strategy.unitTemplate.titlePattern.replace(
-          "{name}",
-          e.name,
-        ),
-        purposePattern: strategy.unitTemplate.purposePattern.replace(
-          "{name}",
-          e.name,
-        ),
-        keywords: [...strategy.unitTemplate.keywords, e.name.toLowerCase()],
-      }));
-    case "perActor":
-      return actors.map((a) => ({
-        titlePattern: strategy.unitTemplate.titlePattern.replace(
-          "{name}",
-          a.name,
-        ),
-        purposePattern: strategy.unitTemplate.purposePattern.replace(
-          "{name}",
-          a.name,
-        ),
-        keywords: [...strategy.unitTemplate.keywords, a.name.toLowerCase()],
-      }));
-    case "perEntityGroup":
-      // For now, entity groups = entities; can be refined later
-      return entities.map((e) => ({
-        titlePattern: strategy.unitTemplate.titlePattern.replace(
-          "{name}",
-          e.name,
-        ),
-        purposePattern: strategy.unitTemplate.purposePattern.replace(
-          "{name}",
-          e.name,
-        ),
-        keywords: [...strategy.unitTemplate.keywords, e.name.toLowerCase()],
-      }));
-  }
-};
-
-/**
- * Build an expanded template by merging base TEMPLATE with conditional modules
- * activated by the given features.
- *
- * Module indices are renumbered sequentially per file after merging.
- */
-export const buildFixedAnalyzeExpandedTemplate = (
-  features: FixedAnalyzeTemplateFeature[],
-): FixedAnalyzeTemplateFileTemplate[] => {
-  if (features.length === 0) return FIXED_ANALYZE_TEMPLATE;
-
-  const activeFeatureIds = new Set(features.map((f) => f.id));
-  const extraModules = new Map<
-    FixedAnalyzeTemplateCategoryId,
-    FixedAnalyzeTemplateModuleTemplate[]
-  >();
-
-  for (const featureId of activeFeatureIds) {
-    const conditionals = FIXED_ANALYZE_TEMPLATE_CONDITIONAL_MODULES[featureId];
-    for (const { targetCategory, module } of conditionals) {
-      const existing = extraModules.get(targetCategory) ?? [];
-      existing.push(module);
-      extraModules.set(targetCategory, existing);
-    }
-  }
-
-  return FIXED_ANALYZE_TEMPLATE.map((fileTemplate) => {
-    const extras = extraModules.get(fileTemplate.categoryId);
-    if (!extras || extras.length === 0) return fileTemplate;
-
-    const mergedModules = [...fileTemplate.modules, ...extras].map((m, i) => ({
-      ...m,
-      index: i,
-    }));
-
-    return { ...fileTemplate, modules: mergedModules };
-  });
-};
-
-/**
- * Generate AutoBeAnalyze.IFile.Scenario objects from the fixed template,
- * optionally expanded with conditional modules based on features. Called after
- * LLM returns actors/entities/features in the scenario phase.
- */
-export const buildFixedAnalyzeScenarioFiles = (
-  _prefix: string,
-  features: FixedAnalyzeTemplateFeature[] = [],
-): AutoBeAnalyze.IFileScenario[] =>
-  buildFixedAnalyzeExpandedTemplate(features).map((t) => ({
-    reason: `Fixed SRS structure: ${t.description}`,
-    filename: t.filename,
-    documentType: t.documentType,
-    outline: t.modules.map((m) => m.title),
-    audience: "general",
-    detailLevel: "detailed specification",
-    constraints: [
-      `File scope: ${t.description}`,
-      `Downstream phase: ${t.downstreamPhase}`,
-    ],
-  }));
-
-/** Deterministically generate the Document Map unit content for 00-toc. */
-export const buildFixedAnalyzeDocumentMapContent = (
-  files: FixedAnalyzeTemplateFileTemplate[],
-): string => {
-  const rows = files
-    .map(
-      (f) =>
-        `| [${f.filename}](./${f.filename}) | ${f.description} | ${f.downstreamPhase} |`,
-    )
-    .join("\n");
-  return `| File | Role | Downstream |\n|------|------|------------|\n${rows}`;
-};
-
-/** Deterministically generate the Canonical Source Declaration unit content. */
-export const buildFixedAnalyzeCanonicalSourceContent = (): string => {
-  const header = `Each type of information has one authoritative location. Other files should reference these canonical sources.\n`;
-  const table = [
-    "| Information Type | Canonical File |",
-    "|------------------|---------------|",
-    "| Domain concepts | [02-domain-model.md](./02-domain-model.md) |",
-    "| Error conditions | [04-business-rules.md](./04-business-rules.md) |",
-    "| Permissions | [01-actors-and-auth.md](./01-actors-and-auth.md) |",
-    "| Actor definitions | [01-actors-and-auth.md](./01-actors-and-auth.md) |",
-    "| Filtering/pagination rules | [04-business-rules.md](./04-business-rules.md) |",
-    "| Data retention/recovery | [05-non-functional.md](./05-non-functional.md) |",
-  ].join("\n");
-  return `${header}\n${table}`;
-};
+import { AutoBeAnalyze } from "@autobe/interface";
+
+/**
+ * Fixed 6-category SRS document structure template.
+ *
+ * Defines the authoritative structure for all analysis documents. LLM is no
+ * longer responsible for deciding file count, file names, or module/unit
+ * layout. Instead, it focuses solely on content generation within this fixed
+ * skeleton.
+ *
+ * Hierarchy: Category (file) -> Module (#) -> Unit (##) -> Section (###)
+ *
+ * @author Juntak
+ */
+
+// ─────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────
+
+export type FixedAnalyzeTemplateCategoryId =
+  | "00-toc"
+  | "01-actors-and-auth"
+  | "02-domain-model"
+  | "03-functional-requirements"
+  | "04-business-rules"
+  | "05-non-functional";
+
+export interface FixedAnalyzeTemplateFileTemplate {
+  categoryId: FixedAnalyzeTemplateCategoryId;
+  /** Currently equals categoryId; reserved for future per-category splits. */
+  fileId: string;
+  filename: `${string}.md`;
+  documentType: string;
+  description: string;
+  downstreamPhase: string;
+  modules: FixedAnalyzeTemplateModuleTemplate[];
+  /** Regex patterns that must NOT appear in this file's sections. */
+  forbiddenPatterns: RegExp[];
+}
+
+export interface FixedAnalyzeTemplateModuleTemplate {
+  index: number;
+  title: string;
+  purpose: string;
+  unitStrategy: FixedAnalyzeTemplateUnitStrategy;
+}
+
+export type FixedAnalyzeTemplateUnitStrategy =
+  | FixedAnalyzeTemplateFixedUnits
+  | FixedAnalyzeTemplatePerEntityUnits
+  | FixedAnalyzeTemplatePerActorUnits
+  | FixedAnalyzeTemplatePerEntityGroupUnits;
+
+export interface FixedAnalyzeTemplateFixedUnits {
+  type: "fixed";
+  units: FixedAnalyzeTemplateUnitTemplate[];
+}
+export interface FixedAnalyzeTemplatePerEntityUnits {
+  type: "perEntity";
+  unitTemplate: FixedAnalyzeTemplateUnitTemplate;
+}
+export interface FixedAnalyzeTemplatePerActorUnits {
+  type: "perActor";
+  unitTemplate: FixedAnalyzeTemplateUnitTemplate;
+}
+export interface FixedAnalyzeTemplatePerEntityGroupUnits {
+  type: "perEntityGroup";
+  unitTemplate: FixedAnalyzeTemplateUnitTemplate;
+}
+
+export interface FixedAnalyzeTemplateUnitTemplate {
+  titlePattern: string;
+  purposePattern: string;
+  keywords: string[];
+}
+
+// ─────────────────────────────────────────────
+// Feature types (conditional module activation)
+// ─────────────────────────────────────────────
+
+export type FixedAnalyzeTemplateFeatureId =
+  | "real-time"
+  | "external-integration"
+  | "file-storage";
+
+export interface FixedAnalyzeTemplateFeature {
+  id: FixedAnalyzeTemplateFeatureId;
+  /** Provider names for external-integration (e.g., ["stripe", "sendgrid"]) */
+  providers?: string[];
+}
+
+// ─────────────────────────────────────────────
+// Canonical source mapping
+// ─────────────────────────────────────────────
+
+export const FIXED_ANALYZE_TEMPLATE_CANONICAL_SOURCE: Record<
+  string,
+  FixedAnalyzeTemplateCategoryId
+> = {
+  "domain-concepts": "02-domain-model",
+  "error-conditions": "04-business-rules",
+  permissions: "01-actors-and-auth",
+};
+
+// ─────────────────────────────────────────────
+// 6-file template definition
+// ─────────────────────────────────────────────
+
+export const FIXED_ANALYZE_TEMPLATE: FixedAnalyzeTemplateFileTemplate[] = [
+  // ── 00-toc ──
+  {
+    categoryId: "00-toc",
+    fileId: "00-toc",
+    filename: "00-toc.md",
+    documentType: "overview",
+    description: "Project summary, scope, glossary, and assumptions",
+    downstreamPhase: "project-setup",
+    forbiddenPatterns: [],
+    modules: [
+      {
+        index: 0,
+        title: "Project Summary",
+        purpose: "High-level vision, goals, and scope of the project.",
+        unitStrategy: {
+          type: "fixed",
+          units: [
+            {
+              titlePattern: "Vision and Goals",
+              purposePattern:
+                "Define the project vision, business objectives, and success criteria.",
+              keywords: [
+                "vision",
+                "goals",
+                "objectives",
+                "success-criteria",
+                "business-value",
+              ],
+            },
+            {
+              titlePattern: "Scope Definition",
+              purposePattern:
+                "Define what is in-scope and out-of-scope for this project.",
+              keywords: [
+                "scope",
+                "boundaries",
+                "in-scope",
+                "out-of-scope",
+                "constraints",
+              ],
+            },
+          ],
+        },
+      },
+      {
+        index: 1,
+        title: "Document Map and Canonical Sources",
+        purpose:
+          "Navigation index and authoritative source declarations for cross-file references.",
+        unitStrategy: {
+          type: "fixed",
+          units: [
+            {
+              titlePattern: "Document Map",
+              purposePattern:
+                "Hyperlinked file index with role summaries and downstream phase mapping.",
+              keywords: [
+                "document-map",
+                "navigation",
+                "file-index",
+                "hyperlink",
+              ],
+            },
+            {
+              titlePattern: "Canonical Source Declaration",
+              purposePattern:
+                "Declare which file is the authoritative source for each data type and the required reference format.",
+              keywords: [
+                "canonical-source",
+                "reference-format",
+                "backtick",
+                "authority",
+              ],
+            },
+          ],
+        },
+      },
+      {
+        index: 2,
+        title: "Glossary and Assumptions",
+        purpose: "Domain terminology definitions and project assumptions.",
+        unitStrategy: {
+          type: "fixed",
+          units: [
+            {
+              titlePattern: "Domain Glossary",
+              purposePattern:
+                "Define domain-specific terms used throughout the documents.",
+              keywords: [
+                "glossary",
+                "terminology",
+                "definitions",
+                "domain-language",
+              ],
+            },
+            {
+              titlePattern: "Assumptions and Constraints",
+              purposePattern:
+                "List project assumptions and environmental constraints.",
+              keywords: [
+                "assumptions",
+                "constraints",
+                "prerequisites",
+                "limitations",
+              ],
+            },
+          ],
+        },
+      },
+    ],
+  },
+
+  // ── 01-actors-and-auth ──
+  {
+    categoryId: "01-actors-and-auth",
+    fileId: "01-actors-and-auth",
+    filename: "01-actors-and-auth.md",
+    documentType: "actors-and-auth",
+    description:
+      "Actor definitions, permission matrix, authentication, session, account lifecycle",
+    downstreamPhase: "auth-middleware",
+    forbiddenPatterns: [
+      /\|\s*(?:type|required|default|constraint)\s*\|/i, // Entity attribute tables → 02
+      /```yaml\s*\n\s*entity:/i, // Entity YAML specs → 02
+    ],
+    modules: [
+      {
+        index: 0,
+        title: "Actor Definitions",
+        purpose:
+          "Define all user actor types with their identity, permissions, and access boundaries.",
+        unitStrategy: {
+          type: "perActor",
+          unitTemplate: {
+            titlePattern: "{name} Actor",
+            purposePattern:
+              "Define the {name} actor's identity, permissions, and access boundaries. Do NOT describe specific operations (03), data isolation policies (05), or domain concepts (02).",
+            keywords: ["actor", "role", "permissions", "access-boundary"],
+          },
+        },
+      },
+      {
+        index: 1,
+        title: "Authentication Flows",
+        purpose:
+          "Registration, login, logout, and session management from a user perspective.",
+        unitStrategy: {
+          type: "fixed",
+          units: [
+            {
+              titlePattern: "Registration and Login",
+              purposePattern:
+                "Define user registration and login flows including validation and error handling.",
+              keywords: ["registration", "login", "authentication"],
+            },
+            {
+              titlePattern: "Session and Logout",
+              purposePattern:
+                "Define session behavior and logout from a user perspective.",
+              keywords: ["session", "logout", "account-security"],
+            },
+          ],
+        },
+      },
+      {
+        index: 2,
+        title: "Account Lifecycle",
+        purpose: "Account creation, deletion, and password management.",
+        unitStrategy: {
+          type: "fixed",
+          units: [
+            {
+              titlePattern: "Account Management",
+              purposePattern:
+                "Define how users create accounts, delete accounts, and change passwords.",
+              keywords: [
+                "account-creation",
+                "account-deletion",
+                "password-change",
+              ],
+            },
+          ],
+        },
+      },
+    ],
+  },
+
+  // ── 02-domain-model ──
+  {
+    categoryId: "02-domain-model",
+    fileId: "02-domain-model",
+    filename: "02-domain-model.md",
+    documentType: "domain-model",
+    description:
+      "Business concepts, relationships, and states from user perspective",
+    downstreamPhase: "database-design",
+    forbiddenPatterns: [
+      /\b(?:GET|POST|PUT|PATCH|DELETE)\s+\/\w+/i, // API endpoint defs → 03
+      /\bRequest\s+Body\b/i,
+      /\bResponse\s+(?:Body|Schema)\b/i,
+    ],
+    modules: [
+      {
+        index: 0,
+        title: "Domain Concepts",
+        purpose:
+          "Describe what each concept means in the business domain and its key attributes.",
+        unitStrategy: {
+          type: "perEntity",
+          unitTemplate: {
+            titlePattern: "{name} Concept",
+            purposePattern:
+              "Describe what {name} represents in the business domain and its key attributes. Do NOT describe operations or workflows — those belong in 03-functional-requirements.",
+            keywords: ["concept", "domain", "business-meaning", "attributes"],
+          },
+        },
+      },
+      {
+        index: 1,
+        title: "Domain Relationships",
+        purpose:
+          "Describe how concepts relate to each other from a business perspective.",
+        unitStrategy: {
+          type: "fixed",
+          units: [
+            {
+              titlePattern: "Conceptual Relationships",
+              purposePattern:
+                "Describe how concepts relate to each other in business terms.",
+              keywords: [
+                "relationship",
+                "association",
+                "belongs-to",
+                "has-many",
+                "ownership",
+              ],
+            },
+            {
+              titlePattern: "Lifecycle and Retention",
+              purposePattern:
+                "Describe concept lifecycle states and transitions only. Detailed retention/recovery policies belong in 05-non-functional. Operation details belong in 03-functional-requirements.",
+              keywords: [
+                "lifecycle",
+                "retention",
+                "archival",
+                "deletion-policy",
+                "recovery",
+              ],
+            },
+          ],
+        },
+      },
+      {
+        index: 2,
+        title: "Business Categories and State Flows",
+        purpose:
+          "Business category classifications and state flow definitions.",
+        unitStrategy: {
+          type: "fixed",
+          units: [
+            {
+              titlePattern: "Business Category Definitions",
+              purposePattern:
+                "Define all business category classifications with their allowed values and descriptions.",
+              keywords: [
+                "business-category",
+                "classification",
+                "allowed-values",
+                "status-type",
+              ],
+            },
+            {
+              titlePattern: "State Transitions",
+              purposePattern:
+                "Define valid state transition paths for stateful concepts.",
+              keywords: [
+                "state-flow",
+                "transition",
+                "workflow",
+                "status-change",
+              ],
+            },
+          ],
+        },
+      },
+    ],
+  },
+
+  // ── 03-functional-requirements ──
+  {
+    categoryId: "03-functional-requirements",
+    fileId: "03-functional-requirements",
+    filename: "03-functional-requirements.md",
+    documentType: "functional-requirements",
+    description:
+      "What operations users can perform, use cases, business workflows",
+    downstreamPhase: "interface-design",
+    forbiddenPatterns: [
+      /\b(?:GET|POST|PUT|PATCH|DELETE)\s+\/\w+/i, // API endpoint defs FORBIDDEN in requirements
+      /\bHTTP\s+[1-5]\d{2}\b/i, // HTTP status codes FORBIDDEN
+      /\bRequest\s+(?:Body|Example)\b/i, // Request schemas FORBIDDEN
+      /\bResponse\s+(?:Body|Example|Schema)\b/i, // Response schemas FORBIDDEN
+      /```json\s*\n\s*\{/i, // JSON examples FORBIDDEN
+      /\b(?:CREATE\s+)?(?:UNIQUE\s+)?INDEX\b/i, // Index defs → 02
+      /\bON\s+DELETE\s+(?:CASCADE|SET\s+NULL|RESTRICT)\b/i, // Cascade rules → 02
+      /```yaml\s*\n\s*errors:/i, // Error catalog YAML → 04
+    ],
+    modules: [
+      {
+        index: 0,
+        title: "Core Business Operations",
+        purpose: "What the system must do for each business concept.",
+        unitStrategy: {
+          type: "perEntity",
+          unitTemplate: {
+            titlePattern: "{name} Operations",
+            purposePattern:
+              "Define business operations for {name}: what create, read, update, delete, and list operations must accomplish from a business perspective.",
+            keywords: [
+              "operation",
+              "business-logic",
+              "use-case",
+              "requirement",
+              "behavior",
+              "functionality",
+            ],
+          },
+        },
+      },
+      {
+        index: 1,
+        title: "Error Scenarios and Edge Cases",
+        purpose:
+          "Business-level error scenarios, edge case coverage, and expected system behaviors for exceptional conditions.",
+        unitStrategy: {
+          type: "perEntity",
+          unitTemplate: {
+            titlePattern: "{name} Error Scenarios",
+            purposePattern:
+              "Define business error conditions, edge cases, and expected system behaviors for all {name} operations.",
+            keywords: [
+              "error-scenario",
+              "edge-case",
+              "validation-rule",
+              "conflict-resolution",
+              "boundary-condition",
+            ],
+          },
+        },
+      },
+      {
+        index: 2,
+        title: "End-to-End User Scenarios",
+        purpose:
+          "Cross-domain user scenarios that span multiple concepts, describing complete user journeys.",
+        unitStrategy: {
+          type: "fixed",
+          units: [
+            {
+              titlePattern: "Cross-Domain User Scenarios",
+              purposePattern:
+                "Define end-to-end user scenarios that span multiple concepts, describing complete user journeys from start to finish.",
+              keywords: [
+                "user-scenario",
+                "end-to-end",
+                "multi-step",
+                "user-journey",
+              ],
+            },
+          ],
+        },
+      },
+    ],
+  },
+
+  // ── 04-business-rules ──
+  {
+    categoryId: "04-business-rules",
+    fileId: "04-business-rules",
+    filename: "04-business-rules.md",
+    documentType: "business-rules",
+    description:
+      "Business rules, validation constraints, data browsing expectations, error scenarios",
+    downstreamPhase: "service-layer",
+    forbiddenPatterns: [
+      /```yaml\s*\n\s*entity:/i, // Entity YAML specs → 02
+      /\b(?:GET|POST|PUT|PATCH|DELETE)\s+\/\w+/i, // API endpoint defs → 03
+    ],
+    modules: [
+      {
+        index: 0,
+        title: "Domain Business Rules",
+        purpose:
+          "Per-concept business rules, validation logic, and domain constraints.",
+        unitStrategy: {
+          type: "perEntity",
+          unitTemplate: {
+            titlePattern: "{name} Rules",
+            purposePattern:
+              "Define validation rules and domain constraints for {name}. Do NOT repeat data isolation (05), lifecycle states (02), or operation flows (03).",
+            keywords: [
+              "business-rule",
+              "validation",
+              "constraint",
+              "domain-logic",
+            ],
+          },
+        },
+      },
+      {
+        index: 1,
+        title: "Data Browsing Expectations",
+        purpose:
+          "Business expectations for how users browse, find, and navigate through lists of data.",
+        unitStrategy: {
+          type: "fixed",
+          units: [
+            {
+              titlePattern: "List Browsing Expectations",
+              purposePattern:
+                "Define business expectations for how users find, filter, and browse lists.",
+              keywords: ["filtering", "sorting", "pagination"],
+            },
+          ],
+        },
+      },
+      {
+        index: 2,
+        title: "Error Conditions",
+        purpose: "Business error scenarios and how the system should respond.",
+        unitStrategy: {
+          type: "fixed",
+          units: [
+            {
+              titlePattern: "Error Scenarios",
+              purposePattern:
+                "Describe error conditions and expected system responses in natural language.",
+              keywords: [
+                "error-scenario",
+                "rejection",
+                "failure-case",
+                "exception",
+              ],
+            },
+          ],
+        },
+      },
+    ],
+  },
+
+  // ── 05-non-functional ──
+  {
+    categoryId: "05-non-functional",
+    fileId: "05-non-functional",
+    filename: "05-non-functional.md",
+    documentType: "non-functional",
+    description: "Data ownership, privacy, retention, and recovery policies",
+    downstreamPhase: "test-infra",
+    forbiddenPatterns: [
+      /\b(?:GET|POST|PUT|PATCH|DELETE)\s+\/\w+/i, // API endpoint defs → 03
+      /```yaml\s*\n\s*entity:/i, // Entity YAML specs → 02
+    ],
+    modules: [
+      {
+        index: 0,
+        title: "Data Policies",
+        purpose:
+          "Data ownership, privacy, retention, and recovery policies from a business perspective.",
+        unitStrategy: {
+          type: "fixed",
+          units: [
+            {
+              titlePattern: "Data Ownership and Privacy",
+              purposePattern:
+                "Define who owns what data, who can access it, and privacy boundaries between users.",
+              keywords: [
+                "data-isolation",
+                "ownership",
+                "access-control",
+                "privacy",
+              ],
+            },
+            {
+              titlePattern: "Data Retention and Recovery",
+              purposePattern:
+                "Define what happens to deleted data, how long it is retained, and how users can recover it.",
+              keywords: [
+                "soft-delete",
+                "retention",
+                "recovery",
+                "permanent-deletion",
+              ],
+            },
+          ],
+        },
+      },
+    ],
+  },
+];
+
+// ─────────────────────────────────────────────
+// Conditional modules (activated by features)
+// ─────────────────────────────────────────────
+
+export const FIXED_ANALYZE_TEMPLATE_CONDITIONAL_MODULES: Record<
+  FixedAnalyzeTemplateFeatureId,
+  Array<{
+    targetCategory: FixedAnalyzeTemplateCategoryId;
+    module: FixedAnalyzeTemplateModuleTemplate;
+  }>
+> = {
+  "real-time": [
+    {
+      targetCategory: "03-functional-requirements",
+      module: {
+        index: 100, // appended after base modules
+        title: "Real-time Events",
+        purpose:
+          "WebSocket/SSE event definitions and subscription specifications.",
+        unitStrategy: {
+          type: "perEntity",
+          unitTemplate: {
+            titlePattern: "{name} Events",
+            purposePattern:
+              "Define real-time events for {name} changes, including event payload and subscription rules.",
+            keywords: [
+              "websocket",
+              "sse",
+              "event",
+              "subscription",
+              "real-time",
+            ],
+          },
+        },
+      },
+    },
+    {
+      targetCategory: "05-non-functional",
+      module: {
+        index: 100,
+        title: "Real-time Communication",
+        purpose:
+          "WebSocket/SSE connection policies and performance requirements.",
+        unitStrategy: {
+          type: "fixed",
+          units: [
+            {
+              titlePattern: "WebSocket Security and Performance",
+              purposePattern:
+                "Define connection limits, heartbeat intervals, reconnection policies, and security requirements for real-time communication.",
+              keywords: [
+                "websocket-security",
+                "connection-limit",
+                "heartbeat",
+                "reconnection",
+              ],
+            },
+          ],
+        },
+      },
+    },
+  ],
+  "external-integration": [
+    {
+      targetCategory: "03-functional-requirements",
+      module: {
+        index: 101,
+        title: "External Integrations",
+        purpose:
+          "Third-party API contracts, webhook handlers, and integration specifications.",
+        unitStrategy: {
+          type: "fixed",
+          units: [
+            {
+              titlePattern: "Integration Contracts",
+              purposePattern:
+                "Define external API dependencies, authentication methods, request/response formats, and error handling for third-party integrations.",
+              keywords: [
+                "integration",
+                "third-party",
+                "webhook",
+                "oauth-provider",
+                "payment",
+              ],
+            },
+          ],
+        },
+      },
+    },
+    {
+      targetCategory: "04-business-rules",
+      module: {
+        index: 100,
+        title: "Integration Error Handling",
+        purpose: "Error handling and retry policies for external integrations.",
+        unitStrategy: {
+          type: "fixed",
+          units: [
+            {
+              titlePattern: "Integration Failure Policies",
+              purposePattern:
+                "Define retry strategies, circuit breaker policies, fallback behavior, and error escalation for external service failures.",
+              keywords: [
+                "retry",
+                "circuit-breaker",
+                "fallback",
+                "integration-error",
+              ],
+            },
+          ],
+        },
+      },
+    },
+    {
+      targetCategory: "05-non-functional",
+      module: {
+        index: 101,
+        title: "External Dependency SLOs",
+        purpose:
+          "Service level objectives for external dependency availability.",
+        unitStrategy: {
+          type: "fixed",
+          units: [
+            {
+              titlePattern: "External Dependency SLOs",
+              purposePattern:
+                "Define availability expectations, timeout thresholds, and degradation policies for external service dependencies.",
+              keywords: [
+                "dependency-slo",
+                "timeout",
+                "degradation",
+                "external-availability",
+              ],
+            },
+          ],
+        },
+      },
+    },
+  ],
+  "file-storage": [
+    {
+      targetCategory: "03-functional-requirements",
+      module: {
+        index: 103,
+        title: "File Storage",
+        purpose:
+          "File upload capabilities, media processing, and storage requirements.",
+        unitStrategy: {
+          type: "fixed",
+          units: [
+            {
+              titlePattern: "File Upload and Management",
+              purposePattern:
+                "Define file upload capabilities, supported formats, processing requirements, and access control for stored files.",
+              keywords: ["file-upload", "media", "storage", "attachment"],
+            },
+          ],
+        },
+      },
+    },
+    {
+      targetCategory: "04-business-rules",
+      module: {
+        index: 102,
+        title: "File Validation Rules",
+        purpose: "Validation rules and policies for file uploads and storage.",
+        unitStrategy: {
+          type: "fixed",
+          units: [
+            {
+              titlePattern: "File Validation and Policies",
+              purposePattern:
+                "Define file type restrictions, virus scanning requirements, content validation, and retention policies for uploaded files.",
+              keywords: [
+                "file-validation",
+                "virus-scan",
+                "content-type",
+                "retention",
+              ],
+            },
+          ],
+        },
+      },
+    },
+    {
+      targetCategory: "05-non-functional",
+      module: {
+        index: 103,
+        title: "Storage Capacity",
+        purpose: "Storage capacity planning and CDN requirements.",
+        unitStrategy: {
+          type: "fixed",
+          units: [
+            {
+              titlePattern: "Storage Capacity Requirements",
+              purposePattern:
+                "Define storage requirements and capacity planning for file storage.",
+              keywords: ["storage-capacity", "cdn", "capacity"],
+            },
+          ],
+        },
+      },
+    },
+  ],
+};
+
+// ─────────────────────────────────────────────
+// Helper functions
+// ─────────────────────────────────────────────
+
+/**
+ * Expand a module's unit strategy into concrete unit templates based on the
+ * domain's entities and actors.
+ */
+export const expandFixedAnalyzeTemplateUnits = (
+  module: FixedAnalyzeTemplateModuleTemplate,
+  entities: Array<{ name: string }>,
+  actors: Array<{ name: string }>,
+): FixedAnalyzeTemplateUnitTemplate[] => {
+  const strategy = module.unitStrategy;
+  switch (strategy.type) {
+    case "fixed":
+      return strategy.units;
+    case "perEntity":
+      return entities.map((e) => ({
+        titlePattern: strategy.unitTemplate.titlePattern.replace(
+          "{name}",
+          e.name,
+        ),
+        purposePattern: strategy.unitTemplate.purposePattern.replace(
+          "{name}",
+          e.name,
+        ),
+        keywords: [...strategy.unitTemplate.keywords, e.name.toLowerCase()],
+      }));
+    case "perActor":
+      return actors.map((a) => ({
+        titlePattern: strategy.unitTemplate.titlePattern.replace(
+          "{name}",
+          a.name,
+        ),
+        purposePattern: strategy.unitTemplate.purposePattern.replace(
+          "{name}",
+          a.name,
+        ),
+        keywords: [...strategy.unitTemplate.keywords, a.name.toLowerCase()],
+      }));
+    case "perEntityGroup":
+      // For now, entity groups = entities; can be refined later
+      return entities.map((e) => ({
+        titlePattern: strategy.unitTemplate.titlePattern.replace(
+          "{name}",
+          e.name,
+        ),
+        purposePattern: strategy.unitTemplate.purposePattern.replace(
+          "{name}",
+          e.name,
+        ),
+        keywords: [...strategy.unitTemplate.keywords, e.name.toLowerCase()],
+      }));
+  }
+};
+
+/**
+ * Build an expanded template by merging base TEMPLATE with conditional modules
+ * activated by the given features.
+ *
+ * Module indices are renumbered sequentially per file after merging.
+ */
+export const buildFixedAnalyzeExpandedTemplate = (
+  features: FixedAnalyzeTemplateFeature[],
+): FixedAnalyzeTemplateFileTemplate[] => {
+  if (features.length === 0) return FIXED_ANALYZE_TEMPLATE;
+
+  const activeFeatureIds = new Set(features.map((f) => f.id));
+  const extraModules = new Map<
+    FixedAnalyzeTemplateCategoryId,
+    FixedAnalyzeTemplateModuleTemplate[]
+  >();
+
+  for (const featureId of activeFeatureIds) {
+    const conditionals = FIXED_ANALYZE_TEMPLATE_CONDITIONAL_MODULES[featureId];
+    for (const { targetCategory, module } of conditionals) {
+      const existing = extraModules.get(targetCategory) ?? [];
+      existing.push(module);
+      extraModules.set(targetCategory, existing);
+    }
+  }
+
+  return FIXED_ANALYZE_TEMPLATE.map((fileTemplate) => {
+    const extras = extraModules.get(fileTemplate.categoryId);
+    if (!extras || extras.length === 0) return fileTemplate;
+
+    const mergedModules = [...fileTemplate.modules, ...extras].map((m, i) => ({
+      ...m,
+      index: i,
+    }));
+
+    return { ...fileTemplate, modules: mergedModules };
+  });
+};
+
+/**
+ * Generate AutoBeAnalyze.IFile.Scenario objects from the fixed template,
+ * optionally expanded with conditional modules based on features. Called after
+ * LLM returns actors/entities/features in the scenario phase.
+ */
+export const buildFixedAnalyzeScenarioFiles = (
+  _prefix: string,
+  features: FixedAnalyzeTemplateFeature[] = [],
+): AutoBeAnalyze.IFileScenario[] =>
+  buildFixedAnalyzeExpandedTemplate(features).map((t) => ({
+    reason: `Fixed SRS structure: ${t.description}`,
+    filename: t.filename,
+    documentType: t.documentType,
+    outline: t.modules.map((m) => m.title),
+    audience: "general",
+    detailLevel: "detailed specification",
+    constraints: [
+      `File scope: ${t.description}`,
+      `Downstream phase: ${t.downstreamPhase}`,
+    ],
+  }));
+
+/** Deterministically generate the Document Map unit content for 00-toc. */
+export const buildFixedAnalyzeDocumentMapContent = (
+  files: FixedAnalyzeTemplateFileTemplate[],
+): string => {
+  const rows = files
+    .map(
+      (f) =>
+        `| [${f.filename}](./${f.filename}) | ${f.description} | ${f.downstreamPhase} |`,
+    )
+    .join("\n");
+  return `| File | Role | Downstream |\n|------|------|------------|\n${rows}`;
+};
+
+/** Deterministically generate the Canonical Source Declaration unit content. */
+export const buildFixedAnalyzeCanonicalSourceContent = (): string => {
+  const header = `Each type of information has one authoritative location. Other files should reference these canonical sources.\n`;
+  const table = [
+    "| Information Type | Canonical File |",
+    "|------------------|---------------|",
+    "| Domain concepts | [02-domain-model.md](./02-domain-model.md) |",
+    "| Error conditions | [04-business-rules.md](./04-business-rules.md) |",
+    "| Permissions | [01-actors-and-auth.md](./01-actors-and-auth.md) |",
+    "| Actor definitions | [01-actors-and-auth.md](./01-actors-and-auth.md) |",
+    "| Filtering/pagination rules | [04-business-rules.md](./04-business-rules.md) |",
+    "| Data retention/recovery | [05-non-functional.md](./05-non-functional.md) |",
+  ].join("\n");
+  return `${header}\n${table}`;
+};