CS-10676: Issue-aware ContextBuilder with buildForIssue() by habdelra · Pull Request #4363 · cardstack/boxel

habdelra · 2026-04-08T19:29:23Z

Summary

Add buildForIssue() method to ContextBuilder for the issue-driven agentic loop
New IssueRelationshipLoader interface for traversing issue → project and knowledge relationships without coupling to the realm I/O layer
New types: ValidationResults (parse/lint/evaluate/instantiate/test pipeline), extended AgentContext with validationResults and briefUrl
Rename IssueCard → IssueData, ProjectCard → ProjectData, KnowledgeArticle → KnowledgeArticleData to clarify these are flattened card data, not card instances
Remove testRealmUrl from AgentContext, ContextBuilder.build(), FactoryLoopConfig, system.md template, and all consumers
25 unit tests, all passing; lint clean

Dependency: #4361 must be reviewed and merged first — this branch is based on cs-10671-refactor-darkfactorygts-rename-ticket-issue-trim-unused.

Test plan

🤖 Generated with Claude Code

…ndency fields Rename the Ticket card type to Issue throughout the software-factory package to align with Phase 2's issue-driven loop language. Drop unused fields from both Project (deadline, teamAgents, risks, createdAt) and Issue (relatedTickets, agentNotes, estimatedHours, actualHours). Add blockedBy (linksToMany) and order (NumberField) to Issue for dependency tracking in the upcoming issue scheduler. Updates span 57 files: card definitions, bootstrap, implement loop, context builder, skill loader, tool builder, prompt templates, test fixtures, smoke tests, skills documentation, and all test files. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The factory has a single agent, so the assignedAgent field and the pick-ticket CLI script are unnecessary. Phase 2's IssueScheduler will handle issue selection programmatically. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The card field is @field status, not issueStatus. The old code incorrectly used ticketStatus and the blind rename propagated the error. Also fix "A issue" → "An issue" grammar. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add buildForIssue() to ContextBuilder for the Phase 2 issue-driven loop. Instead of taking pre-loaded project/knowledge, it traverses issue relationships via an injected IssueRelationshipLoader to load project, knowledge articles, and resolved clarification answers automatically. New types: ValidationResults (parse/lint/evaluate/instantiate/test pipeline), ClarificationAnswer, IssueRelationshipLoader interface. AgentContext extended with validationResults, clarifications, briefUrl, and workspaceDir fields. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b61a7be0f4

ℹ️ 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".

packages/software-factory/scripts/lib/factory-context-builder.ts

packages/software-factory/tests/factory-context-builder.test.ts

packages/software-factory/scripts/lib/factory-context-builder.ts

…from buildForIssue - Remove ClarificationAnswer type and clarifications field from AgentContext - Remove extractClarifications helper and loadBlockedBy from IssueRelationshipLoader - Remove testRealmUrl param from buildForIssue (only targetRealmUrl needed) - Remove workspaceDir from buildForIssue params and AgentContext - Remove all related tests; 25 tests pass Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…/KnowledgeArticleData, remove testRealmUrl from AgentContext Card data types renamed to reflect they are flattened data, not card instances. testRealmUrl removed from AgentContext, ContextBuilder.build(), FactoryLoopConfig, and all consumers — test artifacts use the target realm. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

This PR advances the software-factory “Phase 2” groundwork by introducing an issue-driven context builder (buildForIssue) and completing a broad rename/migration from Ticket → Issue across factory runtime schema, tools, prompts, fixtures, and tests.

Changes:

Add ContextBuilder.buildForIssue() plus an IssueRelationshipLoader abstraction and ValidationResults types for inner-loop validation feedback.
Rename factory concepts and artifacts from Ticket → Issue (schema, tools like update_issue, prompts, fixtures, smoke tests, and unit/integration tests).
Remove the pick-ticket script tool and its registry/executor wiring.

Reviewed changes

Copilot reviewed 61 out of 61 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
packages/software-factory/tests/runtime-schema.spec.ts	Update runtime schema test from Ticket → Issue fields.
packages/software-factory/tests/factory-tool-registry.test.ts	Remove assertion for removed `pick-ticket` tool.
packages/software-factory/tests/factory-tool-executor.test.ts	Update realm-search filter type name to Issue.
packages/software-factory/tests/factory-tool-executor.spec.ts	Update schema/tool tests and fixture search assertions for Issue + `update_issue`.
packages/software-factory/tests/factory-tool-executor.integration.test.ts	Update integration query filter type to Issue.
packages/software-factory/tests/factory-tool-builder.test.ts	Rename/update tool building expectations from `update_ticket` → `update_issue`.
packages/software-factory/tests/factory-test-realm.test.ts	Update TestRun relationship options/IDs from ticket → issue naming.
packages/software-factory/tests/factory-target-realm.spec.ts	Update entrypoint bootstrap summary assertions to issue IDs.
packages/software-factory/tests/factory-skill-loader.test.ts	Rename ticket types/helpers to issue types/helpers and update text extraction API.
packages/software-factory/tests/factory-prompt-loader.test.ts	Update prompt interpolation/tests for `issue.*` variables and removed `testRealmUrl` passing.
packages/software-factory/tests/factory-loop.test.ts	Update loop threading tests to use Issue types and remove testRealmUrl threading.
packages/software-factory/tests/factory-implement.test.ts	Update implement tests to Issue and remove testRealmUrl expectations.
packages/software-factory/tests/factory-entrypoint.test.ts	Update entrypoint tests to issue IDs and issue bootstrap summary naming.
packages/software-factory/tests/factory-entrypoint.integration.test.ts	Update integration summary interface and expectations to issue naming.
packages/software-factory/tests/factory-context-builder.test.ts	Add extensive `buildForIssue()` tests + rename ticket-based builder tests to issue-based.
packages/software-factory/tests/factory-brief.test.ts	Update brief normalization fixture path/content to Issue.
packages/software-factory/tests/factory-bootstrap.test.ts	Update bootstrap unit tests to produce Issues and Issue fields (issueId/issueType).
packages/software-factory/tests/factory-bootstrap.spec.ts	Update live-realm bootstrap spec expectations to Issues.
packages/software-factory/tests/factory-agent.test.ts	Update action validation + message assembly expectations to Issue wording.
packages/software-factory/tests/factory-agent.integration.test.ts	Update integration message assertions to Issue IDs.
packages/software-factory/tests/darkfactory.spec.ts	Update Playwright UI expectations to Issue terminology and remove Agent Notes heading check.
packages/software-factory/test-fixtures/darkfactory-adopter/Projects/demo-project.json	Rename scope/success criteria language to issues; remove dropped relationships/fields.
packages/software-factory/test-fixtures/darkfactory-adopter/project-demo.json	Same as above for alternate fixture instance.
packages/software-factory/test-fixtures/darkfactory-adopter/knowledge-article-demo.json	Update onboarding content to issue terminology.
packages/software-factory/test-fixtures/darkfactory-adopter/Issues/issue-001.json	Rename Ticket fields → Issue fields; remove dropped attributes/relationships.
packages/software-factory/test-fixtures/darkfactory-adopter/issue-demo.json	Same as above for alternate fixture instance.
packages/software-factory/test-fixtures/darkfactory-adopter/agent-demo.json	Update agent capabilities text to “issue triage”.
packages/software-factory/src/factory-entrypoint.ts	Rename summary fields to issue naming and adjust nextStep strings.
packages/software-factory/src/factory-bootstrap.ts	Bootstrap Issues instead of Tickets; update active selection/patching logic.
packages/software-factory/scripts/smoke-tests/factory-tools-smoke.ts	Update smoke test tool name lists and realm-search query type to Issue.
packages/software-factory/scripts/smoke-tests/factory-skill-smoke.ts	Rename CLI arg and sample data from ticket → issue.
packages/software-factory/scripts/smoke-tests/factory-prompt-smoke.ts	Update sample context to `issue` and remove `testRealmUrl` field.
packages/software-factory/scripts/smoke-tests/factory-loop-smoke.ts	Update loop smoke fixtures/types to issue naming and remove testRealmUrl from context.
packages/software-factory/scripts/smoke-tests/factory-context-smoke.ts	Update context builder smoke sample data to issues and remove testRealmUrl checks.
packages/software-factory/scripts/smoke-tests/factory-agent-smoke.ts	Update sample context to `issue` and remove `testRealmUrl`.
packages/software-factory/scripts/pick-ticket.ts	Delete `pick-ticket` script implementation.
packages/software-factory/scripts/lib/test-run-types.ts	Rename ticketURL → issueURL in TestRun options types.
packages/software-factory/scripts/lib/test-run-execution.ts	Pass issueURL into test run creation.
packages/software-factory/scripts/lib/test-run-cards.ts	Rename TestRun relationship from ticket → issue.
packages/software-factory/scripts/lib/factory-tool-registry.ts	Remove `pick-ticket` tool manifest.
packages/software-factory/scripts/lib/factory-tool-executor.ts	Remove `pick-ticket` from script file map.
packages/software-factory/scripts/lib/factory-tool-builder.ts	Replace `update_ticket` tool with `update_issue` and schema name Issue.
packages/software-factory/scripts/lib/factory-skill-loader.ts	Rename Ticket types/APIs to Issue and update keyword matching/extraction helpers.
packages/software-factory/scripts/lib/factory-prompt-loader.ts	Update prompt assembly to pass `issue` (and stop passing testRealmUrl).
packages/software-factory/scripts/lib/factory-loop.ts	Update loop config/context threading to Issue and remove testRealmUrl threading.
packages/software-factory/scripts/lib/factory-implement.ts	Rename to Issue throughout; update status update helper; keep schema-loading list updated.
packages/software-factory/scripts/lib/factory-context-builder.ts	Introduce IssueRelationshipLoader + `buildForIssue()` + validationResults/briefUrl wiring.
packages/software-factory/scripts/lib/factory-agent-types.ts	Rename TicketCard→IssueData and add ValidationResults types + new context fields.
packages/software-factory/scripts/lib/factory-agent-tool-use.ts	Stop passing testRealmUrl into system prompt variables.
packages/software-factory/scripts/boxel-search.ts	Update usage string to suggest Issue rather than Ticket.
packages/software-factory/realm/test-results.gts	Rename TestRun relationship field ticket → issue and update UI headings.
packages/software-factory/realm/darkfactory.gts	Rename Ticket → Issue card type; add blockedBy/order; update Project issues query.
packages/software-factory/README.md	Update public docs to reflect Issues rather than Tickets.
packages/software-factory/prompts/ticket-test.md	Switch template vars to `issue.id`.
packages/software-factory/prompts/ticket-iterate.md	Switch “Current Ticket” section to issue variables/label.
packages/software-factory/prompts/ticket-implement.md	Switch “Current Ticket” section/instructions to issue variables/label.
packages/software-factory/package.json	Remove boxel:pick-ticket script.
packages/software-factory/docs/testing-strategy.md	Update terminology and action type docs to Issue.
packages/software-factory/.agents/skills/software-factory-operations/SKILL.md	Update guidance to `update_issue` and Issues folder layout.
packages/software-factory/.agents/skills/boxel-development/references/dev-realm-search.md	Update example type name to Issue and status field name.
packages/software-factory/.agents/skills/boxel-development/references/dev-qunit-testing.md	Update testing rule to “Every issue…”.

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

packages/software-factory/scripts/lib/factory-prompt-loader.ts

packages/software-factory/scripts/lib/factory-agent-tool-use.ts

packages/software-factory/scripts/lib/factory-context-builder.ts

packages/software-factory/scripts/lib/factory-agent-types.ts

packages/software-factory/scripts/lib/factory-implement.ts

packages/software-factory/tests/factory-entrypoint.test.ts

…Data comment Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…ning consumers Completes testRealmUrl removal across the entire codebase: - ToolExecutorConfig, test-run-types, test-run-execution, test-run-cards - factory-implement.ts (derived URL and loop config) - factory-entrypoint.test.ts (ImplementResult stubs) - All tool executor tests, integration tests, and smoke tests - Renamed testRealmUrl → targetRealmUrl in TestRunRealmOptions Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The "allows tool targeting test realm" test is no longer valid since testRealmUrl was removed from ToolExecutorConfig. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

habdelra and others added 5 commits April 8, 2026 14:04

Remove unnecessary "Phase 2" annotations from comments

94ce436

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chatgpt-codex-connector bot reviewed Apr 8, 2026

View reviewed changes

packages/software-factory/scripts/lib/factory-context-builder.ts Show resolved Hide resolved

packages/software-factory/scripts/lib/factory-context-builder.ts Outdated Show resolved Hide resolved

habdelra commented Apr 8, 2026

View reviewed changes

packages/software-factory/tests/factory-context-builder.test.ts Outdated Show resolved Hide resolved

habdelra commented Apr 8, 2026

View reviewed changes

packages/software-factory/scripts/lib/factory-context-builder.ts Outdated Show resolved Hide resolved

habdelra commented Apr 8, 2026

View reviewed changes

packages/software-factory/scripts/lib/factory-context-builder.ts Outdated Show resolved Hide resolved

habdelra and others added 2 commits April 8, 2026 15:44

habdelra requested a review from Copilot April 8, 2026 20:17

Copilot started reviewing on behalf of habdelra April 8, 2026 20:18 View session

Copilot AI reviewed Apr 8, 2026

View reviewed changes

habdelra and others added 3 commits April 8, 2026 16:27

Remove {{testRealmUrl}} from system.md template, fix KnowledgeArticle…

8d95ca4

…Data comment Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Remove test realm test case and fix tool executor allowed list

ff8ecc6

The "allows tool targeting test realm" test is no longer valid since testRealmUrl was removed from ToolExecutorConfig. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

habdelra requested a review from a team April 8, 2026 21:01

lukemelia approved these changes Apr 8, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CS-10676: Issue-aware ContextBuilder with buildForIssue()#4363

CS-10676: Issue-aware ContextBuilder with buildForIssue()#4363
habdelra wants to merge 10 commits intomainfrom
cs-10676-issue-aware-context-builder

habdelra commented Apr 8, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

habdelra commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

habdelra commented Apr 8, 2026 •

edited

Loading