feat: Adopt program wrapper as canonical PTC format - Update to_json_schema/0

[andreasronge]

Summary

Implements issue #59 to adopt the program wrapper as the canonical PTC format, updating to_json_schema/0 to wrap operations in a program property and use the $defs pattern for recursive references.

Changes

• Updated to_json_schema/0 in lib/ptc_runner/schema.ex to return schema with program wrapper using $defs pattern
• All 33 operations now available under $defs.operation.oneOf
• Updated type_to_json_schema/1 to use "#/$defs/operation" for recursive references
• Regenerated priv/ptc_schema.json with new structure
• Updated all schema tests to validate new program wrapper structure
• Added comprehensive test for recursive operations like pipe.steps

Addresses Review Concerns

The review identified a critical issue with $ref handling when wrapping in program. This implementation:

• ✅ Uses the $defs pattern to properly reference operation definitions
• ✅ Updates all $ref values to point to #/$defs/operation
• ✅ Ensures recursive operations validate correctly
• ✅ Maintains backward compatibility with all operation definitions

Testing

• All 299 tests pass, including new tests for program wrapper structure
• Schema sync test verifies priv/ptc_schema.json matches generated schema
• Recursive operations (pipe, let, and, etc.) validated with correct references

Fixes #59

[github-actions]

PR Review: Adopt program wrapper as canonical PTC format - Update to_json_schema/0

Summary

This PR updates to_json_schema/0 to wrap operations in a program property using the $defs pattern, addressing LLM structured output compatibility issues with root-level oneOf. The implementation correctly addresses the critical $ref handling issue identified in the issue review.

What's Good

• Correctly implements $defs pattern: The PR properly addresses the critical issue that $ref: "#" would break after wrapping. All recursive references now correctly use #/$defs/operation.
• Comprehensive test updates: All schema tests updated to validate the new structure, including a new test for recursive operations like pipe.
• Schema file regenerated: priv/ptc_schema.json is properly updated and synchronized with the generated schema.
• Clean implementation: The changes to lib/ptc_runner/schema.ex are minimal and focused - only the wrapper structure and $ref paths were changed.
• All tests pass: The 54 schema tests pass, confirming the implementation is correct.

Issues (Must Fix)

1. Extraneous file committed - .commit_msg.txt

   • Problem: A .commit_msg.txt file has been committed to the repository. This appears to be a temporary file used during commit message generation and should not be tracked.
   • Impact: Pollutes the repository with tooling artifacts.
   • Fix: Remove this file from the PR. Either delete it from the commit or add .commit_msg.txt to .gitignore.
   • Complexity: Mechanical (delete file or amend commit).

2. Missing trailing newline - priv/ptc_schema.json

   • Problem: The JSON file is missing a trailing newline (diff shows \ No newline at end of file). POSIX standard expects text files to end with a newline.
   • Impact: May cause issues with some tools; inconsistent with standard file conventions.
   • Fix: Add a trailing newline to priv/ptc_schema.json.
   • Complexity: Mechanical (add newline at EOF).

Suggestions (Optional)

None. The implementation is clean and focused.

Security

No concerns. This PR only modifies JSON Schema generation structure.

Verdict

Request Changes - The implementation logic is correct and well-tested. However, the extraneous .commit_msg.txt file must be removed before merge. The missing trailing newline should also be fixed as a standard convention.

[andreasronge]

@claude please fix these issues from PR review:

Issue 1: Remove extraneous .commit_msg.txt file

Location: .commit_msg.txt
Problem: A temporary commit message file was accidentally committed to the repository. This is a tooling artifact that should not be tracked in version control.
Fix: Remove the .commit_msg.txt file from the repository and consider adding .commit_msg.txt to .gitignore to prevent future accidental commits.

Issue 2: Add trailing newline to priv/ptc_schema.json

Location: priv/ptc_schema.json:EOF
Problem: The JSON schema file is missing a trailing newline at the end of the file. POSIX standard expects text files to end with a newline character.
Fix: Add a single newline character at the end of priv/ptc_schema.json.

Please fix ALL issues above in a SINGLE commit. Make minimal changes to resolve each issue.

[andreasronge]

Auto-Triage Summary

Decisions Made

#	Issue	Decision	Action
1	Remove extraneous .commit_msg.txt file	FIX_NOW	Included in fix request above
2	Add trailing newline to priv/ptc_schema.json	FIX_NOW	Included in fix request above

Status

• FIX_NOW items: 2 (batched in single fix comment above)
• Issues created: 0
• Items ignored: 0

Rationale

Both issues identified in the review are mechanical fixes that are directly in-scope for this PR:

1. The .commit_msg.txt file is a tooling artifact that was accidentally committed
2. The missing trailing newline violates POSIX standards and should be fixed as part of the schema file update

All issues have been batched into a single fix request to minimize workflow cycles. The PR logic is correct and well-tested; these are minor cleanup items.

[andreasronge]

Summary

All issues from the PR review have been fixed in a single commit.

Changes Made

1. Removed .commit_msg.txt - Deleted the temporary commit message file that was accidentally tracked in the repository
2. Updated .gitignore - Added .commit_msg.txt to prevent future accidental commits of this tooling artifact
3. Fixed trailing newline in priv/ptc_schema.json - Added a POSIX-compliant newline at the end of the JSON schema file

Verification

• All changes committed in: 2e47d58
• Precommit checks passed (format, compilation, credo, tests)
• Changes pushed to branch: claude/issue-59-implementation

[github-actions]

PR Review: feat: Adopt program wrapper as canonical PTC format - Update to_json_schema/0

Summary

This PR correctly updates to_json_schema/0 to wrap operations in a program property using the $defs pattern for proper recursive references. The implementation directly addresses the critical $ref issue identified in the issue review. Schema generation is correct and all tests pass.

What's Good

• Correct $ref handling: The implementation properly uses $defs pattern with #/$defs/operation references, solving the critical recursive reference issue
• Clean structure: The schema now has a proper root object with program property, $defs.operation.oneOf containing all 33 operations
• Comprehensive tests: Tests updated to verify new structure including:
  • Program wrapper structure validation
  • Recursive operation references (pipe, let, and, etc.)
  • Schema sync test ensures priv/ptc_schema.json stays synchronized
• Generated file updated: priv/ptc_schema.json correctly regenerated with new structure
• Minor cleanup: .gitignore updated for .commit_msg.txt (good housekeeping)

Issues (Must Fix)

None. The schema-related changes are complete and self-contained.

Suggestions (Optional)

1. Test helper prompt update - Nice-to-have
   • File: test/support/llm_client.ex:37-42
   • Suggestion: The LLM prompt example shows old format: {"op": "pipe", "steps": [...]}. After issue Adopt program wrapper as canonical PTC format: Update Parser #58 lands (parser update), this example could be updated to show {"program": {"op": "pipe", "steps": [...]}} for consistency with the schema.
   • Recommendation: Out of scope for this PR - should be addressed as part of issue Adopt program wrapper as canonical PTC format: Update Parser #58 (parser update) or a follow-up.

Security

No concerns. This is a schema format change with no security implications.

Verdict

Approve - The implementation is complete, correctly addresses the $ref issue from the review, and all 296 tests pass. The scope is appropriately limited to schema generation, with the parser update handled separately in issue #58.