@autobe/agent 0.30.4 → 0.30.5

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

@@ -1,51 +1,31 @@
 /**
- * Application interface for the Key Decision Extractor agent.
- *
- * This agent extracts binary/discrete decisions from a single file's section
- * content as structured data. The extracted decisions are then compared
- * programmatically across files to detect contradictions.
+ * Extracts binary/discrete decisions from a file's sections for cross-file
+ * contradiction detection.
  */
 export interface IAutoBeAnalyzeExtractDecisionsApplication {
-  /**
-   * Process decision extraction from a single file's sections.
-   *
-   * Reads the file content and extracts all binary/discrete decisions as
-   * structured data for cross-file contradiction detection.
-   *
-   * @param props Request containing extracted decisions
-   */
+  /** Extract all binary/discrete decisions from a single file's sections. */
   process(props: IAutoBeAnalyzeExtractDecisionsApplicationProps): void;
 }
 
 export interface IAutoBeAnalyzeExtractDecisionsApplicationProps {
   /**
-   * Think before you act.
-   *
-   * Before completing extraction, reflect on what decisions this file makes:
-   *
-   * - What binary (yes/no) choices does this file assert?
-   * - What discrete behavioral choices does this file make?
-   * - Are there decisions where another file could reasonably disagree?
+   * Reasoning about your current state: what's missing (preliminary) or what
+   * you accomplished (completion).
    */
   thinking?: string | null;
 
-  /** Extraction result. */
+  /** Action to perform: submit extracted decisions. */
   request: IAutoBeAnalyzeExtractDecisionsApplicationComplete;
 }
 
 /** Request to complete the decision extraction. */
 export interface IAutoBeAnalyzeExtractDecisionsApplicationComplete {
-  /** Type discriminator for the request. */
+  /** Type discriminator for completion request. */
   type: "complete";
 
   /**
-   * All binary/discrete decisions extracted from this file.
-   *
-   * Each decision represents a specific behavioral choice that the file makes.
-   * Use normalized topic names, decision names, and values.
-   *
-   * Return an empty array if the file has no extractable decisions (e.g., table
-   * of contents).
+   * All binary/discrete decisions extracted from this file. Use normalized
+   * names. Return an empty array if the file has no extractable decisions.
    */
   decisions: IAutoBeAnalyzeExtractedDecision[];
 }
@@ -53,9 +33,7 @@ export interface IAutoBeAnalyzeExtractDecisionsApplicationComplete {
 /** A single extracted decision from the file's content. */
 export interface IAutoBeAnalyzeExtractedDecision {
   /**
-   * Normalized topic grouping.
-   *
-   * Use lowercase, underscore-separated names.
+   * Normalized topic grouping (lowercase, underscore-separated).
    *
    * @example
    *   (password_change, "todo_deletion", "edit_history");
@@ -63,9 +41,7 @@ export interface IAutoBeAnalyzeExtractedDecision {
   topic: string;
 
   /**
-   * Specific decision within the topic.
-   *
-   * Use lowercase, underscore-separated, descriptive names.
+   * Specific decision within the topic (lowercase, underscore-separated).
    *
    * @example
    *   (requires_current_password, "deletion_method", "recorded_values");
@@ -73,27 +49,13 @@ export interface IAutoBeAnalyzeExtractedDecision {
   decision: string;
 
   /**
-   * The value of the decision.
-   *
-   * For binary decisions: "yes" or "no". For discrete decisions: short
-   * descriptive string.
+   * Binary: "yes"/"no". Discrete: short descriptive string.
    *
    * @example
-   *   (yes,
-   *     "no",
-   *     "soft_delete",
-   *     "hard_delete",
-   *     "new_values",
-   *     "previous_values");
+   *   (yes, "soft_delete", "hard_delete");
    */
   value: string;
 
-  /**
-   * Short quote (1-2 sentences) from the source text supporting this decision.
-   *
-   * @example
-   *   "A user may change their password only by providing their
-   *   current password."
-   */
+  /** Short quote (1-2 sentences) from the source text supporting this decision. */
   evidence: string;
 }

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

@@ -9,14 +9,8 @@ import { FixedAnalyzeTemplateFeature } from "./FixedAnalyzeTemplate";
 
 export interface IAutoBeAnalyzeScenarioApplication {
   /**
-   * Process scenario composition task or preliminary data requests.
-   *
-   * Composes project structure with actors and entities based on requirements.
-   * File structure is fixed (6-file SRS template); the LLM only determines
-   * actors, entities, prefix, and language.
-   *
-   * @param props Request containing either preliminary data request or complete
-   *   task
+   * Compose project structure (actors, entities, prefix, language) or request
+   * preliminary data.
    */
   process(props: IAutoBeAnalyzeScenarioApplication.IProps): void;
 }
@@ -26,125 +20,58 @@ export namespace IAutoBeAnalyzeScenarioApplication {
     /**
      * Think before you act.
      *
-     * Before requesting preliminary data or completing your task, reflect on
-     * your current state and explain your reasoning:
+     * For preliminary requests: what previous analysis sections are missing?
      *
-     * For preliminary requests (getPreviousAnalysisSections):
-     *
-     * - What critical information is missing that you don't already have?
-     * - Why do you need it specifically right now?
-     * - Be brief - state the gap, don't list everything you have.
-     *
-     * For completion (complete):
-     *
-     * - What key assets did you acquire?
-     * - What did you accomplished?
-     * - Why is it sufficient to complete?
-     * - Summarize - don't enumerate every single item.
-     *
-     * This reflection helps you avoid duplicate requests and premature
-     * completion.
+     * For completion: is the DTO transformable or non-transformable? What
+     * actors, entities, and prefix were chosen based on requirements?
      */
     thinking?: string | null;
 
     /**
-     * Type discriminator for the request.
-     *
-     * Determines which action to perform: preliminary data retrieval
-     * (getPreviousAnalysisSections) or final scenario composition (complete).
-     * When preliminary returns empty array, that type is removed from the
-     * union, physically preventing repeated calls.
+     * Action to perform. Exhausted preliminary types are removed from the
+     * union.
      */
     request: IComplete | IAutoBePreliminaryGetPreviousAnalysisSections;
   }
 
-  /**
-   * Request to compose project structure with actors and entities.
-   *
-   * The document file structure is fixed as 6-file SRS template. LLM only
-   * determines actors, entities, prefix, and language. Files are generated
-   * programmatically from FixedAnalyzeTemplate.
-   */
+  /** Compose project structure with actors and entities (6-file SRS template). */
   export interface IComplete {
-    /**
-     * Type discriminator for the request.
-     *
-     * Determines which action to perform: preliminary data retrieval or actual
-     * task execution. Value "complete" indicates this is the final task
-     * execution request.
-     */
+    /** Type discriminator for completion request. */
     type: "complete";
 
-    /** Reason for the analysis and composition of the project structure. */
+    /** Why these actors, entities, and prefix were chosen based on requirements. */
     reason: string;
 
-    /**
-     * Prefix for file names and variable names. This will be used for
-     * organizing documentation files.
-     *
-     * DO: Use camelCase naming convention.
-     */
+    /** Prefix for file/variable names (camelCase). */
     prefix: string & CamelCasePattern;
 
-    /**
-     * Actors to be assigned for the project.
-     *
-     * Each actor has:
-     *
-     * - `name`: Actor identifier (camelCase)
-     * - `kind`: "guest" | "member" | "admin"
-     * - `description`: Actor's permissions and capabilities
-     */
+    /** Actors for the project (name, kind, description). */
     actors: AutoBeAnalyze.IActor[];
 
     /**
-     * Language for document content. When specified by the user, this takes
-     * precedence over the locale setting for determining document language. Set
-     * to `null` if not specified.
+     * Language for document content. Overrides locale if set; null if not
+     * specified.
      */
     language: string | null;
 
     /**
-     * Core domain entities with their key attributes and relationships.
-     *
-     * These serve as the AUTHORITATIVE entity list — all downstream document
-     * writers (module, unit, section) MUST reference only these entities. This
-     * prevents hallucination and ensures cross-file consistency.
-     *
-     * Each entity should include:
-     *
-     * - `name`: PascalCase entity name (e.g., "Todo", "User", "Comment")
-     * - `attributes`: Key attributes with type hints (e.g., "title: text(1-500),
-     *   required")
-     * - `relationships`: How this entity relates to others (e.g., "belongsTo User
-     *   via userId")
-     *
-     * Include ALL domain entities that will appear in the requirements
-     * documents. Do NOT include meta-entities (InterpretationLog,
-     * ScopeDecisionLog, etc.) that describe the requirements process rather
-     * than the production system.
+     * AUTHORITATIVE entity list — all downstream writers MUST reference only
+     * these entities. Include ALL domain entities; do NOT include meta-entities
+     * describing the requirements process.
      */
     entities: AutoBeAnalyzeScenarioEntity[];
 
     /**
-     * High-level project features that activate conditional modules.
+     * Features activating conditional modules. DEFAULT IS EMPTY ARRAY [].
      *
      * WARNING: Wrong activation causes cascading hallucination across ALL SRS
-     * files. Each feature adds 2-3 conditional modules that downstream LLMs
-     * MUST fill with content — if the user never requested the feature, those
-     * modules get filled with hallucinated requirements.
-     *
-     * DEFAULT IS EMPTY ARRAY []. Most projects need no features.
-     *
-     * Activation rule: Include ONLY if the user used exact trigger keywords:
+     * files. Include ONLY if user used exact trigger keywords:
      *
-     * - "file-storage": user said "file upload", "attachment", "image upload"
-     * - "real-time": user said "real-time", "WebSocket", "live updates", "chat"
-     * - "external-integration": user said "payment", "Stripe", "OAuth", "email
-     *   service"
+     * - "file-storage": "file upload", "attachment", "image upload"
+     * - "real-time": "real-time", "WebSocket", "live updates", "chat"
+     * - "external-integration": "payment", "Stripe", "OAuth", "email service"
      *
-     * Standard CRUD with auth = features: []. Do NOT activate features based on
-     * inference or general context.
+     * Standard CRUD with auth = []. Do NOT activate based on inference.
      */
     features: FixedAnalyzeTemplateFeature[];
   }

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

@@ -1,69 +1,41 @@
 /**
- * Application interface for the Scenario Review agent.
- *
- * This agent reviews the scenario output against the user's original
- * requirements, checking entity coverage, hallucination, actor classification,
- * relationship completeness, and feature identification accuracy.
+ * Reviews scenario output against user requirements for entity coverage,
+ * hallucination, and consistency.
  */
 export interface IAutoBeAnalyzeScenarioReviewApplication {
   /**
-   * Process scenario review task.
-   *
-   * Reviews the scenario output and provides an approved/rejected verdict with
-   * structured feedback.
-   *
-   * @param props Request containing the review result
+   * Review scenario and provide approved/rejected verdict with structured
+   * feedback.
    */
   process(props: IAutoBeAnalyzeScenarioReviewApplicationProps): void;
 }
 
 export interface IAutoBeAnalyzeScenarioReviewApplicationProps {
   /**
-   * Think before you act.
-   *
-   * Before completing the review, reflect on your analysis:
-   *
-   * - Does every user-mentioned concept have a corresponding entity?
-   * - Are there entities the user never mentioned or implied?
-   * - Are actors correctly classified by identity boundary?
-   * - Are all entity relationships complete and bidirectional?
-   * - Are features correctly identified from user requirements?
+   * Reasoning about your current state: what's missing (preliminary) or what
+   * you accomplished (completion).
    */
   thinking?: string | null;
 
-  /** Review result. */
+  /** Action to perform: submit review verdict. */
   request: IAutoBeAnalyzeScenarioReviewApplicationComplete;
 }
 
 /** Request to complete the scenario review. */
 export interface IAutoBeAnalyzeScenarioReviewApplicationComplete {
-  /** Type discriminator for the request. */
+  /** Type discriminator for completion request. */
   type: "complete";
 
-  /**
-   * Whether the scenario passed review.
-   *
-   * Set to true if all review criteria pass. Set to false if any criterion
-   * fails.
-   */
+  /** Whether the scenario passed review. */
   approved: boolean;
 
   /**
-   * Detailed review feedback.
-   *
-   * When rejecting: describe each issue clearly so the scenario generator can
-   * fix them on the next attempt.
-   *
-   * When approving: may include minor observations.
+   * Detailed review feedback. When rejecting, describe issues clearly for the
+   * next attempt.
    */
   feedback: string;
 
-  /**
-   * Structured issues for targeted scenario regeneration.
-   *
-   * Each issue identifies a specific category and provides a concrete
-   * suggestion for fixing the scenario.
-   */
+  /** Structured issues for targeted scenario regeneration. */
   issues: IAutoBeAnalyzeScenarioReviewApplicationScenarioReviewIssue[];
 }
 

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

@@ -1,70 +1,33 @@
 import { IAutoBePreliminaryGetPreviousAnalysisSections } from "../../common/structures/IAutoBePreliminaryGetPreviousAnalysisSections";
 
 /**
- * Application interface for the Cross-File Section Consistency Review agent.
- *
- * This agent reviews ALL files' section metadata (titles, keywords, purposes)
- * together in a single LLM call, providing cross-file validation for
- * terminology alignment, value consistency, naming conventions, and content
- * deduplication.
- *
- * Unlike the per-file review which checks full content quality, this review
- * only receives lightweight metadata to stay within context limits.
+ * Reviews all files' section metadata in a single call for cross-file
+ * terminology, value, and naming consistency.
  */
 export interface IAutoBeAnalyzeSectionCrossFileReviewApplication {
-  /**
-   * Process cross-file section consistency review or preliminary data requests.
-   *
-   * Reviews section metadata across ALL files in a single call, ensuring
-   * cross-file consistency and uniformity.
-   *
-   * @param props Request containing either preliminary data request or complete
-   *   task
-   */
+  /** Review section metadata across all files for cross-file consistency. */
   process(props: IAutoBeAnalyzeSectionCrossFileReviewApplicationProps): void;
 }
 
 export interface IAutoBeAnalyzeSectionCrossFileReviewApplicationProps {
   /**
-   * Think before you act.
-   *
-   * Before requesting preliminary data or completing your task, reflect on your
-   * current state and explain your reasoning:
-   *
-   * For preliminary requests:
-   *
-   * - What additional context do you need for cross-file validation?
-   *
-   * For completion:
-   *
-   * - Are values and constraints consistent across all files?
-   * - Is terminology aligned across all files?
-   * - Are naming conventions consistent?
-   * - Is there content duplication between files?
+   * Reasoning about your current state: what's missing (preliminary) or what
+   * you accomplished (completion).
    */
   thinking?: string | null;
 
-  /** Type discriminator for the request. */
+  /** Action to perform. Exhausted preliminary types are removed from the union. */
   request:
     | IAutoBeAnalyzeSectionCrossFileReviewApplicationComplete
     | IAutoBePreliminaryGetPreviousAnalysisSections;
 }
 
-/**
- * Request to complete the cross-file section consistency review.
- *
- * Provides per-file review verdicts based on cross-file consistency checks.
- */
+/** Complete the cross-file section consistency review with per-file verdicts. */
 export interface IAutoBeAnalyzeSectionCrossFileReviewApplicationComplete {
-  /** Type discriminator for the request. */
+  /** Type discriminator for completion request. */
   type: "complete";
 
-  /**
-   * Per-file review results.
-   *
-   * Each entry contains the verdict for one file's consistency with other
-   * files.
-   */
+  /** Per-file review results. */
   fileResults: IAutoBeAnalyzeSectionCrossFileReviewApplicationFileResult[];
 }
 
@@ -73,47 +36,25 @@ export interface IAutoBeAnalyzeSectionCrossFileReviewApplicationFileResult {
   /** Index of the file in the scenario's files array. */
   fileIndex: number;
 
-  /**
-   * Whether this file's sections are consistent with other files.
-   *
-   * If true: File's sections are consistent across files. If false: File's
-   * sections must be regenerated with feedback to align with other files.
-   */
+  /** Whether this file's sections are consistent with other files. */
   approved: boolean;
 
   /**
-   * Detailed cross-file consistency feedback for this file.
-   *
-   * Criteria evaluated:
-   *
-   * - Value and constraint consistency across files
-   * - Terminology alignment
-   * - Naming convention consistency
-   * - Content deduplication
-   * - Structural balance
-   *
-   * For rejected files:
-   *
-   * - Specific cross-file inconsistencies identified
-   * - Recommendations for alignment with other files
+   * Cross-file consistency feedback. For rejected files, describe specific
+   * inconsistencies.
    */
   feedback: string;
 
   /**
-   * Structured review issues for targeted rewrites / patches.
-   *
-   * Optional for backward compatibility.
+   * Structured review issues for targeted rewrites. Optional for backward
+   * compatibility.
    */
   issues?: IAutoBeAnalyzeSectionCrossFileReviewApplicationReviewIssue[] | null;
 
   /**
-   * Specific module/unit pairs whose sections have cross-file consistency
-   * issues.
-   *
-   * When rejecting a file, identify EXACTLY which modules and units are
-   * inconsistent with other files. Only these will be regenerated on retry.
-   *
-   * Set to null if all module/units need regeneration, or if approving.
+   * Module/unit pairs with cross-file consistency issues. Only these are
+   * regenerated on retry. Set to null if all module/units need regeneration, or
+   * if approving.
    */
   rejectedModuleUnits:
     | IAutoBeAnalyzeSectionCrossFileReviewApplicationRejectedModuleUnit[]
@@ -125,36 +66,37 @@ export interface IAutoBeAnalyzeSectionCrossFileReviewApplicationRejectedModuleUn
   /** Index of the module section. */
   moduleIndex: number;
 
-  /** Indices of units within this module that need section regeneration. */
+  /** Unit indices needing section regeneration. */
   unitIndices: number[];
 
-  /** Specific feedback for this module/unit group's issues. */
+  /** Feedback for this module/unit group's issues. */
   feedback: string;
 
   /**
-   * Structured issues scoped to this module/unit group.
-   *
-   * Optional for backward compatibility.
+   * Structured issues scoped to this module/unit group. Optional for backward
+   * compatibility.
    */
   issues?: IAutoBeAnalyzeSectionCrossFileReviewApplicationReviewIssue[] | null;
 
   /**
-   * Per-unit mapping of specific section indices that need regeneration.
-   *
-   * Keys are unit indices (from `unitIndices`), values are arrays of section
-   * indices within that unit's `sectionSections[]` that failed review.
-   *
-   * When null/undefined or when a unitIndex is not present as a key, ALL
-   * sections for that unit are regenerated (backward-compatible fallback).
+   * Per-unit mapping of section indices needing regeneration. When null or a
+   * unitIndex is absent, ALL sections for that unit are regenerated.
    */
   sectionIndicesPerUnit?: Record<number, number[]> | null;
 }
 
+/** A specific review issue found during cross-file consistency check. */
 export interface IAutoBeAnalyzeSectionCrossFileReviewApplicationReviewIssue {
+  /** Rule violation code (e.g., "TERM-001", "VALUE-002"). */
   ruleCode: string;
+  /** Module index where the issue was found, or null if file-level. */
   moduleIndex: number | null;
+  /** Unit index where the issue was found, or null if module-level. */
   unitIndex: number | null;
+  /** Section index where the issue was found, or null if unit-level. */
   sectionIndex?: number | null;
+  /** Specific instruction for fixing this issue. */
   fixInstruction: string;
+  /** Supporting evidence from the source text. */
   evidence?: string | null;
 }