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

[habdelra]

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

• All 25 unit tests pass (factory-context-builder.test.ts)
• buildForIssue loads project from issue relationship
• buildForIssue loads knowledge from issue.relatedKnowledge
• buildForIssue includes validation results when provided (2nd+ iteration), omits on first
• Validation results include step name, file paths, error details, stack traces
• Skill selection and token budget enforcement work with buildForIssue
• Bootstrap issue context includes briefUrl
• Throws on missing project or missing issueLoader
• pnpm lint:js and pnpm lint:format pass
• pnpm lint:types passes (excluding pre-existing ../base/ errors)

🤖 Generated with Claude Code

[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".

[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.