feat(agen): detailed guideline about realize phase.

[samchon]

This pull request significantly improves the handling and enforcement of Transformer usage patterns in the agent's realize operation code. It introduces stricter validation and clearer documentation to ensure that Transformer.select() and Transformer.transform() are always used together, preventing common type mismatch errors. The changes also refactor and centralize logic for resolving property transformers, improving maintainability and correctness for composite response types.

Validation and Enforcement of Transformer Usage:

• Added a new validation function validateSelectTransformContract to ensure every Transformer.select() call is paired with a corresponding .transform() call (and vice versa), both in draft and final code. This prevents type mismatches due to improper usage.
• Integrated this validation into both the overall and write orchestrators, so errors are reported if the contract is violated. [1] [2]

Improved Transformer Resolution for Responses:

• Introduced getLocalTransformers, which resolves not only direct matches but also "neighbor" transformers for composite response types (e.g., dashboard endpoints), ensuring all relevant transformers are used for complex DTOs. [1] [2] [3]
• Extracted and centralized the property transformer resolution logic into a new module internal/resolvePropertyTransformer.ts, replacing inline implementations and improving code reuse and clarity. [1] [2] [3]

Documentation and Prompt Updates:

• Updated the realization operation correction prompt to emphasize following the template's Transformer usage, added new error patterns and checklist items for enforcing select/transform pairing, and clarified the most common fixes for type errors. [1] [2] [3] [4]

These changes together provide better guidance and automated enforcement for correct Transformer usage, reducing common errors and improving the reliability of generated code.

[Copilot]

Pull request overview

This PR tightens “realize operation” generation/correction by (1) enforcing correct Transformer usage (select() + transform() pairing), and (2) improving transformer discovery for composite/paginated response DTOs by resolving “neighbor” transformers from response schemas.

Changes:

• Added validateSelectTransformContract to detect mismatched Transformer.select()/Transformer.transform() usage and integrated it into both write and overall correction orchestrators.
• Introduced getLocalTransformers to collect direct and neighbor transformers for complex response types, and centralized property-transformer resolution into internal/resolvePropertyTransformer.ts.
• Updated prompts and added unit tests covering composite/local transformer resolution and the new contract validator.

Reviewed changes

Copilot reviewed 21 out of 27 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
website/public/images/demonstrate/replay-openai-gpt-5.4.png	Adds/updates a demonstration image asset.
website/public/images/demonstrate/replay-openai-gpt-5.4-nano.png	Adds/updates a smaller demonstration image asset.
packages/agent/src/orchestrate/realize/programmers/internal/writeRealizeOperationTemplate.ts	Reuses the centralized property transformer resolver instead of inline logic.
packages/agent/src/orchestrate/realize/programmers/internal/resolvePropertyTransformer.ts	New shared resolver for $ref / array-of-$ref / nullable oneOf cases.
packages/agent/src/orchestrate/realize/programmers/AutoBeRealizeOperationProgrammer.ts	Adds getLocalTransformers and transformer select/transform contract validation.
packages/agent/src/orchestrate/realize/orchestrateRealizeOperationWrite.ts	Uses getLocalTransformers and runs the new contract validator during write.
packages/agent/src/orchestrate/realize/orchestrateRealizeOperationCorrectOverall.ts	Uses getLocalTransformers and runs the new contract validator during overall correction.
packages/agent/prompts/REALIZE_OPERATION_CORRECT.md	Documents the select/transform pairing rule and template-first guidance.
test/src/features/programmer/test_resolve_property_transformer_*.ts	Adds unit tests for the new shared property transformer resolver.
test/src/features/programmer/test_realize_operation_preliminary_*.ts	Adds unit tests for getLocalTransformers behavior (void, pagination, composite, no-match).
test/src/features/programmer/test_realize_operation_validate_contract_*.ts	Adds unit tests for the new select/transform contract validator.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.