feat: Surface defaultOptions as AI schema hints for function-form enum fields

[burieberry]

Summary

Enum fields configured with a function-form options callback were previously invisible to AI schema generation — the generator has no model instance at schema-generation time, so it emitted no enum constraint and agents had no guidance. This PR adds a defaultOptions escape hatch: a static array you can pass alongside the function to give the generator a representative set of values, emitted as a non-constraining description hint rather than a hard enum so agents can still accept custom project-defined values that differ from the defaults.

• packages/base/enum.gts — adds defaultOptions?: any[] to the enumField config and stores it as static defaultOptions on the generated class. Only set when options is a function and defaultOptions is a non-empty array; ignored when options is a static array (which already emits a hard enum through the existing path).
• packages/runtime-common/helpers/ai.ts — renames getStaticEnumValues → getEnumValues with an updated return type { values, isDynamic }. For function-form fields with defaultOptions, emits description: "Typical values: …" instead of enum; for static fields, emits the hard enum constraint as before. Empty or absent defaultOptions correctly emits nothing.
• packages/software-factory/realm/kanban-config.gts — wires defaultOptions into all four enum fields (IssueStatusField, IssueTypeField, IssuePriorityField, ProjectStatusField). Also consolidates three near-identical hasProjectFor* type guards into one generic hasProject<S> and extracts the repeated map/filter/fallback logic into a resolveOptions helper.
• packages/software-factory/realm/issue-tracker.gts — consolidates six separate per-field project/issue types into one IssueWithProject, renames configured* helpers to get*, and removes now-redundant single-line wrapper functions.

Tests

• ai-function-generation-test.ts — three new unit tests: rich-object defaultOptions (.value extraction → description hint), bare-primitive defaultOptions (→ description hint), empty defaultOptions (no hint), no defaultOptions (no hint), and static-array options with defaultOptions supplied (description ignored; hard enum emitted).
• runtime-schema.spec.ts — updated integration test: issueType, priority, and status on Issue now assert the expected description hint strings rather than asserting enum is undefined.

Review notes

• defaultOptions is a schema-generation-only hint and is never consulted at render time — the runtime option-resolution logic in get*Options is unchanged.
• The soft-hint design (description vs. hard enum) is deliberate: project-configured option sets can diverge from the defaults, and a hard enum would cause agents to reject valid custom values.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6a1d8ce1ec

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

Preview deployments

• Host staging preview

• Host production preview

Host Test Results

    1 files  +    1      1 suites  +1   1h 58m 32s ⏱️ + 1h 58m 32s
3 139 tests +3 139  3 124 ✅ +3 124  15 💤 +15  0 ❌ ±0 
3 158 runs  +3 158  3 143 ✅ +3 143  15 💤 +15  0 ❌ ±0 

Results for commit 1990daa. ± Comparison against earlier commit 04c175b.

Realm Server Test Results

    1 files  ±0      1 suites  ±0   12m 29s ⏱️ -10s
1 740 tests ±0  1 740 ✅ ±0  0 💤 ±0  0 ❌ ±0 
1 833 runs  ±0  1 833 ✅ ±0  0 💤 ±0  0 ❌ ±0 

Results for commit 1990daa. ± Comparison against earlier commit 04c175b.

[Copilot]

Pull request overview

Adds a defaultOptions escape hatch for function-form enumField options so AI JSON-schema generation can surface “typical values” hints when runtime option resolution depends on a model instance.

Changes:

• Extend enumField to optionally carry static defaultOptions for function-form enums.
• Update AI schema generation to emit either a hard enum (static options) or a soft “Typical values: …” description hint (dynamic options with defaultOptions).
• Refactor Software Factory kanban option resolution helpers and update tests to assert the new hint behavior.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/base/enum.gts	Adds defaultOptions support on enum FieldDef subclasses for function-form options.
packages/runtime-common/helpers/ai.ts	Emits schema hints for dynamic enums and keeps hard enums for static options.
packages/software-factory/realm/kanban-config.gts	Wires defaultOptions into kanban enum fields and consolidates option-resolution helpers.
packages/software-factory/realm/issue-tracker.gts	Updates consumers to use the renamed/consolidated kanban option helpers and type cleanup.
packages/host/tests/unit/ai-function-generation-test.ts	Adds unit tests covering dynamic defaultOptions hinting and static enum behavior.
packages/software-factory/tests/runtime-schema.spec.ts	Updates integration assertions to expect description hints for dynamic enum fields.

---

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