From cfe5ca1fd18dc3923aaab2dbd9824d3c8da63931 Mon Sep 17 00:00:00 2001
From: Hassan Abdel-Rahman <hassan.abdelrahman@gmail.com>
Date: Wed, 8 Apr 2026 14:04:20 -0400
Subject: [PATCH 01/10] =?UTF-8?q?CS-10671:=20Rename=20Ticket=20=E2=86=92?=
 =?UTF-8?q?=20Issue,=20trim=20unused=20fields,=20add=20Phase=202=20depende?=
 =?UTF-8?q?ncy=20fields?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 .../references/dev-qunit-testing.md           |   2 +-
 .../references/dev-realm-search.md            |  12 +-
 .../software-factory-operations/SKILL.md      |  20 +--
 packages/software-factory/README.md           |  12 +-
 .../software-factory/docs/testing-strategy.md |  34 ++---
 .../prompts/ticket-implement.md               |  18 +--
 .../prompts/ticket-iterate.md                 |   8 +-
 .../software-factory/prompts/ticket-test.md   |   2 +-
 .../software-factory/realm/darkfactory.gts    |  77 ++++------
 .../software-factory/realm/test-results.gts   |  10 +-
 .../software-factory/scripts/boxel-search.ts  |   2 +-
 .../scripts/lib/factory-agent-types.ts        |   6 +-
 .../scripts/lib/factory-context-builder.ts    |  14 +-
 .../scripts/lib/factory-implement.ts          |  68 ++++-----
 .../scripts/lib/factory-loop.ts               |   8 +-
 .../scripts/lib/factory-prompt-loader.ts      |   8 +-
 .../scripts/lib/factory-skill-loader.ts       |  81 +++++-----
 .../scripts/lib/factory-tool-builder.ts       |  16 +-
 .../scripts/lib/factory-tool-registry.ts      |   2 +-
 .../scripts/lib/test-run-cards.ts             |   8 +-
 .../scripts/lib/test-run-execution.ts         |   2 +-
 .../scripts/lib/test-run-types.ts             |   4 +-
 .../software-factory/scripts/pick-ticket.ts   |  26 ++--
 .../smoke-tests/factory-agent-smoke.ts        |   4 +-
 .../smoke-tests/factory-context-smoke.ts      |  34 ++---
 .../scripts/smoke-tests/factory-loop-smoke.ts |  12 +-
 .../smoke-tests/factory-prompt-smoke.ts       |   4 +-
 .../smoke-tests/factory-skill-smoke.ts        |  56 +++----
 .../smoke-tests/factory-tools-smoke.ts        |   6 +-
 .../software-factory/src/factory-bootstrap.ts |  81 +++++-----
 .../src/factory-entrypoint.ts                 |  22 +--
 .../ticket-001.json => Issues/issue-001.json} |  11 +-
 .../Projects/demo-project.json                |  10 +-
 .../darkfactory-adopter/agent-demo.json       |   2 +-
 .../{ticket-demo.json => issue-demo.json}     |  11 +-
 .../knowledge-article-demo.json               |   2 +-
 .../darkfactory-adopter/project-demo.json     |  10 +-
 .../tests/darkfactory.spec.ts                 |  11 +-
 .../tests/factory-agent.integration.test.ts   |   6 +-
 .../tests/factory-agent.test.ts               |  18 +--
 .../tests/factory-bootstrap.spec.ts           |  38 ++---
 .../tests/factory-bootstrap.test.ts           |  93 ++++++-----
 .../tests/factory-brief.test.ts               |  10 +-
 .../tests/factory-context-builder.test.ts     |  76 ++++-----
 .../factory-entrypoint.integration.test.ts    |  14 +-
 .../tests/factory-entrypoint.test.ts          |  22 +--
 .../tests/factory-implement.test.ts           |  14 +-
 .../tests/factory-loop.test.ts                |  24 +--
 .../tests/factory-prompt-loader.test.ts       |  86 +++++------
 .../tests/factory-skill-loader.test.ts        | 144 +++++++++---------
 .../tests/factory-target-realm.spec.ts        |  12 +-
 .../tests/factory-test-realm.test.ts          |  62 ++++----
 .../tests/factory-tool-builder.test.ts        |  36 ++---
 .../factory-tool-executor.integration.test.ts |   2 +-
 .../tests/factory-tool-executor.spec.ts       |  46 +++---
 .../tests/factory-tool-executor.test.ts       |   2 +-
 .../tests/runtime-schema.spec.ts              |   6 +-
 57 files changed, 689 insertions(+), 738 deletions(-)
 rename packages/software-factory/test-fixtures/darkfactory-adopter/{Tickets/ticket-001.json => Issues/issue-001.json} (75%)
 rename packages/software-factory/test-fixtures/darkfactory-adopter/{ticket-demo.json => issue-demo.json} (74%)

diff --git a/packages/software-factory/.agents/skills/boxel-development/references/dev-qunit-testing.md b/packages/software-factory/.agents/skills/boxel-development/references/dev-qunit-testing.md
index e8702270457..367a763a186 100644
--- a/packages/software-factory/.agents/skills/boxel-development/references/dev-qunit-testing.md
+++ b/packages/software-factory/.agents/skills/boxel-development/references/dev-qunit-testing.md
@@ -141,5 +141,5 @@ When tests fail, the orchestrator feeds test failure details back to the agent.
 - **All test data lives in browser memory only** — never write to external realms during tests.
 - **Use `import.meta.url`** to resolve card definitions — never hardcode realm URLs.
 - **Use `data-test-*` attributes** for stable test selectors, not CSS classes.
-- **Every ticket must have at least one test file** as `{card-name}.test.gts` co-located with the card definition.
+- **Every issue must have at least one test file** as `{card-name}.test.gts` co-located with the card definition.
 - **Test files live in the target realm** as realm files alongside the card definitions they test.
diff --git a/packages/software-factory/.agents/skills/boxel-development/references/dev-realm-search.md b/packages/software-factory/.agents/skills/boxel-development/references/dev-realm-search.md
index 109c7adf77a..f4c9e53f445 100644
--- a/packages/software-factory/.agents/skills/boxel-development/references/dev-realm-search.md
+++ b/packages/software-factory/.agents/skills/boxel-development/references/dev-realm-search.md
@@ -40,9 +40,9 @@ Use `eq` to match exact field values. You must specify `on` to scope the field t
   "filter": {
     "on": {
       "module": "http://localhost:4201/software-factory/darkfactory",
-      "name": "Ticket"
+      "name": "Issue"
     },
-    "eq": { "ticketStatus": "in_progress" }
+    "eq": { "issueStatus": "in_progress" }
   }
 }
 ```
@@ -226,21 +226,21 @@ You can only filter/sort on fields that exist on the card type. To find which fi
   "commandInput": {
     "codeRef": {
       "module": "http://localhost:4201/software-factory/darkfactory",
-      "name": "Ticket"
+      "name": "Issue"
     }
   }
 }
 ```
 
-2. The result contains `attributes.properties` listing all searchable fields (e.g., `ticketStatus`, `summary`, `priority`).
+2. The result contains `attributes.properties` listing all searchable fields (e.g., `issueStatus`, `summary`, `priority`).
 
 3. Use those field names in your `eq`, `contains`, `range`, or `sort` with the matching `on` type.
 
-The card tools (`update_project`, `update_ticket`, `create_knowledge`, `create_catalog_spec`) also have dynamic JSON schemas in their parameters that list available fields.
+The card tools (`update_project`, `update_issue`, `create_knowledge`, `create_catalog_spec`) also have dynamic JSON schemas in their parameters that list available fields.
 
 ### Inheritance
 
-Filtering on a base card type's fields matches all cards that inherit from it. For example, filtering on `CardDef` fields like `cardTitle` or `cardDescription` finds cards of any type. Filtering on a `Ticket` field like `ticketStatus` finds only Ticket cards (and any subtypes of Ticket).
+Filtering on a base card type's fields matches all cards that inherit from it. For example, filtering on `CardDef` fields like `cardTitle` or `cardDescription` finds cards of any type. Filtering on an `Issue` field like `issueStatus` finds only Issue cards (and any subtypes of Issue).
 
 ### Searching Through Relationship Fields
 
diff --git a/packages/software-factory/.agents/skills/software-factory-operations/SKILL.md b/packages/software-factory/.agents/skills/software-factory-operations/SKILL.md
index 1dc03ce401c..7bcd6583832 100644
--- a/packages/software-factory/.agents/skills/software-factory-operations/SKILL.md
+++ b/packages/software-factory/.agents/skills/software-factory-operations/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: software-factory-operations
-description: Use when implementing cards in a target realm through the factory execution loop — covers the tool-use workflow for searching, writing, testing, and updating tickets via factory tools.
+description: Use when implementing cards in a target realm through the factory execution loop — covers the tool-use workflow for searching, writing, testing, and updating issues via factory tools.
 ---
 
 # Software Factory Operations
@@ -12,7 +12,7 @@ Use this skill when operating inside the factory execution loop. The factory age
 - **Source realm** (`packages/software-factory/realm`)
   Publishes shared modules, briefs, templates, and tracker schema. Never write to this realm.
 - **Target realm** (user-specified, passed to `factory:go`)
-  Receives all generated artifacts: Project, Ticket, KnowledgeArticle, card definitions, card instances, Catalog Spec cards, and QUnit test files.
+  Receives all generated artifacts: Project, Issue, KnowledgeArticle, card definitions, card instances, Catalog Spec cards, and QUnit test files.
 
 ## Available Tools
 
@@ -30,7 +30,7 @@ The agent has these tools during the execution loop. Use them by name — they a
 ### Updating Project State
 
 - `update_project({ path, attributes, relationships? })` — Update a Project card in the target realm. The tool's parameters include a dynamic JSON schema describing available fields — use it to know valid field names and types. The tool auto-constructs the JSON:API document with the correct `adoptsFrom`.
-- `update_ticket({ path, attributes, relationships? })` — Update a Ticket card. Same structured interface with dynamic field schema in the tool parameters.
+- `update_issue({ path, attributes, relationships? })` — Update an Issue card. Same structured interface with dynamic field schema in the tool parameters.
 - `create_knowledge({ path, attributes, relationships? })` — Create or update a KnowledgeArticle card. Same structured interface with dynamic field schema in the tool parameters.
 - `create_catalog_spec({ path, attributes, relationships? })` — Create a Catalog Spec card in the target realm's `Spec/` folder. Makes a card definition discoverable in the Boxel catalog. Same structured interface with dynamic field schema. The tool auto-constructs the document with `adoptsFrom` pointing to `https://cardstack.com/base/spec#Spec`.
 
@@ -60,20 +60,20 @@ Returns `{ status: "ready", result: "<serialized JsonCard with schema>" }`. Pars
 
 ### Control Flow
 
-- `signal_done()` — Signal that the current ticket is complete. Call this only after all implementation and test files have been written.
+- `signal_done()` — Signal that the current issue is complete. Call this only after all implementation and test files have been written.
 - `request_clarification({ message })` — Signal that you cannot proceed and need human input. Describe what is blocking.
 
 ## Required Flow
 
 1. **Inspect before writing.** Use `search_realm` and `read_file` to understand what already exists in the target realm before creating or modifying files.
-2. **Move ticket to `in_progress`.** Use `update_ticket` to set the ticket status before starting implementation.
+2. **Move issue to `in_progress`.** Use `update_issue` to set the issue status before starting implementation.
 3. **Write card definitions** (`.gts`) via `write_file` to the target realm.
 4. **Write card instances** (`.json`) via `write_file` to the target realm.
 5. **Write a Catalog Spec card** (`Spec/<card-name>.json`) for each top-level card defined in the brief. Link sample instances via `linkedExamples`.
-6. **Write `.test.gts` test files** co-located with card definitions via `write_file` to the target realm. Every ticket must have at least one test file.
+6. **Write `.test.gts` test files** co-located with card definitions via `write_file` to the target realm. Every issue must have at least one test file.
 7. **Call `signal_done()`** when all implementation and test files are written. The orchestrator triggers test execution after this.
 8. **If tests fail**, the orchestrator feeds failure details back. Use `read_file` to inspect current state, then `write_file` to fix implementation or test files. Call `signal_done()` again.
-9. **Update ticket state** via `update_ticket` — update notes, acceptance criteria, and related knowledge as work progresses.
+9. **Update issue state** via `update_issue` — update notes, acceptance criteria, and related knowledge as work progresses.
 
 ## Target Realm Artifact Structure
 
@@ -86,11 +86,11 @@ target-realm/
 ├── Spec/
 │   └── card-name.json               # Catalog Spec card
 ├── Test Runs/
-│   └── ticket-slug-1.json           # TestRun card
+│   └── issue-slug-1.json            # TestRun card
 ├── Projects/
 │   └── project-name.json            # Project card
-├── Tickets/
-│   └── ticket-slug.json             # Ticket card
+├── Issues/
+│   └── issue-slug.json              # Issue card
 └── Knowledge Articles/
     └── article-name.json            # KnowledgeArticle card
 ```
diff --git a/packages/software-factory/README.md b/packages/software-factory/README.md
index 9f1def93f5d..fd9cc8e9a64 100644
--- a/packages/software-factory/README.md
+++ b/packages/software-factory/README.md
@@ -7,15 +7,15 @@ The software factory is an automated card-development system that takes a brief
 The factory flow has four phases:
 
 1. **Intake** — Fetch a brief card from a source realm, normalize it into a structured representation
-2. **Bootstrap** — Create a target realm (if needed), populate it with a Project card, Knowledge Articles, and starter Tickets
-3. **Implementation** — An LLM agent picks up the active ticket and uses tool calls to write card definitions (`.gts`), sample instances (`.json`), catalog specs (`Spec/`), and QUnit test files (`.test.gts`) into the target realm
+2. **Bootstrap** — Create a target realm (if needed), populate it with a Project card, Knowledge Articles, and starter Issues
+3. **Implementation** — An LLM agent picks up the active issue and uses tool calls to write card definitions (`.gts`), sample instances (`.json`), catalog specs (`Spec/`), and QUnit test files (`.test.gts`) into the target realm
 4. **Verification** — The orchestrator runs QUnit tests via Playwright in a real browser, collects structured results into a TestRun card, and feeds failures back to the agent for iteration
 
-The agent iterates (implement → test → fix) until tests pass or max iterations are reached. The orchestrator (the "ralph loop") controls iteration count, test execution, and ticket selection deterministically — the LLM handles only the implementation work.
+The agent iterates (implement → test → fix) until tests pass or max iterations are reached. The orchestrator (the "ralph loop") controls iteration count, test execution, and issue selection deterministically — the LLM handles only the implementation work.
 
 ### Realm Roles
 
-- **Source realm** (`packages/software-factory/realm/`) — publishes shared modules, card type definitions (Project, Ticket, KnowledgeArticle, TestRun), briefs, and templates. Never written to by the factory.
+- **Source realm** (`packages/software-factory/realm/`) — publishes shared modules, card type definitions (Project, Issue, KnowledgeArticle, TestRun), briefs, and templates. Never written to by the factory.
 - **Target realm** (user-specified) — receives all generated artifacts: card definitions, instances, specs, test files, and TestRun results.
 - **Fixture realm** (`test-fixtures/`) — disposable test input for development-time verification of the factory itself.
 
@@ -24,7 +24,7 @@ The agent iterates (implement → test → fix) until tests pass or max iteratio
 | Path                  | What it is                                                          |
 | --------------------- | ------------------------------------------------------------------- |
 | `Projects/`           | Project card with objective, scope, success criteria                |
-| `Tickets/`            | Ticket cards tracking implementation work                           |
+| `Issues/`             | Issue cards tracking implementation work                            |
 | `Knowledge Articles/` | Context articles derived from the brief                             |
 | `*.gts`               | Card definition files                                               |
 | `*.test.gts`          | Co-located QUnit test files                                         |
@@ -81,7 +81,7 @@ The `--debug` flag shows LLM prompts, tool calls and their results, and `console
 | Folder / File              | What it is                                                                |
 | -------------------------- | ------------------------------------------------------------------------- |
 | `Projects/`                | A Project card with the brief's objective and success criteria            |
-| `Tickets/`                 | Ticket cards — the active ticket should show status `done`                |
+| `Issues/`                  | Issue cards — the active issue should show status `done`                  |
 | `Knowledge Articles/`      | Context articles derived from the brief                                   |
 | `*.gts`                    | Card definition file(s) for the implemented card                          |
 | `*.test.gts`               | Co-located QUnit test file(s)                                             |
diff --git a/packages/software-factory/docs/testing-strategy.md b/packages/software-factory/docs/testing-strategy.md
index a9c92a0a24b..7c5e648add0 100644
--- a/packages/software-factory/docs/testing-strategy.md
+++ b/packages/software-factory/docs/testing-strategy.md
@@ -35,7 +35,7 @@ The testing strategy assumes three separate realm roles:
   - `packages/software-factory/realm`
   - publishes shared modules, briefs, templates, and other software-factory inputs
 - target realm
-  - the user-selected realm where the factory writes generated tickets, knowledge articles, and implementation artifacts
+  - the user-selected realm where the factory writes generated issues, knowledge articles, and implementation artifacts
 - fixture realm
   - disposable test data used to verify source-realm publishing and target-realm behavior during development
 
@@ -47,7 +47,7 @@ If the source realm includes output-like examples, they should be clearly labele
 
 The factory requires the agent to produce tests alongside implementation code. This is not optional.
 
-Flow per ticket:
+Flow per issue:
 
 1. agent implements the card or feature in the target realm
 2. agent generates QUnit test files co-located with card definitions (`.test.gts`)
@@ -57,9 +57,9 @@ Flow per ticket:
 6. test results are parsed from the QUnit test output, grouped by module into `TestModuleResult` entries, and written back to the TestRun card's `moduleResults` field. Each TestModuleResult has a `moduleRef` (CodeRefField with `module` = test module URL, `name` = "default") and its own `passedCount`/`failedCount` computeds. TestRun's `passedCount`/`failedCount` are rolled up across all TestModuleResults.
 7. if tests fail, the full test output (errors, stack traces) is available on the TestRun card and fed back to the agent
 8. agent iterates on implementation and/or tests until all tests pass
-9. passing TestRun cards serve as durable verification evidence for the ticket, linked to the Project card
+9. passing TestRun cards serve as durable verification evidence for the issue, linked to the Project card
 
-This loop is the primary quality gate. A ticket cannot be marked done without at least one passing TestRun in the target realm.
+This loop is the primary quality gate. A issue cannot be marked done without at least one passing TestRun in the target realm.
 
 ## Core Principle
 
@@ -153,7 +153,7 @@ We are trying to prove that:
 
 - briefs are normalized correctly
 - project artifacts are created correctly
-- ticket state transitions are correct
+- issue state transitions are correct
 - verification gates are enforced
 - reruns resume instead of duplicating work
 - failure paths are handled predictably
@@ -165,7 +165,7 @@ This is the straightforward part.
 Test the `DarkFactory` cards like normal Boxel artifacts:
 
 - `Project`
-- `Ticket`
+- `Issue`
 - `KnowledgeArticle`
 - `AgentProfile`
 
@@ -224,7 +224,7 @@ Examples:
 - a vague brief defaults to thin-MVP planning
 - a missing target realm gets bootstrapped correctly via `/_create-realm` while reusing the public tracker module URL
 - rerunning bootstrap does not create duplicate cards
-- existing `in_progress` tickets are resumed instead of replaced
+- existing `in_progress` issues are resumed instead of replaced
 
 ## Terminology: "Spec" Disambiguation
 
@@ -250,11 +250,11 @@ The agent produces actions using these actual action types:
 - `update_file` — replace the content of an existing file
 - `create_test` — create a QUnit test file co-located with card definitions (`.test.gts`)
 - `update_test` — update an existing QUnit test file
-- `update_ticket` — update the current ticket with notes or status changes
+- `update_issue` — update the current issue with notes or status changes
 - `create_knowledge` — create a knowledge article
 - `invoke_tool` — run a registered tool (search-realm, realm-read, etc.)
 - `request_clarification` — signal that the agent cannot proceed
-- `done` — signal that all work for this ticket is complete
+- `done` — signal that all work for this issue is complete
 
 Then test the loop as a state machine.
 
@@ -272,9 +272,9 @@ Then test the loop as a state machine.
 
 Assertions should be about workflow behavior:
 
-- the right ticket is chosen
+- the right issue is chosen
 - the right state transitions occur
-- failed verification keeps the ticket open
+- failed verification keeps the issue open
 - successful verification advances the loop
 - clarification paths stop correctly
 - retries and resumes are handled correctly
@@ -292,10 +292,10 @@ Suggested acceptance cases:
 1. Sticky Note bootstrap
    - brief URL points to `software-factory/Wiki/sticky-note`
    - target realm is a scratch or temp realm
-   - result is one project, starter knowledge cards, and starter tickets
+   - result is one project, starter knowledge cards, and starter issues
 
 2. Sticky Note first implementation pass
-   - loop executes the first active ticket
+   - loop executes the first active issue
    - one implementation artifact is created (card definition + card instance)
    - one Catalog Spec card is created in the `Spec/` folder
    - one QUnit test file is created co-located with the card definition (`.test.gts`)
@@ -312,7 +312,7 @@ These tests are slower and more brittle, so keep them few and high-signal.
 Avoid tests that depend on:
 
 - exact phrasing of generated text
-- exact ticket wording
+- exact issue wording
 - exact `agentNotes` wording
 - full open-ended model behavior
 
@@ -398,7 +398,7 @@ These are the highest-value early tests:
    - use a dedicated fixture realm, not the published realm itself, for any mutable test setup
 2. brief normalization handles the sticky-note wiki card
 3. target realm bootstrap creates required surfaces in a temp realm
-4. artifact bootstrap creates one project and one `in_progress` ticket
+4. artifact bootstrap creates one project and one `in_progress` issue
 5. rerunning bootstrap does not duplicate artifacts
 6. fake loop test covers success path
 7. fake loop test covers failed verification path
@@ -406,7 +406,7 @@ These are the highest-value early tests:
 
 ## Ticket Mapping
 
-Testing is part of implementation and should stay attached to the current Linear tickets.
+Testing is part of implementation and should stay attached to the current Linear issues.
 
 The current mapping is:
 
@@ -425,7 +425,7 @@ The current mapping is:
 - ~~`CS-10451`~~ _(cancelled — hard-coded verification policy conflicts with phase-2 issue-driven approach where test execution is an issue type, not an orchestrator-enforced gate)_
   - ~~verification-policy unit tests~~
 - `CS-10450`
-  - execution loop implementation, broken into child tickets:
+  - execution loop implementation, broken into child issues:
     - ~~action dispatcher~~ _(replaced by agent-driven tool calls in CS-10568)_
     - context builder (assemble `AgentContext` from skills, realm state) — CS-10567
     - core loop orchestrator (run → test → iterate cycle) — CS-10568
diff --git a/packages/software-factory/prompts/ticket-implement.md b/packages/software-factory/prompts/ticket-implement.md
index beb7741cb93..80130d38eb9 100644
--- a/packages/software-factory/prompts/ticket-implement.md
+++ b/packages/software-factory/prompts/ticket-implement.md
@@ -18,19 +18,19 @@ Success criteria:
 {{content}}
 {{/each}}
 
-# Current Ticket
+# Current Issue
 
-ID: {{ticket.id}}
-Summary: {{ticket.summary}}
-Status: {{ticket.status}}
-Priority: {{ticket.priority}}
+ID: {{issue.id}}
+Summary: {{issue.summary}}
+Status: {{issue.status}}
+Priority: {{issue.priority}}
 
 Description:
-{{ticket.description}}
+{{issue.description}}
 
-{{#if ticket.checklist}}
+{{#if issue.checklist}}
 Checklist:
-{{#each ticket.checklist}}
+{{#each issue.checklist}}
 - [ ] {{.}}
 {{/each}}
 {{/if}}
@@ -54,7 +54,7 @@ You previously invoked the following tools. Use these results to inform your imp
 
 # Instructions
 
-Implement this ticket:
+Implement this issue:
 
 1. Use search_realm and read_file to inspect existing realm state
 2. Use write_file to create or update card definitions (.gts) and/or card instances (.json) in the target realm
diff --git a/packages/software-factory/prompts/ticket-iterate.md b/packages/software-factory/prompts/ticket-iterate.md
index a2516d80982..984953ca766 100644
--- a/packages/software-factory/prompts/ticket-iterate.md
+++ b/packages/software-factory/prompts/ticket-iterate.md
@@ -2,13 +2,13 @@
 
 {{project.objective}}
 
-# Current Ticket
+# Current Issue
 
-ID: {{ticket.id}}
-Summary: {{ticket.summary}}
+ID: {{issue.id}}
+Summary: {{issue.summary}}
 
 Description:
-{{ticket.description}}
+{{issue.description}}
 
 # Previous Attempt (iteration {{iteration}})
 
diff --git a/packages/software-factory/prompts/ticket-test.md b/packages/software-factory/prompts/ticket-test.md
index 9cc9f0563a6..a79c182ed49 100644
--- a/packages/software-factory/prompts/ticket-test.md
+++ b/packages/software-factory/prompts/ticket-test.md
@@ -1,6 +1,6 @@
 # Test Generation
 
-You implemented the following files for ticket {{ticket.id}}:
+You implemented the following files for issue {{issue.id}}:
 
 {{#each implementedFiles}}
 
diff --git a/packages/software-factory/realm/darkfactory.gts b/packages/software-factory/realm/darkfactory.gts
index 25b69f62607..f52808ca441 100644
--- a/packages/software-factory/realm/darkfactory.gts
+++ b/packages/software-factory/realm/darkfactory.gts
@@ -10,12 +10,11 @@ import {
 import StringField from 'https://cardstack.com/base/string';
 import NumberField from 'https://cardstack.com/base/number';
 import DateTimeField from 'https://cardstack.com/base/datetime';
-import DateField from 'https://cardstack.com/base/date';
 import MarkdownField from 'https://cardstack.com/base/markdown';
 import TextAreaField from 'https://cardstack.com/base/text-area';
 import enumField from 'https://cardstack.com/base/enum';
 
-export const TicketStatusField = enumField(StringField, {
+export const IssueStatusField = enumField(StringField, {
   options: [
     { value: 'backlog', label: 'Backlog' },
     { value: 'in_progress', label: 'In Progress' },
@@ -25,7 +24,7 @@ export const TicketStatusField = enumField(StringField, {
   ],
 });
 
-export const TicketPriorityField = enumField(StringField, {
+export const IssuePriorityField = enumField(StringField, {
   options: [
     { value: 'critical', label: 'Critical' },
     { value: 'high', label: 'High' },
@@ -34,7 +33,7 @@ export const TicketPriorityField = enumField(StringField, {
   ],
 });
 
-export const TicketTypeField = enumField(StringField, {
+export const IssueTypeField = enumField(StringField, {
   options: [
     { value: 'feature', label: 'Feature' },
     { value: 'bug', label: 'Bug' },
@@ -241,45 +240,43 @@ export class KnowledgeArticle extends CardDef {
   };
 }
 
-export class Ticket extends CardDef {
-  static displayName = 'Ticket';
+export class Issue extends CardDef {
+  static displayName = 'Issue';
 
-  @field ticketId = contains(StringField);
+  @field issueId = contains(StringField);
   @field summary = contains(StringField);
   @field description = contains(MarkdownField);
-  @field ticketType = contains(TicketTypeField);
-  @field status = contains(TicketStatusField);
-  @field priority = contains(TicketPriorityField);
+  @field issueType = contains(IssueTypeField);
+  @field status = contains(IssueStatusField);
+  @field priority = contains(IssuePriorityField);
   @field project = linksTo(() => Project);
   @field assignedAgent = linksTo(() => AgentProfile);
-  @field relatedTickets = linksToMany(() => Ticket);
+  @field blockedBy = linksToMany(() => Issue);
   @field relatedKnowledge = linksToMany(() => KnowledgeArticle);
   @field acceptanceCriteria = contains(MarkdownField);
-  @field agentNotes = contains(MarkdownField);
-  @field estimatedHours = contains(NumberField);
-  @field actualHours = contains(NumberField);
+  @field order = contains(NumberField);
   @field createdAt = contains(DateTimeField);
   @field updatedAt = contains(DateTimeField);
 
   @field title = contains(StringField, {
-    computeVia: function (this: Ticket) {
+    computeVia: function (this: Issue) {
       return this.cardInfo.name?.trim()?.length
         ? this.cardInfo.name
-        : (this.summary ?? 'Untitled Ticket');
+        : (this.summary ?? 'Untitled Issue');
     },
   });
 
-  static fitted = class Fitted extends Component<typeof Ticket> {
+  static fitted = class Fitted extends Component<typeof Issue> {
     <template>
-      <div class='ticket-card compact'>
+      <div class='issue-card compact'>
         <div class='row'>
-          <strong>{{if @model.ticketId @model.ticketId 'TICKET'}}</strong>
+          <strong>{{if @model.issueId @model.issueId 'ISSUE'}}</strong>
           <span>{{if @model.status @model.status 'backlog'}}</span>
         </div>
-        <div>{{if @model.summary @model.summary 'Untitled Ticket'}}</div>
+        <div>{{if @model.summary @model.summary 'Untitled Issue'}}</div>
       </div>
       <style scoped>
-        .ticket-card {
+        .issue-card {
           display: grid;
           gap: 0.35rem;
         }
@@ -301,15 +298,15 @@ export class Ticket extends CardDef {
 
   static embedded = this.fitted;
 
-  static isolated = class Isolated extends Component<typeof Ticket> {
+  static isolated = class Isolated extends Component<typeof Issue> {
     <template>
       <article class='surface'>
         <header>
           <div class='row'>
-            <strong>{{if @model.ticketId @model.ticketId 'TICKET'}}</strong>
+            <strong>{{if @model.issueId @model.issueId 'ISSUE'}}</strong>
             <span>{{if @model.status @model.status 'backlog'}}</span>
           </div>
-          <h1>{{if @model.summary @model.summary 'Untitled Ticket'}}</h1>
+          <h1>{{if @model.summary @model.summary 'Untitled Issue'}}</h1>
         </header>
         {{#if @model.project}}
           <section>
@@ -329,22 +326,16 @@ export class Ticket extends CardDef {
             <@fields.acceptanceCriteria />
           </section>
         {{/if}}
-        {{#if @model.agentNotes}}
-          <section>
-            <h2>Agent Notes</h2>
-            <@fields.agentNotes />
-          </section>
-        {{/if}}
         {{#if @model.relatedKnowledge.length}}
           <section>
             <h2>Related Knowledge</h2>
             <@fields.relatedKnowledge />
           </section>
         {{/if}}
-        {{#if @model.relatedTickets.length}}
+        {{#if @model.blockedBy.length}}
           <section>
-            <h2>Related Tickets</h2>
-            <@fields.relatedTickets />
+            <h2>Blocked By</h2>
+            <@fields.blockedBy />
           </section>
         {{/if}}
       </article>
@@ -371,28 +362,24 @@ export class Project extends CardDef {
   @field projectCode = contains(StringField);
   @field projectName = contains(StringField);
   @field projectStatus = contains(ProjectStatusField);
-  @field deadline = contains(DateField);
   @field objective = contains(TextAreaField);
   @field scope = contains(MarkdownField);
   @field technicalContext = contains(MarkdownField);
-  @field tickets = linksToMany(() => Ticket, {
+  @field issues = linksToMany(() => Issue, {
     query: {
       filter: {
         on: {
           // @ts-ignore this is not a CJS file, import.meta is allowed
           module: new URL('./darkfactory', import.meta.url).href,
-          name: 'Ticket',
+          name: 'Issue',
         },
         eq: { 'project.id': '$this.id' },
       },
     },
   });
   @field knowledgeBase = linksToMany(() => KnowledgeArticle);
-  @field teamAgents = linksToMany(() => AgentProfile);
   @field successCriteria = contains(MarkdownField);
-  @field risks = contains(MarkdownField);
   @field testArtifactsRealmUrl = contains(StringField);
-  @field createdAt = contains(DateTimeField);
 
   @field title = contains(StringField, {
     computeVia: function (this: Project) {
@@ -492,16 +479,10 @@ export class Project extends CardDef {
             <@fields.successCriteria />
           </section>
         {{/if}}
-        {{#if @model.risks}}
-          <section>
-            <h2>Risks</h2>
-            <@fields.risks />
-          </section>
-        {{/if}}
-        {{#if @model.tickets.length}}
+        {{#if @model.issues.length}}
           <section>
-            <h2>Tickets</h2>
-            <@fields.tickets />
+            <h2>Issues</h2>
+            <@fields.issues />
           </section>
         {{/if}}
         {{#if @model.knowledgeBase.length}}
diff --git a/packages/software-factory/realm/test-results.gts b/packages/software-factory/realm/test-results.gts
index b93f4cd0f8e..9452126507f 100644
--- a/packages/software-factory/realm/test-results.gts
+++ b/packages/software-factory/realm/test-results.gts
@@ -12,7 +12,7 @@ import NumberField from 'https://cardstack.com/base/number';
 import DateTimeField from 'https://cardstack.com/base/datetime';
 import CodeRefField from 'https://cardstack.com/base/code-ref';
 import enumField from 'https://cardstack.com/base/enum';
-import { Project, Ticket } from './darkfactory';
+import { Project, Issue } from './darkfactory';
 
 export const TestRunStatusField = enumField(StringField, {
   options: [
@@ -189,7 +189,7 @@ export class TestRun extends CardDef {
   @field runAt = contains(DateTimeField);
   @field completedAt = contains(DateTimeField);
   @field project = linksTo(() => Project);
-  @field ticket = linksTo(() => Ticket);
+  @field issue = linksTo(() => Issue);
   @field status = contains(TestRunStatusField);
   @field durationMs = contains(NumberField);
   @field moduleResults = containsMany(TestModuleResult);
@@ -338,11 +338,11 @@ export class TestRun extends CardDef {
           </section>
         {{/if}}
 
-        {{#if @model.ticket}}
+        {{#if @model.issue}}
           <section>
-            <h2>Ticket</h2>
+            <h2>Issue</h2>
             <div class='linked-card'>
-              <@fields.ticket @format='embedded' />
+              <@fields.issue @format='embedded' />
             </div>
           </section>
         {{/if}}
diff --git a/packages/software-factory/scripts/boxel-search.ts b/packages/software-factory/scripts/boxel-search.ts
index 86030a0919b..ba8ec56de65 100644
--- a/packages/software-factory/scripts/boxel-search.ts
+++ b/packages/software-factory/scripts/boxel-search.ts
@@ -14,7 +14,7 @@ async function main(): Promise<void> {
   let args = parseArgs(process.argv.slice(2));
   if (typeof args.realm !== 'string') {
     throw new Error(
-      'Usage: npm run boxel:search -- --realm <realm-url> [--type-name Ticket --type-module <module>] [--eq field=value] [--contains field=value]',
+      'Usage: npm run boxel:search -- --realm <realm-url> [--type-name Issue --type-module <module>] [--eq field=value] [--contains field=value]',
     );
   }
 
diff --git a/packages/software-factory/scripts/lib/factory-agent-types.ts b/packages/software-factory/scripts/lib/factory-agent-types.ts
index 6123150c3fb..97395cbd330 100644
--- a/packages/software-factory/scripts/lib/factory-agent-types.ts
+++ b/packages/software-factory/scripts/lib/factory-agent-types.ts
@@ -25,7 +25,7 @@ export const VALID_ACTION_TYPES = [
   'update_file',
   'create_test',
   'update_test',
-  'update_ticket',
+  'update_issue',
   'create_knowledge',
   'invoke_tool',
   'request_clarification',
@@ -66,7 +66,7 @@ export interface ProjectCard {
   [key: string]: unknown;
 }
 
-export interface TicketCard {
+export interface IssueCard {
   id: string;
   [key: string]: unknown;
 }
@@ -120,7 +120,7 @@ export interface ToolResult {
 
 export interface AgentContext {
   project: ProjectCard;
-  ticket: TicketCard;
+  issue: IssueCard;
   knowledge: KnowledgeArticle[];
   skills: ResolvedSkill[];
   /** @deprecated Tools are now provided separately as FactoryTool[] to agent.run(). */
diff --git a/packages/software-factory/scripts/lib/factory-context-builder.ts b/packages/software-factory/scripts/lib/factory-context-builder.ts
index e54b4a5ce01..86882d6e747 100644
--- a/packages/software-factory/scripts/lib/factory-context-builder.ts
+++ b/packages/software-factory/scripts/lib/factory-context-builder.ts
@@ -1,9 +1,9 @@
 import type {
   AgentContext,
+  IssueCard,
   KnowledgeArticle,
   ProjectCard,
   TestResult,
-  TicketCard,
 } from './factory-agent';
 
 import type { ResolvedSkill } from './factory-agent';
@@ -51,22 +51,22 @@ export class ContextBuilder {
    */
   async build(params: {
     project: ProjectCard;
-    ticket: TicketCard;
+    issue: IssueCard;
     knowledge: KnowledgeArticle[];
     targetRealmUrl: string;
     testRealmUrl: string;
     /** Test results from the previous iteration, if any. */
     testResults?: TestResult;
   }): Promise<AgentContext> {
-    let { project, ticket, knowledge, targetRealmUrl, testRealmUrl } = params;
+    let { project, issue, knowledge, targetRealmUrl, testRealmUrl } = params;
 
-    // Step 1: Resolve which skills are needed for this ticket
-    let skillNames = this.skillResolver.resolve(ticket, project);
+    // Step 1: Resolve which skills are needed for this issue
+    let skillNames = this.skillResolver.resolve(issue, project);
 
     // Step 2: Load skill content from disk
     let skills: ResolvedSkill[] = await this.skillLoader.loadAll(
       skillNames,
-      ticket,
+      issue,
     );
 
     // Step 3: Enforce token budget if configured
@@ -75,7 +75,7 @@ export class ContextBuilder {
     // Step 4: Assemble the context
     let context: AgentContext = {
       project,
-      ticket,
+      issue,
       knowledge,
       skills,
       targetRealmUrl,
diff --git a/packages/software-factory/scripts/lib/factory-implement.ts b/packages/software-factory/scripts/lib/factory-implement.ts
index 39f43847508..343f5eae3e5 100644
--- a/packages/software-factory/scripts/lib/factory-implement.ts
+++ b/packages/software-factory/scripts/lib/factory-implement.ts
@@ -16,10 +16,10 @@
 import { resolve } from 'node:path';
 
 import type {
+  IssueCard,
   KnowledgeArticle,
   ProjectCard,
   TestResult,
-  TicketCard,
 } from './factory-agent';
 import {
   resolveFactoryModel,
@@ -118,8 +118,8 @@ export interface ImplementResult {
   toolCallLog: FactoryLoopResult['toolCallLog'];
   testResults?: TestResult;
   message?: string;
-  /** The ticket that was worked on. */
-  ticketId: string;
+  /** The issue that was worked on. */
+  issueId: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -145,7 +145,7 @@ export async function runFactoryImplement(
     authorization: config.authorization,
     fetch: fetchImpl,
   };
-  let { project, ticket, knowledge } = await fetchCardData(
+  let { project, issue, knowledge } = await fetchCardData(
     targetRealmUrl,
     config.bootstrapResult,
     fetchOptions,
@@ -223,7 +223,7 @@ export async function runFactoryImplement(
   };
   let testRunner: TestRunner =
     config.testRunner ??
-    buildTestRunner(targetRealmUrl, ticket, sharedToolCallLog, {
+    buildTestRunner(targetRealmUrl, issue, sharedToolCallLog, {
       authorization: config.authorization,
       fetch: fetchImpl,
       realmServerUrl,
@@ -237,21 +237,21 @@ export async function runFactoryImplement(
     tools,
     testRunner,
     project,
-    ticket,
+    issue,
     knowledge,
     targetRealmUrl,
     testRealmUrl,
     maxIterations: config.maxIterations,
   });
 
-  // 8. Post-loop: update ticket status on success
+  // 8. Post-loop: update issue status on success
   if (loopResult.outcome === 'tests_passed' || loopResult.outcome === 'done') {
     try {
-      await updateTicketStatus(targetRealmUrl, ticket.id, 'done', fetchOptions);
-      console.error('[factory-implement] Updated ticket status to done');
+      await updateIssueStatus(targetRealmUrl, issue.id, 'done', fetchOptions);
+      console.error('[factory-implement] Updated issue status to done');
     } catch (error) {
       console.warn(
-        `[factory-implement] Could not update ticket status: ${
+        `[factory-implement] Could not update issue status: ${
           error instanceof Error ? error.message : String(error)
         }`,
       );
@@ -264,7 +264,7 @@ export async function runFactoryImplement(
     toolCallLog: loopResult.toolCallLog,
     testResults: loopResult.testResults,
     message: loopResult.message,
-    ticketId: ticket.id,
+    issueId: issue.id,
   };
 }
 
@@ -380,7 +380,7 @@ async function fetchCardData(
   fetchOptions: RealmFetchOptions,
 ): Promise<{
   project: ProjectCard;
-  ticket: TicketCard;
+  issue: IssueCard;
   knowledge: KnowledgeArticle[];
 }> {
   // Fetch the project card
@@ -390,10 +390,10 @@ async function fetchCardData(
     fetchOptions,
   );
 
-  // Fetch the active ticket card
-  let ticket = await fetchCard(
+  // Fetch the active issue card
+  let issue = await fetchCard(
     targetRealmUrl,
-    bootstrapResult.activeTicket.id,
+    bootstrapResult.activeIssue.id,
     fetchOptions,
   );
 
@@ -411,7 +411,7 @@ async function fetchCardData(
     }
   }
 
-  return { project, ticket, knowledge };
+  return { project, issue, knowledge };
 }
 
 async function fetchCard(
@@ -459,7 +459,7 @@ interface TestRunnerConfig {
  */
 function buildTestRunner(
   targetRealmUrl: string,
-  ticket: TicketCard,
+  issue: IssueCard,
   toolCallLog: ToolCallEntry[],
   runConfig: TestRunnerConfig,
 ): TestRunner {
@@ -480,7 +480,7 @@ function buildTestRunner(
           {
             testName: 'test-discovery',
             error:
-              'No .test.gts test files found. Every ticket must include at least one test file.',
+              'No .test.gts test files found. Every issue must include at least one test file.',
           },
         ],
         durationMs: 0,
@@ -508,12 +508,12 @@ function buildTestRunner(
       });
     }
 
-    let slug = deriveTicketSlug(ticket.id);
+    let slug = deriveIssueSlug(issue.id);
     let start = Date.now();
 
     try {
       console.error(
-        `[factory-implement] Running test file(s) for ticket: ${slug}`,
+        `[factory-implement] Running test file(s) for issue: ${slug}`,
       );
 
       let handle = await executeTestRunFromRealm({
@@ -666,15 +666,15 @@ async function readTestRunFailures(
 }
 
 // ---------------------------------------------------------------------------
-// Ticket slug derivation
+// Issue slug derivation
 // ---------------------------------------------------------------------------
 
 /**
- * Derive a ticket slug from a ticket ID.
- * e.g., "Tickets/sticky-note-define-core" → "sticky-note-define-core"
+ * Derive an issue slug from an issue ID.
+ * e.g., "Issues/sticky-note-define-core" → "sticky-note-define-core"
  */
-function deriveTicketSlug(ticketId: string): string {
-  let parts = ticketId.split('/');
+function deriveIssueSlug(issueId: string): string {
+  let parts = issueId.split('/');
   return parts[parts.length - 1];
 }
 
@@ -683,19 +683,19 @@ function deriveTicketSlug(ticketId: string): string {
 // ---------------------------------------------------------------------------
 
 /**
- * Update the status field on a ticket card in the target realm.
+ * Update the status field on an issue card in the target realm.
  * Reads the current card, sets the new status, and writes it back.
  */
-async function updateTicketStatus(
+async function updateIssueStatus(
   realmUrl: string,
-  ticketId: string,
+  issueId: string,
   status: string,
   fetchOptions: RealmFetchOptions,
 ): Promise<void> {
-  let result = await readFile(realmUrl, ticketId, fetchOptions);
+  let result = await readFile(realmUrl, issueId, fetchOptions);
   if (!result.ok || !result.document) {
     throw new Error(
-      `Cannot read ticket ${ticketId}: ${result.error ?? 'unknown'}`,
+      `Cannot read issue ${issueId}: ${result.error ?? 'unknown'}`,
     );
   }
 
@@ -707,13 +707,13 @@ async function updateTicketStatus(
 
   let writeResult = await writeFile(
     realmUrl,
-    ticketId,
+    issueId,
     JSON.stringify(doc, null, 2),
     fetchOptions,
   );
   if (!writeResult.ok) {
     throw new Error(
-      `Failed to write ticket ${ticketId}: ${writeResult.error ?? 'unknown'}`,
+      `Failed to write issue ${issueId}: ${writeResult.error ?? 'unknown'}`,
     );
   }
 }
@@ -722,7 +722,7 @@ async function updateTicketStatus(
 // DarkFactory schema loading
 // ---------------------------------------------------------------------------
 
-const DARKFACTORY_CARD_TYPES = ['Project', 'Ticket', 'KnowledgeArticle'];
+const DARKFACTORY_CARD_TYPES = ['Project', 'Issue', 'KnowledgeArticle'];
 
 /** Card types from base that the factory also needs schemas for. */
 const BASE_CARD_TYPES: { module: string; name: string }[] = [
@@ -731,7 +731,7 @@ const BASE_CARD_TYPES: { module: string; name: string }[] = [
 
 /**
  * Fetch JSON schemas for card types the factory uses. Includes both
- * DarkFactory types (Project, Ticket, KnowledgeArticle) from the target
+ * DarkFactory types (Project, Issue, KnowledgeArticle) from the target
  * realm and base types (Spec) from the base realm. Returns a Map
  * suitable for passing to ToolBuilderConfig.cardTypeSchemas.
  */
diff --git a/packages/software-factory/scripts/lib/factory-loop.ts b/packages/software-factory/scripts/lib/factory-loop.ts
index 98b3e3ff630..8451493bcc7 100644
--- a/packages/software-factory/scripts/lib/factory-loop.ts
+++ b/packages/software-factory/scripts/lib/factory-loop.ts
@@ -20,10 +20,10 @@
 
 import type {
   AgentContext,
+  IssueCard,
   KnowledgeArticle,
   ProjectCard,
   TestResult,
-  TicketCard,
 } from './factory-agent';
 
 import type { FactoryTool, ToolCallEntry } from './factory-tool-builder';
@@ -74,7 +74,7 @@ export type TestRunner = () => Promise<TestResult>;
 export interface ContextBuilderLike {
   build(params: {
     project: ProjectCard;
-    ticket: TicketCard;
+    issue: IssueCard;
     knowledge: KnowledgeArticle[];
     targetRealmUrl: string;
     testRealmUrl: string;
@@ -88,7 +88,7 @@ export interface FactoryLoopConfig {
   tools: FactoryTool[];
   testRunner: TestRunner;
   project: ProjectCard;
-  ticket: TicketCard;
+  issue: IssueCard;
   knowledge: KnowledgeArticle[];
   targetRealmUrl: string;
   testRealmUrl: string;
@@ -126,7 +126,7 @@ export async function runFactoryLoop(
     // Build context — includes test results from prior iteration if any
     let context = await contextBuilder.build({
       project: config.project,
-      ticket: config.ticket,
+      issue: config.issue,
       knowledge: config.knowledge,
       targetRealmUrl: config.targetRealmUrl,
       testRealmUrl: config.testRealmUrl,
diff --git a/packages/software-factory/scripts/lib/factory-prompt-loader.ts b/packages/software-factory/scripts/lib/factory-prompt-loader.ts
index 9e8aa19ed77..454f6a7829a 100644
--- a/packages/software-factory/scripts/lib/factory-prompt-loader.ts
+++ b/packages/software-factory/scripts/lib/factory-prompt-loader.ts
@@ -367,7 +367,7 @@ function buildToolResultsData(
 
 /**
  * Assemble the system prompt for a one-shot LLM call.
- * This is the same for all calls within a ticket.
+ * This is the same for all calls within an issue.
  *
  * Uses the tool-use system prompt template (prompts/system.md). Tools are
  * provided natively via the LLM API's tool definitions parameter, not
@@ -405,7 +405,7 @@ export function assembleImplementPrompt(
 
   return loader.load('ticket-implement', {
     project: context.project,
-    ticket: context.ticket,
+    issue: context.issue,
     knowledge: context.knowledge,
     toolResults: toolResultsData.length > 0 ? toolResultsData : undefined,
   });
@@ -418,7 +418,7 @@ export function assembleTestPrompt(options: AssembleTestPromptOptions): string {
   let { context, implementedFiles, loader } = options;
 
   return loader.load('ticket-test', {
-    ticket: context.ticket,
+    issue: context.issue,
     implementedFiles,
   });
 }
@@ -450,7 +450,7 @@ export function assembleIteratePrompt(
 
   return loader.load('ticket-iterate', {
     project: context.project,
-    ticket: context.ticket,
+    issue: context.issue,
     iteration,
     previousActions: previousActionsData,
     testResults: context.testResults
diff --git a/packages/software-factory/scripts/lib/factory-skill-loader.ts b/packages/software-factory/scripts/lib/factory-skill-loader.ts
index 82d74bdc7b9..41884999c6b 100644
--- a/packages/software-factory/scripts/lib/factory-skill-loader.ts
+++ b/packages/software-factory/scripts/lib/factory-skill-loader.ts
@@ -1,7 +1,7 @@
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 
-import type { ProjectCard, ResolvedSkill, TicketCard } from './factory-agent';
+import type { IssueCard, ProjectCard, ResolvedSkill } from './factory-agent';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -42,7 +42,7 @@ const SKILL_PRIORITY: readonly string[] = [
 // Keyword matchers for skill resolution
 // ---------------------------------------------------------------------------
 
-/** Keywords in ticket content that indicate .gts component work. */
+/** Keywords in issue content that indicate .gts component work. */
 const GTS_KEYWORDS = [
   '.gts',
   'component',
@@ -53,7 +53,7 @@ const GTS_KEYWORDS = [
   'FieldDef',
 ];
 
-/** Keywords that indicate factory workflow / delivery tickets. */
+/** Keywords that indicate factory workflow / delivery issues. */
 const FACTORY_WORKFLOW_KEYWORDS = [
   'factory',
   'delivery',
@@ -132,17 +132,17 @@ interface RawSkillData {
 // ---------------------------------------------------------------------------
 
 export interface SkillResolver {
-  resolve(ticket: TicketCard, project: ProjectCard): string[];
+  resolve(issue: IssueCard, project: ProjectCard): string[];
 }
 
 export class DefaultSkillResolver implements SkillResolver {
   /**
-   * Determine which skills to load based on ticket and project context.
+   * Determine which skills to load based on issue and project context.
    *
    * Resolution rules (from the phase-1 plan):
    * 1. boxel-development + boxel-file-structure — always loaded (common case)
-   * 2. ember-best-practices — when ticket involves .gts component code
-   * 3. software-factory-operations — for factory delivery workflow tickets
+   * 2. ember-best-practices — when issue involves .gts component code
+   * 3. software-factory-operations — for factory delivery workflow issues
    * 4. KnowledgeArticle tags can specify additional skills
    *
    * CLI skills (boxel-sync, boxel-track, boxel-watch, boxel-restore,
@@ -150,21 +150,21 @@ export class DefaultSkillResolver implements SkillResolver {
    * tool registry does not include boxel-cli tools (deferred to CS-10520).
    * These skills reference commands the agent cannot invoke.
    */
-  resolve(ticket: TicketCard, project: ProjectCard): string[] {
-    let ticketText = extractTicketText(ticket);
+  resolve(issue: IssueCard, project: ProjectCard): string[] {
+    let issueText = extractIssueText(issue);
     let skills: string[] = ['boxel-development', 'boxel-file-structure'];
 
-    if (matchesAnyKeyword(ticketText, GTS_KEYWORDS)) {
+    if (matchesAnyKeyword(issueText, GTS_KEYWORDS)) {
       skills.push('ember-best-practices');
     }
 
-    if (matchesAnyKeyword(ticketText, FACTORY_WORKFLOW_KEYWORDS)) {
+    if (matchesAnyKeyword(issueText, FACTORY_WORKFLOW_KEYWORDS)) {
       skills.push('software-factory-operations');
     }
 
     // Check for additional skills from knowledge articles on the project
-    // and from related knowledge on the ticket itself.
-    let additionalSkills = extractKnowledgeSkillTags(project, ticket);
+    // and from related knowledge on the issue itself.
+    let additionalSkills = extractKnowledgeSkillTags(project, issue);
     for (let skillName of additionalSkills) {
       if (!skills.includes(skillName)) {
         skills.push(skillName);
@@ -182,8 +182,8 @@ export class DefaultSkillResolver implements SkillResolver {
 // ---------------------------------------------------------------------------
 
 export interface SkillLoaderInterface {
-  load(skillName: string, ticket?: TicketCard): Promise<ResolvedSkill>;
-  loadAll(skillNames: string[], ticket?: TicketCard): Promise<ResolvedSkill[]>;
+  load(skillName: string, issue?: IssueCard): Promise<ResolvedSkill>;
+  loadAll(skillNames: string[], issue?: IssueCard): Promise<ResolvedSkill[]>;
 }
 
 export class SkillLoader implements SkillLoaderInterface {
@@ -206,13 +206,13 @@ export class SkillLoader implements SkillLoaderInterface {
   /**
    * Load a single skill by name.
    * Searches the primary skills directory first, then each fallback directory.
-   * When a ticket is provided, `boxel-development` references are filtered to
-   * only include ticket-relevant files (always applied, not just with a budget).
+   * When an issue is provided, `boxel-development` references are filtered to
+   * only include issue-relevant files (always applied, not just with a budget).
    * Results are cached for the duration of the factory run.
    */
-  async load(skillName: string, ticket?: TicketCard): Promise<ResolvedSkill> {
+  async load(skillName: string, issue?: IssueCard): Promise<ResolvedSkill> {
     let raw = await this.loadRaw(skillName);
-    return toResolvedSkill(raw, ticket);
+    return toResolvedSkill(raw, issue);
   }
 
   /**
@@ -221,13 +221,13 @@ export class SkillLoader implements SkillLoaderInterface {
    */
   async loadAll(
     skillNames: string[],
-    ticket?: TicketCard,
+    issue?: IssueCard,
   ): Promise<ResolvedSkill[]> {
     let results: ResolvedSkill[] = [];
 
     for (let name of skillNames) {
       try {
-        let skill = await this.load(name, ticket);
+        let skill = await this.load(name, issue);
         results.push(skill);
       } catch (error) {
         console.warn(
@@ -347,7 +347,7 @@ export class SkillLoader implements SkillLoaderInterface {
  * fit within the remaining budget.
  *
  * Reference filtering for `boxel-development` is handled at load time by the
- * SkillLoader when a ticket is provided — it is always applied regardless of
+ * SkillLoader when an issue is provided — it is always applied regardless of
  * whether a budget is set.
  */
 export function enforceSkillBudget(
@@ -411,18 +411,15 @@ export function estimateTokens(skill: ResolvedSkill): number {
 
 /**
  * Convert RawSkillData (with named references) to the public ResolvedSkill
- * interface. For `boxel-development`, filters references by ticket relevance
+ * interface. For `boxel-development`, filters references by issue relevance
  * using actual filenames — this happens on every load, not just when a
  * budget is enforced.
  */
-function toResolvedSkill(
-  raw: RawSkillData,
-  ticket?: TicketCard,
-): ResolvedSkill {
+function toResolvedSkill(raw: RawSkillData, issue?: IssueCard): ResolvedSkill {
   let refs = raw.references;
 
-  if (refs && raw.name === 'boxel-development' && ticket) {
-    refs = filterBoxelDevelopmentRefs(refs, ticket);
+  if (refs && raw.name === 'boxel-development' && issue) {
+    refs = filterBoxelDevelopmentRefs(refs, issue);
   }
 
   let refContents =
@@ -437,14 +434,14 @@ function toResolvedSkill(
 
 /**
  * Filter boxel-development references to include only the "always load"
- * references plus those whose keywords match the ticket text.
+ * references plus those whose keywords match the issue text.
  * Uses actual filenames from disk — no index-based reconstruction.
  */
 function filterBoxelDevelopmentRefs(
   refs: NamedReference[],
-  ticket: TicketCard,
+  issue: IssueCard,
 ): NamedReference[] {
-  let ticketText = extractTicketText(ticket);
+  let issueText = extractIssueText(issue);
 
   return refs.filter((ref) => {
     // Always-load refs are always included
@@ -456,14 +453,14 @@ function filterBoxelDevelopmentRefs(
       return true;
     }
 
-    // Check if ticket text matches any keywords for this reference
+    // Check if issue text matches any keywords for this reference
     let keywords = REFERENCE_KEYWORD_MAP[ref.fileName];
-    if (keywords && matchesAnyKeyword(ticketText, keywords)) {
+    if (keywords && matchesAnyKeyword(issueText, keywords)) {
       return true;
     }
 
     // References not in the keyword map (e.g., dev-file-editing.md) are only
-    // loaded when no ticket context is available (handled by the caller).
+    // loaded when no issue context is available (handled by the caller).
     return false;
   });
 }
@@ -473,12 +470,12 @@ function filterBoxelDevelopmentRefs(
 // ---------------------------------------------------------------------------
 
 /**
- * Extract searchable text from a ticket card.
+ * Extract searchable text from an issue card.
  * Concatenates known text fields (id, title, description, tags, labels, etc.)
  * into a single lowercase string for keyword matching.
  */
-export function extractTicketText(ticket: TicketCard): string {
-  let parts: string[] = [ticket.id];
+export function extractIssueText(issue: IssueCard): string {
+  let parts: string[] = [issue.id];
 
   for (let key of [
     'title',
@@ -491,7 +488,7 @@ export function extractTicketText(ticket: TicketCard): string {
     'scope',
     'notes',
   ]) {
-    let value = ticket[key];
+    let value = issue[key];
     if (typeof value === 'string') {
       parts.push(value);
     } else if (Array.isArray(value)) {
@@ -517,17 +514,17 @@ export function extractTicketText(ticket: TicketCard): string {
 /**
  * Extract additional skill names from knowledge articles.
  * Checks both the project's `knowledgeBase` field (Project card schema) and
- * the ticket's `relatedKnowledge` field (Ticket card schema), as well as the
+ * the issue's `relatedKnowledge` field (Issue card schema), as well as the
  * generic `knowledge` field for forward compatibility.
  */
 function extractKnowledgeSkillTags(
   project: ProjectCard,
-  ticket?: TicketCard,
+  issue?: IssueCard,
 ): string[] {
   let articles: unknown[] = [];
 
   // Collect knowledge articles from all known field names
-  for (let source of [project, ticket]) {
+  for (let source of [project, issue]) {
     if (!source) {
       continue;
     }
diff --git a/packages/software-factory/scripts/lib/factory-tool-builder.ts b/packages/software-factory/scripts/lib/factory-tool-builder.ts
index a990364100b..e132e081df2 100644
--- a/packages/software-factory/scripts/lib/factory-tool-builder.ts
+++ b/packages/software-factory/scripts/lib/factory-tool-builder.ts
@@ -118,7 +118,7 @@ export function buildFactoryTools(
   let schemas = config.cardTypeSchemas;
   let cardToolEntries: [string, string, () => FactoryTool][] = [
     ['Project', 'update_project', () => buildUpdateProjectTool(config)],
-    ['Ticket', 'update_ticket', () => buildUpdateTicketTool(config)],
+    ['Issue', 'update_issue', () => buildUpdateIssueTool(config)],
     [
       'KnowledgeArticle',
       'create_knowledge',
@@ -306,14 +306,14 @@ function buildUpdateProjectTool(config: ToolBuilderConfig): FactoryTool {
   };
 }
 
-function buildUpdateTicketTool(config: ToolBuilderConfig): FactoryTool {
-  let schema = resolveCardSchema(config, 'Ticket');
+function buildUpdateIssueTool(config: ToolBuilderConfig): FactoryTool {
+  let schema = resolveCardSchema(config, 'Issue');
   return {
-    name: 'update_ticket',
+    name: 'update_issue',
     description:
-      'Update a ticket card in the target realm. Auth: per-realm JWT.',
+      'Update an issue card in the target realm. Auth: per-realm JWT.',
     parameters: buildCardToolParams(
-      'Realm-relative path to the ticket card (e.g., "Ticket/1.json")',
+      'Realm-relative path to the issue card (e.g., "Issues/1.json")',
       schema,
     ),
     execute: async (args) => {
@@ -325,7 +325,7 @@ function buildUpdateTicketTool(config: ToolBuilderConfig): FactoryTool {
       let realmUrl = config.targetRealmUrl;
       let fetchOptions = buildFetchOptions(config, realmUrl);
       let document = buildCardDocument(
-        'Ticket',
+        'Issue',
         realmUrl,
         attributes,
         relationships,
@@ -432,7 +432,7 @@ function buildRunTestsTool(config: ToolBuilderConfig): FactoryTool {
         slug: {
           type: 'string',
           description:
-            'Ticket slug used to name the test run (e.g., "define-sticky-note-core")',
+            'Issue slug used to name the test run (e.g., "define-sticky-note-core")',
         },
         testNames: {
           type: 'array',
diff --git a/packages/software-factory/scripts/lib/factory-tool-registry.ts b/packages/software-factory/scripts/lib/factory-tool-registry.ts
index 4dcfde90528..e918e0ff38e 100644
--- a/packages/software-factory/scripts/lib/factory-tool-registry.ts
+++ b/packages/software-factory/scripts/lib/factory-tool-registry.ts
@@ -97,7 +97,7 @@ const SCRIPT_TOOLS: ToolManifest[] = [
         name: 'module',
         type: 'string',
         required: false,
-        description: 'Ticket schema module URL',
+        description: 'Issue schema module URL',
       },
     ],
   },
diff --git a/packages/software-factory/scripts/lib/test-run-cards.ts b/packages/software-factory/scripts/lib/test-run-cards.ts
index dd051990012..151329a339c 100644
--- a/packages/software-factory/scripts/lib/test-run-cards.ts
+++ b/packages/software-factory/scripts/lib/test-run-cards.ts
@@ -26,7 +26,7 @@ export async function createTestRun(
     options.testResultsModuleUrl,
     {
       sequenceNumber: seq,
-      ticketURL: options.ticketURL,
+      issueURL: options.issueURL,
       moduleRef: options.moduleRef,
       projectCardUrl: options.projectCardUrl,
     },
@@ -153,13 +153,13 @@ export function buildTestRunCardDocument(
   let relationships:
     | Record<string, { links: { self: string | null } }>
     | undefined;
-  if (options?.projectCardUrl || options?.ticketURL) {
+  if (options?.projectCardUrl || options?.issueURL) {
     relationships = {};
     if (options?.projectCardUrl) {
       relationships.project = { links: { self: options.projectCardUrl } };
     }
-    if (options?.ticketURL) {
-      relationships.ticket = { links: { self: options.ticketURL } };
+    if (options?.issueURL) {
+      relationships.issue = { links: { self: options.issueURL } };
     }
   }
 
diff --git a/packages/software-factory/scripts/lib/test-run-execution.ts b/packages/software-factory/scripts/lib/test-run-execution.ts
index b891c76427f..4a1b68bda04 100644
--- a/packages/software-factory/scripts/lib/test-run-execution.ts
+++ b/packages/software-factory/scripts/lib/test-run-execution.ts
@@ -56,7 +56,7 @@ export async function resolveTestRun(
   let createResult = await createTestRun(options.slug, options.testNames, {
     ...realmOptions,
     sequenceNumber,
-    ticketURL: options.ticketURL,
+    issueURL: options.issueURL,
     projectCardUrl: options.projectCardUrl,
   });
 
diff --git a/packages/software-factory/scripts/lib/test-run-types.ts b/packages/software-factory/scripts/lib/test-run-types.ts
index c8aef707a59..0397158e3c0 100644
--- a/packages/software-factory/scripts/lib/test-run-types.ts
+++ b/packages/software-factory/scripts/lib/test-run-types.ts
@@ -41,7 +41,7 @@ export interface TestRunRealmOptions {
 /** Additional options for creating a new TestRun card. */
 export interface CreateTestRunOptions {
   sequenceNumber?: number;
-  ticketURL?: string;
+  issueURL?: string;
   projectCardUrl?: string;
   moduleRef?: ResolvedCodeRef;
 }
@@ -129,7 +129,7 @@ export interface ExecuteTestRunOptions {
   authorization?: string;
   fetch?: typeof globalThis.fetch;
   forceNew?: boolean;
-  ticketURL?: string;
+  issueURL?: string;
   /** URL to the Project card — used for TestRun relationship. */
   projectCardUrl?: string;
   /** Realm server URL. Required — never inferred from targetRealmUrl. */
diff --git a/packages/software-factory/scripts/pick-ticket.ts b/packages/software-factory/scripts/pick-ticket.ts
index 7892b347ca6..da8d4d2e3d2 100644
--- a/packages/software-factory/scripts/pick-ticket.ts
+++ b/packages/software-factory/scripts/pick-ticket.ts
@@ -8,15 +8,15 @@ import {
   type SearchSort,
 } from './lib/boxel';
 
-type TicketStatus = 'backlog' | 'in_progress' | 'blocked' | 'review' | 'done';
-type TicketPriority = 'critical' | 'high' | 'medium' | 'low';
+type IssueStatus = 'backlog' | 'in_progress' | 'blocked' | 'review' | 'done';
+type IssuePriority = 'critical' | 'high' | 'medium' | 'low';
 
-interface CompactTicket {
+interface CompactIssue {
   id: string;
-  ticketId: string | null;
+  issueId: string | null;
   summary: string | null;
-  status: TicketStatus | null;
-  priority: TicketPriority | null;
+  status: IssueStatus | null;
+  priority: IssuePriority | null;
   project: string | null;
 }
 
@@ -59,7 +59,7 @@ async function main(): Promise<void> {
   let args = parseArgs(process.argv.slice(2));
   if (typeof args.realm !== 'string') {
     throw new Error(
-      'Usage: npm run boxel:pick-ticket -- --realm <realm-url> [--module <ticket-schema-module-url>]',
+      'Usage: npm run boxel:pick-ticket -- --realm <realm-url> [--module <issue-schema-module-url>]',
     );
   }
 
@@ -90,7 +90,7 @@ async function main(): Promise<void> {
     filter: {
       type: {
         module: moduleUrl,
-        name: 'Ticket',
+        name: 'Issue',
       },
       any: statusList.map((status) => ({
         eq: { status },
@@ -102,7 +102,7 @@ async function main(): Promise<void> {
         direction: 'asc',
         on: {
           module: moduleUrl,
-          name: 'Ticket',
+          name: 'Issue',
         },
       },
       {
@@ -110,7 +110,7 @@ async function main(): Promise<void> {
         direction: 'asc',
         on: {
           module: moduleUrl,
-          name: 'Ticket',
+          name: 'Issue',
         },
       },
     ],
@@ -131,9 +131,9 @@ async function main(): Promise<void> {
   }
 
   let results = await searchRealm({ realmUrl, jwt, query });
-  let compact: CompactTicket[] = (results.data ?? []).map((card) => ({
+  let compact: CompactIssue[] = (results.data ?? []).map((card) => ({
     id: card.id,
-    ticketId: stringAttribute(card, 'ticketId'),
+    issueId: stringAttribute(card, 'issueId'),
     summary: stringAttribute(card, 'summary'),
     status: enumAttribute(card, 'status', [
       'backlog',
@@ -153,7 +153,7 @@ async function main(): Promise<void> {
 
   printJson({
     count: compact.length,
-    tickets: compact,
+    issues: compact,
   });
 }
 
diff --git a/packages/software-factory/scripts/smoke-tests/factory-agent-smoke.ts b/packages/software-factory/scripts/smoke-tests/factory-agent-smoke.ts
index 92edfd83ac7..009aeb4042c 100644
--- a/packages/software-factory/scripts/smoke-tests/factory-agent-smoke.ts
+++ b/packages/software-factory/scripts/smoke-tests/factory-agent-smoke.ts
@@ -100,8 +100,8 @@ async function main(): Promise<void> {
       title: 'Smoke Test Project',
       description: 'A trivial project used to verify the factory agent works.',
     },
-    ticket: {
-      id: 'Tickets/smoke-test-hello',
+    issue: {
+      id: 'Issues/smoke-test-hello',
       title: 'Create a hello-world card',
       description:
         'Create a simple HelloWorld card definition that renders "Hello, world!" in its fitted view.',
diff --git a/packages/software-factory/scripts/smoke-tests/factory-context-smoke.ts b/packages/software-factory/scripts/smoke-tests/factory-context-smoke.ts
index 963ee61a305..08760c2aac0 100644
--- a/packages/software-factory/scripts/smoke-tests/factory-context-smoke.ts
+++ b/packages/software-factory/scripts/smoke-tests/factory-context-smoke.ts
@@ -14,7 +14,7 @@ import { parseArgs } from 'node:util';
 import type {
   KnowledgeArticle,
   ProjectCard,
-  TicketCard,
+  IssueCard,
 } from '../lib/factory-agent';
 import { ContextBuilder } from '../lib/factory-context-builder';
 import {
@@ -62,29 +62,29 @@ const SAMPLE_KNOWLEDGE: KnowledgeArticle[] = [
   },
 ];
 
-const SAMPLE_TICKETS: { label: string; ticket: TicketCard }[] = [
+const SAMPLE_ISSUES: { label: string; issue: IssueCard }[] = [
   {
     label: 'Card definition (.gts work)',
-    ticket: {
-      id: 'Tickets/define-sticky-note',
+    issue: {
+      id: 'Issues/define-sticky-note',
       title: 'Define StickyNote card',
       description:
         'Create a .gts card definition for StickyNote with title, body, and color fields. Include fitted and isolated views.',
     },
   },
   {
-    label: 'Factory workflow ticket',
-    ticket: {
-      id: 'Tickets/improve-orchestrator',
+    label: 'Factory workflow issue',
+    issue: {
+      id: 'Issues/improve-orchestrator',
       title: 'Improve factory delivery pipeline',
       description:
-        'Update the factory orchestrator to handle multi-ticket workflows with better error recovery.',
+        'Update the factory orchestrator to handle multi-issue workflows with better error recovery.',
     },
   },
   {
-    label: 'Minimal ticket (base case)',
-    ticket: {
-      id: 'Tickets/add-timestamps',
+    label: 'Minimal issue (base case)',
+    issue: {
+      id: 'Issues/add-timestamps',
       title: 'Add timestamp fields',
       description: 'Add createdAt and updatedAt fields to the card.',
     },
@@ -132,9 +132,9 @@ async function main(): Promise<void> {
   console.log('=== Context Builder Smoke Test ===');
   console.log('');
 
-  for (let { label, ticket } of SAMPLE_TICKETS) {
+  for (let { label, issue } of SAMPLE_ISSUES) {
     console.log(`--- ${label} ---`);
-    console.log(`  Ticket: ${ticket.title}`);
+    console.log(`  Issue: ${issue.title}`);
     console.log('');
 
     // -------------------------------------------------------------------
@@ -143,7 +143,7 @@ async function main(): Promise<void> {
 
     let ctx = await builder.build({
       project: SAMPLE_PROJECT,
-      ticket,
+      issue,
       knowledge: SAMPLE_KNOWLEDGE,
       targetRealmUrl: 'https://example.test/user/target/',
       testRealmUrl: 'https://example.test/user/target-test-artifacts/',
@@ -151,7 +151,7 @@ async function main(): Promise<void> {
 
     console.log('  First pass (no test results):');
     check('project.id set', ctx.project.id === SAMPLE_PROJECT.id);
-    check('ticket.id set', ctx.ticket.id === ticket.id);
+    check('issue.id set', ctx.issue.id === issue.id);
     check(
       `knowledge: ${ctx.knowledge.length} article(s)`,
       ctx.knowledge.length === SAMPLE_KNOWLEDGE.length,
@@ -186,7 +186,7 @@ async function main(): Promise<void> {
 
     let ctxWithResults = await builder.build({
       project: SAMPLE_PROJECT,
-      ticket,
+      issue,
       knowledge: SAMPLE_KNOWLEDGE,
       targetRealmUrl: 'https://example.test/user/target/',
       testRealmUrl: 'https://example.test/user/target-test-artifacts/',
@@ -245,7 +245,7 @@ async function main(): Promise<void> {
 
     let ctx = await builder.build({
       project: SAMPLE_PROJECT,
-      ticket: SAMPLE_TICKETS[0].ticket,
+      issue: SAMPLE_ISSUES[0].issue,
       knowledge: [],
       targetRealmUrl: 'https://example.test/user/target/',
       testRealmUrl: 'https://example.test/user/target-test-artifacts/',
diff --git a/packages/software-factory/scripts/smoke-tests/factory-loop-smoke.ts b/packages/software-factory/scripts/smoke-tests/factory-loop-smoke.ts
index d62810d9b5f..efc547877af 100644
--- a/packages/software-factory/scripts/smoke-tests/factory-loop-smoke.ts
+++ b/packages/software-factory/scripts/smoke-tests/factory-loop-smoke.ts
@@ -16,7 +16,7 @@ import type {
   KnowledgeArticle,
   ProjectCard,
   TestResult,
-  TicketCard,
+  IssueCard,
 } from '../lib/factory-agent';
 
 import type { FactoryTool, ToolCallEntry } from '../lib/factory-tool-builder';
@@ -110,7 +110,7 @@ class MockLoopAgent implements LoopAgent {
 class StubContextBuilder implements ContextBuilderLike {
   async build(params: {
     project: ProjectCard;
-    ticket: TicketCard;
+    issue: IssueCard;
     knowledge: KnowledgeArticle[];
     targetRealmUrl: string;
     testRealmUrl: string;
@@ -118,7 +118,7 @@ class StubContextBuilder implements ContextBuilderLike {
   }): Promise<AgentContext> {
     return {
       project: params.project,
-      ticket: params.ticket,
+      issue: params.issue,
       knowledge: params.knowledge,
       skills: [],
       targetRealmUrl: params.targetRealmUrl,
@@ -137,8 +137,8 @@ const PROJECT: ProjectCard = {
   name: 'Sticky Notes MVP',
 };
 
-const TICKET: TicketCard = {
-  id: 'Tickets/define-sticky-note',
+const ISSUE: IssueCard = {
+  id: 'Issues/define-sticky-note',
   title: 'Define StickyNote card',
   description: 'Create a .gts card definition for StickyNote.',
 };
@@ -186,7 +186,7 @@ function makeBaseConfig(
     tools: TOOLS,
     testRunner: makeTestRunner([]),
     project: PROJECT,
-    ticket: TICKET,
+    issue: ISSUE,
     knowledge: KNOWLEDGE,
     targetRealmUrl: 'https://example.test/target/',
     testRealmUrl: 'https://example.test/target-test-artifacts/',
diff --git a/packages/software-factory/scripts/smoke-tests/factory-prompt-smoke.ts b/packages/software-factory/scripts/smoke-tests/factory-prompt-smoke.ts
index d81a41b8283..cfef5e388f4 100644
--- a/packages/software-factory/scripts/smoke-tests/factory-prompt-smoke.ts
+++ b/packages/software-factory/scripts/smoke-tests/factory-prompt-smoke.ts
@@ -39,8 +39,8 @@ const SAMPLE_CONTEXT: AgentContext = {
       'All tests pass',
     ],
   },
-  ticket: {
-    id: 'Tickets/define-sticky-note-core',
+  issue: {
+    id: 'Issues/define-sticky-note-core',
     summary: 'Define the core StickyNote CardDef',
     status: 'in-progress',
     priority: 'high',
diff --git a/packages/software-factory/scripts/smoke-tests/factory-skill-smoke.ts b/packages/software-factory/scripts/smoke-tests/factory-skill-smoke.ts
index bd58a9c30be..cfd5f5c2834 100644
--- a/packages/software-factory/scripts/smoke-tests/factory-skill-smoke.ts
+++ b/packages/software-factory/scripts/smoke-tests/factory-skill-smoke.ts
@@ -6,7 +6,7 @@
  * Usage:
  *   pnpm smoke:skill
  *   pnpm smoke:skill --max-tokens 8000
- *   pnpm smoke:skill --ticket-text "Create a .gts component with styling"
+ *   pnpm smoke:skill --issue-text "Create a .gts component with styling"
  */
 
 import { parseArgs } from 'node:util';
@@ -17,21 +17,21 @@ import {
   enforceSkillBudget,
   estimateTokens,
 } from '../lib/factory-skill-loader';
-import type { ProjectCard, TicketCard } from '../lib/factory-agent';
+import type { ProjectCard, IssueCard } from '../lib/factory-agent';
 
-const SAMPLE_TICKETS: { label: string; ticket: TicketCard }[] = [
+const SAMPLE_ISSUES: { label: string; issue: IssueCard }[] = [
   {
     label: 'Generic card work (base case)',
-    ticket: {
-      id: 'Tickets/generic',
+    issue: {
+      id: 'Issues/generic',
       title: 'Create a contact card',
       description: 'Build a contact card with name, email, and phone fields.',
     },
   },
   {
     label: '.gts component work (triggers ember-best-practices)',
-    ticket: {
-      id: 'Tickets/gts-component',
+    issue: {
+      id: 'Issues/gts-component',
       title: 'Build a dashboard component',
       description:
         'Create a .gts component for the dashboard with template and styling.',
@@ -39,18 +39,18 @@ const SAMPLE_TICKETS: { label: string; ticket: TicketCard }[] = [
   },
   {
     label: 'Factory workflow (triggers software-factory-operations)',
-    ticket: {
-      id: 'Tickets/factory-workflow',
+    issue: {
+      id: 'Issues/factory-workflow',
       title: 'Improve factory delivery pipeline',
       description:
-        'Update the factory orchestrator to handle multi-ticket workflows.',
+        'Update the factory orchestrator to handle multi-issue workflows.',
     },
   },
   {
     label:
       'Realm sync work (CLI skills excluded — no boxel-cli tools in registry)',
-    ticket: {
-      id: 'Tickets/sync-work',
+    issue: {
+      id: 'Issues/sync-work',
       title: 'Sync and restore workspace',
       description:
         'Sync local workspace changes to staging, then restore a checkpoint.',
@@ -63,7 +63,7 @@ async function main(): Promise<void> {
     args: process.argv.slice(2),
     options: {
       'max-tokens': { type: 'string' },
-      'ticket-text': { type: 'string' },
+      'issue-text': { type: 'string' },
     },
     strict: true,
     allowPositionals: true,
@@ -84,7 +84,7 @@ async function main(): Promise<void> {
     process.exit(1);
   }
 
-  let customTicketText = values['ticket-text'];
+  let customIssueText = values['issue-text'];
 
   let resolver = new DefaultSkillResolver();
   let loader = new SkillLoader();
@@ -92,30 +92,30 @@ async function main(): Promise<void> {
 
   console.log('=== Skill Loader & Resolver Smoke Test ===\n');
 
-  // If custom ticket text is provided, use only that
-  let tickets = customTicketText
+  // If custom issue text is provided, use only that
+  let issues = customIssueText
     ? [
         {
-          label: `Custom: "${customTicketText}"`,
-          ticket: {
-            id: 'Tickets/custom',
-            title: customTicketText,
-            description: customTicketText,
-          } as TicketCard,
+          label: `Custom: "${customIssueText}"`,
+          issue: {
+            id: 'Issues/custom',
+            title: customIssueText,
+            description: customIssueText,
+          } as IssueCard,
         },
       ]
-    : SAMPLE_TICKETS;
+    : SAMPLE_ISSUES;
 
-  for (let { label, ticket } of tickets) {
+  for (let { label, issue } of issues) {
     console.log(`--- ${label} ---`);
-    console.log(`  Ticket: ${ticket.title}`);
+    console.log(`  Issue: ${issue.title}`);
 
     // 1. Resolve
-    let skillNames = resolver.resolve(ticket, project);
+    let skillNames = resolver.resolve(issue, project);
     console.log(`  Resolved skills: [${skillNames.join(', ')}]`);
 
-    // 2. Load (with ticket context for reference filtering)
-    let skills = await loader.loadAll(skillNames, ticket);
+    // 2. Load (with issue context for reference filtering)
+    let skills = await loader.loadAll(skillNames, issue);
     console.log(`  Loaded: ${skills.length}/${skillNames.length} skills`);
 
     for (let skill of skills) {
diff --git a/packages/software-factory/scripts/smoke-tests/factory-tools-smoke.ts b/packages/software-factory/scripts/smoke-tests/factory-tools-smoke.ts
index e56a50cf70f..3ea188dbf7f 100644
--- a/packages/software-factory/scripts/smoke-tests/factory-tools-smoke.ts
+++ b/packages/software-factory/scripts/smoke-tests/factory-tools-smoke.ts
@@ -206,7 +206,7 @@ async function main(): Promise<void> {
 
   let searchResult = await mockExecutor.execute('realm-search', {
     'realm-url': 'https://realms.example.test/user/target/',
-    query: JSON.stringify({ filter: { type: { name: 'Ticket' } } }),
+    query: JSON.stringify({ filter: { type: { name: 'Issue' } } }),
   });
   check('realm-search exitCode=0', searchResult.exitCode === 0);
 
@@ -266,10 +266,10 @@ async function main(): Promise<void> {
   let toolNames = factoryTools.map((t) => t.name);
   console.log(`  Built ${factoryTools.length} tools:`);
   console.log(
-    `    factory: ${toolNames.filter((n) => ['write_file', 'read_file', 'search_realm', 'run_command', 'signal_done', 'request_clarification', 'update_project', 'update_ticket', 'create_knowledge'].includes(n)).join(', ')}`,
+    `    factory: ${toolNames.filter((n) => ['write_file', 'read_file', 'search_realm', 'run_command', 'signal_done', 'request_clarification', 'update_project', 'update_issue', 'create_knowledge'].includes(n)).join(', ')}`,
   );
   console.log(
-    `    registered: ${toolNames.filter((n) => !['write_file', 'read_file', 'search_realm', 'run_command', 'signal_done', 'request_clarification', 'update_project', 'update_ticket', 'create_knowledge'].includes(n)).join(', ')}`,
+    `    registered: ${toolNames.filter((n) => !['write_file', 'read_file', 'search_realm', 'run_command', 'signal_done', 'request_clarification', 'update_project', 'update_issue', 'create_knowledge'].includes(n)).join(', ')}`,
   );
   console.log('');
 
diff --git a/packages/software-factory/src/factory-bootstrap.ts b/packages/software-factory/src/factory-bootstrap.ts
index a24f2c19662..cd71f5dadf8 100644
--- a/packages/software-factory/src/factory-bootstrap.ts
+++ b/packages/software-factory/src/factory-bootstrap.ts
@@ -20,8 +20,8 @@ interface CardDocument {
 export interface FactoryBootstrapResult {
   project: FactoryBootstrapArtifact;
   knowledgeArticles: FactoryBootstrapArtifact[];
-  tickets: FactoryBootstrapArtifact[];
-  activeTicket: FactoryBootstrapArtifact;
+  issues: FactoryBootstrapArtifact[];
+  activeIssue: FactoryBootstrapArtifact;
 }
 
 export interface FactoryBootstrapArtifact {
@@ -57,10 +57,10 @@ export async function bootstrapProjectArtifacts(
     `Knowledge Articles/${slug}-brief-context`,
     `Knowledge Articles/${slug}-agent-onboarding`,
   ];
-  let ticketPaths = [
-    `Tickets/${slug}-define-core`,
-    `Tickets/${slug}-design-views`,
-    `Tickets/${slug}-add-integration`,
+  let issuePaths = [
+    `Issues/${slug}-define-core`,
+    `Issues/${slug}-design-views`,
+    `Issues/${slug}-add-integration`,
   ];
 
   let projectDoc = buildProjectDocument(brief, {
@@ -73,7 +73,7 @@ export async function bootstrapProjectArtifacts(
     darkfactoryModuleUrl,
     now,
   });
-  let ticketDocs = buildTicketDocuments(brief, {
+  let issueDocs = buildIssueDocuments(brief, {
     darkfactoryModuleUrl,
     projectCode,
     slug,
@@ -92,39 +92,39 @@ export async function bootstrapProjectArtifacts(
       createCardIfMissing(targetRealmUrl, path, knowledgeDocs[i], fetchImpl),
     ),
   );
-  let tickets = await Promise.all(
-    ticketPaths.map((path, i) =>
-      createCardIfMissing(targetRealmUrl, path, ticketDocs[i], fetchImpl),
+  let issues = await Promise.all(
+    issuePaths.map((path, i) =>
+      createCardIfMissing(targetRealmUrl, path, issueDocs[i], fetchImpl),
     ),
   );
 
-  let inProgressPath = await hasInProgressTicket(
+  let inProgressPath = await hasInProgressIssue(
     targetRealmUrl,
-    ticketPaths,
+    issuePaths,
     fetchImpl,
   );
 
-  let activeTicket: FactoryBootstrapArtifact;
+  let activeIssue: FactoryBootstrapArtifact;
 
   if (inProgressPath) {
-    let idx = ticketPaths.indexOf(inProgressPath);
-    activeTicket = idx >= 0 ? tickets[idx] : tickets[0];
+    let idx = issuePaths.indexOf(inProgressPath);
+    activeIssue = idx >= 0 ? issues[idx] : issues[0];
   } else {
-    await patchTicketStatus(
+    await patchIssueStatus(
       targetRealmUrl,
-      ticketPaths[0],
+      issuePaths[0],
       'in_progress',
       darkfactoryModuleUrl,
       fetchImpl,
     );
-    activeTicket = tickets[0];
+    activeIssue = issues[0];
   }
 
   return {
     project,
     knowledgeArticles,
-    tickets,
-    activeTicket,
+    issues,
+    activeIssue,
   };
 }
 
@@ -288,7 +288,7 @@ function buildKnowledgeDocuments(
   ];
 }
 
-function buildTicketDocuments(
+function buildIssueDocuments(
   brief: FactoryBrief,
   context: {
     darkfactoryModuleUrl: string;
@@ -298,16 +298,16 @@ function buildTicketDocuments(
     now: string;
   },
 ): CardDocument[] {
-  let ticketTemplates = deriveTicketContent(brief, context.sections);
+  let issueTemplates = deriveIssueContent(brief, context.sections);
 
-  return ticketTemplates.map((template, i) => ({
+  return issueTemplates.map((template, i) => ({
     data: {
       type: 'card' as const,
       attributes: {
-        ticketId: `${context.projectCode}-${i + 1}`,
+        issueId: `${context.projectCode}-${i + 1}`,
         summary: template.summary,
         description: template.description,
-        ticketType: 'feature',
+        issueType: 'feature',
         status: i === 0 ? 'in_progress' : 'backlog',
         priority: i === 0 ? 'high' : 'medium',
         acceptanceCriteria: template.acceptanceCriteria,
@@ -322,23 +322,23 @@ function buildTicketDocuments(
       meta: {
         adoptsFrom: {
           module: context.darkfactoryModuleUrl,
-          name: 'Ticket',
+          name: 'Issue',
         },
       },
     },
   }));
 }
 
-interface TicketTemplate {
+interface IssueTemplate {
   summary: string;
   description: string;
   acceptanceCriteria: string;
 }
 
-function deriveTicketContent(
+function deriveIssueContent(
   brief: FactoryBrief,
   sections: { heading: string; body: string }[],
-): TicketTemplate[] {
+): IssueTemplate[] {
   let namedSections = sections.filter((s) => s.heading);
 
   let coreMechanicsSection = namedSections.find((s) =>
@@ -438,8 +438,7 @@ function buildOnboardingContent(brief: FactoryBrief): string {
     '## How to Work on This Project',
     '',
     '- Use the Project card for scope and success criteria',
-    '- Use Ticket cards for execution — pick the active ticket and implement it',
-    '- Update agent notes on each ticket as you make progress',
+    '- Use Issue cards for execution — pick the active issue and implement it',
     '- Create or update Knowledge Articles when meaningful decisions occur',
   ];
 
@@ -491,12 +490,12 @@ async function createCardIfMissing(
   return { id: cardPath, status: 'created' };
 }
 
-async function hasInProgressTicket(
+async function hasInProgressIssue(
   realmUrl: string,
-  ticketPaths: string[],
+  issuePaths: string[],
   fetchImpl: typeof globalThis.fetch,
 ): Promise<string | null> {
-  for (let path of ticketPaths) {
+  for (let path of issuePaths) {
     let url = new URL(path, realmUrl).href;
     let response = await fetchImpl(url, {
       method: 'GET',
@@ -517,15 +516,15 @@ async function hasInProgressTicket(
   return null;
 }
 
-async function patchTicketStatus(
+async function patchIssueStatus(
   realmUrl: string,
-  ticketPath: string,
+  issuePath: string,
   status: string,
   darkfactoryModuleUrl: string,
   fetchImpl: typeof globalThis.fetch,
 ): Promise<void> {
-  let url = new URL(ticketPath, realmUrl).href;
-  let writeUrl = new URL(`${ticketPath}.json`, realmUrl).href;
+  let url = new URL(issuePath, realmUrl).href;
+  let writeUrl = new URL(`${issuePath}.json`, realmUrl).href;
 
   let getResponse = await fetchImpl(url, {
     method: 'GET',
@@ -539,7 +538,7 @@ async function patchTicketStatus(
   let existing = (await getResponse.json()) as CardDocument;
   existing.data.attributes.status = status;
   existing.data.meta = {
-    adoptsFrom: { module: darkfactoryModuleUrl, name: 'Ticket' },
+    adoptsFrom: { module: darkfactoryModuleUrl, name: 'Issue' },
   };
 
   let patchResponse = await fetchImpl(writeUrl, {
@@ -554,11 +553,11 @@ async function patchTicketStatus(
   if (!patchResponse.ok) {
     let text = await formatErrorResponse(patchResponse);
     throw new Error(
-      `Failed to patch ticket status for ${ticketPath}: HTTP ${patchResponse.status} ${text}`.trim(),
+      `Failed to patch issue status for ${issuePath}: HTTP ${patchResponse.status} ${text}`.trim(),
     );
   }
 
-  await waitForCardToBeReadable(realmUrl, ticketPath, fetchImpl);
+  await waitForCardToBeReadable(realmUrl, issuePath, fetchImpl);
 }
 
 async function waitForCardToBeReadable(
diff --git a/packages/software-factory/src/factory-entrypoint.ts b/packages/software-factory/src/factory-entrypoint.ts
index 2c3234aebfb..9680457d4df 100644
--- a/packages/software-factory/src/factory-entrypoint.ts
+++ b/packages/software-factory/src/factory-entrypoint.ts
@@ -47,8 +47,8 @@ export interface FactoryEntrypointBriefSummary extends FactoryBrief {
 export interface FactoryEntrypointBootstrapSummary {
   projectId: string;
   knowledgeArticleIds: string[];
-  ticketIds: string[];
-  activeTicket: {
+  issueIds: string[];
+  activeIssue: {
     id: string;
     status: string;
   };
@@ -57,7 +57,7 @@ export interface FactoryEntrypointBootstrapSummary {
 export interface FactoryEntrypointImplementSummary {
   outcome: ImplementResult['outcome'];
   iterations: number;
-  ticketId: string;
+  issueId: string;
   message?: string;
   toolCallCount: number;
 }
@@ -262,7 +262,7 @@ export async function runFactoryEntrypoint(
     summary.implement = {
       outcome: implementResult.outcome,
       iterations: implementResult.iterations,
-      ticketId: implementResult.ticketId,
+      issueId: implementResult.issueId,
       message: implementResult.message,
       toolCallCount: implementResult.toolCallLog.length,
     };
@@ -273,7 +273,7 @@ export async function runFactoryEntrypoint(
     summary.result = {
       status: succeeded ? 'completed' : 'failed',
       nextStep: succeeded
-        ? 'advance-to-next-ticket'
+        ? 'advance-to-next-issue'
         : `implement-${implementResult.outcome}`,
     };
   }
@@ -322,7 +322,7 @@ export function buildFactoryEntrypointSummary(
     {
       name: 'bootstrapped-project-artifacts',
       status: 'ok',
-      detail: `project=${artifacts.project.status} tickets=${artifacts.tickets.map((t) => t.status).join(',')}`,
+      detail: `project=${artifacts.project.status} issues=${artifacts.issues.map((t) => t.status).join(',')}`,
     },
   ];
 
@@ -340,10 +340,10 @@ export function buildFactoryEntrypointSummary(
     bootstrap: {
       projectId: artifacts.project.id,
       knowledgeArticleIds: artifacts.knowledgeArticles.map((ka) => ka.id),
-      ticketIds: artifacts.tickets.map((t) => t.id),
-      activeTicket: {
-        id: artifacts.activeTicket.id,
-        status: artifacts.activeTicket.status,
+      issueIds: artifacts.issues.map((t) => t.id),
+      activeIssue: {
+        id: artifacts.activeIssue.id,
+        status: artifacts.activeIssue.status,
       },
     },
     actions,
@@ -352,7 +352,7 @@ export function buildFactoryEntrypointSummary(
       nextStep:
         options.mode === 'bootstrap'
           ? 'bootstrap-target-realm'
-          : 'bootstrap-and-select-active-ticket',
+          : 'bootstrap-and-select-active-issue',
     },
   };
 }
diff --git a/packages/software-factory/test-fixtures/darkfactory-adopter/Tickets/ticket-001.json b/packages/software-factory/test-fixtures/darkfactory-adopter/Issues/issue-001.json
similarity index 75%
rename from packages/software-factory/test-fixtures/darkfactory-adopter/Tickets/ticket-001.json
rename to packages/software-factory/test-fixtures/darkfactory-adopter/Issues/issue-001.json
index 4be0d4cf1f1..b7bca6d2170 100644
--- a/packages/software-factory/test-fixtures/darkfactory-adopter/Tickets/ticket-001.json
+++ b/packages/software-factory/test-fixtures/darkfactory-adopter/Issues/issue-001.json
@@ -2,16 +2,13 @@
   "data": {
     "type": "card",
     "attributes": {
-      "ticketId": "DF-1",
+      "issueId": "DF-1",
       "summary": "Verify public DarkFactory adoption",
       "description": "Render tracker cards from an adopter realm using the public software-factory module URL.",
-      "ticketType": "task",
+      "issueType": "task",
       "status": "in_progress",
       "priority": "high",
-      "acceptanceCriteria": "- [x] Project resolves from public module\n- [x] Ticket resolves from public module\n- [x] Knowledge article link renders",
-      "agentNotes": "Testing the shared DarkFactory module from a fixture realm.",
-      "estimatedHours": 2,
-      "actualHours": 1,
+      "acceptanceCriteria": "- [x] Project resolves from public module\n- [x] Issue resolves from public module\n- [x] Knowledge article link renders",
       "createdAt": "2026-03-16T11:00:00.000Z",
       "updatedAt": "2026-03-16T12:00:00.000Z"
     },
@@ -35,7 +32,7 @@
     "meta": {
       "adoptsFrom": {
         "module": "https://sf.boxel.test/darkfactory",
-        "name": "Ticket"
+        "name": "Issue"
       }
     }
   }
diff --git a/packages/software-factory/test-fixtures/darkfactory-adopter/Projects/demo-project.json b/packages/software-factory/test-fixtures/darkfactory-adopter/Projects/demo-project.json
index ab25bf2d475..b4e99ce52db 100644
--- a/packages/software-factory/test-fixtures/darkfactory-adopter/Projects/demo-project.json
+++ b/packages/software-factory/test-fixtures/darkfactory-adopter/Projects/demo-project.json
@@ -6,21 +6,15 @@
       "projectName": "DarkFactory Adoption Harness",
       "projectStatus": "active",
       "objective": "Prove the public software-factory tracker module can be adopted by an external realm.",
-      "scope": "## Scope\n\n- Render a project\n- Render a ticket\n- Render a knowledge article\n- Verify the project ticket query resolves",
+      "scope": "## Scope\n\n- Render a project\n- Render an issue\n- Render a knowledge article\n- Verify the project issue query resolves",
       "technicalContext": "The fixture realm adopts cards from the public `darkfactory` module URL and runs inside the software-factory Playwright harness.",
-      "successCriteria": "- [x] Public module resolves\n- [x] Adopter instances render\n- [x] Query-backed tickets section shows the linked ticket",
-      "risks": "- Public URL remapping could break module resolution\n- Ticket query may fail if canonical card refs drift"
+      "successCriteria": "- [x] Public module resolves\n- [x] Adopter instances render\n- [x] Query-backed issues section shows the linked issue"
     },
     "relationships": {
       "knowledgeBase.0": {
         "links": {
           "self": "../Knowledge Articles/agent-onboarding"
         }
-      },
-      "teamAgents.0": {
-        "links": {
-          "self": "../Agent Profiles/demo-agent"
-        }
       }
     },
     "meta": {
diff --git a/packages/software-factory/test-fixtures/darkfactory-adopter/agent-demo.json b/packages/software-factory/test-fixtures/darkfactory-adopter/agent-demo.json
index d5b6fb381c4..3fbd8d375b2 100644
--- a/packages/software-factory/test-fixtures/darkfactory-adopter/agent-demo.json
+++ b/packages/software-factory/test-fixtures/darkfactory-adopter/agent-demo.json
@@ -3,7 +3,7 @@
     "type": "card",
     "attributes": {
       "agentId": "codex-darkfactory",
-      "capabilities": ["ticket triage", "ui verification"],
+      "capabilities": ["issue triage", "ui verification"],
       "specialization": "Boxel tracker workflows",
       "notes": "Primary test agent for DarkFactory rendering coverage."
     },
diff --git a/packages/software-factory/test-fixtures/darkfactory-adopter/ticket-demo.json b/packages/software-factory/test-fixtures/darkfactory-adopter/issue-demo.json
similarity index 74%
rename from packages/software-factory/test-fixtures/darkfactory-adopter/ticket-demo.json
rename to packages/software-factory/test-fixtures/darkfactory-adopter/issue-demo.json
index ba8c1c4efcf..a1d80e08f33 100644
--- a/packages/software-factory/test-fixtures/darkfactory-adopter/ticket-demo.json
+++ b/packages/software-factory/test-fixtures/darkfactory-adopter/issue-demo.json
@@ -2,16 +2,13 @@
   "data": {
     "type": "card",
     "attributes": {
-      "ticketId": "DF-1",
+      "issueId": "DF-1",
       "summary": "Verify public DarkFactory adoption",
       "description": "Render tracker cards from an adopter realm using the public software-factory module URL.",
-      "ticketType": "task",
+      "issueType": "task",
       "status": "in_progress",
       "priority": "high",
-      "acceptanceCriteria": "- [x] Project resolves from public module\n- [x] Ticket resolves from public module\n- [x] Knowledge article link renders",
-      "agentNotes": "Testing the shared DarkFactory module from a fixture realm.",
-      "estimatedHours": 2,
-      "actualHours": 1,
+      "acceptanceCriteria": "- [x] Project resolves from public module\n- [x] Issue resolves from public module\n- [x] Knowledge article link renders",
       "createdAt": "2026-03-16T11:00:00.000Z",
       "updatedAt": "2026-03-16T12:00:00.000Z"
     },
@@ -35,7 +32,7 @@
     "meta": {
       "adoptsFrom": {
         "module": "https://sf.boxel.test/darkfactory",
-        "name": "Ticket"
+        "name": "Issue"
       }
     }
   }
diff --git a/packages/software-factory/test-fixtures/darkfactory-adopter/knowledge-article-demo.json b/packages/software-factory/test-fixtures/darkfactory-adopter/knowledge-article-demo.json
index b074e3d66b9..51961f288eb 100644
--- a/packages/software-factory/test-fixtures/darkfactory-adopter/knowledge-article-demo.json
+++ b/packages/software-factory/test-fixtures/darkfactory-adopter/knowledge-article-demo.json
@@ -4,7 +4,7 @@
     "attributes": {
       "articleTitle": "Agent Onboarding",
       "articleType": "onboarding",
-      "content": "# Agent Onboarding\n\nUse the project card for scope, the ticket card for execution, and update notes as you go.",
+      "content": "# Agent Onboarding\n\nUse the project card for scope, the issue card for execution, and update notes as you go.",
       "tags": ["onboarding", "tracker", "tests"],
       "updatedAt": "2026-03-16T12:00:00.000Z"
     },
diff --git a/packages/software-factory/test-fixtures/darkfactory-adopter/project-demo.json b/packages/software-factory/test-fixtures/darkfactory-adopter/project-demo.json
index 58cdd9963d3..212d5e7e993 100644
--- a/packages/software-factory/test-fixtures/darkfactory-adopter/project-demo.json
+++ b/packages/software-factory/test-fixtures/darkfactory-adopter/project-demo.json
@@ -6,21 +6,15 @@
       "projectName": "DarkFactory Adoption Harness",
       "projectStatus": "active",
       "objective": "Prove the public software-factory tracker module can be adopted by an external realm.",
-      "scope": "## Scope\n\n- Render a project\n- Render a ticket\n- Render a knowledge article\n- Verify the project ticket query resolves",
+      "scope": "## Scope\n\n- Render a project\n- Render an issue\n- Render a knowledge article\n- Verify the project issue query resolves",
       "technicalContext": "The fixture realm adopts cards from the public `darkfactory` module URL and runs inside the software-factory Playwright harness.",
-      "successCriteria": "- [x] Public module resolves\n- [x] Adopter instances render\n- [x] Query-backed tickets section shows the linked ticket",
-      "risks": "- Public URL remapping could break module resolution\n- Ticket query may fail if canonical card refs drift"
+      "successCriteria": "- [x] Public module resolves\n- [x] Adopter instances render\n- [x] Query-backed issues section shows the linked issue"
     },
     "relationships": {
       "knowledgeBase.0": {
         "links": {
           "self": "./knowledge-article-demo"
         }
-      },
-      "teamAgents.0": {
-        "links": {
-          "self": "./agent-demo"
-        }
       }
     },
     "meta": {
diff --git a/packages/software-factory/tests/darkfactory.spec.ts b/packages/software-factory/tests/darkfactory.spec.ts
index fcb014bd8f3..c101d7a3a98 100644
--- a/packages/software-factory/tests/darkfactory.spec.ts
+++ b/packages/software-factory/tests/darkfactory.spec.ts
@@ -38,11 +38,11 @@ test('renders a project adopted from the public DarkFactory module', async ({
   await expect(authedPage.getByText('Agent Onboarding')).toBeVisible();
 });
 
-test('renders a ticket adopted from the public DarkFactory module', async ({
+test('renders an issue adopted from the public DarkFactory module', async ({
   authedPage,
   cardURL,
 }) => {
-  await gotoCard(authedPage, cardURL('ticket-demo'));
+  await gotoCard(authedPage, cardURL('issue-demo'));
 
   await expect(
     authedPage.getByRole('heading', {
@@ -58,9 +58,6 @@ test('renders a ticket adopted from the public DarkFactory module', async ({
   await expect(
     authedPage.getByRole('heading', { name: 'Acceptance Criteria' }),
   ).toBeVisible();
-  await expect(
-    authedPage.getByRole('heading', { name: 'Agent Notes' }),
-  ).toBeVisible();
   await expect(
     authedPage.getByRole('heading', { name: 'Related Knowledge' }),
   ).toBeVisible();
@@ -80,7 +77,7 @@ test('renders a knowledge article and agent profile adopted from the public Dark
   ).toBeVisible();
   await expect(
     authedPage.getByText(
-      'Use the project card for scope, the ticket card for execution, and update notes as you go.',
+      'Use the project card for scope, the issue card for execution, and update notes as you go.',
     ),
   ).toBeVisible();
 
@@ -90,7 +87,7 @@ test('renders a knowledge article and agent profile adopted from the public Dark
     authedPage.getByRole('heading', { name: 'codex-darkfactory' }),
   ).toBeVisible({ timeout: 120_000 });
   await expect(authedPage.getByText('Boxel tracker workflows')).toBeVisible();
-  await expect(authedPage.getByText('ticket triage')).toBeVisible();
+  await expect(authedPage.getByText('issue triage')).toBeVisible();
 });
 
 test('renders a DarkFactory card with active projects from the adopter realm', async ({
diff --git a/packages/software-factory/tests/factory-agent.integration.test.ts b/packages/software-factory/tests/factory-agent.integration.test.ts
index 0d943107e7b..f9713841dbb 100644
--- a/packages/software-factory/tests/factory-agent.integration.test.ts
+++ b/packages/software-factory/tests/factory-agent.integration.test.ts
@@ -16,7 +16,7 @@ import {
 function makeMinimalContext(overrides?: Partial<AgentContext>): AgentContext {
   return {
     project: { id: 'Projects/test-project' },
-    ticket: { id: 'Tickets/test-ticket' },
+    issue: { id: 'Issues/test-issue' },
     knowledge: [],
     skills: [],
     tools: [],
@@ -187,8 +187,8 @@ module(
         assert.strictEqual(messages[0].role, 'system');
         assert.strictEqual(messages[1].role, 'user');
         assert.ok(
-          messages[1].content.includes('Tickets/test-ticket'),
-          'user message includes ticket ID',
+          messages[1].content.includes('Issues/test-issue'),
+          'user message includes issue ID',
         );
       } finally {
         await stopServer(server);
diff --git a/packages/software-factory/tests/factory-agent.test.ts b/packages/software-factory/tests/factory-agent.test.ts
index 64eec32508c..b254114e3d9 100644
--- a/packages/software-factory/tests/factory-agent.test.ts
+++ b/packages/software-factory/tests/factory-agent.test.ts
@@ -30,7 +30,7 @@ import {
 function makeMinimalContext(overrides?: Partial<AgentContext>): AgentContext {
   return {
     project: { id: 'Projects/test-project' },
-    ticket: { id: 'Tickets/test-ticket' },
+    issue: { id: 'Issues/test-issue' },
     knowledge: [],
     skills: [],
     tools: [],
@@ -87,7 +87,7 @@ module('factory-agent > validateAgentActions', function () {
         content: 'c',
         realm: 'test',
       },
-      { type: 'update_ticket', content: 'notes' },
+      { type: 'update_issue', content: 'notes' },
       { type: 'create_knowledge', path: 'k.md', content: 'c' },
       { type: 'invoke_tool', tool: 'search-realm' },
       { type: 'request_clarification', content: 'unclear' },
@@ -392,7 +392,7 @@ module('factory-agent > OpenRouterFactoryAgent.buildMessages', function () {
     );
   });
 
-  test('user message includes project and ticket context', function (assert) {
+  test('user message includes project and issue context', function (assert) {
     let agent = new OpenRouterFactoryAgent({
       model: 'anthropic/claude-sonnet-4',
       realmServerUrl: 'https://realms.example.test/',
@@ -400,8 +400,8 @@ module('factory-agent > OpenRouterFactoryAgent.buildMessages', function () {
 
     let ctx = makeMinimalContext({
       project: { id: 'Projects/sticky-note', objective: 'Build sticky notes' },
-      ticket: {
-        id: 'Tickets/define-core',
+      issue: {
+        id: 'Issues/define-core',
         summary: 'Define core card',
         description: 'Create the StickyNote card.',
       },
@@ -409,12 +409,12 @@ module('factory-agent > OpenRouterFactoryAgent.buildMessages', function () {
     let messages = agent.buildMessages(ctx);
 
     assert.ok(
-      messages[1].content.includes('Tickets/define-core'),
-      'user message includes ticket ID',
+      messages[1].content.includes('Issues/define-core'),
+      'user message includes issue ID',
     );
     assert.ok(
       messages[1].content.includes('Define core card'),
-      'user message includes ticket summary',
+      'user message includes issue summary',
     );
   });
 
@@ -536,7 +536,7 @@ module('factory-agent > OpenRouterFactoryAgent.buildMessages', function () {
     let messages = agent.buildMessages(ctx);
 
     assert.ok(
-      messages[1].content.includes('Implement this ticket'),
+      messages[1].content.includes('Implement this issue'),
       'uses implement template',
     );
     assert.ok(
diff --git a/packages/software-factory/tests/factory-bootstrap.spec.ts b/packages/software-factory/tests/factory-bootstrap.spec.ts
index f01bf4b65c7..21deff42b9e 100644
--- a/packages/software-factory/tests/factory-bootstrap.spec.ts
+++ b/packages/software-factory/tests/factory-bootstrap.spec.ts
@@ -76,8 +76,8 @@ test('bootstrap creates card instances and reruns idempotently in a live realm',
   expect(result1.project.id).toBe('Projects/sticky-note-mvp');
   expect(result1.project.status).toBe('created');
   expect(result1.knowledgeArticles).toHaveLength(2);
-  expect(result1.tickets).toHaveLength(3);
-  expect(result1.activeTicket.id).toBe('Tickets/sticky-note-define-core');
+  expect(result1.issues).toHaveLength(3);
+  expect(result1.activeIssue.id).toBe('Issues/sticky-note-define-core');
 
   let projectResponse = await authenticatedFetch(
     realm.cardURL('Projects/sticky-note-mvp'),
@@ -95,31 +95,31 @@ test('bootstrap creates card instances and reruns idempotently in a live realm',
   expect(projectJson.data.meta.adoptsFrom.module).toBe(darkfactoryModuleUrl);
   expect(projectJson.data.meta.adoptsFrom.name).toBe('Project');
 
-  let ticketResponse = await authenticatedFetch(
-    realm.cardURL('Tickets/sticky-note-define-core'),
+  let issueResponse = await authenticatedFetch(
+    realm.cardURL('Issues/sticky-note-define-core'),
     { headers: { Accept: SupportedMimeType.CardSource } },
   );
-  expect(ticketResponse.ok).toBe(true);
-  let ticketJson = (await ticketResponse.json()) as {
+  expect(issueResponse.ok).toBe(true);
+  let issueJson = (await issueResponse.json()) as {
     data: {
-      attributes: { ticketId: string; status: string; summary: string };
+      attributes: { issueId: string; status: string; summary: string };
       meta: { adoptsFrom: { module: string; name: string } };
     };
   };
-  expect(ticketJson.data.attributes.ticketId).toBe('SN-1');
-  expect(ticketJson.data.attributes.status).toBe('in_progress');
-  expect(ticketJson.data.attributes.summary).toContain('Sticky Note');
-  expect(ticketJson.data.meta.adoptsFrom.name).toBe('Ticket');
+  expect(issueJson.data.attributes.issueId).toBe('SN-1');
+  expect(issueJson.data.attributes.status).toBe('in_progress');
+  expect(issueJson.data.attributes.summary).toContain('Sticky Note');
+  expect(issueJson.data.meta.adoptsFrom.name).toBe('Issue');
 
-  let ticket2Response = await authenticatedFetch(
-    realm.cardURL('Tickets/sticky-note-design-views'),
+  let issue2Response = await authenticatedFetch(
+    realm.cardURL('Issues/sticky-note-design-views'),
     { headers: { Accept: SupportedMimeType.CardSource } },
   );
-  expect(ticket2Response.ok).toBe(true);
-  let ticket2Json = (await ticket2Response.json()) as {
+  expect(issue2Response.ok).toBe(true);
+  let issue2Json = (await issue2Response.json()) as {
     data: { attributes: { status: string } };
   };
-  expect(ticket2Json.data.attributes.status).toBe('backlog');
+  expect(issue2Json.data.attributes.status).toBe('backlog');
 
   let contextResponse = await authenticatedFetch(
     realm.cardURL('Knowledge Articles/sticky-note-brief-context'),
@@ -142,9 +142,9 @@ test('bootstrap creates card instances and reruns idempotently in a live realm',
   expect(result2.project.status).toBe('existing');
   expect(result2.knowledgeArticles[0].status).toBe('existing');
   expect(result2.knowledgeArticles[1].status).toBe('existing');
-  expect(result2.tickets[0].status).toBe('existing');
-  expect(result2.tickets[1].status).toBe('existing');
-  expect(result2.tickets[2].status).toBe('existing');
+  expect(result2.issues[0].status).toBe('existing');
+  expect(result2.issues[1].status).toBe('existing');
+  expect(result2.issues[2].status).toBe('existing');
 });
 
 test('bootstrapped project card renders correctly in the browser', async ({
diff --git a/packages/software-factory/tests/factory-bootstrap.test.ts b/packages/software-factory/tests/factory-bootstrap.test.ts
index 90604e03028..77d33f6100c 100644
--- a/packages/software-factory/tests/factory-bootstrap.test.ts
+++ b/packages/software-factory/tests/factory-bootstrap.test.ts
@@ -148,17 +148,17 @@ module('factory-bootstrap', function () {
       assert.strictEqual(result.knowledgeArticles.length, 2);
       assert.strictEqual(result.knowledgeArticles[0].status, 'created');
       assert.strictEqual(result.knowledgeArticles[1].status, 'created');
-      assert.strictEqual(result.tickets.length, 3);
-      assert.strictEqual(result.tickets[0].status, 'created');
-      assert.strictEqual(result.tickets[1].status, 'created');
-      assert.strictEqual(result.tickets[2].status, 'created');
+      assert.strictEqual(result.issues.length, 3);
+      assert.strictEqual(result.issues[0].status, 'created');
+      assert.strictEqual(result.issues[1].status, 'created');
+      assert.strictEqual(result.issues[2].status, 'created');
       assert.strictEqual(
-        result.activeTicket.id,
-        'Tickets/sticky-note-define-core',
+        result.activeIssue.id,
+        'Issues/sticky-note-define-core',
       );
     });
 
-    test('created tickets have correct IDs and structure', async function (assert) {
+    test('created issues have correct IDs and structure', async function (assert) {
       let writtenBodies: Record<string, unknown> = {};
 
       let result = await bootstrapProjectArtifacts(
@@ -173,39 +173,36 @@ module('factory-bootstrap', function () {
         },
       );
 
+      assert.strictEqual(result.issues[0].id, 'Issues/sticky-note-define-core');
       assert.strictEqual(
-        result.tickets[0].id,
-        'Tickets/sticky-note-define-core',
+        result.issues[1].id,
+        'Issues/sticky-note-design-views',
       );
       assert.strictEqual(
-        result.tickets[1].id,
-        'Tickets/sticky-note-design-views',
-      );
-      assert.strictEqual(
-        result.tickets[2].id,
-        'Tickets/sticky-note-add-integration',
+        result.issues[2].id,
+        'Issues/sticky-note-add-integration',
       );
 
-      let ticket1 = writtenBodies['Tickets/sticky-note-define-core'] as {
+      let issue1 = writtenBodies['Issues/sticky-note-define-core'] as {
         data: {
-          attributes: { ticketId: string; status: string; summary: string };
+          attributes: { issueId: string; status: string; summary: string };
         };
       };
-      assert.strictEqual(ticket1.data.attributes.ticketId, 'SN-1');
-      assert.strictEqual(ticket1.data.attributes.status, 'in_progress');
-      assert.true(ticket1.data.attributes.summary.includes('Sticky Note'));
+      assert.strictEqual(issue1.data.attributes.issueId, 'SN-1');
+      assert.strictEqual(issue1.data.attributes.status, 'in_progress');
+      assert.true(issue1.data.attributes.summary.includes('Sticky Note'));
 
-      let ticket2 = writtenBodies['Tickets/sticky-note-design-views'] as {
-        data: { attributes: { ticketId: string; status: string } };
+      let issue2 = writtenBodies['Issues/sticky-note-design-views'] as {
+        data: { attributes: { issueId: string; status: string } };
       };
-      assert.strictEqual(ticket2.data.attributes.ticketId, 'SN-2');
-      assert.strictEqual(ticket2.data.attributes.status, 'backlog');
+      assert.strictEqual(issue2.data.attributes.issueId, 'SN-2');
+      assert.strictEqual(issue2.data.attributes.status, 'backlog');
 
-      let ticket3 = writtenBodies['Tickets/sticky-note-add-integration'] as {
-        data: { attributes: { ticketId: string; status: string } };
+      let issue3 = writtenBodies['Issues/sticky-note-add-integration'] as {
+        data: { attributes: { issueId: string; status: string } };
       };
-      assert.strictEqual(ticket3.data.attributes.ticketId, 'SN-3');
-      assert.strictEqual(ticket3.data.attributes.status, 'backlog');
+      assert.strictEqual(issue3.data.attributes.issueId, 'SN-3');
+      assert.strictEqual(issue3.data.attributes.status, 'backlog');
     });
 
     test('created project has correct content from brief', async function (assert) {
@@ -310,7 +307,7 @@ module('factory-bootstrap', function () {
       );
     });
 
-    test('ticket descriptions derive from brief sections', async function (assert) {
+    test('issue descriptions derive from brief sections', async function (assert) {
       let writtenBodies: Record<string, unknown> = {};
 
       await bootstrapProjectArtifacts(stickyNoteBrief, targetRealmUrl, {
@@ -321,22 +318,22 @@ module('factory-bootstrap', function () {
         }),
       });
 
-      let ticket1 = writtenBodies['Tickets/sticky-note-define-core'] as {
+      let issue1 = writtenBodies['Issues/sticky-note-define-core'] as {
         data: { attributes: { description: string } };
       };
       assert.true(
-        ticket1.data.attributes.description.includes(
+        issue1.data.attributes.description.includes(
           'drafting, review, and reuse',
         ),
-        'first ticket description derived from Core Mechanics section',
+        'first issue description derived from Core Mechanics section',
       );
 
-      let ticket3 = writtenBodies['Tickets/sticky-note-add-integration'] as {
+      let issue3 = writtenBodies['Issues/sticky-note-add-integration'] as {
         data: { attributes: { description: string } };
       };
       assert.true(
-        ticket3.data.attributes.description.includes('Document'),
-        'third ticket description derived from Integration Points section',
+        issue3.data.attributes.description.includes('Document'),
+        'third issue description derived from Integration Points section',
       );
     });
 
@@ -350,7 +347,7 @@ module('factory-bootstrap', function () {
           darkfactoryModuleUrl,
           fetch: buildMockFetch(fetchCalls, {
             allExist: true,
-            existingTicketStatus: 'in_progress',
+            existingIssueStatus: 'in_progress',
           }),
         },
       );
@@ -358,9 +355,9 @@ module('factory-bootstrap', function () {
       assert.strictEqual(result.project.status, 'existing');
       assert.strictEqual(result.knowledgeArticles[0].status, 'existing');
       assert.strictEqual(result.knowledgeArticles[1].status, 'existing');
-      assert.strictEqual(result.tickets[0].status, 'existing');
-      assert.strictEqual(result.tickets[1].status, 'existing');
-      assert.strictEqual(result.tickets[2].status, 'existing');
+      assert.strictEqual(result.issues[0].status, 'existing');
+      assert.strictEqual(result.issues[1].status, 'existing');
+      assert.strictEqual(result.issues[2].status, 'existing');
 
       let writeCalls = fetchCalls.filter((c) => c.method === 'POST');
       assert.strictEqual(writeCalls.length, 0, 'no write calls made');
@@ -384,9 +381,9 @@ module('factory-bootstrap', function () {
       assert.strictEqual(result.project.status, 'existing');
       assert.strictEqual(result.knowledgeArticles[0].status, 'existing');
       assert.strictEqual(result.knowledgeArticles[1].status, 'created');
-      assert.strictEqual(result.tickets[0].status, 'created');
-      assert.strictEqual(result.tickets[1].status, 'created');
-      assert.strictEqual(result.tickets[2].status, 'created');
+      assert.strictEqual(result.issues[0].status, 'created');
+      assert.strictEqual(result.issues[1].status, 'created');
+      assert.strictEqual(result.issues[2].status, 'created');
     });
 
     test('handles brief with minimal content gracefully', async function (assert) {
@@ -406,7 +403,7 @@ module('factory-bootstrap', function () {
 
       assert.strictEqual(result.project.id, 'Projects/my-widget-mvp');
       assert.strictEqual(result.project.status, 'created');
-      assert.strictEqual(result.tickets.length, 3);
+      assert.strictEqual(result.issues.length, 3);
 
       let project = writtenBodies['Projects/my-widget-mvp'] as {
         data: { attributes: { projectName: string; objective: string } };
@@ -438,8 +435,8 @@ module('factory-bootstrap', function () {
 
       assert.strictEqual(result.project.id, 'Projects/my-app-v2-0-beta-mvp');
       assert.strictEqual(
-        result.tickets[0].id,
-        'Tickets/my-app-v2-0-beta-define-core',
+        result.issues[0].id,
+        'Issues/my-app-v2-0-beta-define-core',
       );
     });
 
@@ -483,7 +480,7 @@ type MockFetchOptions = {
   allMissing?: boolean;
   allExist?: boolean;
   existingPaths?: Set<string>;
-  existingTicketStatus?: string;
+  existingIssueStatus?: string;
   captureWrites?: Record<string, unknown>;
 };
 
@@ -521,12 +518,12 @@ function buildMockFetch(
             data: {
               type: 'card',
               attributes: {
-                status: options.existingTicketStatus ?? 'backlog',
+                status: options.existingIssueStatus ?? 'backlog',
               },
               meta: {
                 adoptsFrom: {
                   module: darkfactoryModuleUrl,
-                  name: 'Ticket',
+                  name: 'Issue',
                 },
               },
             },
diff --git a/packages/software-factory/tests/factory-brief.test.ts b/packages/software-factory/tests/factory-brief.test.ts
index 7c08852c532..91f84c072e0 100644
--- a/packages/software-factory/tests/factory-brief.test.ts
+++ b/packages/software-factory/tests/factory-brief.test.ts
@@ -14,11 +14,11 @@ import {
 const stickyNoteFixture = JSON.parse(
   readFileSync(resolve(__dirname, '../realm/Wiki/sticky-note.json'), 'utf8'),
 ) as unknown;
-const darkfactoryTicketFixture = JSON.parse(
+const darkfactoryIssueFixture = JSON.parse(
   readFileSync(
     resolve(
       __dirname,
-      '../test-fixtures/darkfactory-adopter/Tickets/ticket-001.json',
+      '../test-fixtures/darkfactory-adopter/Issues/issue-001.json',
     ),
     'utf8',
   ),
@@ -63,10 +63,10 @@ module('factory-brief', function () {
 
   test('normalizeFactoryBrief falls back to summary and description text when content is absent', function (assert) {
     let sourceUrl =
-      'https://briefs.example.test/darkfactory-adopter/Tickets/ticket-001';
-    let brief = normalizeFactoryBrief(darkfactoryTicketFixture, sourceUrl);
+      'https://briefs.example.test/darkfactory-adopter/Issues/issue-001';
+    let brief = normalizeFactoryBrief(darkfactoryIssueFixture, sourceUrl);
 
-    assert.strictEqual(brief.title, 'Ticket 001');
+    assert.strictEqual(brief.title, 'Issue 001');
     assert.strictEqual(
       brief.content,
       'Render tracker cards from an adopter realm using the public software-factory module URL.',
diff --git a/packages/software-factory/tests/factory-context-builder.test.ts b/packages/software-factory/tests/factory-context-builder.test.ts
index ff9db0d3991..b9f82de136c 100644
--- a/packages/software-factory/tests/factory-context-builder.test.ts
+++ b/packages/software-factory/tests/factory-context-builder.test.ts
@@ -5,7 +5,7 @@ import type {
   ProjectCard,
   ResolvedSkill,
   TestResult,
-  TicketCard,
+  IssueCard,
 } from '../scripts/lib/factory-agent';
 
 import {
@@ -25,15 +25,15 @@ import type {
 class StubSkillResolver implements SkillResolver {
   /** Pre-configured skill names returned by resolve(). */
   skillNames: string[];
-  /** Records all (ticket, project) pairs passed to resolve(). */
-  calls: { ticket: TicketCard; project: ProjectCard }[] = [];
+  /** Records all (issue, project) pairs passed to resolve(). */
+  calls: { issue: IssueCard; project: ProjectCard }[] = [];
 
   constructor(skillNames: string[] = ['boxel-development']) {
     this.skillNames = skillNames;
   }
 
-  resolve(ticket: TicketCard, project: ProjectCard): string[] {
-    this.calls.push({ ticket, project });
+  resolve(issue: IssueCard, project: ProjectCard): string[] {
+    this.calls.push({ issue, project });
     return this.skillNames;
   }
 }
@@ -41,14 +41,14 @@ class StubSkillResolver implements SkillResolver {
 class StubSkillLoader implements SkillLoaderInterface {
   /** Map from skill name to the ResolvedSkill that load() returns. */
   private skillMap: Map<string, ResolvedSkill>;
-  /** Records all loadAll() calls: [skillNames, ticket]. */
-  loadAllCalls: { skillNames: string[]; ticket?: TicketCard }[] = [];
+  /** Records all loadAll() calls: [skillNames, issue]. */
+  loadAllCalls: { skillNames: string[]; issue?: IssueCard }[] = [];
 
   constructor(skills: ResolvedSkill[] = []) {
     this.skillMap = new Map(skills.map((s) => [s.name, s]));
   }
 
-  async load(skillName: string, _ticket?: TicketCard): Promise<ResolvedSkill> {
+  async load(skillName: string, _issue?: IssueCard): Promise<ResolvedSkill> {
     let skill = this.skillMap.get(skillName);
     if (!skill) {
       throw new Error(`StubSkillLoader: unknown skill "${skillName}"`);
@@ -58,9 +58,9 @@ class StubSkillLoader implements SkillLoaderInterface {
 
   async loadAll(
     skillNames: string[],
-    ticket?: TicketCard,
+    issue?: IssueCard,
   ): Promise<ResolvedSkill[]> {
-    this.loadAllCalls.push({ skillNames, ticket });
+    this.loadAllCalls.push({ skillNames, issue });
     let results: ResolvedSkill[] = [];
     for (let name of skillNames) {
       let skill = this.skillMap.get(name);
@@ -80,9 +80,9 @@ function makeProject(overrides?: Partial<ProjectCard>): ProjectCard {
   return { id: 'project-1', name: 'Sticky Notes', ...overrides };
 }
 
-function makeTicket(overrides?: Partial<TicketCard>): TicketCard {
+function makeIssue(overrides?: Partial<IssueCard>): IssueCard {
   return {
-    id: 'ticket-1',
+    id: 'issue-1',
     title: 'Implement StickyNote card',
     description: 'Create a .gts card definition for StickyNote',
     ...overrides,
@@ -126,15 +126,15 @@ function makeConfig(overrides?: Partial<ContextBuilderConfig>) {
 // ---------------------------------------------------------------------------
 
 module('factory-context-builder > skill resolution', function () {
-  test('resolves skills from ticket and project', async function (assert) {
+  test('resolves skills from issue and project', async function (assert) {
     let { config, resolver } = makeConfig();
     let builder = new ContextBuilder(config);
-    let ticket = makeTicket();
+    let issue = makeIssue();
     let project = makeProject();
 
     await builder.build({
       project,
-      ticket,
+      issue,
       knowledge: [],
       targetRealmUrl: 'https://example.test/target/',
       testRealmUrl: 'https://example.test/target-test-artifacts/',
@@ -142,9 +142,9 @@ module('factory-context-builder > skill resolution', function () {
 
     assert.strictEqual(resolver.calls.length, 1, 'resolve() called once');
     assert.strictEqual(
-      resolver.calls[0].ticket,
-      ticket,
-      'resolve() received the ticket',
+      resolver.calls[0].issue,
+      issue,
+      'resolve() received the issue',
     );
     assert.strictEqual(
       resolver.calls[0].project,
@@ -170,7 +170,7 @@ module('factory-context-builder > skill resolution', function () {
 
     await builder.build({
       project: makeProject(),
-      ticket: makeTicket(),
+      issue: makeIssue(),
       knowledge: [],
       targetRealmUrl: 'https://example.test/target/',
       testRealmUrl: 'https://example.test/target-test-artifacts/',
@@ -184,7 +184,7 @@ module('factory-context-builder > skill resolution', function () {
     );
   });
 
-  test('passes ticket to loadAll for reference filtering', async function (assert) {
+  test('passes issue to loadAll for reference filtering', async function (assert) {
     let resolver = new StubSkillResolver(['boxel-development']);
     let loader = new StubSkillLoader([makeSkill('boxel-development')]);
     let { config } = makeConfig({
@@ -192,20 +192,20 @@ module('factory-context-builder > skill resolution', function () {
       skillLoader: loader,
     });
     let builder = new ContextBuilder(config);
-    let ticket = makeTicket();
+    let issue = makeIssue();
 
     await builder.build({
       project: makeProject(),
-      ticket,
+      issue,
       knowledge: [],
       targetRealmUrl: 'https://example.test/target/',
       testRealmUrl: 'https://example.test/target-test-artifacts/',
     });
 
     assert.strictEqual(
-      loader.loadAllCalls[0].ticket,
-      ticket,
-      'loadAll() received the ticket for reference filtering',
+      loader.loadAllCalls[0].issue,
+      issue,
+      'loadAll() received the issue for reference filtering',
     );
   });
 
@@ -226,7 +226,7 @@ module('factory-context-builder > skill resolution', function () {
 
     let ctx = await builder.build({
       project: makeProject(),
-      ticket: makeTicket(),
+      issue: makeIssue(),
       knowledge: [],
       targetRealmUrl: 'https://example.test/target/',
       testRealmUrl: 'https://example.test/target-test-artifacts/',
@@ -263,7 +263,7 @@ module('factory-context-builder > skill budget', function () {
 
     let ctx = await builder.build({
       project: makeProject(),
-      ticket: makeTicket(),
+      issue: makeIssue(),
       knowledge: [],
       targetRealmUrl: 'https://example.test/target/',
       testRealmUrl: 'https://example.test/target-test-artifacts/',
@@ -294,7 +294,7 @@ module('factory-context-builder > skill budget', function () {
 
     let ctx = await builder.build({
       project: makeProject(),
-      ticket: makeTicket(),
+      issue: makeIssue(),
       knowledge: [],
       targetRealmUrl: 'https://example.test/target/',
       testRealmUrl: 'https://example.test/target-test-artifacts/',
@@ -315,7 +315,7 @@ module('factory-context-builder > tools excluded', function () {
 
     let ctx = await builder.build({
       project: makeProject(),
-      ticket: makeTicket(),
+      issue: makeIssue(),
       knowledge: [],
       targetRealmUrl: 'https://example.test/target/',
       testRealmUrl: 'https://example.test/target-test-artifacts/',
@@ -340,7 +340,7 @@ module('factory-context-builder > test results', function () {
 
     let ctx = await builder.build({
       project: makeProject(),
-      ticket: makeTicket(),
+      issue: makeIssue(),
       knowledge: [],
       targetRealmUrl: 'https://example.test/target/',
       testRealmUrl: 'https://example.test/target-test-artifacts/',
@@ -367,7 +367,7 @@ module('factory-context-builder > test results', function () {
 
     let ctx = await builder.build({
       project: makeProject(),
-      ticket: makeTicket(),
+      issue: makeIssue(),
       knowledge: [],
       targetRealmUrl: 'https://example.test/target/',
       testRealmUrl: 'https://example.test/target-test-artifacts/',
@@ -390,7 +390,7 @@ module('factory-context-builder > test results', function () {
 
     let ctx = await builder.build({
       project: makeProject(),
-      ticket: makeTicket(),
+      issue: makeIssue(),
       knowledge: [],
       targetRealmUrl: 'https://example.test/target/',
       testRealmUrl: 'https://example.test/target-test-artifacts/',
@@ -410,23 +410,23 @@ module('factory-context-builder > test results', function () {
 // ---------------------------------------------------------------------------
 
 module('factory-context-builder > core fields', function () {
-  test('includes project, ticket, and knowledge in context', async function (assert) {
+  test('includes project, issue, and knowledge in context', async function (assert) {
     let { config } = makeConfig();
     let builder = new ContextBuilder(config);
     let project = makeProject();
-    let ticket = makeTicket();
+    let issue = makeIssue();
     let knowledge = [makeKnowledge(), makeKnowledge({ id: 'ka-2' })];
 
     let ctx = await builder.build({
       project,
-      ticket,
+      issue,
       knowledge,
       targetRealmUrl: 'https://example.test/target/',
       testRealmUrl: 'https://example.test/target-test-artifacts/',
     });
 
     assert.strictEqual(ctx.project, project, 'project passed through');
-    assert.strictEqual(ctx.ticket, ticket, 'ticket passed through');
+    assert.strictEqual(ctx.issue, issue, 'issue passed through');
     assert.strictEqual(ctx.knowledge, knowledge, 'knowledge passed through');
   });
 
@@ -436,7 +436,7 @@ module('factory-context-builder > core fields', function () {
 
     let ctx = await builder.build({
       project: makeProject(),
-      ticket: makeTicket(),
+      issue: makeIssue(),
       knowledge: [],
       targetRealmUrl: 'https://example.test/my-realm/',
       testRealmUrl: 'https://example.test/my-realm-test-artifacts/',
@@ -455,7 +455,7 @@ module('factory-context-builder > core fields', function () {
 
     let ctx = await builder.build({
       project: makeProject(),
-      ticket: makeTicket(),
+      issue: makeIssue(),
       knowledge: [],
       targetRealmUrl: 'https://example.test/target/',
       testRealmUrl: 'https://example.test/target-test-artifacts/',
diff --git a/packages/software-factory/tests/factory-entrypoint.integration.test.ts b/packages/software-factory/tests/factory-entrypoint.integration.test.ts
index 8a886cd2a24..67fbaf3eea3 100644
--- a/packages/software-factory/tests/factory-entrypoint.integration.test.ts
+++ b/packages/software-factory/tests/factory-entrypoint.integration.test.ts
@@ -28,8 +28,8 @@ interface FactoryEntrypointIntegrationSummary {
   bootstrap: {
     projectId: string;
     knowledgeArticleIds: string[];
-    ticketIds: string[];
-    activeTicket: { id: string; status: string };
+    issueIds: string[];
+    activeIssue: { id: string; status: string };
   };
   result: Record<string, string>;
 }
@@ -256,15 +256,15 @@ module('factory-entrypoint integration', function () {
         summary.bootstrap.projectId,
         'Projects/sticky-note-mvp',
       );
-      assert.strictEqual(summary.bootstrap.ticketIds.length, 3);
+      assert.strictEqual(summary.bootstrap.issueIds.length, 3);
       assert.strictEqual(
-        summary.bootstrap.activeTicket.id,
-        'Tickets/sticky-note-define-core',
+        summary.bootstrap.activeIssue.id,
+        'Issues/sticky-note-define-core',
       );
-      assert.strictEqual(summary.bootstrap.activeTicket.status, 'created');
+      assert.strictEqual(summary.bootstrap.activeIssue.status, 'created');
       assert.deepEqual(summary.result, {
         status: 'ready',
-        nextStep: 'bootstrap-and-select-active-ticket',
+        nextStep: 'bootstrap-and-select-active-issue',
       });
     } finally {
       await new Promise<void>((resolvePromise, reject) =>
diff --git a/packages/software-factory/tests/factory-entrypoint.test.ts b/packages/software-factory/tests/factory-entrypoint.test.ts
index 574ffbf179e..c698dae40c0 100644
--- a/packages/software-factory/tests/factory-entrypoint.test.ts
+++ b/packages/software-factory/tests/factory-entrypoint.test.ts
@@ -42,12 +42,12 @@ const mockBootstrapResult: FactoryBootstrapResult = {
       status: 'created',
     },
   ],
-  tickets: [
-    { id: 'Tickets/sticky-note-define-core', status: 'created' },
-    { id: 'Tickets/sticky-note-design-views', status: 'created' },
-    { id: 'Tickets/sticky-note-add-integration', status: 'created' },
+  issues: [
+    { id: 'Issues/sticky-note-define-core', status: 'created' },
+    { id: 'Issues/sticky-note-design-views', status: 'created' },
+    { id: 'Issues/sticky-note-add-integration', status: 'created' },
   ],
-  activeTicket: { id: 'Tickets/sticky-note-define-core', status: 'created' },
+  activeIssue: { id: 'Issues/sticky-note-define-core', status: 'created' },
 };
 
 module('factory-entrypoint', function (hooks) {
@@ -140,12 +140,12 @@ module('factory-entrypoint', function (hooks) {
       ],
     );
     assert.strictEqual(summary.bootstrap.projectId, 'Projects/sticky-note-mvp');
-    assert.strictEqual(summary.bootstrap.ticketIds.length, 3);
+    assert.strictEqual(summary.bootstrap.issueIds.length, 3);
     assert.strictEqual(
-      summary.bootstrap.activeTicket.id,
-      'Tickets/sticky-note-define-core',
+      summary.bootstrap.activeIssue.id,
+      'Issues/sticky-note-define-core',
     );
-    assert.strictEqual(summary.bootstrap.activeTicket.status, 'created');
+    assert.strictEqual(summary.bootstrap.activeIssue.status, 'created');
     assert.deepEqual(summary.result, {
       status: 'ready',
       nextStep: 'bootstrap-target-realm',
@@ -194,7 +194,7 @@ module('factory-entrypoint', function (hooks) {
           outcome: 'done' as const,
           iterations: 1,
           toolCallLog: [],
-          ticketId: 'Tickets/sticky-note-define-core',
+          issueId: 'Issues/sticky-note-define-core',
           testRealmUrl:
             'https://realms.example.test/hassan/personal-test-artifacts/',
         }),
@@ -268,7 +268,7 @@ module('factory-entrypoint', function (hooks) {
           outcome: 'done' as const,
           iterations: 1,
           toolCallLog: [],
-          ticketId: 'Tickets/sticky-note-define-core',
+          issueId: 'Issues/sticky-note-define-core',
           testRealmUrl:
             'https://realms.example.test/app/hassan/personal-test-artifacts/',
         }),
diff --git a/packages/software-factory/tests/factory-implement.test.ts b/packages/software-factory/tests/factory-implement.test.ts
index e970e23d473..86b6834cc6c 100644
--- a/packages/software-factory/tests/factory-implement.test.ts
+++ b/packages/software-factory/tests/factory-implement.test.ts
@@ -60,8 +60,8 @@ function makeBootstrapResult(): FactoryBootstrapResult {
     knowledgeArticles: [
       { id: 'Knowledge Articles/sticky-note-brief-context', status: 'created' },
     ],
-    tickets: [{ id: 'Tickets/sticky-note-define-core', status: 'created' }],
-    activeTicket: { id: 'Tickets/sticky-note-define-core', status: 'created' },
+    issues: [{ id: 'Issues/sticky-note-define-core', status: 'created' }],
+    activeIssue: { id: 'Issues/sticky-note-define-core', status: 'created' },
   };
 }
 
@@ -120,8 +120,8 @@ function makeConfig(overrides?: Partial<ImplementConfig>): ImplementConfig {
       objective: 'Build a sticky note card',
       successCriteria: ['Card renders'],
     }),
-    'Tickets/sticky-note-define-core': makeCardDocument(
-      'Tickets/sticky-note-define-core',
+    'Issues/sticky-note-define-core': makeCardDocument(
+      'Issues/sticky-note-define-core',
       {
         summary: 'Define StickyNote card',
         description: 'Create the core StickyNote card definition',
@@ -196,7 +196,7 @@ module('factory-implement', function () {
 
       assert.strictEqual(result.outcome, 'tests_passed');
       assert.strictEqual(result.iterations, 1);
-      assert.strictEqual(result.ticketId, 'Tickets/sticky-note-define-core');
+      assert.strictEqual(result.issueId, 'Issues/sticky-note-define-core');
       assert.ok(result.toolCallLog.length >= 1);
       assert.strictEqual(agent.callCount, 1);
     });
@@ -228,7 +228,7 @@ module('factory-implement', function () {
       assert.strictEqual(result.iterations, 1);
     });
 
-    test('passes project, ticket, and knowledge to the agent context', async function (assert) {
+    test('passes project, issue, and knowledge to the agent context', async function (assert) {
       let agent = new MockLoopAgentForTest([{ status: 'done', toolCalls: [] }]);
 
       let config = makeConfig({ agent });
@@ -237,7 +237,7 @@ module('factory-implement', function () {
       assert.strictEqual(agent.callCount, 1);
       let ctx = agent.receivedContexts[0];
       assert.strictEqual(ctx.project.id, 'Projects/sticky-note-mvp');
-      assert.strictEqual(ctx.ticket.id, 'Tickets/sticky-note-define-core');
+      assert.strictEqual(ctx.issue.id, 'Issues/sticky-note-define-core');
       assert.strictEqual(ctx.knowledge.length, 1);
       assert.strictEqual(
         ctx.knowledge[0].id,
diff --git a/packages/software-factory/tests/factory-loop.test.ts b/packages/software-factory/tests/factory-loop.test.ts
index 2750bbd53c0..6ea55c7c278 100644
--- a/packages/software-factory/tests/factory-loop.test.ts
+++ b/packages/software-factory/tests/factory-loop.test.ts
@@ -5,7 +5,7 @@ import type {
   KnowledgeArticle,
   ProjectCard,
   TestResult,
-  TicketCard,
+  IssueCard,
 } from '../scripts/lib/factory-agent';
 
 import type {
@@ -107,7 +107,7 @@ class MockFactoryAgent implements LoopAgent {
 class StubContextBuilder implements ContextBuilderLike {
   buildCalls: {
     project: ProjectCard;
-    ticket: TicketCard;
+    issue: IssueCard;
     knowledge: KnowledgeArticle[];
     targetRealmUrl: string;
     testRealmUrl: string;
@@ -116,7 +116,7 @@ class StubContextBuilder implements ContextBuilderLike {
 
   async build(params: {
     project: ProjectCard;
-    ticket: TicketCard;
+    issue: IssueCard;
     knowledge: KnowledgeArticle[];
     targetRealmUrl: string;
     testRealmUrl: string;
@@ -125,7 +125,7 @@ class StubContextBuilder implements ContextBuilderLike {
     this.buildCalls.push(params);
     return {
       project: params.project,
-      ticket: params.ticket,
+      issue: params.issue,
       knowledge: params.knowledge,
       skills: [],
       targetRealmUrl: params.targetRealmUrl,
@@ -143,8 +143,8 @@ function makeProject(overrides?: Partial<ProjectCard>): ProjectCard {
   return { id: 'project-1', name: 'Sticky Notes', ...overrides };
 }
 
-function makeTicket(overrides?: Partial<TicketCard>): TicketCard {
-  return { id: 'ticket-1', title: 'Implement StickyNote card', ...overrides };
+function makeIssue(overrides?: Partial<IssueCard>): IssueCard {
+  return { id: 'issue-1', title: 'Implement StickyNote card', ...overrides };
 }
 
 function makeKnowledge(
@@ -215,7 +215,7 @@ function makeLoopConfig(
     tools: DEFAULT_TOOLS,
     testRunner: makeTestRunner([makePassingTestResult()]),
     project: makeProject(),
-    ticket: makeTicket(),
+    issue: makeIssue(),
     knowledge: [makeKnowledge()],
     targetRealmUrl: 'https://example.test/target/',
     testRealmUrl: 'https://example.test/target-test-artifacts/',
@@ -648,9 +648,9 @@ module('factory-loop > context threading', function () {
     );
   });
 
-  test('context includes correct project and ticket across iterations', async function (assert) {
+  test('context includes correct project and issue across iterations', async function (assert) {
     let project = makeProject({ id: 'p-42' });
-    let ticket = makeTicket({ id: 't-99' });
+    let issue = makeIssue({ id: 't-99' });
     let agent = new MockFactoryAgent([
       {
         toolCalls: [
@@ -670,7 +670,7 @@ module('factory-loop > context threading', function () {
       makeLoopConfig({
         agent,
         project,
-        ticket,
+        issue,
         testRunner: makeTestRunner([
           makeFailingTestResult(),
           makePassingTestResult(),
@@ -679,9 +679,9 @@ module('factory-loop > context threading', function () {
     );
 
     assert.strictEqual(agent.receivedContexts[0].project, project);
-    assert.strictEqual(agent.receivedContexts[0].ticket, ticket);
+    assert.strictEqual(agent.receivedContexts[0].issue, issue);
     assert.strictEqual(agent.receivedContexts[1].project, project);
-    assert.strictEqual(agent.receivedContexts[1].ticket, ticket);
+    assert.strictEqual(agent.receivedContexts[1].issue, issue);
   });
 
   test('tools are passed consistently across iterations', async function (assert) {
diff --git a/packages/software-factory/tests/factory-prompt-loader.test.ts b/packages/software-factory/tests/factory-prompt-loader.test.ts
index 44585ee7a24..e875dc6699d 100644
--- a/packages/software-factory/tests/factory-prompt-loader.test.ts
+++ b/packages/software-factory/tests/factory-prompt-loader.test.ts
@@ -20,7 +20,7 @@ import type { AgentAction, AgentContext } from '../scripts/lib/factory-agent';
 function makeMinimalContext(overrides?: Partial<AgentContext>): AgentContext {
   return {
     project: { id: 'Projects/test-project' },
-    ticket: { id: 'Tickets/test-ticket' },
+    issue: { id: 'Issues/test-issue' },
     knowledge: [],
     skills: [],
     tools: [],
@@ -41,10 +41,10 @@ module('factory-prompt-loader > interpolate > simple variables', function () {
   });
 
   test('replaces dot-path variables', function (assert) {
-    let result = interpolate('ID: {{ticket.id}}', {
-      ticket: { id: 'Ticket/123' },
+    let result = interpolate('ID: {{issue.id}}', {
+      issue: { id: 'Issue/123' },
     });
-    assert.strictEqual(result, 'ID: Ticket/123');
+    assert.strictEqual(result, 'ID: Issue/123');
   });
 
   test('replaces deeply nested dot paths', function (assert) {
@@ -175,9 +175,9 @@ module('factory-prompt-loader > interpolate > #if blocks', function () {
   });
 
   test('supports dot-path conditions', function (assert) {
-    let template = '{{#if ticket.checklist}}has checklist{{/if}}';
+    let template = '{{#if issue.checklist}}has checklist{{/if}}';
     let result = interpolate(template, {
-      ticket: { checklist: ['step 1'] },
+      issue: { checklist: ['step 1'] },
     });
     assert.strictEqual(result, 'has checklist');
   });
@@ -353,7 +353,7 @@ module('factory-prompt-loader > assembleSystemPrompt', function () {
 // ---------------------------------------------------------------------------
 
 module('factory-prompt-loader > assembleImplementPrompt', function () {
-  test('includes project and ticket context', function (assert) {
+  test('includes project and issue context', function (assert) {
     let loader = new FilePromptLoader();
     let ctx = makeMinimalContext({
       project: {
@@ -361,8 +361,8 @@ module('factory-prompt-loader > assembleImplementPrompt', function () {
         objective: 'Build a sticky note card app',
         successCriteria: ['Card renders', 'Tests pass'],
       },
-      ticket: {
-        id: 'Tickets/define-core',
+      issue: {
+        id: 'Issues/define-core',
         summary: 'Define the core StickyNote card',
         status: 'in-progress',
         priority: 'high',
@@ -377,12 +377,12 @@ module('factory-prompt-loader > assembleImplementPrompt', function () {
       'project objective',
     );
     assert.ok(result.includes('Card renders'), 'success criteria');
-    assert.ok(result.includes('Tickets/define-core'), 'ticket ID');
+    assert.ok(result.includes('Issues/define-core'), 'issue ID');
     assert.ok(
       result.includes('Define the core StickyNote card'),
-      'ticket summary',
+      'issue summary',
     );
-    assert.ok(result.includes('StickyNote CardDef'), 'ticket description');
+    assert.ok(result.includes('StickyNote CardDef'), 'issue description');
   });
 
   test('includes knowledge articles', function (assert) {
@@ -408,7 +408,7 @@ module('factory-prompt-loader > assembleImplementPrompt', function () {
     let result = assembleImplementPrompt({ context: ctx, loader });
 
     assert.ok(
-      result.includes('Implement this ticket'),
+      result.includes('Implement this issue'),
       'has implementation instructions',
     );
     assert.ok(result.includes('signal_done'), 'mentions signal_done');
@@ -417,12 +417,12 @@ module('factory-prompt-loader > assembleImplementPrompt', function () {
   test('includes checklist when present', function (assert) {
     let loader = new FilePromptLoader();
     let ctx = makeMinimalContext({
-      ticket: {
-        id: 'Tickets/test',
+      issue: {
+        id: 'Issues/test',
         summary: 'Test',
         status: 'open',
         priority: 'medium',
-        description: 'Test ticket',
+        description: 'Test issue',
         checklist: ['Step 1', 'Step 2'],
       },
     });
@@ -461,7 +461,7 @@ module('factory-prompt-loader > assembleImplementPrompt', function () {
       'includes tool output data',
     );
     assert.ok(
-      result.includes('Implement this ticket'),
+      result.includes('Implement this issue'),
       'still includes implementation instructions',
     );
   });
@@ -483,15 +483,15 @@ module('factory-prompt-loader > assembleImplementPrompt', function () {
 // ---------------------------------------------------------------------------
 
 module('factory-prompt-loader > assembleIteratePrompt', function () {
-  test('includes ticket context and previous actions', function (assert) {
+  test('includes issue context and previous actions', function (assert) {
     let loader = new FilePromptLoader();
     let ctx = makeMinimalContext({
       project: {
         id: 'Projects/test',
         objective: 'Test objective',
       },
-      ticket: {
-        id: 'Tickets/define-core',
+      issue: {
+        id: 'Issues/define-core',
         summary: 'Define core card',
         description: 'Create the card definition.',
       },
@@ -532,9 +532,9 @@ module('factory-prompt-loader > assembleIteratePrompt', function () {
       loader,
     });
 
-    // Ticket context
-    assert.ok(result.includes('Tickets/define-core'), 'includes ticket ID');
-    assert.ok(result.includes('Define core card'), 'includes ticket summary');
+    // Issue context
+    assert.ok(result.includes('Issues/define-core'), 'includes issue ID');
+    assert.ok(result.includes('Define core card'), 'includes issue summary');
 
     // Previous actions
     assert.ok(result.includes('iteration 2'), 'includes iteration number');
@@ -648,13 +648,13 @@ module('factory-prompt-loader > assembleIteratePrompt', function () {
     );
   });
 
-  test('is self-contained: includes project, ticket, actions, test results', function (assert) {
+  test('is self-contained: includes project, issue, actions, test results', function (assert) {
     let loader = new FilePromptLoader();
     let ctx = makeMinimalContext({
       project: { id: 'Projects/app', objective: 'Build the app' },
-      ticket: {
-        id: 'Tickets/t1',
-        summary: 'First ticket',
+      issue: {
+        id: 'Issues/t1',
+        summary: 'First issue',
         description: 'Do the thing.',
       },
       testResults: {
@@ -687,9 +687,9 @@ module('factory-prompt-loader > assembleIteratePrompt', function () {
 
     // All required sections are present
     assert.ok(result.includes('Build the app'), 'project context');
-    assert.ok(result.includes('Tickets/t1'), 'ticket ID');
-    assert.ok(result.includes('First ticket'), 'ticket summary');
-    assert.ok(result.includes('Do the thing'), 'ticket description');
+    assert.ok(result.includes('Issues/t1'), 'issue ID');
+    assert.ok(result.includes('First issue'), 'issue summary');
+    assert.ok(result.includes('Do the thing'), 'issue description');
     assert.ok(result.includes('iteration 3'), 'iteration number');
     assert.ok(result.includes('card.gts'), 'previous action');
     assert.ok(result.includes('error-a'), 'test failure 1');
@@ -703,10 +703,10 @@ module('factory-prompt-loader > assembleIteratePrompt', function () {
 // ---------------------------------------------------------------------------
 
 module('factory-prompt-loader > assembleTestPrompt', function () {
-  test('includes ticket and implemented files', function (assert) {
+  test('includes issue and implemented files', function (assert) {
     let loader = new FilePromptLoader();
     let ctx = makeMinimalContext({
-      ticket: { id: 'Tickets/t1', summary: 'Test ticket' },
+      issue: { id: 'Issues/t1', summary: 'Test issue' },
     });
 
     let result = assembleTestPrompt({
@@ -721,7 +721,7 @@ module('factory-prompt-loader > assembleTestPrompt', function () {
       loader,
     });
 
-    assert.ok(result.includes('Tickets/t1'), 'includes ticket ID');
+    assert.ok(result.includes('Issues/t1'), 'includes issue ID');
     assert.ok(result.includes('sticky-note.gts'), 'includes file path');
     assert.ok(
       result.includes('export class StickyNote'),
@@ -754,13 +754,13 @@ module('factory-prompt-loader > buildOneShotMessages', function () {
 module(
   'factory-prompt-loader > one-shot message assembly integration',
   function () {
-    test('first pass: [system, ticket-implement]', function (assert) {
+    test('first pass: [system, issue-implement]', function (assert) {
       let loader = new FilePromptLoader();
       let ctx = makeMinimalContext({
         project: { id: 'Projects/app', objective: 'Build app' },
-        ticket: {
-          id: 'Tickets/t1',
-          summary: 'First ticket',
+        issue: {
+          id: 'Issues/t1',
+          summary: 'First issue',
           status: 'open',
           priority: 'high',
           description: 'Implement the feature.',
@@ -777,18 +777,18 @@ module(
 
       // System has agent role
       assert.ok(messages[0].content.includes('software factory agent'));
-      // User has ticket
-      assert.ok(messages[1].content.includes('Tickets/t1'));
+      // User has issue
+      assert.ok(messages[1].content.includes('Issues/t1'));
       assert.ok(messages[1].content.includes('Implement the feature'));
     });
 
-    test('iteration pass: [system, ticket-iterate]', function (assert) {
+    test('iteration pass: [system, issue-iterate]', function (assert) {
       let loader = new FilePromptLoader();
       let ctx = makeMinimalContext({
         project: { id: 'Projects/app', objective: 'Build app' },
-        ticket: {
-          id: 'Tickets/t1',
-          summary: 'First ticket',
+        issue: {
+          id: 'Issues/t1',
+          summary: 'First issue',
           description: 'Implement the feature.',
         },
         testResults: {
diff --git a/packages/software-factory/tests/factory-skill-loader.test.ts b/packages/software-factory/tests/factory-skill-loader.test.ts
index f46eaa03eb0..11807bb4b33 100644
--- a/packages/software-factory/tests/factory-skill-loader.test.ts
+++ b/packages/software-factory/tests/factory-skill-loader.test.ts
@@ -7,7 +7,7 @@ import { module, test } from 'qunit';
 import type {
   ProjectCard,
   ResolvedSkill,
-  TicketCard,
+  IssueCard,
 } from '../scripts/lib/factory-agent';
 import {
   DefaultSkillResolver,
@@ -15,7 +15,7 @@ import {
   SkillLoadError,
   enforceSkillBudget,
   estimateTokens,
-  extractTicketText,
+  extractIssueText,
 } from '../scripts/lib/factory-skill-loader';
 
 // ---------------------------------------------------------------------------
@@ -70,11 +70,11 @@ function writeSkill(
   }
 }
 
-function makeTicket(overrides?: Partial<TicketCard>): TicketCard {
+function makeIssue(overrides?: Partial<IssueCard>): IssueCard {
   return {
-    id: 'Tickets/test-ticket',
-    title: 'Test ticket',
-    description: 'A test ticket for unit testing',
+    id: 'Issues/test-issue',
+    title: 'Test issue',
+    description: 'A test issue for unit testing',
     ...overrides,
   };
 }
@@ -93,10 +93,10 @@ function makeProject(overrides?: Partial<ProjectCard>): ProjectCard {
 module('factory-skill-loader > DefaultSkillResolver', function () {
   test('always includes boxel-development and boxel-file-structure', function (assert) {
     let resolver = new DefaultSkillResolver();
-    let ticket = makeTicket({ description: 'Generic task with no keywords' });
+    let issue = makeIssue({ description: 'Generic task with no keywords' });
     let project = makeProject();
 
-    let skills = resolver.resolve(ticket, project);
+    let skills = resolver.resolve(issue, project);
 
     assert.true(
       skills.includes('boxel-development'),
@@ -108,14 +108,14 @@ module('factory-skill-loader > DefaultSkillResolver', function () {
     );
   });
 
-  test('includes ember-best-practices when ticket mentions .gts', function (assert) {
+  test('includes ember-best-practices when issue mentions .gts', function (assert) {
     let resolver = new DefaultSkillResolver();
-    let ticket = makeTicket({
+    let issue = makeIssue({
       description: 'Create a new card definition in .gts format',
     });
     let project = makeProject();
 
-    let skills = resolver.resolve(ticket, project);
+    let skills = resolver.resolve(issue, project);
 
     assert.true(
       skills.includes('ember-best-practices'),
@@ -123,14 +123,14 @@ module('factory-skill-loader > DefaultSkillResolver', function () {
     );
   });
 
-  test('includes ember-best-practices when ticket mentions component', function (assert) {
+  test('includes ember-best-practices when issue mentions component', function (assert) {
     let resolver = new DefaultSkillResolver();
-    let ticket = makeTicket({
+    let issue = makeIssue({
       description: 'Build a new component for the dashboard',
     });
     let project = makeProject();
 
-    let skills = resolver.resolve(ticket, project);
+    let skills = resolver.resolve(issue, project);
 
     assert.true(
       skills.includes('ember-best-practices'),
@@ -138,14 +138,14 @@ module('factory-skill-loader > DefaultSkillResolver', function () {
     );
   });
 
-  test('includes ember-best-practices when ticket mentions CardDef', function (assert) {
+  test('includes ember-best-practices when issue mentions CardDef', function (assert) {
     let resolver = new DefaultSkillResolver();
-    let ticket = makeTicket({
+    let issue = makeIssue({
       title: 'Define a new CardDef for employees',
     });
     let project = makeProject();
 
-    let skills = resolver.resolve(ticket, project);
+    let skills = resolver.resolve(issue, project);
 
     assert.true(
       skills.includes('ember-best-practices'),
@@ -153,14 +153,14 @@ module('factory-skill-loader > DefaultSkillResolver', function () {
     );
   });
 
-  test('includes software-factory-operations for delivery workflow tickets', function (assert) {
+  test('includes software-factory-operations for delivery workflow issues', function (assert) {
     let resolver = new DefaultSkillResolver();
-    let ticket = makeTicket({
+    let issue = makeIssue({
       description: 'Improve the factory delivery pipeline',
     });
     let project = makeProject();
 
-    let skills = resolver.resolve(ticket, project);
+    let skills = resolver.resolve(issue, project);
 
     assert.true(
       skills.includes('software-factory-operations'),
@@ -168,14 +168,14 @@ module('factory-skill-loader > DefaultSkillResolver', function () {
     );
   });
 
-  test('excludes CLI-only skills even when ticket mentions sync', function (assert) {
+  test('excludes CLI-only skills even when issue mentions sync', function (assert) {
     let resolver = new DefaultSkillResolver();
-    let ticket = makeTicket({
+    let issue = makeIssue({
       description: 'Sync the workspace after local edits',
     });
     let project = makeProject();
 
-    let skills = resolver.resolve(ticket, project);
+    let skills = resolver.resolve(issue, project);
 
     assert.false(
       skills.includes('boxel-sync'),
@@ -183,14 +183,14 @@ module('factory-skill-loader > DefaultSkillResolver', function () {
     );
   });
 
-  test('excludes CLI-only skills even when ticket mentions restore', function (assert) {
+  test('excludes CLI-only skills even when issue mentions restore', function (assert) {
     let resolver = new DefaultSkillResolver();
-    let ticket = makeTicket({
+    let issue = makeIssue({
       description: 'Restore workspace to a previous checkpoint',
     });
     let project = makeProject();
 
-    let skills = resolver.resolve(ticket, project);
+    let skills = resolver.resolve(issue, project);
 
     assert.false(
       skills.includes('boxel-restore'),
@@ -198,14 +198,14 @@ module('factory-skill-loader > DefaultSkillResolver', function () {
     );
   });
 
-  test('excludes all CLI-only skills even when ticket mentions multiple CLI operations', function (assert) {
+  test('excludes all CLI-only skills even when issue mentions multiple CLI operations', function (assert) {
     let resolver = new DefaultSkillResolver();
-    let ticket = makeTicket({
+    let issue = makeIssue({
       description: 'Sync the workspace, track changes, and watch for updates',
     });
     let project = makeProject();
 
-    let skills = resolver.resolve(ticket, project);
+    let skills = resolver.resolve(issue, project);
 
     assert.false(skills.includes('boxel-sync'), 'boxel-sync excluded');
     assert.false(skills.includes('boxel-track'), 'boxel-track excluded');
@@ -214,7 +214,7 @@ module('factory-skill-loader > DefaultSkillResolver', function () {
 
   test('excludes CLI-only skills even when added via knowledge article tags', function (assert) {
     let resolver = new DefaultSkillResolver();
-    let ticket = makeTicket();
+    let issue = makeIssue();
     let project = makeProject({
       knowledge: [
         {
@@ -224,7 +224,7 @@ module('factory-skill-loader > DefaultSkillResolver', function () {
       ],
     });
 
-    let skills = resolver.resolve(ticket, project);
+    let skills = resolver.resolve(issue, project);
 
     assert.false(
       skills.includes('boxel-sync'),
@@ -238,7 +238,7 @@ module('factory-skill-loader > DefaultSkillResolver', function () {
 
   test('extracts additional skills from knowledge article tags', function (assert) {
     let resolver = new DefaultSkillResolver();
-    let ticket = makeTicket();
+    let issue = makeIssue();
     let project = makeProject({
       knowledge: [
         {
@@ -248,7 +248,7 @@ module('factory-skill-loader > DefaultSkillResolver', function () {
       ],
     });
 
-    let skills = resolver.resolve(ticket, project);
+    let skills = resolver.resolve(issue, project);
 
     assert.true(
       skills.includes('custom-skill'),
@@ -258,7 +258,7 @@ module('factory-skill-loader > DefaultSkillResolver', function () {
 
   test('extracts additional skills from knowledge article skills array', function (assert) {
     let resolver = new DefaultSkillResolver();
-    let ticket = makeTicket();
+    let issue = makeIssue();
     let project = makeProject({
       knowledge: [
         {
@@ -268,7 +268,7 @@ module('factory-skill-loader > DefaultSkillResolver', function () {
       ],
     });
 
-    let skills = resolver.resolve(ticket, project);
+    let skills = resolver.resolve(issue, project);
 
     assert.true(skills.includes('extra-skill-a'), 'includes extra-skill-a');
     assert.true(skills.includes('extra-skill-b'), 'includes extra-skill-b');
@@ -276,7 +276,7 @@ module('factory-skill-loader > DefaultSkillResolver', function () {
 
   test('reads skills from knowledgeBase field (Project schema)', function (assert) {
     let resolver = new DefaultSkillResolver();
-    let ticket = makeTicket();
+    let issue = makeIssue();
     let project = makeProject({
       knowledgeBase: [
         {
@@ -286,7 +286,7 @@ module('factory-skill-loader > DefaultSkillResolver', function () {
       ],
     });
 
-    let skills = resolver.resolve(ticket, project);
+    let skills = resolver.resolve(issue, project);
 
     assert.true(
       skills.includes('schema-skill'),
@@ -294,9 +294,9 @@ module('factory-skill-loader > DefaultSkillResolver', function () {
     );
   });
 
-  test('reads skills from relatedKnowledge field (Ticket schema)', function (assert) {
+  test('reads skills from relatedKnowledge field (Issue schema)', function (assert) {
     let resolver = new DefaultSkillResolver();
-    let ticket = makeTicket({
+    let issue = makeIssue({
       relatedKnowledge: [
         {
           id: 'Knowledge Articles/ticket-knowledge',
@@ -306,17 +306,17 @@ module('factory-skill-loader > DefaultSkillResolver', function () {
     });
     let project = makeProject();
 
-    let skills = resolver.resolve(ticket, project);
+    let skills = resolver.resolve(issue, project);
 
     assert.true(
       skills.includes('ticket-skill'),
-      'includes skill from ticket relatedKnowledge',
+      'includes skill from issue relatedKnowledge',
     );
   });
 
   test('does not duplicate skills', function (assert) {
     let resolver = new DefaultSkillResolver();
-    let ticket = makeTicket({
+    let issue = makeIssue({
       description: 'Create a .gts component with template patterns',
     });
     let project = makeProject({
@@ -328,20 +328,20 @@ module('factory-skill-loader > DefaultSkillResolver', function () {
       ],
     });
 
-    let skills = resolver.resolve(ticket, project);
+    let skills = resolver.resolve(issue, project);
     let devCount = skills.filter((s) => s === 'boxel-development').length;
     assert.strictEqual(devCount, 1, 'boxel-development appears only once');
   });
 
-  test('reads ticket text from title, description, tags, and labels', function (assert) {
-    let ticket = makeTicket({
+  test('reads issue text from title, description, tags, and labels', function (assert) {
+    let issue = makeIssue({
       title: 'Fix the component rendering',
       description: 'The template is broken',
       tags: ['ember', 'glimmer'],
       labels: [{ name: 'bug' }],
     });
 
-    let text = extractTicketText(ticket);
+    let text = extractIssueText(issue);
 
     assert.true(text.includes('fix the component rendering'));
     assert.true(text.includes('the template is broken'));
@@ -352,10 +352,10 @@ module('factory-skill-loader > DefaultSkillResolver', function () {
 
   test('handles project with no knowledge array', function (assert) {
     let resolver = new DefaultSkillResolver();
-    let ticket = makeTicket();
+    let issue = makeIssue();
     let project = makeProject(); // no knowledge field
 
-    let skills = resolver.resolve(ticket, project);
+    let skills = resolver.resolve(issue, project);
 
     // Should still resolve the base skills without error
     assert.true(skills.includes('boxel-development'));
@@ -683,7 +683,7 @@ module('factory-skill-loader > SkillLoader', function (hooks) {
     }
   });
 
-  test('filters boxel-development references by ticket when loaded with ticket', async function (assert) {
+  test('filters boxel-development references by issue when loaded with issue', async function (assert) {
     // Set up a boxel-development skill with references matching the real structure
     writeSkill(tempDir, 'boxel-development', '# Boxel Development', {
       references: {
@@ -698,24 +698,24 @@ module('factory-skill-loader > SkillLoader', function (hooks) {
 
     let loader = new SkillLoader(tempDir, []);
 
-    // Load WITHOUT ticket — should get all references
+    // Load WITHOUT issue — should get all references
     let allRefs = await loader.load('boxel-development');
     assert.strictEqual(
       allRefs.references!.length,
       6,
-      'all 6 references loaded without ticket',
+      'all 6 references loaded without issue',
     );
 
-    // Load WITH a styling ticket — should get always-load + styling only
+    // Load WITH a styling issue — should get always-load + styling only
     loader.clearCache();
-    let stylingTicket = makeTicket({
+    let stylingIssue = makeIssue({
       description: 'Fix the CSS styling on the card',
     });
-    let filtered = await loader.load('boxel-development', stylingTicket);
+    let filtered = await loader.load('boxel-development', stylingIssue);
 
     assert.true(
       filtered.references!.length < 6,
-      'fewer references with ticket filtering',
+      'fewer references with issue filtering',
     );
     // Always-load refs should be present
     assert.true(
@@ -736,7 +736,7 @@ module('factory-skill-loader > SkillLoader', function (hooks) {
 
   test('reference filtering works without budget (no-budget path)', async function (assert) {
     // Verifies the P1 fix: callers that omit maxSkillTokens still get
-    // ticket-relevant references, not all 19. The filtering happens at load
+    // issue-relevant references, not all 19. The filtering happens at load
     // time, so enforceSkillBudget(skills, undefined) returns already-filtered
     // skills — no budget required.
     writeSkill(tempDir, 'boxel-development', '# Boxel Development', {
@@ -751,12 +751,12 @@ module('factory-skill-loader > SkillLoader', function (hooks) {
     });
 
     let loader = new SkillLoader(tempDir, []);
-    let ticket = makeTicket({
+    let issue = makeIssue({
       description: 'Fix the CSS styling on the card',
     });
 
-    // Load with ticket — filtering happens at load time
-    let skills = await loader.loadAll(['boxel-development'], ticket);
+    // Load with issue — filtering happens at load time
+    let skills = await loader.loadAll(['boxel-development'], issue);
     assert.strictEqual(skills.length, 1);
 
     // Pass through enforceSkillBudget with NO budget (undefined)
@@ -937,44 +937,44 @@ module('factory-skill-loader > enforceSkillBudget', function () {
 });
 
 // ---------------------------------------------------------------------------
-// Re-resolution on new ticket
+// Re-resolution on new issue
 // ---------------------------------------------------------------------------
 
-module('factory-skill-loader > re-resolution on new ticket', function () {
-  test('resolver produces different skills for different tickets', function (assert) {
+module('factory-skill-loader > re-resolution on new issue', function () {
+  test('resolver produces different skills for different issues', function (assert) {
     let resolver = new DefaultSkillResolver();
     let project = makeProject();
 
-    let ticket1 = makeTicket({
+    let issue1 = makeIssue({
       description: 'Create a .gts component for the landing page',
     });
-    let ticket2 = makeTicket({
+    let issue2 = makeIssue({
       description: 'Improve the factory delivery pipeline',
     });
 
-    let skills1 = resolver.resolve(ticket1, project);
-    let skills2 = resolver.resolve(ticket2, project);
+    let skills1 = resolver.resolve(issue1, project);
+    let skills2 = resolver.resolve(issue2, project);
 
     assert.true(
       skills1.includes('ember-best-practices'),
-      'ticket1 gets ember-best-practices',
+      'issue1 gets ember-best-practices',
     );
     assert.false(
       skills1.includes('software-factory-operations'),
-      'ticket1 does not get software-factory-operations',
+      'issue1 does not get software-factory-operations',
     );
 
     assert.true(
       skills2.includes('software-factory-operations'),
-      'ticket2 gets software-factory-operations',
+      'issue2 gets software-factory-operations',
     );
     assert.false(
       skills2.includes('ember-best-practices'),
-      'ticket2 does not get ember-best-practices',
+      'issue2 does not get ember-best-practices',
     );
   });
 
-  test('cache can be cleared between tickets for fresh loading', async function (assert) {
+  test('cache can be cleared between issues for fresh loading', async function (assert) {
     tempDir = createTempSkillsDir();
     writeSkill(tempDir, 'boxel-development', '# Dev v1');
 
@@ -982,7 +982,7 @@ module('factory-skill-loader > re-resolution on new ticket', function () {
     let first = await loader.load('boxel-development');
     assert.true(first.content.includes('Dev v1'));
 
-    // Simulate moving to a new ticket: clear cache, potentially new skill content
+    // Simulate moving to a new issue: clear cache, potentially new skill content
     writeSkill(tempDir, 'boxel-development', '# Dev v2');
     loader.clearCache();
 
diff --git a/packages/software-factory/tests/factory-target-realm.spec.ts b/packages/software-factory/tests/factory-target-realm.spec.ts
index 48e98072f96..0984fbac4cd 100644
--- a/packages/software-factory/tests/factory-target-realm.spec.ts
+++ b/packages/software-factory/tests/factory-target-realm.spec.ts
@@ -105,21 +105,21 @@ test('factory:go creates a target realm and bootstraps project artifacts end-to-
       targetRealm: { url: string; ownerUsername: string };
       bootstrap: {
         projectId: string;
-        ticketIds: string[];
+        issueIds: string[];
         knowledgeArticleIds: string[];
-        activeTicket: { id: string; status: string };
+        activeIssue: { id: string; status: string };
       };
     };
 
     expect(summary.command).toBe('factory:go');
     expect(summary.targetRealm.ownerUsername).toBe(targetUsername);
     expect(summary.bootstrap.projectId).toBe('Projects/sticky-note-mvp');
-    expect(summary.bootstrap.ticketIds).toHaveLength(3);
+    expect(summary.bootstrap.issueIds).toHaveLength(3);
     expect(summary.bootstrap.knowledgeArticleIds).toHaveLength(2);
-    expect(summary.bootstrap.activeTicket.id).toBe(
-      'Tickets/sticky-note-define-core',
+    expect(summary.bootstrap.activeIssue.id).toBe(
+      'Issues/sticky-note-define-core',
     );
-    expect(summary.bootstrap.activeTicket.status).toBe('created');
+    expect(summary.bootstrap.activeIssue.status).toBe('created');
 
     // Verify the project card actually exists in the newly created target realm
     // by authenticating as the target user who owns the realm
diff --git a/packages/software-factory/tests/factory-test-realm.test.ts b/packages/software-factory/tests/factory-test-realm.test.ts
index 9104140bb80..2c3338121c0 100644
--- a/packages/software-factory/tests/factory-test-realm.test.ts
+++ b/packages/software-factory/tests/factory-test-realm.test.ts
@@ -226,11 +226,11 @@ module('factory-test-realm > buildTestRunCardDocument', function () {
     assert.strictEqual(doc.data.attributes!.sequenceNumber, 5);
   });
 
-  test('includes ticket relationship when ticketURL is provided', function (assert) {
+  test('includes issue relationship when issueURL is provided', function (assert) {
     let doc = buildTestRunCardDocument(
       ['test A'],
       testRealmOptions.testResultsModuleUrl,
-      { ticketURL: '../Ticket/define-sticky-note-core' },
+      { issueURL: '../Issues/define-sticky-note-core' },
     );
 
     let relationships = doc.data.relationships as Record<
@@ -238,8 +238,8 @@ module('factory-test-realm > buildTestRunCardDocument', function () {
       { links: { self: string | null } }
     >;
     assert.strictEqual(
-      relationships.ticket.links.self,
-      '../Ticket/define-sticky-note-core',
+      relationships.issue.links.self,
+      '../Issues/define-sticky-note-core',
     );
   });
 
@@ -260,13 +260,13 @@ module('factory-test-realm > buildTestRunCardDocument', function () {
     );
   });
 
-  test('includes both project and ticket relationships', function (assert) {
+  test('includes both project and issue relationships', function (assert) {
     let doc = buildTestRunCardDocument(
       ['test A'],
       testRealmOptions.testResultsModuleUrl,
       {
         projectCardUrl: 'http://localhost:4201/test/Projects/hello-world',
-        ticketURL: '../Ticket/implement-feature',
+        issueURL: '../Issues/implement-feature',
       },
     );
 
@@ -279,12 +279,12 @@ module('factory-test-realm > buildTestRunCardDocument', function () {
       'http://localhost:4201/test/Projects/hello-world',
     );
     assert.strictEqual(
-      relationships.ticket.links.self,
-      '../Ticket/implement-feature',
+      relationships.issue.links.self,
+      '../Issues/implement-feature',
     );
   });
 
-  test('omits relationships when no ticketURL or projectCardUrl', function (assert) {
+  test('omits relationships when no issueURL or projectCardUrl', function (assert) {
     let doc = buildTestRunCardDocument(
       ['test A'],
       testRealmOptions.testResultsModuleUrl,
@@ -526,7 +526,7 @@ module('factory-test-realm > resolveTestRun', function () {
     let handle = await resolveTestRun({
       ...testRealmOptions,
       targetRealmUrl: 'https://realms.example.test/user/personal/',
-      slug: 'my-ticket',
+      slug: 'my-issue',
       testNames: ['test A'],
       realmServerUrl: 'https://realms.example.test/',
       hostAppUrl: 'https://realms.example.test/',
@@ -534,37 +534,37 @@ module('factory-test-realm > resolveTestRun', function () {
     });
 
     assert.strictEqual(handle.status, 'running');
-    assert.strictEqual(handle.testRunId, 'Test Runs/my-ticket-1');
+    assert.strictEqual(handle.testRunId, 'Test Runs/my-issue-1');
   });
 
   test('creates new TestRun when most recent is completed', async function (assert) {
     let handle = await resolveTestRun({
       ...testRealmOptions,
       targetRealmUrl: 'https://realms.example.test/user/personal/',
-      slug: 'my-ticket',
+      slug: 'my-issue',
       testNames: ['test A'],
       realmServerUrl: 'https://realms.example.test/',
       hostAppUrl: 'https://realms.example.test/',
       fetch: buildMockSearchFetch([
-        { id: 'Test Runs/my-ticket-2', status: 'passed', sequenceNumber: 2 },
+        { id: 'Test Runs/my-issue-2', status: 'passed', sequenceNumber: 2 },
       ]),
     });
 
     assert.strictEqual(handle.status, 'running');
-    assert.strictEqual(handle.testRunId, 'Test Runs/my-ticket-3');
+    assert.strictEqual(handle.testRunId, 'Test Runs/my-issue-3');
   });
 
   test('resumes most recent running TestRun by default', async function (assert) {
     let handle = await resolveTestRun({
       ...testRealmOptions,
       targetRealmUrl: 'https://realms.example.test/user/personal/',
-      slug: 'my-ticket',
+      slug: 'my-issue',
       testNames: ['test A', 'test B'],
       realmServerUrl: 'https://realms.example.test/',
       hostAppUrl: 'https://realms.example.test/',
       fetch: buildMockSearchFetch([
         {
-          id: 'Test Runs/my-ticket-2',
+          id: 'Test Runs/my-issue-2',
           status: 'running',
           sequenceNumber: 2,
           moduleResults: [
@@ -580,26 +580,26 @@ module('factory-test-realm > resolveTestRun', function () {
     });
 
     assert.strictEqual(handle.status, 'running');
-    assert.strictEqual(handle.testRunId, 'Test Runs/my-ticket-2');
+    assert.strictEqual(handle.testRunId, 'Test Runs/my-issue-2');
   });
 
   test('ignores partial TestRun with forceNew: true', async function (assert) {
     let handle = await resolveTestRun({
       ...testRealmOptions,
       targetRealmUrl: 'https://realms.example.test/user/personal/',
-      slug: 'my-ticket',
+      slug: 'my-issue',
       testNames: ['test A'],
       forceNew: true,
       realmServerUrl: 'https://realms.example.test/',
       hostAppUrl: 'https://realms.example.test/',
       fetch: buildMockSearchFetch([
-        { id: 'Test Runs/my-ticket-2', status: 'running', sequenceNumber: 2 },
+        { id: 'Test Runs/my-issue-2', status: 'running', sequenceNumber: 2 },
       ]),
     });
 
     assert.strictEqual(handle.status, 'running');
     // forceNew creates a new run with incremented sequence
-    assert.strictEqual(handle.testRunId, 'Test Runs/my-ticket-3');
+    assert.strictEqual(handle.testRunId, 'Test Runs/my-issue-3');
   });
 
   test('does NOT resume older partial TestRun when newer completed exists', async function (assert) {
@@ -608,33 +608,33 @@ module('factory-test-realm > resolveTestRun', function () {
     let handle = await resolveTestRun({
       ...testRealmOptions,
       targetRealmUrl: 'https://realms.example.test/user/personal/',
-      slug: 'my-ticket',
+      slug: 'my-issue',
       testNames: ['test A'],
       realmServerUrl: 'https://realms.example.test/',
       hostAppUrl: 'https://realms.example.test/',
       fetch: buildMockSearchFetch([
-        { id: 'Test Runs/my-ticket-3', status: 'passed', sequenceNumber: 3 },
+        { id: 'Test Runs/my-issue-3', status: 'passed', sequenceNumber: 3 },
       ]),
     });
 
     assert.strictEqual(handle.status, 'running');
-    assert.strictEqual(handle.testRunId, 'Test Runs/my-ticket-4');
+    assert.strictEqual(handle.testRunId, 'Test Runs/my-issue-4');
   });
 
   test('sequence numbers increment correctly', async function (assert) {
     let handle = await resolveTestRun({
       ...testRealmOptions,
       targetRealmUrl: 'https://realms.example.test/user/personal/',
-      slug: 'my-ticket',
+      slug: 'my-issue',
       testNames: ['test A'],
       realmServerUrl: 'https://realms.example.test/',
       hostAppUrl: 'https://realms.example.test/',
       fetch: buildMockSearchFetch([
-        { id: 'Test Runs/my-ticket-7', status: 'failed', sequenceNumber: 7 },
+        { id: 'Test Runs/my-issue-7', status: 'failed', sequenceNumber: 7 },
       ]),
     });
 
-    assert.strictEqual(handle.testRunId, 'Test Runs/my-ticket-8');
+    assert.strictEqual(handle.testRunId, 'Test Runs/my-issue-8');
   });
 
   test('consecutive forceNew calls create separate TestRuns with incrementing sequences', async function (assert) {
@@ -644,7 +644,7 @@ module('factory-test-realm > resolveTestRun', function () {
     let handle1 = await resolveTestRun({
       ...testRealmOptions,
       targetRealmUrl: 'https://realms.example.test/user/personal/',
-      slug: 'my-ticket',
+      slug: 'my-issue',
       testNames: ['test A'],
       forceNew: true,
       realmServerUrl: 'https://realms.example.test/',
@@ -652,28 +652,28 @@ module('factory-test-realm > resolveTestRun', function () {
       fetch: buildMockSearchFetch([]),
     });
 
-    assert.strictEqual(handle1.testRunId, 'Test Runs/my-ticket-1');
+    assert.strictEqual(handle1.testRunId, 'Test Runs/my-issue-1');
     assert.false(handle1.resumed, 'first run is not resumed');
 
     // Second call with forceNew — should get sequence 2, not resume sequence 1
     let handle2 = await resolveTestRun({
       ...testRealmOptions,
       targetRealmUrl: 'https://realms.example.test/user/personal/',
-      slug: 'my-ticket',
+      slug: 'my-issue',
       testNames: ['test A'],
       forceNew: true,
       realmServerUrl: 'https://realms.example.test/',
       hostAppUrl: 'https://realms.example.test/',
       fetch: buildMockSearchFetch([
         {
-          id: 'Test Runs/my-ticket-1',
+          id: 'Test Runs/my-issue-1',
           status: 'running',
           sequenceNumber: 1,
         },
       ]),
     });
 
-    assert.strictEqual(handle2.testRunId, 'Test Runs/my-ticket-2');
+    assert.strictEqual(handle2.testRunId, 'Test Runs/my-issue-2');
     assert.false(handle2.resumed, 'second run is not resumed');
     assert.notStrictEqual(
       handle1.testRunId,
diff --git a/packages/software-factory/tests/factory-tool-builder.test.ts b/packages/software-factory/tests/factory-tool-builder.test.ts
index 07e8f9494c8..38b2e59eb70 100644
--- a/packages/software-factory/tests/factory-tool-builder.test.ts
+++ b/packages/software-factory/tests/factory-tool-builder.test.ts
@@ -43,7 +43,7 @@ const DEFAULT_CARD_TYPE_SCHEMAS = new Map<
     },
   ],
   [
-    'Ticket',
+    'Issue',
     {
       attributes: {
         type: 'object',
@@ -174,7 +174,7 @@ module('factory-tool-builder > tool building', function () {
     assert.true(toolNames.includes('write_file'));
     assert.true(toolNames.includes('read_file'));
     assert.true(toolNames.includes('search_realm'));
-    assert.true(toolNames.includes('update_ticket'));
+    assert.true(toolNames.includes('update_issue'));
     assert.true(toolNames.includes('create_knowledge'));
     assert.true(toolNames.includes('signal_done'));
     assert.true(toolNames.includes('request_clarification'));
@@ -303,21 +303,21 @@ module('factory-tool-builder > realm targeting and auth', function () {
     assert.strictEqual(requests[0].headers['Authorization'], TARGET_TOKEN);
   });
 
-  test('update_ticket uses target realm JWT', async function (assert) {
+  test('update_issue uses target realm JWT', async function (assert) {
     let { fetch: mockFetch, requests } = createMockFetch(200, {});
     let registry = new ToolRegistry();
     let { executor } = createMockToolExecutor(new Map());
     let config = makeConfig({ fetch: mockFetch });
     let tools = buildFactoryTools(config, executor, registry);
-    let updateTool = findTool(tools, 'update_ticket');
+    let updateTool = findTool(tools, 'update_issue');
 
     await updateTool.execute({
-      path: 'Ticket/1.json',
+      path: 'Issues/1.json',
       attributes: { status: 'done' },
     });
 
     assert.strictEqual(requests[0].headers['Authorization'], TARGET_TOKEN);
-    assert.strictEqual(requests[0].url, `${TARGET_REALM}Ticket/1.json`);
+    assert.strictEqual(requests[0].url, `${TARGET_REALM}Issues/1.json`);
   });
 
   test('create_knowledge uses target realm JWT', async function (assert) {
@@ -346,7 +346,7 @@ module('factory-tool-builder > realm targeting and auth', function () {
     let searchTool = findTool(tools, 'search_realm');
 
     await searchTool.execute({
-      query: { filter: { type: { name: 'Ticket' } } },
+      query: { filter: { type: { name: 'Issue' } } },
     });
 
     assert.strictEqual(requests[0].headers['Authorization'], TARGET_TOKEN);
@@ -630,7 +630,7 @@ module(
             },
           ],
           [
-            'Ticket',
+            'Issue',
             {
               attributes: {
                 type: 'object',
@@ -680,13 +680,13 @@ module(
         ['planning', 'active'],
       );
 
-      // update_ticket uses runtime schema with relationships
-      let ticketTool = findTool(tools, 'update_ticket');
-      let ticketParams = ticketTool.parameters as {
+      // update_issue uses runtime schema with relationships
+      let issueTool = findTool(tools, 'update_issue');
+      let issueParams = issueTool.parameters as {
         properties: Record<string, Record<string, unknown>>;
       };
-      assert.true('attributes' in ticketParams.properties);
-      assert.true('relationships' in ticketParams.properties);
+      assert.true('attributes' in issueParams.properties);
+      assert.true('relationships' in issueParams.properties);
 
       // create_knowledge uses runtime schema
       let knowledgeTool = findTool(tools, 'create_knowledge');
@@ -707,22 +707,22 @@ module(
       let tools = buildFactoryTools(config, executor, registry);
       let toolNames = tools.map((t) => t.name);
       assert.false(toolNames.includes('update_project'));
-      assert.false(toolNames.includes('update_ticket'));
+      assert.false(toolNames.includes('update_issue'));
       assert.false(toolNames.includes('create_knowledge'));
       assert.true(toolNames.includes('write_file'));
       assert.true(toolNames.includes('run_command'));
     });
 
-    test('update_ticket assembles JSON:API document from attributes', async function (assert) {
+    test('update_issue assembles JSON:API document from attributes', async function (assert) {
       let { fetch: mockFetch, requests } = createMockFetch(200, {});
       let registry = new ToolRegistry();
       let { executor } = createMockToolExecutor(new Map());
       let config = makeConfig({ fetch: mockFetch });
       let tools = buildFactoryTools(config, executor, registry);
-      let tool = findTool(tools, 'update_ticket');
+      let tool = findTool(tools, 'update_issue');
 
       await tool.execute({
-        path: 'Ticket/1.json',
+        path: 'Issues/1.json',
         attributes: { status: 'done', summary: 'Build sticky note' },
       });
 
@@ -730,7 +730,7 @@ module(
       let body = JSON.parse(requests[0].body);
       assert.strictEqual(body.data.type, 'card');
       assert.strictEqual(body.data.attributes.status, 'done');
-      assert.strictEqual(body.data.meta.adoptsFrom.name, 'Ticket');
+      assert.strictEqual(body.data.meta.adoptsFrom.name, 'Issue');
       assert.strictEqual(
         body.data.meta.adoptsFrom.module,
         `${TARGET_REALM}darkfactory`,
diff --git a/packages/software-factory/tests/factory-tool-executor.integration.test.ts b/packages/software-factory/tests/factory-tool-executor.integration.test.ts
index b99b7eb3de4..5dd2b600b1a 100644
--- a/packages/software-factory/tests/factory-tool-executor.integration.test.ts
+++ b/packages/software-factory/tests/factory-tool-executor.integration.test.ts
@@ -214,7 +214,7 @@ module('factory-tool-executor integration > realm-api requests', function () {
 
       let query = JSON.stringify({
         filter: {
-          type: { module: 'https://example.test/ticket', name: 'Ticket' },
+          type: { module: 'https://example.test/issue', name: 'Issue' },
         },
       });
 
diff --git a/packages/software-factory/tests/factory-tool-executor.spec.ts b/packages/software-factory/tests/factory-tool-executor.spec.ts
index 46ff960880a..ce5a305fa36 100644
--- a/packages/software-factory/tests/factory-tool-executor.spec.ts
+++ b/packages/software-factory/tests/factory-tool-executor.spec.ts
@@ -230,7 +230,7 @@ async function buildToolsForRealm(realm: {
       relationships?: Record<string, unknown>;
     }
   >();
-  for (let name of ['Project', 'Ticket', 'KnowledgeArticle']) {
+  for (let name of ['Project', 'Issue', 'KnowledgeArticle']) {
     let schema = await fetchCardTypeSchema(
       realm.realmServerURL.href,
       realm.realmURL.href,
@@ -297,18 +297,18 @@ test('update_project writes and reads back a project card', async ({
   );
 });
 
-test('update_ticket writes and reads back a ticket card', async ({ realm }) => {
+test('update_issue writes and reads back an issue card', async ({ realm }) => {
   let tools = await buildToolsForRealm(realm);
-  let updateTicket = tools.find((t) => t.name === 'update_ticket')!;
+  let updateIssue = tools.find((t) => t.name === 'update_issue')!;
   let readFile = tools.find((t) => t.name === 'read_file')!;
 
-  expect(updateTicket).toBeDefined();
+  expect(updateIssue).toBeDefined();
 
-  let writeResult = (await updateTicket.execute({
-    path: 'Tickets/tool-test-ticket.json',
+  let writeResult = (await updateIssue.execute({
+    path: 'Issues/tool-test-issue.json',
     attributes: {
-      summary: 'Test ticket for update_ticket tool',
-      ticketStatus: 'in_progress',
+      summary: 'Test issue for update_issue tool',
+      issueStatus: 'in_progress',
       priority: 'high',
     },
   })) as CardWriteResult;
@@ -316,16 +316,14 @@ test('update_ticket writes and reads back a ticket card', async ({ realm }) => {
   expect(writeResult.ok).toBe(true);
 
   let readResult = (await readFile.execute({
-    path: 'Tickets/tool-test-ticket.json',
+    path: 'Issues/tool-test-issue.json',
   })) as CardReadResult;
 
   expect(readResult.ok).toBe(true);
   expect(readResult.document!.data.attributes!.summary).toBe(
-    'Test ticket for update_ticket tool',
-  );
-  expect(readResult.document!.data.attributes!.ticketStatus).toBe(
-    'in_progress',
+    'Test issue for update_issue tool',
   );
+  expect(readResult.document!.data.attributes!.issueStatus).toBe('in_progress');
 });
 
 test('create_knowledge writes and reads back a knowledge article', async ({
@@ -393,7 +391,7 @@ test('create_catalog_spec writes and reads back a Spec card', async ({
 
 // ---------------------------------------------------------------------------
 // realm-search with pre-seeded fixture data
-// The darkfactory-adopter fixture has Project and Ticket cards with
+// The darkfactory-adopter fixture has Project and Issue cards with
 // distinct types — we search for each and verify the filter works.
 // ---------------------------------------------------------------------------
 
@@ -448,26 +446,26 @@ test.describe('realm-search with seeded fixture data', () => {
     ).toBe(true);
     let projectIds = (projectOutput.data ?? []).map((d) => d.id);
 
-    // Verify no Ticket cards leak into the Project results
-    let ticketResult = await executor.execute('realm-search', {
+    // Verify no Issue cards leak into the Project results
+    let issueResult = await executor.execute('realm-search', {
       'realm-url': realm.realmURL.href,
       query: JSON.stringify({
         filter: {
-          type: { module: darkfactoryModule, name: 'Ticket' },
+          type: { module: darkfactoryModule, name: 'Issue' },
         },
       }),
     });
-    expect(ticketResult.exitCode).toBe(0);
-    let ticketOutput = ticketResult.output as {
+    expect(issueResult.exitCode).toBe(0);
+    let issueOutput = issueResult.output as {
       data?: { id: string }[];
     };
-    let ticketIds = (ticketOutput.data ?? []).map((d) => d.id);
+    let issueIds = (issueOutput.data ?? []).map((d) => d.id);
 
-    // Project and Ticket result sets must be disjoint
-    for (let ticketId of ticketIds) {
+    // Project and Issue result sets must be disjoint
+    for (let issueId of issueIds) {
       expect(
-        projectIds.includes(ticketId),
-        `Ticket ${ticketId} should not appear in Project results`,
+        projectIds.includes(issueId),
+        `Issue ${issueId} should not appear in Project results`,
       ).toBe(false);
     }
   });
diff --git a/packages/software-factory/tests/factory-tool-executor.test.ts b/packages/software-factory/tests/factory-tool-executor.test.ts
index 87af5ddb5b5..60c6ea048c8 100644
--- a/packages/software-factory/tests/factory-tool-executor.test.ts
+++ b/packages/software-factory/tests/factory-tool-executor.test.ts
@@ -363,7 +363,7 @@ module('factory-tool-executor > realm-api execution', function () {
 
     let result = await executor.execute('realm-search', {
       'realm-url': 'https://realms.example.test/user/target/',
-      query: JSON.stringify({ filter: { type: { name: 'Ticket' } } }),
+      query: JSON.stringify({ filter: { type: { name: 'Issue' } } }),
     });
 
     assert.strictEqual(capturedMethod, 'QUERY');
diff --git a/packages/software-factory/tests/runtime-schema.spec.ts b/packages/software-factory/tests/runtime-schema.spec.ts
index 33aebcbd505..b1728c43076 100644
--- a/packages/software-factory/tests/runtime-schema.spec.ts
+++ b/packages/software-factory/tests/runtime-schema.spec.ts
@@ -59,7 +59,7 @@ test('fetches Project schema via GetCardTypeSchemaCommand', async ({
   expect(schema.attributes.properties).toHaveProperty('scope');
 });
 
-test('fetches Ticket schema with enum fields', async ({ realm }) => {
+test('fetches Issue schema with enum fields', async ({ realm }) => {
   let realmServerUrl = realm.realmServerURL.href;
   let sourceRealmUrl = ensureTrailingSlash(
     sourceRealmURLFor(realm.realmServerURL).href,
@@ -68,7 +68,7 @@ test('fetches Ticket schema with enum fields', async ({ realm }) => {
   let schema = await fetchCardTypeSchema(
     realmServerUrl,
     sourceRealmUrl,
-    { module: `${sourceRealmUrl}darkfactory`, name: 'Ticket' },
+    { module: `${sourceRealmUrl}darkfactory`, name: 'Issue' },
     { authorization: `Bearer ${realm.ownerBearerToken}` },
   );
 
@@ -78,7 +78,7 @@ test('fetches Ticket schema with enum fields', async ({ realm }) => {
   let attrs = schema!.attributes as {
     properties: Record<string, Record<string, unknown>>;
   };
-  expect(attrs.properties).toHaveProperty('ticketId');
+  expect(attrs.properties).toHaveProperty('issueId');
   expect(attrs.properties).toHaveProperty('summary');
   expect(attrs.properties).toHaveProperty('status');
   expect(attrs.properties).toHaveProperty('priority');

From 97a125e68137c25aa27263c8f0252c507d489a10 Mon Sep 17 00:00:00 2001
From: Hassan Abdel-Rahman <hassan.abdelrahman@gmail.com>
Date: Wed, 8 Apr 2026 14:18:45 -0400
Subject: [PATCH 02/10] Remove assignedAgent field from Issue and delete
 pick-ticket.ts

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>
---
 packages/software-factory/package.json        |   1 -
 .../software-factory/realm/darkfactory.gts    |   1 -
 .../scripts/lib/factory-tool-executor.ts      |   1 -
 .../scripts/lib/factory-tool-registry.ts      |  39 -----
 .../software-factory/scripts/pick-ticket.ts   | 165 ------------------
 .../darkfactory-adopter/Issues/issue-001.json |   5 -
 .../darkfactory-adopter/issue-demo.json       |   5 -
 .../tests/factory-tool-registry.test.ts       |   1 -
 8 files changed, 218 deletions(-)
 delete mode 100644 packages/software-factory/scripts/pick-ticket.ts

diff --git a/packages/software-factory/package.json b/packages/software-factory/package.json
index 37b27080075..5b186c586a7 100644
--- a/packages/software-factory/package.json
+++ b/packages/software-factory/package.json
@@ -5,7 +5,6 @@
   "license": "MIT",
   "description": "Software Factory workspace package",
   "scripts": {
-    "boxel:pick-ticket": "NODE_NO_WARNINGS=1 ts-node --transpileOnly scripts/pick-ticket.ts",
     "boxel:search": "NODE_NO_WARNINGS=1 ts-node --transpileOnly scripts/boxel-search.ts",
     "boxel:session": "NODE_NO_WARNINGS=1 ts-node --transpileOnly scripts/boxel-session.ts",
     "cache:prepare": "NODE_NO_WARNINGS=1 ts-node --transpileOnly src/cli/cache-realm.ts",
diff --git a/packages/software-factory/realm/darkfactory.gts b/packages/software-factory/realm/darkfactory.gts
index f52808ca441..c2c5a362d8e 100644
--- a/packages/software-factory/realm/darkfactory.gts
+++ b/packages/software-factory/realm/darkfactory.gts
@@ -250,7 +250,6 @@ export class Issue extends CardDef {
   @field status = contains(IssueStatusField);
   @field priority = contains(IssuePriorityField);
   @field project = linksTo(() => Project);
-  @field assignedAgent = linksTo(() => AgentProfile);
   @field blockedBy = linksToMany(() => Issue);
   @field relatedKnowledge = linksToMany(() => KnowledgeArticle);
   @field acceptanceCriteria = contains(MarkdownField);
diff --git a/packages/software-factory/scripts/lib/factory-tool-executor.ts b/packages/software-factory/scripts/lib/factory-tool-executor.ts
index 3d4063ed14f..fc7f66beba8 100644
--- a/packages/software-factory/scripts/lib/factory-tool-executor.ts
+++ b/packages/software-factory/scripts/lib/factory-tool-executor.ts
@@ -26,7 +26,6 @@ const DEFAULT_TIMEOUT_MS = 60_000;
  */
 const SCRIPT_FILE_MAP: Record<string, string> = {
   'search-realm': 'boxel-search.ts',
-  'pick-ticket': 'pick-ticket.ts',
   'get-session': 'boxel-session.ts',
   'run-realm-tests': 'run-realm-tests.ts',
 };
diff --git a/packages/software-factory/scripts/lib/factory-tool-registry.ts b/packages/software-factory/scripts/lib/factory-tool-registry.ts
index e918e0ff38e..7201762ebc3 100644
--- a/packages/software-factory/scripts/lib/factory-tool-registry.ts
+++ b/packages/software-factory/scripts/lib/factory-tool-registry.ts
@@ -62,45 +62,6 @@ const SCRIPT_TOOLS: ToolManifest[] = [
       },
     ],
   },
-  {
-    name: 'pick-ticket',
-    description: 'Find tickets by status, priority, project, or agent.',
-    category: 'script',
-    outputFormat: 'json',
-    args: [
-      {
-        name: 'realm',
-        type: 'string',
-        required: true,
-        description: 'Target realm URL',
-      },
-      {
-        name: 'status',
-        type: 'string',
-        required: false,
-        description:
-          'Comma-separated status filter (default: backlog,in_progress,review)',
-      },
-      {
-        name: 'project',
-        type: 'string',
-        required: false,
-        description: 'Filter by project ID',
-      },
-      {
-        name: 'agent',
-        type: 'string',
-        required: false,
-        description: 'Filter by assigned agent ID',
-      },
-      {
-        name: 'module',
-        type: 'string',
-        required: false,
-        description: 'Issue schema module URL',
-      },
-    ],
-  },
   {
     name: 'get-session',
     description:
diff --git a/packages/software-factory/scripts/pick-ticket.ts b/packages/software-factory/scripts/pick-ticket.ts
deleted file mode 100644
index da8d4d2e3d2..00000000000
--- a/packages/software-factory/scripts/pick-ticket.ts
+++ /dev/null
@@ -1,165 +0,0 @@
-import {
-  getAccessibleRealmTokens,
-  matrixLogin,
-  parseArgs,
-  printJson,
-  searchRealm,
-  type SearchResultCard,
-  type SearchSort,
-} from './lib/boxel';
-
-type IssueStatus = 'backlog' | 'in_progress' | 'blocked' | 'review' | 'done';
-type IssuePriority = 'critical' | 'high' | 'medium' | 'low';
-
-interface CompactIssue {
-  id: string;
-  issueId: string | null;
-  summary: string | null;
-  status: IssueStatus | null;
-  priority: IssuePriority | null;
-  project: string | null;
-}
-
-function cardAttribute(card: SearchResultCard, key: string): unknown {
-  return card.attributes?.[key];
-}
-
-function stringAttribute(card: SearchResultCard, key: string): string | null {
-  let value = cardAttribute(card, key);
-  return typeof value === 'string' ? value : null;
-}
-
-function enumAttribute<T extends string>(
-  card: SearchResultCard,
-  key: string,
-  allowedValues: readonly T[],
-): T | null {
-  let value = cardAttribute(card, key);
-  if (typeof value !== 'string') {
-    return null;
-  }
-
-  return allowedValues.includes(value as T) ? (value as T) : null;
-}
-
-function cardProjectLink(card: SearchResultCard): string | null {
-  let project = card.relationships?.project;
-  if (typeof project !== 'object' || project === null) {
-    return null;
-  }
-  let links = (project as { links?: unknown }).links;
-  if (typeof links !== 'object' || links === null) {
-    return null;
-  }
-  let self = (links as { self?: unknown }).self;
-  return typeof self === 'string' ? self : null;
-}
-
-async function main(): Promise<void> {
-  let args = parseArgs(process.argv.slice(2));
-  if (typeof args.realm !== 'string') {
-    throw new Error(
-      'Usage: npm run boxel:pick-ticket -- --realm <realm-url> [--module <issue-schema-module-url>]',
-    );
-  }
-
-  let realmUrl = args.realm;
-  let statusList = (
-    typeof args.status === 'string' ? args.status : 'backlog,in_progress,review'
-  )
-    .split(',')
-    .map((value) => value.trim())
-    .filter(Boolean);
-  let moduleUrl =
-    typeof args.module === 'string'
-      ? args.module
-      : `${realmUrl.endsWith('/') ? realmUrl : `${realmUrl}/`}darkfactory`;
-
-  let matrixAuth = await matrixLogin();
-  let realmTokens = await getAccessibleRealmTokens(matrixAuth);
-  let jwt = realmTokens[realmUrl.endsWith('/') ? realmUrl : `${realmUrl}/`];
-
-  let query: {
-    filter: {
-      type: { module: string; name: string };
-      any: Array<{ eq: { status: string } }>;
-      eq?: Record<string, string>;
-    };
-    sort: SearchSort[];
-  } = {
-    filter: {
-      type: {
-        module: moduleUrl,
-        name: 'Issue',
-      },
-      any: statusList.map((status) => ({
-        eq: { status },
-      })),
-    },
-    sort: [
-      {
-        by: 'priority',
-        direction: 'asc',
-        on: {
-          module: moduleUrl,
-          name: 'Issue',
-        },
-      },
-      {
-        by: 'updatedAt',
-        direction: 'asc',
-        on: {
-          module: moduleUrl,
-          name: 'Issue',
-        },
-      },
-    ],
-  };
-
-  if (typeof args.project === 'string') {
-    query.filter.eq = {
-      ...(query.filter.eq ?? {}),
-      'project.id': args.project,
-    };
-  }
-
-  if (typeof args.agent === 'string') {
-    query.filter.eq = {
-      ...(query.filter.eq ?? {}),
-      'assignedAgent.id': args.agent,
-    };
-  }
-
-  let results = await searchRealm({ realmUrl, jwt, query });
-  let compact: CompactIssue[] = (results.data ?? []).map((card) => ({
-    id: card.id,
-    issueId: stringAttribute(card, 'issueId'),
-    summary: stringAttribute(card, 'summary'),
-    status: enumAttribute(card, 'status', [
-      'backlog',
-      'in_progress',
-      'blocked',
-      'review',
-      'done',
-    ]),
-    priority: enumAttribute(card, 'priority', [
-      'critical',
-      'high',
-      'medium',
-      'low',
-    ]),
-    project: cardProjectLink(card),
-  }));
-
-  printJson({
-    count: compact.length,
-    issues: compact,
-  });
-}
-
-main().catch((error: unknown) => {
-  let message =
-    error instanceof Error ? (error.stack ?? error.message) : String(error);
-  console.error(message);
-  process.exit(1);
-});
diff --git a/packages/software-factory/test-fixtures/darkfactory-adopter/Issues/issue-001.json b/packages/software-factory/test-fixtures/darkfactory-adopter/Issues/issue-001.json
index b7bca6d2170..acc44fa39a7 100644
--- a/packages/software-factory/test-fixtures/darkfactory-adopter/Issues/issue-001.json
+++ b/packages/software-factory/test-fixtures/darkfactory-adopter/Issues/issue-001.json
@@ -18,11 +18,6 @@
           "self": "../Projects/demo-project"
         }
       },
-      "assignedAgent": {
-        "links": {
-          "self": "../Agent Profiles/demo-agent"
-        }
-      },
       "relatedKnowledge.0": {
         "links": {
           "self": "../Knowledge Articles/agent-onboarding"
diff --git a/packages/software-factory/test-fixtures/darkfactory-adopter/issue-demo.json b/packages/software-factory/test-fixtures/darkfactory-adopter/issue-demo.json
index a1d80e08f33..9f60e245402 100644
--- a/packages/software-factory/test-fixtures/darkfactory-adopter/issue-demo.json
+++ b/packages/software-factory/test-fixtures/darkfactory-adopter/issue-demo.json
@@ -18,11 +18,6 @@
           "self": "./project-demo"
         }
       },
-      "assignedAgent": {
-        "links": {
-          "self": "./agent-demo"
-        }
-      },
       "relatedKnowledge.0": {
         "links": {
           "self": "./knowledge-article-demo"
diff --git a/packages/software-factory/tests/factory-tool-registry.test.ts b/packages/software-factory/tests/factory-tool-registry.test.ts
index c80e4e418d5..b251ae29721 100644
--- a/packages/software-factory/tests/factory-tool-registry.test.ts
+++ b/packages/software-factory/tests/factory-tool-registry.test.ts
@@ -264,7 +264,6 @@ module('factory-tool-registry > built-in manifests', function () {
   test('expected script tools are registered', function (assert) {
     let registry = new ToolRegistry();
     assert.true(registry.has('search-realm'));
-    assert.true(registry.has('pick-ticket'));
     assert.true(registry.has('get-session'));
     assert.true(registry.has('run-realm-tests'));
   });

From 963692130eb15273d3290ca5cde2f594b8b405ed Mon Sep 17 00:00:00 2001
From: Hassan Abdel-Rahman <hassan.abdelrahman@gmail.com>
Date: Wed, 8 Apr 2026 14:28:27 -0400
Subject: [PATCH 03/10] =?UTF-8?q?Fix=20issueStatus=20=E2=86=92=20status=20?=
 =?UTF-8?q?in=20test=20and=20docs=20(PR=20review=20feedback)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 .../skills/boxel-development/references/dev-realm-search.md | 6 +++---
 packages/software-factory/docs/testing-strategy.md          | 2 +-
 .../software-factory/tests/factory-tool-executor.spec.ts    | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/packages/software-factory/.agents/skills/boxel-development/references/dev-realm-search.md b/packages/software-factory/.agents/skills/boxel-development/references/dev-realm-search.md
index f4c9e53f445..e4b1ec7563a 100644
--- a/packages/software-factory/.agents/skills/boxel-development/references/dev-realm-search.md
+++ b/packages/software-factory/.agents/skills/boxel-development/references/dev-realm-search.md
@@ -42,7 +42,7 @@ Use `eq` to match exact field values. You must specify `on` to scope the field t
       "module": "http://localhost:4201/software-factory/darkfactory",
       "name": "Issue"
     },
-    "eq": { "issueStatus": "in_progress" }
+    "eq": { "status": "in_progress" }
   }
 }
 ```
@@ -232,7 +232,7 @@ You can only filter/sort on fields that exist on the card type. To find which fi
 }
 ```
 
-2. The result contains `attributes.properties` listing all searchable fields (e.g., `issueStatus`, `summary`, `priority`).
+2. The result contains `attributes.properties` listing all searchable fields (e.g., `status`, `summary`, `priority`).
 
 3. Use those field names in your `eq`, `contains`, `range`, or `sort` with the matching `on` type.
 
@@ -240,7 +240,7 @@ The card tools (`update_project`, `update_issue`, `create_knowledge`, `create_ca
 
 ### Inheritance
 
-Filtering on a base card type's fields matches all cards that inherit from it. For example, filtering on `CardDef` fields like `cardTitle` or `cardDescription` finds cards of any type. Filtering on an `Issue` field like `issueStatus` finds only Issue cards (and any subtypes of Issue).
+Filtering on a base card type's fields matches all cards that inherit from it. For example, filtering on `CardDef` fields like `cardTitle` or `cardDescription` finds cards of any type. Filtering on an `Issue` field like `status` finds only Issue cards (and any subtypes of Issue).
 
 ### Searching Through Relationship Fields
 
diff --git a/packages/software-factory/docs/testing-strategy.md b/packages/software-factory/docs/testing-strategy.md
index 7c5e648add0..554adcdde97 100644
--- a/packages/software-factory/docs/testing-strategy.md
+++ b/packages/software-factory/docs/testing-strategy.md
@@ -59,7 +59,7 @@ Flow per issue:
 8. agent iterates on implementation and/or tests until all tests pass
 9. passing TestRun cards serve as durable verification evidence for the issue, linked to the Project card
 
-This loop is the primary quality gate. A issue cannot be marked done without at least one passing TestRun in the target realm.
+This loop is the primary quality gate. An issue cannot be marked done without at least one passing TestRun in the target realm.
 
 ## Core Principle
 
diff --git a/packages/software-factory/tests/factory-tool-executor.spec.ts b/packages/software-factory/tests/factory-tool-executor.spec.ts
index ce5a305fa36..fed21fb9f5b 100644
--- a/packages/software-factory/tests/factory-tool-executor.spec.ts
+++ b/packages/software-factory/tests/factory-tool-executor.spec.ts
@@ -308,7 +308,7 @@ test('update_issue writes and reads back an issue card', async ({ realm }) => {
     path: 'Issues/tool-test-issue.json',
     attributes: {
       summary: 'Test issue for update_issue tool',
-      issueStatus: 'in_progress',
+      status: 'in_progress',
       priority: 'high',
     },
   })) as CardWriteResult;
@@ -323,7 +323,7 @@ test('update_issue writes and reads back an issue card', async ({ realm }) => {
   expect(readResult.document!.data.attributes!.summary).toBe(
     'Test issue for update_issue tool',
   );
-  expect(readResult.document!.data.attributes!.issueStatus).toBe('in_progress');
+  expect(readResult.document!.data.attributes!.status).toBe('in_progress');
 });
 
 test('create_knowledge writes and reads back a knowledge article', async ({

From b61a7be0f47d01291417df57e31918d428849499 Mon Sep 17 00:00:00 2001
From: Hassan Abdel-Rahman <hassan.abdelrahman@gmail.com>
Date: Wed, 8 Apr 2026 15:29:03 -0400
Subject: [PATCH 04/10] CS-10676: Issue-aware ContextBuilder with
 buildForIssue() method

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>
---
 .../scripts/lib/factory-agent-types.ts        |  47 ++
 .../scripts/lib/factory-context-builder.ts    | 140 +++++
 .../tests/factory-context-builder.test.ts     | 512 ++++++++++++++++++
 3 files changed, 699 insertions(+)

diff --git a/packages/software-factory/scripts/lib/factory-agent-types.ts b/packages/software-factory/scripts/lib/factory-agent-types.ts
index 97395cbd330..ba8b9e4824f 100644
--- a/packages/software-factory/scripts/lib/factory-agent-types.ts
+++ b/packages/software-factory/scripts/lib/factory-agent-types.ts
@@ -111,6 +111,45 @@ export interface TestResult {
   durationMs: number;
 }
 
+// ---------------------------------------------------------------------------
+// Validation types (Phase 2 — broader than TestResult)
+// ---------------------------------------------------------------------------
+
+/** Steps in the post-iteration validation pipeline. */
+export type ValidationStep =
+  | 'parse'
+  | 'lint'
+  | 'evaluate'
+  | 'instantiate'
+  | 'test';
+
+export interface ValidationError {
+  file?: string;
+  message: string;
+  stackTrace?: string;
+}
+
+/** Result of a single validation step. */
+export interface ValidationStepResult {
+  step: ValidationStep;
+  passed: boolean;
+  files?: string[];
+  errors: ValidationError[];
+}
+
+/** Aggregated results from a full validation run (all steps). */
+export interface ValidationResults {
+  passed: boolean;
+  steps: ValidationStepResult[];
+}
+
+/** A resolved clarification answer from a previously-blocked issue. */
+export interface ClarificationAnswer {
+  issueId: string;
+  question: string;
+  answer: string;
+}
+
 export interface ToolResult {
   tool: string;
   exitCode: number;
@@ -134,6 +173,14 @@ export interface AgentContext {
   iteration?: number;
   targetRealmUrl: string;
   testRealmUrl: string;
+  /** Validation results from the prior inner-loop iteration (Phase 2). */
+  validationResults?: ValidationResults;
+  /** Resolved clarification answers from previously-blocked issues (Phase 2). */
+  clarifications?: ClarificationAnswer[];
+  /** Brief URL for bootstrap issues (Phase 2). */
+  briefUrl?: string;
+  /** Local workspace directory path (Phase 2). */
+  workspaceDir?: string;
 }
 
 export interface AgentAction {
diff --git a/packages/software-factory/scripts/lib/factory-context-builder.ts b/packages/software-factory/scripts/lib/factory-context-builder.ts
index 86882d6e747..256af7819b7 100644
--- a/packages/software-factory/scripts/lib/factory-context-builder.ts
+++ b/packages/software-factory/scripts/lib/factory-context-builder.ts
@@ -1,9 +1,11 @@
 import type {
   AgentContext,
+  ClarificationAnswer,
   IssueCard,
   KnowledgeArticle,
   ProjectCard,
   TestResult,
+  ValidationResults,
 } from './factory-agent';
 
 import type { ResolvedSkill } from './factory-agent';
@@ -14,6 +16,23 @@ import {
   type SkillResolver,
 } from './factory-skill-loader';
 
+// ---------------------------------------------------------------------------
+// Issue relationship loader (Phase 2)
+// ---------------------------------------------------------------------------
+
+/**
+ * Loads related cards from an issue's relationships.
+ *
+ * The Phase 2 `buildForIssue()` method uses this to traverse the issue's
+ * linksTo / linksToMany fields (project, relatedKnowledge, blockedBy)
+ * without coupling ContextBuilder to the realm I/O layer.
+ */
+export interface IssueRelationshipLoader {
+  loadProject(issue: IssueCard): Promise<ProjectCard | undefined>;
+  loadKnowledge(issue: IssueCard): Promise<KnowledgeArticle[]>;
+  loadBlockedBy(issue: IssueCard): Promise<IssueCard[]>;
+}
+
 // ---------------------------------------------------------------------------
 // Configuration
 // ---------------------------------------------------------------------------
@@ -23,6 +42,8 @@ export interface ContextBuilderConfig {
   skillLoader: SkillLoaderInterface;
   /** Maximum token budget for skills. When set, enforceSkillBudget() trims. */
   maxSkillTokens?: number;
+  /** Loader for traversing issue relationships (required for buildForIssue). */
+  issueLoader?: IssueRelationshipLoader;
 }
 
 // ---------------------------------------------------------------------------
@@ -33,11 +54,13 @@ export class ContextBuilder {
   private skillResolver: SkillResolver;
   private skillLoader: SkillLoaderInterface;
   private maxSkillTokens: number | undefined;
+  private issueLoader: IssueRelationshipLoader | undefined;
 
   constructor(config: ContextBuilderConfig) {
     this.skillResolver = config.skillResolver;
     this.skillLoader = config.skillLoader;
     this.maxSkillTokens = config.maxSkillTokens;
+    this.issueLoader = config.issueLoader;
   }
 
   /**
@@ -89,4 +112,121 @@ export class ContextBuilder {
 
     return context;
   }
+
+  /**
+   * Build agent context from the current issue (Phase 2 issue-driven loop).
+   *
+   * Unlike `build()` which takes pre-loaded project/knowledge, this method
+   * traverses issue relationships to load them automatically:
+   * - project from issue.project
+   * - knowledge from issue.relatedKnowledge
+   * - resolved clarification answers from issue.blockedBy (done clarifications)
+   *
+   * Accepts optional validationResults from the prior inner-loop iteration
+   * so the agent can self-correct on failures.
+   */
+  async buildForIssue(params: {
+    issue: IssueCard;
+    targetRealmUrl: string;
+    testRealmUrl: string;
+    workspaceDir?: string;
+    validationResults?: ValidationResults;
+    briefUrl?: string;
+  }): Promise<AgentContext> {
+    if (!this.issueLoader) {
+      throw new Error(
+        'buildForIssue() requires an issueLoader in ContextBuilderConfig',
+      );
+    }
+
+    let { issue, targetRealmUrl, testRealmUrl } = params;
+
+    // Step 1: Traverse issue relationships
+    let [project, knowledge, blockedByIssues] = await Promise.all([
+      this.issueLoader.loadProject(issue),
+      this.issueLoader.loadKnowledge(issue),
+      this.issueLoader.loadBlockedBy(issue),
+    ]);
+
+    if (!project) {
+      throw new Error(
+        `Issue "${issue.id}" has no linked project — cannot build context`,
+      );
+    }
+
+    // Step 2: Extract clarification answers from resolved blockedBy issues
+    let clarifications = extractClarifications(blockedByIssues);
+
+    // Step 3: Resolve and load skills
+    let skillNames = this.skillResolver.resolve(issue, project);
+    let skills: ResolvedSkill[] = await this.skillLoader.loadAll(
+      skillNames,
+      issue,
+    );
+
+    // Step 4: Enforce token budget if configured
+    skills = enforceSkillBudget(skills, this.maxSkillTokens);
+
+    // Step 5: Assemble the context
+    let context: AgentContext = {
+      project,
+      issue,
+      knowledge,
+      skills,
+      targetRealmUrl,
+      testRealmUrl,
+    };
+
+    if (params.validationResults) {
+      context.validationResults = params.validationResults;
+    }
+
+    if (clarifications.length > 0) {
+      context.clarifications = clarifications;
+    }
+
+    if (params.briefUrl) {
+      context.briefUrl = params.briefUrl;
+    }
+
+    if (params.workspaceDir) {
+      context.workspaceDir = params.workspaceDir;
+    }
+
+    return context;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract clarification answers from resolved blockedBy issues.
+ *
+ * A clarification issue is one with issueType === 'clarification' and
+ * status === 'done'. The question comes from the issue summary, and the
+ * answer from the issue description.
+ */
+function extractClarifications(
+  blockedByIssues: IssueCard[],
+): ClarificationAnswer[] {
+  let clarifications: ClarificationAnswer[] = [];
+
+  for (let blocked of blockedByIssues) {
+    if (
+      blocked.issueType === 'clarification' &&
+      blocked.status === 'done' &&
+      typeof blocked.summary === 'string' &&
+      typeof blocked.description === 'string'
+    ) {
+      clarifications.push({
+        issueId: blocked.id,
+        question: blocked.summary,
+        answer: blocked.description,
+      });
+    }
+  }
+
+  return clarifications;
 }
diff --git a/packages/software-factory/tests/factory-context-builder.test.ts b/packages/software-factory/tests/factory-context-builder.test.ts
index b9f82de136c..04b718e42c0 100644
--- a/packages/software-factory/tests/factory-context-builder.test.ts
+++ b/packages/software-factory/tests/factory-context-builder.test.ts
@@ -5,12 +5,14 @@ import type {
   ProjectCard,
   ResolvedSkill,
   TestResult,
+  ValidationResults,
   IssueCard,
 } from '../scripts/lib/factory-agent';
 
 import {
   ContextBuilder,
   type ContextBuilderConfig,
+  type IssueRelationshipLoader,
 } from '../scripts/lib/factory-context-builder';
 
 import type {
@@ -72,6 +74,37 @@ class StubSkillLoader implements SkillLoaderInterface {
   }
 }
 
+class StubIssueRelationshipLoader implements IssueRelationshipLoader {
+  project: ProjectCard | undefined;
+  knowledge: KnowledgeArticle[];
+  blockedBy: IssueCard[];
+
+  constructor(opts?: {
+    project?: ProjectCard | null;
+    knowledge?: KnowledgeArticle[];
+    blockedBy?: IssueCard[];
+  }) {
+    this.project =
+      opts && 'project' in opts
+        ? (opts.project ?? undefined)
+        : { id: 'project-1', name: 'Sticky Notes' };
+    this.knowledge = opts?.knowledge ?? [];
+    this.blockedBy = opts?.blockedBy ?? [];
+  }
+
+  async loadProject(_issue: IssueCard): Promise<ProjectCard | undefined> {
+    return this.project;
+  }
+
+  async loadKnowledge(_issue: IssueCard): Promise<KnowledgeArticle[]> {
+    return this.knowledge;
+  }
+
+  async loadBlockedBy(_issue: IssueCard): Promise<IssueCard[]> {
+    return this.blockedBy;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Fixtures
 // ---------------------------------------------------------------------------
@@ -464,3 +497,482 @@ module('factory-context-builder > core fields', function () {
     assert.deepEqual(ctx.knowledge, [], 'empty knowledge is fine');
   });
 });
+
+// ===========================================================================
+// Tests: buildForIssue (Phase 2)
+// ===========================================================================
+
+function makeIssueConfig(
+  loaderOpts?: ConstructorParameters<typeof StubIssueRelationshipLoader>[0],
+  configOverrides?: Partial<ContextBuilderConfig>,
+) {
+  let resolver = new StubSkillResolver();
+  let loader = new StubSkillLoader([
+    makeSkill('boxel-development'),
+    makeSkill('boxel-file-structure'),
+    makeSkill('ember-best-practices'),
+  ]);
+  let issueLoader = new StubIssueRelationshipLoader(loaderOpts);
+
+  return {
+    config: {
+      skillResolver: resolver,
+      skillLoader: loader,
+      issueLoader,
+      ...configOverrides,
+    } as ContextBuilderConfig,
+    resolver,
+    loader,
+    issueLoader,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests: buildForIssue — relationship traversal
+// ---------------------------------------------------------------------------
+
+module('factory-context-builder > buildForIssue > relationships', function () {
+  test('loads project from issue.project relationship', async function (assert) {
+    let project = makeProject({ id: 'proj-99', name: 'Todo App' });
+    let { config } = makeIssueConfig({ project });
+    let builder = new ContextBuilder(config);
+
+    let ctx = await builder.buildForIssue({
+      issue: makeIssue(),
+      targetRealmUrl: 'https://example.test/target/',
+      testRealmUrl: 'https://example.test/target-test-artifacts/',
+    });
+
+    assert.strictEqual(ctx.project.id, 'proj-99', 'project loaded from issue');
+    assert.strictEqual(ctx.project.name, 'Todo App');
+  });
+
+  test('loads knowledge from issue.relatedKnowledge', async function (assert) {
+    let knowledge = [
+      makeKnowledge({ id: 'ka-1', title: 'Card Basics' }),
+      makeKnowledge({ id: 'ka-2', title: 'Styling Guide' }),
+    ];
+    let { config } = makeIssueConfig({ knowledge });
+    let builder = new ContextBuilder(config);
+
+    let ctx = await builder.buildForIssue({
+      issue: makeIssue(),
+      targetRealmUrl: 'https://example.test/target/',
+      testRealmUrl: 'https://example.test/target-test-artifacts/',
+    });
+
+    assert.strictEqual(ctx.knowledge.length, 2, 'two knowledge articles');
+    assert.strictEqual(ctx.knowledge[0].id, 'ka-1');
+    assert.strictEqual(ctx.knowledge[1].id, 'ka-2');
+  });
+
+  test('includes resolved clarification answers for previously-blocked issues', async function (assert) {
+    let blockedBy: IssueCard[] = [
+      {
+        id: 'clarification-1',
+        issueType: 'clarification',
+        status: 'done',
+        summary: 'What color scheme should StickyNote use?',
+        description: 'Use yellow background with dark text.',
+      },
+      {
+        id: 'clarification-2',
+        issueType: 'clarification',
+        status: 'done',
+        summary: 'Should StickyNote support markdown?',
+        description: 'No, plain text only for now.',
+      },
+    ];
+    let { config } = makeIssueConfig({ blockedBy });
+    let builder = new ContextBuilder(config);
+
+    let ctx = await builder.buildForIssue({
+      issue: makeIssue(),
+      targetRealmUrl: 'https://example.test/target/',
+      testRealmUrl: 'https://example.test/target-test-artifacts/',
+    });
+
+    assert.strictEqual(ctx.clarifications?.length, 2, 'two clarifications');
+    assert.strictEqual(ctx.clarifications?.[0].issueId, 'clarification-1');
+    assert.strictEqual(
+      ctx.clarifications?.[0].question,
+      'What color scheme should StickyNote use?',
+    );
+    assert.strictEqual(
+      ctx.clarifications?.[0].answer,
+      'Use yellow background with dark text.',
+    );
+    assert.strictEqual(ctx.clarifications?.[1].issueId, 'clarification-2');
+  });
+
+  test('excludes non-clarification blockers and unresolved clarifications', async function (assert) {
+    let blockedBy: IssueCard[] = [
+      // Regular implementation issue (not a clarification) — should be excluded
+      {
+        id: 'impl-1',
+        issueType: 'feature',
+        status: 'done',
+        summary: 'Implement base card',
+        description: 'Create the base card definition',
+      },
+      // Clarification still blocked (not done) — should be excluded
+      {
+        id: 'clarification-pending',
+        issueType: 'clarification',
+        status: 'blocked',
+        summary: 'Pending question',
+        description: '',
+      },
+      // Resolved clarification — should be included
+      {
+        id: 'clarification-done',
+        issueType: 'clarification',
+        status: 'done',
+        summary: 'What icon to use?',
+        description: 'Use the sticky-note icon from Phosphor.',
+      },
+    ];
+    let { config } = makeIssueConfig({ blockedBy });
+    let builder = new ContextBuilder(config);
+
+    let ctx = await builder.buildForIssue({
+      issue: makeIssue(),
+      targetRealmUrl: 'https://example.test/target/',
+      testRealmUrl: 'https://example.test/target-test-artifacts/',
+    });
+
+    assert.strictEqual(
+      ctx.clarifications?.length,
+      1,
+      'only one resolved clarification',
+    );
+    assert.strictEqual(ctx.clarifications?.[0].issueId, 'clarification-done');
+  });
+
+  test('omits clarifications field when none exist', async function (assert) {
+    let { config } = makeIssueConfig({ blockedBy: [] });
+    let builder = new ContextBuilder(config);
+
+    let ctx = await builder.buildForIssue({
+      issue: makeIssue(),
+      targetRealmUrl: 'https://example.test/target/',
+      testRealmUrl: 'https://example.test/target-test-artifacts/',
+    });
+
+    assert.strictEqual(
+      ctx.clarifications,
+      undefined,
+      'no clarifications field when empty',
+    );
+  });
+
+  test('throws when issue has no linked project', async function (assert) {
+    let { config } = makeIssueConfig({ project: null });
+    let builder = new ContextBuilder(config);
+
+    try {
+      await builder.buildForIssue({
+        issue: makeIssue({ id: 'orphan-issue' }),
+        targetRealmUrl: 'https://example.test/target/',
+        testRealmUrl: 'https://example.test/target-test-artifacts/',
+      });
+      assert.ok(false, 'should have thrown');
+    } catch (error) {
+      assert.ok(
+        (error as Error).message.includes('orphan-issue'),
+        'error mentions the issue id',
+      );
+      assert.ok(
+        (error as Error).message.includes('no linked project'),
+        'error explains the problem',
+      );
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests: buildForIssue — validation results
+// ---------------------------------------------------------------------------
+
+module(
+  'factory-context-builder > buildForIssue > validation results',
+  function () {
+    test('includes validation results when provided (2nd+ inner-loop iteration)', async function (assert) {
+      let { config } = makeIssueConfig();
+      let builder = new ContextBuilder(config);
+      let validationResults: ValidationResults = {
+        passed: false,
+        steps: [
+          { step: 'parse', passed: true, errors: [] },
+          {
+            step: 'lint',
+            passed: false,
+            files: ['sticky-note.gts'],
+            errors: [
+              {
+                file: 'sticky-note.gts',
+                message: "Expected ';' after statement",
+              },
+            ],
+          },
+        ],
+      };
+
+      let ctx = await builder.buildForIssue({
+        issue: makeIssue(),
+        targetRealmUrl: 'https://example.test/target/',
+        testRealmUrl: 'https://example.test/target-test-artifacts/',
+        validationResults,
+      });
+
+      assert.deepEqual(
+        ctx.validationResults,
+        validationResults,
+        'validation results included',
+      );
+      assert.strictEqual(
+        ctx.validationResults?.steps.length,
+        2,
+        'two validation steps',
+      );
+      assert.strictEqual(
+        ctx.validationResults?.steps[1].step,
+        'lint',
+        'lint step present',
+      );
+    });
+
+    test('omits validation results on first inner-loop iteration (none provided)', async function (assert) {
+      let { config } = makeIssueConfig();
+      let builder = new ContextBuilder(config);
+
+      let ctx = await builder.buildForIssue({
+        issue: makeIssue(),
+        targetRealmUrl: 'https://example.test/target/',
+        testRealmUrl: 'https://example.test/target-test-artifacts/',
+      });
+
+      assert.strictEqual(
+        ctx.validationResults,
+        undefined,
+        'no validation results on first iteration',
+      );
+    });
+
+    test('validation results include step name, file paths, error details', async function (assert) {
+      let { config } = makeIssueConfig();
+      let builder = new ContextBuilder(config);
+      let validationResults: ValidationResults = {
+        passed: false,
+        steps: [
+          {
+            step: 'evaluate',
+            passed: false,
+            files: ['sticky-note.gts'],
+            errors: [
+              {
+                file: 'sticky-note.gts',
+                message: 'Cannot find module ./base-card',
+                stackTrace: 'at ModuleLoader.load (loader.ts:42)',
+              },
+            ],
+          },
+          {
+            step: 'test',
+            passed: false,
+            files: ['sticky-note.test.gts'],
+            errors: [
+              {
+                file: 'sticky-note.test.gts',
+                message: 'Expected element to exist',
+              },
+            ],
+          },
+        ],
+      };
+
+      let ctx = await builder.buildForIssue({
+        issue: makeIssue(),
+        targetRealmUrl: 'https://example.test/target/',
+        testRealmUrl: 'https://example.test/target-test-artifacts/',
+        validationResults,
+      });
+
+      let evalStep = ctx.validationResults?.steps[0];
+      assert.strictEqual(evalStep?.step, 'evaluate');
+      assert.deepEqual(evalStep?.files, ['sticky-note.gts']);
+      assert.strictEqual(
+        evalStep?.errors[0].stackTrace,
+        'at ModuleLoader.load (loader.ts:42)',
+      );
+
+      let testStep = ctx.validationResults?.steps[1];
+      assert.strictEqual(testStep?.step, 'test');
+      assert.strictEqual(
+        testStep?.errors[0].message,
+        'Expected element to exist',
+      );
+    });
+  },
+);
+
+// ---------------------------------------------------------------------------
+// Tests: buildForIssue — skills
+// ---------------------------------------------------------------------------
+
+module('factory-context-builder > buildForIssue > skills', function () {
+  test('skill selection works based on issue content', async function (assert) {
+    let { config, resolver } = makeIssueConfig();
+    let builder = new ContextBuilder(config);
+    let issue = makeIssue({
+      description: 'Create a .gts card definition with ember components',
+    });
+    let project = makeProject({ id: 'project-1', name: 'Todo App' });
+    // Pre-set the project so the resolver gets it
+    (config.issueLoader as StubIssueRelationshipLoader).project = project;
+
+    await builder.buildForIssue({
+      issue,
+      targetRealmUrl: 'https://example.test/target/',
+      testRealmUrl: 'https://example.test/target-test-artifacts/',
+    });
+
+    assert.strictEqual(resolver.calls.length, 1, 'resolver called once');
+    assert.strictEqual(
+      resolver.calls[0].issue,
+      issue,
+      'resolver received the issue',
+    );
+    assert.strictEqual(
+      resolver.calls[0].project,
+      project,
+      'resolver received the loaded project',
+    );
+  });
+
+  test('token budget enforcement still works with buildForIssue', async function (assert) {
+    let resolver = new StubSkillResolver([
+      'boxel-development',
+      'ember-best-practices',
+    ]);
+    let loader = new StubSkillLoader([
+      makeSkill('boxel-development', 'A'.repeat(36)), // 9 tokens
+      makeSkill('ember-best-practices', 'B'.repeat(36)), // 9 tokens
+    ]);
+    let issueLoader = new StubIssueRelationshipLoader();
+    let config: ContextBuilderConfig = {
+      skillResolver: resolver,
+      skillLoader: loader,
+      issueLoader,
+      maxSkillTokens: 10,
+    };
+    let builder = new ContextBuilder(config);
+
+    let ctx = await builder.buildForIssue({
+      issue: makeIssue(),
+      targetRealmUrl: 'https://example.test/target/',
+      testRealmUrl: 'https://example.test/target-test-artifacts/',
+    });
+
+    assert.strictEqual(ctx.skills.length, 1, 'budget trimmed to one skill');
+    assert.strictEqual(
+      ctx.skills[0].name,
+      'boxel-development',
+      'higher-priority skill kept',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests: buildForIssue — bootstrap and context fields
+// ---------------------------------------------------------------------------
+
+module(
+  'factory-context-builder > buildForIssue > bootstrap and fields',
+  function () {
+    test('bootstrap issue context includes brief URL', async function (assert) {
+      let { config } = makeIssueConfig();
+      let builder = new ContextBuilder(config);
+
+      let ctx = await builder.buildForIssue({
+        issue: makeIssue({ issueType: 'bootstrap' }),
+        targetRealmUrl: 'https://example.test/target/',
+        testRealmUrl: 'https://example.test/target-test-artifacts/',
+        briefUrl: 'https://example.test/briefs/sticky-notes',
+      });
+
+      assert.strictEqual(
+        ctx.briefUrl,
+        'https://example.test/briefs/sticky-notes',
+        'briefUrl included for bootstrap issue',
+      );
+    });
+
+    test('omits briefUrl when not provided', async function (assert) {
+      let { config } = makeIssueConfig();
+      let builder = new ContextBuilder(config);
+
+      let ctx = await builder.buildForIssue({
+        issue: makeIssue(),
+        targetRealmUrl: 'https://example.test/target/',
+        testRealmUrl: 'https://example.test/target-test-artifacts/',
+      });
+
+      assert.strictEqual(ctx.briefUrl, undefined, 'no briefUrl');
+    });
+
+    test('includes workspaceDir when provided', async function (assert) {
+      let { config } = makeIssueConfig();
+      let builder = new ContextBuilder(config);
+
+      let ctx = await builder.buildForIssue({
+        issue: makeIssue(),
+        targetRealmUrl: 'https://example.test/target/',
+        testRealmUrl: 'https://example.test/target-test-artifacts/',
+        workspaceDir: '/tmp/factory-workspace',
+      });
+
+      assert.strictEqual(
+        ctx.workspaceDir,
+        '/tmp/factory-workspace',
+        'workspaceDir included',
+      );
+    });
+
+    test('includes realm URLs in context', async function (assert) {
+      let { config } = makeIssueConfig();
+      let builder = new ContextBuilder(config);
+
+      let ctx = await builder.buildForIssue({
+        issue: makeIssue(),
+        targetRealmUrl: 'https://example.test/my-realm/',
+        testRealmUrl: 'https://example.test/my-realm-test-artifacts/',
+      });
+
+      assert.strictEqual(ctx.targetRealmUrl, 'https://example.test/my-realm/');
+      assert.strictEqual(
+        ctx.testRealmUrl,
+        'https://example.test/my-realm-test-artifacts/',
+      );
+    });
+
+    test('throws when issueLoader is not configured', async function (assert) {
+      let { config } = makeConfig(); // no issueLoader
+      let builder = new ContextBuilder(config);
+
+      try {
+        await builder.buildForIssue({
+          issue: makeIssue(),
+          targetRealmUrl: 'https://example.test/target/',
+          testRealmUrl: 'https://example.test/target-test-artifacts/',
+        });
+        assert.ok(false, 'should have thrown');
+      } catch (error) {
+        assert.ok(
+          (error as Error).message.includes('issueLoader'),
+          'error mentions issueLoader',
+        );
+      }
+    });
+  },
+);

From 94ce4369d603ee45c860ce254d36fb502cff6790 Mon Sep 17 00:00:00 2001
From: Hassan Abdel-Rahman <hassan.abdelrahman@gmail.com>
Date: Wed, 8 Apr 2026 15:32:45 -0400
Subject: [PATCH 05/10] Remove unnecessary "Phase 2" annotations from comments

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../scripts/lib/factory-agent-types.ts                 | 10 +++++-----
 .../scripts/lib/factory-context-builder.ts             |  6 +++---
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/packages/software-factory/scripts/lib/factory-agent-types.ts b/packages/software-factory/scripts/lib/factory-agent-types.ts
index ba8b9e4824f..316226591d5 100644
--- a/packages/software-factory/scripts/lib/factory-agent-types.ts
+++ b/packages/software-factory/scripts/lib/factory-agent-types.ts
@@ -112,7 +112,7 @@ export interface TestResult {
 }
 
 // ---------------------------------------------------------------------------
-// Validation types (Phase 2 — broader than TestResult)
+// Validation types (broader than TestResult)
 // ---------------------------------------------------------------------------
 
 /** Steps in the post-iteration validation pipeline. */
@@ -173,13 +173,13 @@ export interface AgentContext {
   iteration?: number;
   targetRealmUrl: string;
   testRealmUrl: string;
-  /** Validation results from the prior inner-loop iteration (Phase 2). */
+  /** Validation results from the prior inner-loop iteration. */
   validationResults?: ValidationResults;
-  /** Resolved clarification answers from previously-blocked issues (Phase 2). */
+  /** Resolved clarification answers from previously-blocked issues. */
   clarifications?: ClarificationAnswer[];
-  /** Brief URL for bootstrap issues (Phase 2). */
+  /** Brief URL for bootstrap issues. */
   briefUrl?: string;
-  /** Local workspace directory path (Phase 2). */
+  /** Local workspace directory path. */
   workspaceDir?: string;
 }
 
diff --git a/packages/software-factory/scripts/lib/factory-context-builder.ts b/packages/software-factory/scripts/lib/factory-context-builder.ts
index 256af7819b7..2a6eebb3992 100644
--- a/packages/software-factory/scripts/lib/factory-context-builder.ts
+++ b/packages/software-factory/scripts/lib/factory-context-builder.ts
@@ -17,13 +17,13 @@ import {
 } from './factory-skill-loader';
 
 // ---------------------------------------------------------------------------
-// Issue relationship loader (Phase 2)
+// Issue relationship loader
 // ---------------------------------------------------------------------------
 
 /**
  * Loads related cards from an issue's relationships.
  *
- * The Phase 2 `buildForIssue()` method uses this to traverse the issue's
+ * The `buildForIssue()` method uses this to traverse the issue's
  * linksTo / linksToMany fields (project, relatedKnowledge, blockedBy)
  * without coupling ContextBuilder to the realm I/O layer.
  */
@@ -114,7 +114,7 @@ export class ContextBuilder {
   }
 
   /**
-   * Build agent context from the current issue (Phase 2 issue-driven loop).
+   * Build agent context from the current issue (issue-driven loop).
    *
    * Unlike `build()` which takes pre-loaded project/knowledge, this method
    * traverses issue relationships to load them automatically:

From 2862e56f57370f9829cf4b0335d069fe92994d5c Mon Sep 17 00:00:00 2001
From: Hassan Abdel-Rahman <hassan.abdelrahman@gmail.com>
Date: Wed, 8 Apr 2026 15:44:06 -0400
Subject: [PATCH 06/10] Address PR review: remove clarifications, testRealmUrl,
 workspaceDir 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>
---
 .../scripts/lib/factory-agent-types.ts        |  11 --
 .../scripts/lib/factory-context-builder.ts    |  65 +-------
 .../tests/factory-context-builder.test.ts     | 144 +-----------------
 3 files changed, 8 insertions(+), 212 deletions(-)

diff --git a/packages/software-factory/scripts/lib/factory-agent-types.ts b/packages/software-factory/scripts/lib/factory-agent-types.ts
index 316226591d5..f626ae3d5f7 100644
--- a/packages/software-factory/scripts/lib/factory-agent-types.ts
+++ b/packages/software-factory/scripts/lib/factory-agent-types.ts
@@ -143,13 +143,6 @@ export interface ValidationResults {
   steps: ValidationStepResult[];
 }
 
-/** A resolved clarification answer from a previously-blocked issue. */
-export interface ClarificationAnswer {
-  issueId: string;
-  question: string;
-  answer: string;
-}
-
 export interface ToolResult {
   tool: string;
   exitCode: number;
@@ -175,12 +168,8 @@ export interface AgentContext {
   testRealmUrl: string;
   /** Validation results from the prior inner-loop iteration. */
   validationResults?: ValidationResults;
-  /** Resolved clarification answers from previously-blocked issues. */
-  clarifications?: ClarificationAnswer[];
   /** Brief URL for bootstrap issues. */
   briefUrl?: string;
-  /** Local workspace directory path. */
-  workspaceDir?: string;
 }
 
 export interface AgentAction {
diff --git a/packages/software-factory/scripts/lib/factory-context-builder.ts b/packages/software-factory/scripts/lib/factory-context-builder.ts
index 2a6eebb3992..3e9ca75d444 100644
--- a/packages/software-factory/scripts/lib/factory-context-builder.ts
+++ b/packages/software-factory/scripts/lib/factory-context-builder.ts
@@ -1,6 +1,5 @@
 import type {
   AgentContext,
-  ClarificationAnswer,
   IssueCard,
   KnowledgeArticle,
   ProjectCard,
@@ -24,13 +23,12 @@ import {
  * Loads related cards from an issue's relationships.
  *
  * The `buildForIssue()` method uses this to traverse the issue's
- * linksTo / linksToMany fields (project, relatedKnowledge, blockedBy)
+ * linksTo / linksToMany fields (project, relatedKnowledge)
  * without coupling ContextBuilder to the realm I/O layer.
  */
 export interface IssueRelationshipLoader {
   loadProject(issue: IssueCard): Promise<ProjectCard | undefined>;
   loadKnowledge(issue: IssueCard): Promise<KnowledgeArticle[]>;
-  loadBlockedBy(issue: IssueCard): Promise<IssueCard[]>;
 }
 
 // ---------------------------------------------------------------------------
@@ -120,7 +118,6 @@ export class ContextBuilder {
    * traverses issue relationships to load them automatically:
    * - project from issue.project
    * - knowledge from issue.relatedKnowledge
-   * - resolved clarification answers from issue.blockedBy (done clarifications)
    *
    * Accepts optional validationResults from the prior inner-loop iteration
    * so the agent can self-correct on failures.
@@ -128,8 +125,6 @@ export class ContextBuilder {
   async buildForIssue(params: {
     issue: IssueCard;
     targetRealmUrl: string;
-    testRealmUrl: string;
-    workspaceDir?: string;
     validationResults?: ValidationResults;
     briefUrl?: string;
   }): Promise<AgentContext> {
@@ -139,13 +134,12 @@ export class ContextBuilder {
       );
     }
 
-    let { issue, targetRealmUrl, testRealmUrl } = params;
+    let { issue, targetRealmUrl } = params;
 
     // Step 1: Traverse issue relationships
-    let [project, knowledge, blockedByIssues] = await Promise.all([
+    let [project, knowledge] = await Promise.all([
       this.issueLoader.loadProject(issue),
       this.issueLoader.loadKnowledge(issue),
-      this.issueLoader.loadBlockedBy(issue),
     ]);
 
     if (!project) {
@@ -154,79 +148,34 @@ export class ContextBuilder {
       );
     }
 
-    // Step 2: Extract clarification answers from resolved blockedBy issues
-    let clarifications = extractClarifications(blockedByIssues);
-
-    // Step 3: Resolve and load skills
+    // Step 2: Resolve and load skills
     let skillNames = this.skillResolver.resolve(issue, project);
     let skills: ResolvedSkill[] = await this.skillLoader.loadAll(
       skillNames,
       issue,
     );
 
-    // Step 4: Enforce token budget if configured
+    // Step 3: Enforce token budget if configured
     skills = enforceSkillBudget(skills, this.maxSkillTokens);
 
-    // Step 5: Assemble the context
+    // Step 4: Assemble the context
     let context: AgentContext = {
       project,
       issue,
       knowledge,
       skills,
       targetRealmUrl,
-      testRealmUrl,
+      testRealmUrl: targetRealmUrl,
     };
 
     if (params.validationResults) {
       context.validationResults = params.validationResults;
     }
 
-    if (clarifications.length > 0) {
-      context.clarifications = clarifications;
-    }
-
     if (params.briefUrl) {
       context.briefUrl = params.briefUrl;
     }
 
-    if (params.workspaceDir) {
-      context.workspaceDir = params.workspaceDir;
-    }
-
     return context;
   }
 }
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Extract clarification answers from resolved blockedBy issues.
- *
- * A clarification issue is one with issueType === 'clarification' and
- * status === 'done'. The question comes from the issue summary, and the
- * answer from the issue description.
- */
-function extractClarifications(
-  blockedByIssues: IssueCard[],
-): ClarificationAnswer[] {
-  let clarifications: ClarificationAnswer[] = [];
-
-  for (let blocked of blockedByIssues) {
-    if (
-      blocked.issueType === 'clarification' &&
-      blocked.status === 'done' &&
-      typeof blocked.summary === 'string' &&
-      typeof blocked.description === 'string'
-    ) {
-      clarifications.push({
-        issueId: blocked.id,
-        question: blocked.summary,
-        answer: blocked.description,
-      });
-    }
-  }
-
-  return clarifications;
-}
diff --git a/packages/software-factory/tests/factory-context-builder.test.ts b/packages/software-factory/tests/factory-context-builder.test.ts
index 04b718e42c0..92c40de596e 100644
--- a/packages/software-factory/tests/factory-context-builder.test.ts
+++ b/packages/software-factory/tests/factory-context-builder.test.ts
@@ -77,19 +77,16 @@ class StubSkillLoader implements SkillLoaderInterface {
 class StubIssueRelationshipLoader implements IssueRelationshipLoader {
   project: ProjectCard | undefined;
   knowledge: KnowledgeArticle[];
-  blockedBy: IssueCard[];
 
   constructor(opts?: {
     project?: ProjectCard | null;
     knowledge?: KnowledgeArticle[];
-    blockedBy?: IssueCard[];
   }) {
     this.project =
       opts && 'project' in opts
         ? (opts.project ?? undefined)
         : { id: 'project-1', name: 'Sticky Notes' };
     this.knowledge = opts?.knowledge ?? [];
-    this.blockedBy = opts?.blockedBy ?? [];
   }
 
   async loadProject(_issue: IssueCard): Promise<ProjectCard | undefined> {
@@ -99,10 +96,6 @@ class StubIssueRelationshipLoader implements IssueRelationshipLoader {
   async loadKnowledge(_issue: IssueCard): Promise<KnowledgeArticle[]> {
     return this.knowledge;
   }
-
-  async loadBlockedBy(_issue: IssueCard): Promise<IssueCard[]> {
-    return this.blockedBy;
-  }
 }
 
 // ---------------------------------------------------------------------------
@@ -299,7 +292,6 @@ module('factory-context-builder > skill budget', function () {
       issue: makeIssue(),
       knowledge: [],
       targetRealmUrl: 'https://example.test/target/',
-      testRealmUrl: 'https://example.test/target-test-artifacts/',
     });
 
     assert.strictEqual(ctx.skills.length, 1, 'budget trimmed to one skill');
@@ -540,7 +532,6 @@ module('factory-context-builder > buildForIssue > relationships', function () {
     let ctx = await builder.buildForIssue({
       issue: makeIssue(),
       targetRealmUrl: 'https://example.test/target/',
-      testRealmUrl: 'https://example.test/target-test-artifacts/',
     });
 
     assert.strictEqual(ctx.project.id, 'proj-99', 'project loaded from issue');
@@ -558,7 +549,6 @@ module('factory-context-builder > buildForIssue > relationships', function () {
     let ctx = await builder.buildForIssue({
       issue: makeIssue(),
       targetRealmUrl: 'https://example.test/target/',
-      testRealmUrl: 'https://example.test/target-test-artifacts/',
     });
 
     assert.strictEqual(ctx.knowledge.length, 2, 'two knowledge articles');
@@ -566,106 +556,6 @@ module('factory-context-builder > buildForIssue > relationships', function () {
     assert.strictEqual(ctx.knowledge[1].id, 'ka-2');
   });
 
-  test('includes resolved clarification answers for previously-blocked issues', async function (assert) {
-    let blockedBy: IssueCard[] = [
-      {
-        id: 'clarification-1',
-        issueType: 'clarification',
-        status: 'done',
-        summary: 'What color scheme should StickyNote use?',
-        description: 'Use yellow background with dark text.',
-      },
-      {
-        id: 'clarification-2',
-        issueType: 'clarification',
-        status: 'done',
-        summary: 'Should StickyNote support markdown?',
-        description: 'No, plain text only for now.',
-      },
-    ];
-    let { config } = makeIssueConfig({ blockedBy });
-    let builder = new ContextBuilder(config);
-
-    let ctx = await builder.buildForIssue({
-      issue: makeIssue(),
-      targetRealmUrl: 'https://example.test/target/',
-      testRealmUrl: 'https://example.test/target-test-artifacts/',
-    });
-
-    assert.strictEqual(ctx.clarifications?.length, 2, 'two clarifications');
-    assert.strictEqual(ctx.clarifications?.[0].issueId, 'clarification-1');
-    assert.strictEqual(
-      ctx.clarifications?.[0].question,
-      'What color scheme should StickyNote use?',
-    );
-    assert.strictEqual(
-      ctx.clarifications?.[0].answer,
-      'Use yellow background with dark text.',
-    );
-    assert.strictEqual(ctx.clarifications?.[1].issueId, 'clarification-2');
-  });
-
-  test('excludes non-clarification blockers and unresolved clarifications', async function (assert) {
-    let blockedBy: IssueCard[] = [
-      // Regular implementation issue (not a clarification) — should be excluded
-      {
-        id: 'impl-1',
-        issueType: 'feature',
-        status: 'done',
-        summary: 'Implement base card',
-        description: 'Create the base card definition',
-      },
-      // Clarification still blocked (not done) — should be excluded
-      {
-        id: 'clarification-pending',
-        issueType: 'clarification',
-        status: 'blocked',
-        summary: 'Pending question',
-        description: '',
-      },
-      // Resolved clarification — should be included
-      {
-        id: 'clarification-done',
-        issueType: 'clarification',
-        status: 'done',
-        summary: 'What icon to use?',
-        description: 'Use the sticky-note icon from Phosphor.',
-      },
-    ];
-    let { config } = makeIssueConfig({ blockedBy });
-    let builder = new ContextBuilder(config);
-
-    let ctx = await builder.buildForIssue({
-      issue: makeIssue(),
-      targetRealmUrl: 'https://example.test/target/',
-      testRealmUrl: 'https://example.test/target-test-artifacts/',
-    });
-
-    assert.strictEqual(
-      ctx.clarifications?.length,
-      1,
-      'only one resolved clarification',
-    );
-    assert.strictEqual(ctx.clarifications?.[0].issueId, 'clarification-done');
-  });
-
-  test('omits clarifications field when none exist', async function (assert) {
-    let { config } = makeIssueConfig({ blockedBy: [] });
-    let builder = new ContextBuilder(config);
-
-    let ctx = await builder.buildForIssue({
-      issue: makeIssue(),
-      targetRealmUrl: 'https://example.test/target/',
-      testRealmUrl: 'https://example.test/target-test-artifacts/',
-    });
-
-    assert.strictEqual(
-      ctx.clarifications,
-      undefined,
-      'no clarifications field when empty',
-    );
-  });
-
   test('throws when issue has no linked project', async function (assert) {
     let { config } = makeIssueConfig({ project: null });
     let builder = new ContextBuilder(config);
@@ -674,7 +564,6 @@ module('factory-context-builder > buildForIssue > relationships', function () {
       await builder.buildForIssue({
         issue: makeIssue({ id: 'orphan-issue' }),
         targetRealmUrl: 'https://example.test/target/',
-        testRealmUrl: 'https://example.test/target-test-artifacts/',
       });
       assert.ok(false, 'should have thrown');
     } catch (error) {
@@ -721,7 +610,6 @@ module(
       let ctx = await builder.buildForIssue({
         issue: makeIssue(),
         targetRealmUrl: 'https://example.test/target/',
-        testRealmUrl: 'https://example.test/target-test-artifacts/',
         validationResults,
       });
 
@@ -749,7 +637,6 @@ module(
       let ctx = await builder.buildForIssue({
         issue: makeIssue(),
         targetRealmUrl: 'https://example.test/target/',
-        testRealmUrl: 'https://example.test/target-test-artifacts/',
       });
 
       assert.strictEqual(
@@ -794,7 +681,6 @@ module(
       let ctx = await builder.buildForIssue({
         issue: makeIssue(),
         targetRealmUrl: 'https://example.test/target/',
-        testRealmUrl: 'https://example.test/target-test-artifacts/',
         validationResults,
       });
 
@@ -834,7 +720,6 @@ module('factory-context-builder > buildForIssue > skills', function () {
     await builder.buildForIssue({
       issue,
       targetRealmUrl: 'https://example.test/target/',
-      testRealmUrl: 'https://example.test/target-test-artifacts/',
     });
 
     assert.strictEqual(resolver.calls.length, 1, 'resolver called once');
@@ -871,7 +756,6 @@ module('factory-context-builder > buildForIssue > skills', function () {
     let ctx = await builder.buildForIssue({
       issue: makeIssue(),
       targetRealmUrl: 'https://example.test/target/',
-      testRealmUrl: 'https://example.test/target-test-artifacts/',
     });
 
     assert.strictEqual(ctx.skills.length, 1, 'budget trimmed to one skill');
@@ -897,7 +781,6 @@ module(
       let ctx = await builder.buildForIssue({
         issue: makeIssue({ issueType: 'bootstrap' }),
         targetRealmUrl: 'https://example.test/target/',
-        testRealmUrl: 'https://example.test/target-test-artifacts/',
         briefUrl: 'https://example.test/briefs/sticky-notes',
       });
 
@@ -915,45 +798,21 @@ module(
       let ctx = await builder.buildForIssue({
         issue: makeIssue(),
         targetRealmUrl: 'https://example.test/target/',
-        testRealmUrl: 'https://example.test/target-test-artifacts/',
       });
 
       assert.strictEqual(ctx.briefUrl, undefined, 'no briefUrl');
     });
 
-    test('includes workspaceDir when provided', async function (assert) {
-      let { config } = makeIssueConfig();
-      let builder = new ContextBuilder(config);
-
-      let ctx = await builder.buildForIssue({
-        issue: makeIssue(),
-        targetRealmUrl: 'https://example.test/target/',
-        testRealmUrl: 'https://example.test/target-test-artifacts/',
-        workspaceDir: '/tmp/factory-workspace',
-      });
-
-      assert.strictEqual(
-        ctx.workspaceDir,
-        '/tmp/factory-workspace',
-        'workspaceDir included',
-      );
-    });
-
-    test('includes realm URLs in context', async function (assert) {
+    test('includes targetRealmUrl in context', async function (assert) {
       let { config } = makeIssueConfig();
       let builder = new ContextBuilder(config);
 
       let ctx = await builder.buildForIssue({
         issue: makeIssue(),
         targetRealmUrl: 'https://example.test/my-realm/',
-        testRealmUrl: 'https://example.test/my-realm-test-artifacts/',
       });
 
       assert.strictEqual(ctx.targetRealmUrl, 'https://example.test/my-realm/');
-      assert.strictEqual(
-        ctx.testRealmUrl,
-        'https://example.test/my-realm-test-artifacts/',
-      );
     });
 
     test('throws when issueLoader is not configured', async function (assert) {
@@ -964,7 +823,6 @@ module(
         await builder.buildForIssue({
           issue: makeIssue(),
           targetRealmUrl: 'https://example.test/target/',
-          testRealmUrl: 'https://example.test/target-test-artifacts/',
         });
         assert.ok(false, 'should have thrown');
       } catch (error) {

From ce5772fb3b3b885324ff9d159e54c6a8cd4f24e0 Mon Sep 17 00:00:00 2001
From: Hassan Abdel-Rahman <hassan.abdelrahman@gmail.com>
Date: Wed, 8 Apr 2026 16:00:24 -0400
Subject: [PATCH 07/10] =?UTF-8?q?Rename=20IssueCard/ProjectCard/KnowledgeA?=
 =?UTF-8?q?rticle=20=E2=86=92=20IssueData/ProjectData/KnowledgeArticleData?=
 =?UTF-8?q?,=20remove=20testRealmUrl=20from=20AgentContext?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 .../scripts/lib/factory-agent-tool-use.ts     |  1 -
 .../scripts/lib/factory-agent-types.ts        | 13 +++--
 .../scripts/lib/factory-context-builder.ts    | 23 ++++----
 .../scripts/lib/factory-implement.ts          | 19 ++++---
 .../scripts/lib/factory-loop.ts               | 21 ++++----
 .../scripts/lib/factory-prompt-loader.ts      |  1 -
 .../scripts/lib/factory-skill-loader.ts       | 24 ++++-----
 .../smoke-tests/factory-agent-smoke.ts        |  1 -
 .../smoke-tests/factory-context-smoke.ts      | 19 +++----
 .../scripts/smoke-tests/factory-loop-smoke.ts | 21 ++++----
 .../smoke-tests/factory-prompt-smoke.ts       |  1 -
 .../smoke-tests/factory-skill-smoke.ts        |  8 +--
 .../tests/factory-agent.integration.test.ts   |  1 -
 .../tests/factory-agent.test.ts               |  1 -
 .../tests/factory-context-builder.test.ts     | 54 +++++++------------
 .../tests/factory-implement.test.ts           | 21 --------
 .../tests/factory-loop.test.ts                | 39 +++++---------
 .../tests/factory-prompt-loader.test.ts       |  4 --
 .../tests/factory-skill-loader.test.ts        |  8 +--
 19 files changed, 102 insertions(+), 178 deletions(-)

diff --git a/packages/software-factory/scripts/lib/factory-agent-tool-use.ts b/packages/software-factory/scripts/lib/factory-agent-tool-use.ts
index 627fcf2d9a6..7f6f875fb9e 100644
--- a/packages/software-factory/scripts/lib/factory-agent-tool-use.ts
+++ b/packages/software-factory/scripts/lib/factory-agent-tool-use.ts
@@ -314,7 +314,6 @@ export class ToolUseFactoryAgent implements LoopAgent {
 
     return this.promptLoader.load('system', {
       targetRealmUrl: context.targetRealmUrl,
-      testRealmUrl: context.testRealmUrl,
       skills,
     });
   }
diff --git a/packages/software-factory/scripts/lib/factory-agent-types.ts b/packages/software-factory/scripts/lib/factory-agent-types.ts
index f626ae3d5f7..e9f5d147688 100644
--- a/packages/software-factory/scripts/lib/factory-agent-types.ts
+++ b/packages/software-factory/scripts/lib/factory-agent-types.ts
@@ -61,17 +61,17 @@ export interface FactoryAgentConfig {
   debug?: boolean;
 }
 
-export interface ProjectCard {
+export interface ProjectData {
   id: string;
   [key: string]: unknown;
 }
 
-export interface IssueCard {
+export interface IssueData {
   id: string;
   [key: string]: unknown;
 }
 
-export interface KnowledgeArticle {
+export interface KnowledgeArticleData {
   id: string;
   [key: string]: unknown;
 }
@@ -151,9 +151,9 @@ export interface ToolResult {
 }
 
 export interface AgentContext {
-  project: ProjectCard;
-  issue: IssueCard;
-  knowledge: KnowledgeArticle[];
+  project: ProjectData;
+  issue: IssueData;
+  knowledge: KnowledgeArticleData[];
   skills: ResolvedSkill[];
   /** @deprecated Tools are now provided separately as FactoryTool[] to agent.run(). */
   tools?: ToolManifest[];
@@ -165,7 +165,6 @@ export interface AgentContext {
   /** @deprecated Iteration tracking is now owned by the orchestrator. */
   iteration?: number;
   targetRealmUrl: string;
-  testRealmUrl: string;
   /** Validation results from the prior inner-loop iteration. */
   validationResults?: ValidationResults;
   /** Brief URL for bootstrap issues. */
diff --git a/packages/software-factory/scripts/lib/factory-context-builder.ts b/packages/software-factory/scripts/lib/factory-context-builder.ts
index 3e9ca75d444..9d2589d5c9a 100644
--- a/packages/software-factory/scripts/lib/factory-context-builder.ts
+++ b/packages/software-factory/scripts/lib/factory-context-builder.ts
@@ -1,8 +1,8 @@
 import type {
   AgentContext,
-  IssueCard,
-  KnowledgeArticle,
-  ProjectCard,
+  IssueData,
+  KnowledgeArticleData,
+  ProjectData,
   TestResult,
   ValidationResults,
 } from './factory-agent';
@@ -27,8 +27,8 @@ import {
  * without coupling ContextBuilder to the realm I/O layer.
  */
 export interface IssueRelationshipLoader {
-  loadProject(issue: IssueCard): Promise<ProjectCard | undefined>;
-  loadKnowledge(issue: IssueCard): Promise<KnowledgeArticle[]>;
+  loadProject(issue: IssueData): Promise<ProjectData | undefined>;
+  loadKnowledge(issue: IssueData): Promise<KnowledgeArticleData[]>;
 }
 
 // ---------------------------------------------------------------------------
@@ -71,15 +71,14 @@ export class ContextBuilder {
    * 4. Return AgentContext (tools are provided separately as FactoryTool[])
    */
   async build(params: {
-    project: ProjectCard;
-    issue: IssueCard;
-    knowledge: KnowledgeArticle[];
+    project: ProjectData;
+    issue: IssueData;
+    knowledge: KnowledgeArticleData[];
     targetRealmUrl: string;
-    testRealmUrl: string;
     /** Test results from the previous iteration, if any. */
     testResults?: TestResult;
   }): Promise<AgentContext> {
-    let { project, issue, knowledge, targetRealmUrl, testRealmUrl } = params;
+    let { project, issue, knowledge, targetRealmUrl } = params;
 
     // Step 1: Resolve which skills are needed for this issue
     let skillNames = this.skillResolver.resolve(issue, project);
@@ -100,7 +99,6 @@ export class ContextBuilder {
       knowledge,
       skills,
       targetRealmUrl,
-      testRealmUrl,
     };
 
     // Include test results when iterating after a failed test run
@@ -123,7 +121,7 @@ export class ContextBuilder {
    * so the agent can self-correct on failures.
    */
   async buildForIssue(params: {
-    issue: IssueCard;
+    issue: IssueData;
     targetRealmUrl: string;
     validationResults?: ValidationResults;
     briefUrl?: string;
@@ -165,7 +163,6 @@ export class ContextBuilder {
       knowledge,
       skills,
       targetRealmUrl,
-      testRealmUrl: targetRealmUrl,
     };
 
     if (params.validationResults) {
diff --git a/packages/software-factory/scripts/lib/factory-implement.ts b/packages/software-factory/scripts/lib/factory-implement.ts
index 343f5eae3e5..9b2d81d2310 100644
--- a/packages/software-factory/scripts/lib/factory-implement.ts
+++ b/packages/software-factory/scripts/lib/factory-implement.ts
@@ -16,9 +16,9 @@
 import { resolve } from 'node:path';
 
 import type {
-  IssueCard,
-  KnowledgeArticle,
-  ProjectCard,
+  IssueData,
+  KnowledgeArticleData,
+  ProjectData,
   TestResult,
 } from './factory-agent';
 import {
@@ -240,7 +240,6 @@ export async function runFactoryImplement(
     issue,
     knowledge,
     targetRealmUrl,
-    testRealmUrl,
     maxIterations: config.maxIterations,
   });
 
@@ -379,9 +378,9 @@ async function fetchCardData(
   bootstrapResult: FactoryBootstrapResult,
   fetchOptions: RealmFetchOptions,
 ): Promise<{
-  project: ProjectCard;
-  issue: IssueCard;
-  knowledge: KnowledgeArticle[];
+  project: ProjectData;
+  issue: IssueData;
+  knowledge: KnowledgeArticleData[];
 }> {
   // Fetch the project card
   let project = await fetchCard(
@@ -398,7 +397,7 @@ async function fetchCardData(
   );
 
   // Fetch all knowledge articles
-  let knowledge: KnowledgeArticle[] = [];
+  let knowledge: KnowledgeArticleData[] = [];
   for (let ka of bootstrapResult.knowledgeArticles) {
     try {
       let card = await fetchCard(targetRealmUrl, ka.id, fetchOptions);
@@ -459,7 +458,7 @@ interface TestRunnerConfig {
  */
 function buildTestRunner(
   targetRealmUrl: string,
-  issue: IssueCard,
+  issue: IssueData,
   toolCallLog: ToolCallEntry[],
   runConfig: TestRunnerConfig,
 ): TestRunner {
@@ -731,7 +730,7 @@ const BASE_CARD_TYPES: { module: string; name: string }[] = [
 
 /**
  * Fetch JSON schemas for card types the factory uses. Includes both
- * DarkFactory types (Project, Issue, KnowledgeArticle) from the target
+ * DarkFactory types (Project, Issue, KnowledgeArticleData) from the target
  * realm and base types (Spec) from the base realm. Returns a Map
  * suitable for passing to ToolBuilderConfig.cardTypeSchemas.
  */
diff --git a/packages/software-factory/scripts/lib/factory-loop.ts b/packages/software-factory/scripts/lib/factory-loop.ts
index 8451493bcc7..682b3c2ac8e 100644
--- a/packages/software-factory/scripts/lib/factory-loop.ts
+++ b/packages/software-factory/scripts/lib/factory-loop.ts
@@ -20,9 +20,9 @@
 
 import type {
   AgentContext,
-  IssueCard,
-  KnowledgeArticle,
-  ProjectCard,
+  IssueData,
+  KnowledgeArticleData,
+  ProjectData,
   TestResult,
 } from './factory-agent';
 
@@ -73,11 +73,10 @@ export type TestRunner = () => Promise<TestResult>;
  */
 export interface ContextBuilderLike {
   build(params: {
-    project: ProjectCard;
-    issue: IssueCard;
-    knowledge: KnowledgeArticle[];
+    project: ProjectData;
+    issue: IssueData;
+    knowledge: KnowledgeArticleData[];
     targetRealmUrl: string;
-    testRealmUrl: string;
     testResults?: TestResult;
   }): Promise<AgentContext>;
 }
@@ -87,11 +86,10 @@ export interface FactoryLoopConfig {
   contextBuilder: ContextBuilderLike;
   tools: FactoryTool[];
   testRunner: TestRunner;
-  project: ProjectCard;
-  issue: IssueCard;
-  knowledge: KnowledgeArticle[];
+  project: ProjectData;
+  issue: IssueData;
+  knowledge: KnowledgeArticleData[];
   targetRealmUrl: string;
-  testRealmUrl: string;
   /** Maximum iterations before the loop gives up. Default: 5. */
   maxIterations?: number;
 }
@@ -129,7 +127,6 @@ export async function runFactoryLoop(
       issue: config.issue,
       knowledge: config.knowledge,
       targetRealmUrl: config.targetRealmUrl,
-      testRealmUrl: config.testRealmUrl,
       testResults,
     });
 
diff --git a/packages/software-factory/scripts/lib/factory-prompt-loader.ts b/packages/software-factory/scripts/lib/factory-prompt-loader.ts
index 454f6a7829a..3ac6d61d1e5 100644
--- a/packages/software-factory/scripts/lib/factory-prompt-loader.ts
+++ b/packages/software-factory/scripts/lib/factory-prompt-loader.ts
@@ -386,7 +386,6 @@ export function assembleSystemPrompt(
 
   return loader.load('system', {
     targetRealmUrl: context.targetRealmUrl,
-    testRealmUrl: context.testRealmUrl,
     skills,
   });
 }
diff --git a/packages/software-factory/scripts/lib/factory-skill-loader.ts b/packages/software-factory/scripts/lib/factory-skill-loader.ts
index 41884999c6b..d1bed6cd911 100644
--- a/packages/software-factory/scripts/lib/factory-skill-loader.ts
+++ b/packages/software-factory/scripts/lib/factory-skill-loader.ts
@@ -1,7 +1,7 @@
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 
-import type { IssueCard, ProjectCard, ResolvedSkill } from './factory-agent';
+import type { IssueData, ProjectData, ResolvedSkill } from './factory-agent';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -132,7 +132,7 @@ interface RawSkillData {
 // ---------------------------------------------------------------------------
 
 export interface SkillResolver {
-  resolve(issue: IssueCard, project: ProjectCard): string[];
+  resolve(issue: IssueData, project: ProjectData): string[];
 }
 
 export class DefaultSkillResolver implements SkillResolver {
@@ -150,7 +150,7 @@ export class DefaultSkillResolver implements SkillResolver {
    * tool registry does not include boxel-cli tools (deferred to CS-10520).
    * These skills reference commands the agent cannot invoke.
    */
-  resolve(issue: IssueCard, project: ProjectCard): string[] {
+  resolve(issue: IssueData, project: ProjectData): string[] {
     let issueText = extractIssueText(issue);
     let skills: string[] = ['boxel-development', 'boxel-file-structure'];
 
@@ -182,8 +182,8 @@ export class DefaultSkillResolver implements SkillResolver {
 // ---------------------------------------------------------------------------
 
 export interface SkillLoaderInterface {
-  load(skillName: string, issue?: IssueCard): Promise<ResolvedSkill>;
-  loadAll(skillNames: string[], issue?: IssueCard): Promise<ResolvedSkill[]>;
+  load(skillName: string, issue?: IssueData): Promise<ResolvedSkill>;
+  loadAll(skillNames: string[], issue?: IssueData): Promise<ResolvedSkill[]>;
 }
 
 export class SkillLoader implements SkillLoaderInterface {
@@ -210,7 +210,7 @@ export class SkillLoader implements SkillLoaderInterface {
    * only include issue-relevant files (always applied, not just with a budget).
    * Results are cached for the duration of the factory run.
    */
-  async load(skillName: string, issue?: IssueCard): Promise<ResolvedSkill> {
+  async load(skillName: string, issue?: IssueData): Promise<ResolvedSkill> {
     let raw = await this.loadRaw(skillName);
     return toResolvedSkill(raw, issue);
   }
@@ -221,7 +221,7 @@ export class SkillLoader implements SkillLoaderInterface {
    */
   async loadAll(
     skillNames: string[],
-    issue?: IssueCard,
+    issue?: IssueData,
   ): Promise<ResolvedSkill[]> {
     let results: ResolvedSkill[] = [];
 
@@ -415,7 +415,7 @@ export function estimateTokens(skill: ResolvedSkill): number {
  * using actual filenames — this happens on every load, not just when a
  * budget is enforced.
  */
-function toResolvedSkill(raw: RawSkillData, issue?: IssueCard): ResolvedSkill {
+function toResolvedSkill(raw: RawSkillData, issue?: IssueData): ResolvedSkill {
   let refs = raw.references;
 
   if (refs && raw.name === 'boxel-development' && issue) {
@@ -439,7 +439,7 @@ function toResolvedSkill(raw: RawSkillData, issue?: IssueCard): ResolvedSkill {
  */
 function filterBoxelDevelopmentRefs(
   refs: NamedReference[],
-  issue: IssueCard,
+  issue: IssueData,
 ): NamedReference[] {
   let issueText = extractIssueText(issue);
 
@@ -474,7 +474,7 @@ function filterBoxelDevelopmentRefs(
  * Concatenates known text fields (id, title, description, tags, labels, etc.)
  * into a single lowercase string for keyword matching.
  */
-export function extractIssueText(issue: IssueCard): string {
+export function extractIssueText(issue: IssueData): string {
   let parts: string[] = [issue.id];
 
   for (let key of [
@@ -518,8 +518,8 @@ export function extractIssueText(issue: IssueCard): string {
  * generic `knowledge` field for forward compatibility.
  */
 function extractKnowledgeSkillTags(
-  project: ProjectCard,
-  issue?: IssueCard,
+  project: ProjectData,
+  issue?: IssueData,
 ): string[] {
   let articles: unknown[] = [];
 
diff --git a/packages/software-factory/scripts/smoke-tests/factory-agent-smoke.ts b/packages/software-factory/scripts/smoke-tests/factory-agent-smoke.ts
index 009aeb4042c..d053589f877 100644
--- a/packages/software-factory/scripts/smoke-tests/factory-agent-smoke.ts
+++ b/packages/software-factory/scripts/smoke-tests/factory-agent-smoke.ts
@@ -110,7 +110,6 @@ async function main(): Promise<void> {
     skills: [],
     tools: [],
     targetRealmUrl: 'https://example.test/user/target/',
-    testRealmUrl: 'https://example.test/user/target-tests/',
   };
 
   console.log('Sending plan() request...');
diff --git a/packages/software-factory/scripts/smoke-tests/factory-context-smoke.ts b/packages/software-factory/scripts/smoke-tests/factory-context-smoke.ts
index 08760c2aac0..92f6fd9ee95 100644
--- a/packages/software-factory/scripts/smoke-tests/factory-context-smoke.ts
+++ b/packages/software-factory/scripts/smoke-tests/factory-context-smoke.ts
@@ -12,9 +12,9 @@
 import { parseArgs } from 'node:util';
 
 import type {
-  KnowledgeArticle,
-  ProjectCard,
-  IssueCard,
+  KnowledgeArticleData,
+  ProjectData,
+  IssueData,
 } from '../lib/factory-agent';
 import { ContextBuilder } from '../lib/factory-context-builder';
 import {
@@ -44,12 +44,12 @@ function check(label: string, ok: boolean, detail?: string): void {
 // Fixtures
 // ---------------------------------------------------------------------------
 
-const SAMPLE_PROJECT: ProjectCard = {
+const SAMPLE_PROJECT: ProjectData = {
   id: 'Projects/sticky-notes',
   name: 'Sticky Notes MVP',
 };
 
-const SAMPLE_KNOWLEDGE: KnowledgeArticle[] = [
+const SAMPLE_KNOWLEDGE: KnowledgeArticleData[] = [
   {
     id: 'Knowledge/card-basics',
     title: 'Boxel Card Development Basics',
@@ -62,7 +62,7 @@ const SAMPLE_KNOWLEDGE: KnowledgeArticle[] = [
   },
 ];
 
-const SAMPLE_ISSUES: { label: string; issue: IssueCard }[] = [
+const SAMPLE_ISSUES: { label: string; issue: IssueData }[] = [
   {
     label: 'Card definition (.gts work)',
     issue: {
@@ -146,7 +146,6 @@ async function main(): Promise<void> {
       issue,
       knowledge: SAMPLE_KNOWLEDGE,
       targetRealmUrl: 'https://example.test/user/target/',
-      testRealmUrl: 'https://example.test/user/target-test-artifacts/',
     });
 
     console.log('  First pass (no test results):');
@@ -166,10 +165,6 @@ async function main(): Promise<void> {
       'targetRealmUrl set',
       ctx.targetRealmUrl === 'https://example.test/user/target/',
     );
-    check(
-      'testRealmUrl set',
-      ctx.testRealmUrl === 'https://example.test/user/target-test-artifacts/',
-    );
 
     let totalTokens = ctx.skills.reduce((s, sk) => s + estimateTokens(sk), 0);
     console.log(`  Skill breakdown (~${totalTokens} total tokens):`);
@@ -189,7 +184,6 @@ async function main(): Promise<void> {
       issue,
       knowledge: SAMPLE_KNOWLEDGE,
       targetRealmUrl: 'https://example.test/user/target/',
-      testRealmUrl: 'https://example.test/user/target-test-artifacts/',
       testResults: {
         status: 'failed',
         passedCount: 2,
@@ -248,7 +242,6 @@ async function main(): Promise<void> {
       issue: SAMPLE_ISSUES[0].issue,
       knowledge: [],
       targetRealmUrl: 'https://example.test/user/target/',
-      testRealmUrl: 'https://example.test/user/target-test-artifacts/',
     });
 
     let totalTokens = ctx.skills.reduce((s, sk) => s + estimateTokens(sk), 0);
diff --git a/packages/software-factory/scripts/smoke-tests/factory-loop-smoke.ts b/packages/software-factory/scripts/smoke-tests/factory-loop-smoke.ts
index efc547877af..709a1a6869d 100644
--- a/packages/software-factory/scripts/smoke-tests/factory-loop-smoke.ts
+++ b/packages/software-factory/scripts/smoke-tests/factory-loop-smoke.ts
@@ -13,10 +13,10 @@ import { parseArgs } from 'node:util';
 
 import type {
   AgentContext,
-  KnowledgeArticle,
-  ProjectCard,
+  KnowledgeArticleData,
+  ProjectData,
   TestResult,
-  IssueCard,
+  IssueData,
 } from '../lib/factory-agent';
 
 import type { FactoryTool, ToolCallEntry } from '../lib/factory-tool-builder';
@@ -109,11 +109,10 @@ class MockLoopAgent implements LoopAgent {
 
 class StubContextBuilder implements ContextBuilderLike {
   async build(params: {
-    project: ProjectCard;
-    issue: IssueCard;
-    knowledge: KnowledgeArticle[];
+    project: ProjectData;
+    issue: IssueData;
+    knowledge: KnowledgeArticleData[];
     targetRealmUrl: string;
-    testRealmUrl: string;
     testResults?: TestResult;
   }): Promise<AgentContext> {
     return {
@@ -122,7 +121,6 @@ class StubContextBuilder implements ContextBuilderLike {
       knowledge: params.knowledge,
       skills: [],
       targetRealmUrl: params.targetRealmUrl,
-      testRealmUrl: params.testRealmUrl,
       testResults: params.testResults,
     };
   }
@@ -132,18 +130,18 @@ class StubContextBuilder implements ContextBuilderLike {
 // Fixtures
 // ---------------------------------------------------------------------------
 
-const PROJECT: ProjectCard = {
+const PROJECT: ProjectData = {
   id: 'Projects/sticky-notes',
   name: 'Sticky Notes MVP',
 };
 
-const ISSUE: IssueCard = {
+const ISSUE: IssueData = {
   id: 'Issues/define-sticky-note',
   title: 'Define StickyNote card',
   description: 'Create a .gts card definition for StickyNote.',
 };
 
-const KNOWLEDGE: KnowledgeArticle[] = [
+const KNOWLEDGE: KnowledgeArticleData[] = [
   { id: 'Knowledge/card-basics', title: 'Boxel Card Development Basics' },
 ];
 
@@ -189,7 +187,6 @@ function makeBaseConfig(
     issue: ISSUE,
     knowledge: KNOWLEDGE,
     targetRealmUrl: 'https://example.test/target/',
-    testRealmUrl: 'https://example.test/target-test-artifacts/',
     ...overrides,
   };
 }
diff --git a/packages/software-factory/scripts/smoke-tests/factory-prompt-smoke.ts b/packages/software-factory/scripts/smoke-tests/factory-prompt-smoke.ts
index cfef5e388f4..563def4fea1 100644
--- a/packages/software-factory/scripts/smoke-tests/factory-prompt-smoke.ts
+++ b/packages/software-factory/scripts/smoke-tests/factory-prompt-smoke.ts
@@ -104,7 +104,6 @@ const SAMPLE_CONTEXT: AgentContext = {
     },
   ],
   targetRealmUrl: 'http://localhost:4201/user/personal/',
-  testRealmUrl: 'http://localhost:4201/user/personal-tests/',
 };
 
 const SAMPLE_PREVIOUS_ACTIONS: AgentAction[] = [
diff --git a/packages/software-factory/scripts/smoke-tests/factory-skill-smoke.ts b/packages/software-factory/scripts/smoke-tests/factory-skill-smoke.ts
index cfd5f5c2834..adc7eb848ba 100644
--- a/packages/software-factory/scripts/smoke-tests/factory-skill-smoke.ts
+++ b/packages/software-factory/scripts/smoke-tests/factory-skill-smoke.ts
@@ -17,9 +17,9 @@ import {
   enforceSkillBudget,
   estimateTokens,
 } from '../lib/factory-skill-loader';
-import type { ProjectCard, IssueCard } from '../lib/factory-agent';
+import type { ProjectData, IssueData } from '../lib/factory-agent';
 
-const SAMPLE_ISSUES: { label: string; issue: IssueCard }[] = [
+const SAMPLE_ISSUES: { label: string; issue: IssueData }[] = [
   {
     label: 'Generic card work (base case)',
     issue: {
@@ -88,7 +88,7 @@ async function main(): Promise<void> {
 
   let resolver = new DefaultSkillResolver();
   let loader = new SkillLoader();
-  let project: ProjectCard = { id: 'Projects/smoke-test' };
+  let project: ProjectData = { id: 'Projects/smoke-test' };
 
   console.log('=== Skill Loader & Resolver Smoke Test ===\n');
 
@@ -101,7 +101,7 @@ async function main(): Promise<void> {
             id: 'Issues/custom',
             title: customIssueText,
             description: customIssueText,
-          } as IssueCard,
+          } as IssueData,
         },
       ]
     : SAMPLE_ISSUES;
diff --git a/packages/software-factory/tests/factory-agent.integration.test.ts b/packages/software-factory/tests/factory-agent.integration.test.ts
index f9713841dbb..dae3e5fdb3b 100644
--- a/packages/software-factory/tests/factory-agent.integration.test.ts
+++ b/packages/software-factory/tests/factory-agent.integration.test.ts
@@ -21,7 +21,6 @@ function makeMinimalContext(overrides?: Partial<AgentContext>): AgentContext {
     skills: [],
     tools: [],
     targetRealmUrl: 'https://realms.example.test/user/target/',
-    testRealmUrl: 'https://realms.example.test/user/target-tests/',
     ...overrides,
   };
 }
diff --git a/packages/software-factory/tests/factory-agent.test.ts b/packages/software-factory/tests/factory-agent.test.ts
index b254114e3d9..e9ba6ad5aa1 100644
--- a/packages/software-factory/tests/factory-agent.test.ts
+++ b/packages/software-factory/tests/factory-agent.test.ts
@@ -35,7 +35,6 @@ function makeMinimalContext(overrides?: Partial<AgentContext>): AgentContext {
     skills: [],
     tools: [],
     targetRealmUrl: 'https://realms.example.test/user/target/',
-    testRealmUrl: 'https://realms.example.test/user/target-tests/',
     ...overrides,
   };
 }
diff --git a/packages/software-factory/tests/factory-context-builder.test.ts b/packages/software-factory/tests/factory-context-builder.test.ts
index 92c40de596e..c1239746641 100644
--- a/packages/software-factory/tests/factory-context-builder.test.ts
+++ b/packages/software-factory/tests/factory-context-builder.test.ts
@@ -1,12 +1,12 @@
 import { module, test } from 'qunit';
 
 import type {
-  KnowledgeArticle,
-  ProjectCard,
+  KnowledgeArticleData,
+  ProjectData,
   ResolvedSkill,
   TestResult,
   ValidationResults,
-  IssueCard,
+  IssueData,
 } from '../scripts/lib/factory-agent';
 
 import {
@@ -28,13 +28,13 @@ class StubSkillResolver implements SkillResolver {
   /** Pre-configured skill names returned by resolve(). */
   skillNames: string[];
   /** Records all (issue, project) pairs passed to resolve(). */
-  calls: { issue: IssueCard; project: ProjectCard }[] = [];
+  calls: { issue: IssueData; project: ProjectData }[] = [];
 
   constructor(skillNames: string[] = ['boxel-development']) {
     this.skillNames = skillNames;
   }
 
-  resolve(issue: IssueCard, project: ProjectCard): string[] {
+  resolve(issue: IssueData, project: ProjectData): string[] {
     this.calls.push({ issue, project });
     return this.skillNames;
   }
@@ -44,13 +44,13 @@ class StubSkillLoader implements SkillLoaderInterface {
   /** Map from skill name to the ResolvedSkill that load() returns. */
   private skillMap: Map<string, ResolvedSkill>;
   /** Records all loadAll() calls: [skillNames, issue]. */
-  loadAllCalls: { skillNames: string[]; issue?: IssueCard }[] = [];
+  loadAllCalls: { skillNames: string[]; issue?: IssueData }[] = [];
 
   constructor(skills: ResolvedSkill[] = []) {
     this.skillMap = new Map(skills.map((s) => [s.name, s]));
   }
 
-  async load(skillName: string, _issue?: IssueCard): Promise<ResolvedSkill> {
+  async load(skillName: string, _issue?: IssueData): Promise<ResolvedSkill> {
     let skill = this.skillMap.get(skillName);
     if (!skill) {
       throw new Error(`StubSkillLoader: unknown skill "${skillName}"`);
@@ -60,7 +60,7 @@ class StubSkillLoader implements SkillLoaderInterface {
 
   async loadAll(
     skillNames: string[],
-    issue?: IssueCard,
+    issue?: IssueData,
   ): Promise<ResolvedSkill[]> {
     this.loadAllCalls.push({ skillNames, issue });
     let results: ResolvedSkill[] = [];
@@ -75,12 +75,12 @@ class StubSkillLoader implements SkillLoaderInterface {
 }
 
 class StubIssueRelationshipLoader implements IssueRelationshipLoader {
-  project: ProjectCard | undefined;
-  knowledge: KnowledgeArticle[];
+  project: ProjectData | undefined;
+  knowledge: KnowledgeArticleData[];
 
   constructor(opts?: {
-    project?: ProjectCard | null;
-    knowledge?: KnowledgeArticle[];
+    project?: ProjectData | null;
+    knowledge?: KnowledgeArticleData[];
   }) {
     this.project =
       opts && 'project' in opts
@@ -89,11 +89,11 @@ class StubIssueRelationshipLoader implements IssueRelationshipLoader {
     this.knowledge = opts?.knowledge ?? [];
   }
 
-  async loadProject(_issue: IssueCard): Promise<ProjectCard | undefined> {
+  async loadProject(_issue: IssueData): Promise<ProjectData | undefined> {
     return this.project;
   }
 
-  async loadKnowledge(_issue: IssueCard): Promise<KnowledgeArticle[]> {
+  async loadKnowledge(_issue: IssueData): Promise<KnowledgeArticleData[]> {
     return this.knowledge;
   }
 }
@@ -102,11 +102,11 @@ class StubIssueRelationshipLoader implements IssueRelationshipLoader {
 // Fixtures
 // ---------------------------------------------------------------------------
 
-function makeProject(overrides?: Partial<ProjectCard>): ProjectCard {
+function makeProject(overrides?: Partial<ProjectData>): ProjectData {
   return { id: 'project-1', name: 'Sticky Notes', ...overrides };
 }
 
-function makeIssue(overrides?: Partial<IssueCard>): IssueCard {
+function makeIssue(overrides?: Partial<IssueData>): IssueData {
   return {
     id: 'issue-1',
     title: 'Implement StickyNote card',
@@ -116,8 +116,8 @@ function makeIssue(overrides?: Partial<IssueCard>): IssueCard {
 }
 
 function makeKnowledge(
-  overrides?: Partial<KnowledgeArticle>,
-): KnowledgeArticle {
+  overrides?: Partial<KnowledgeArticleData>,
+): KnowledgeArticleData {
   return { id: 'ka-1', title: 'Boxel Card Basics', ...overrides };
 }
 
@@ -163,7 +163,6 @@ module('factory-context-builder > skill resolution', function () {
       issue,
       knowledge: [],
       targetRealmUrl: 'https://example.test/target/',
-      testRealmUrl: 'https://example.test/target-test-artifacts/',
     });
 
     assert.strictEqual(resolver.calls.length, 1, 'resolve() called once');
@@ -199,7 +198,6 @@ module('factory-context-builder > skill resolution', function () {
       issue: makeIssue(),
       knowledge: [],
       targetRealmUrl: 'https://example.test/target/',
-      testRealmUrl: 'https://example.test/target-test-artifacts/',
     });
 
     assert.strictEqual(loader.loadAllCalls.length, 1, 'loadAll() called once');
@@ -225,7 +223,6 @@ module('factory-context-builder > skill resolution', function () {
       issue,
       knowledge: [],
       targetRealmUrl: 'https://example.test/target/',
-      testRealmUrl: 'https://example.test/target-test-artifacts/',
     });
 
     assert.strictEqual(
@@ -255,7 +252,6 @@ module('factory-context-builder > skill resolution', function () {
       issue: makeIssue(),
       knowledge: [],
       targetRealmUrl: 'https://example.test/target/',
-      testRealmUrl: 'https://example.test/target-test-artifacts/',
     });
 
     assert.strictEqual(ctx.skills.length, 2, 'two skills in context');
@@ -322,7 +318,6 @@ module('factory-context-builder > skill budget', function () {
       issue: makeIssue(),
       knowledge: [],
       targetRealmUrl: 'https://example.test/target/',
-      testRealmUrl: 'https://example.test/target-test-artifacts/',
     });
 
     assert.strictEqual(ctx.skills.length, 2, 'all skills included');
@@ -343,7 +338,6 @@ module('factory-context-builder > tools excluded', function () {
       issue: makeIssue(),
       knowledge: [],
       targetRealmUrl: 'https://example.test/target/',
-      testRealmUrl: 'https://example.test/target-test-artifacts/',
     });
 
     assert.strictEqual(
@@ -368,7 +362,6 @@ module('factory-context-builder > test results', function () {
       issue: makeIssue(),
       knowledge: [],
       targetRealmUrl: 'https://example.test/target/',
-      testRealmUrl: 'https://example.test/target-test-artifacts/',
     });
 
     assert.strictEqual(ctx.testResults, undefined, 'no testResults');
@@ -395,7 +388,7 @@ module('factory-context-builder > test results', function () {
       issue: makeIssue(),
       knowledge: [],
       targetRealmUrl: 'https://example.test/target/',
-      testRealmUrl: 'https://example.test/target-test-artifacts/',
+
       testResults,
     });
 
@@ -418,7 +411,7 @@ module('factory-context-builder > test results', function () {
       issue: makeIssue(),
       knowledge: [],
       targetRealmUrl: 'https://example.test/target/',
-      testRealmUrl: 'https://example.test/target-test-artifacts/',
+
       testResults,
     });
 
@@ -447,7 +440,6 @@ module('factory-context-builder > core fields', function () {
       issue,
       knowledge,
       targetRealmUrl: 'https://example.test/target/',
-      testRealmUrl: 'https://example.test/target-test-artifacts/',
     });
 
     assert.strictEqual(ctx.project, project, 'project passed through');
@@ -464,14 +456,9 @@ module('factory-context-builder > core fields', function () {
       issue: makeIssue(),
       knowledge: [],
       targetRealmUrl: 'https://example.test/my-realm/',
-      testRealmUrl: 'https://example.test/my-realm-test-artifacts/',
     });
 
     assert.strictEqual(ctx.targetRealmUrl, 'https://example.test/my-realm/');
-    assert.strictEqual(
-      ctx.testRealmUrl,
-      'https://example.test/my-realm-test-artifacts/',
-    );
   });
 
   test('handles empty knowledge array', async function (assert) {
@@ -483,7 +470,6 @@ module('factory-context-builder > core fields', function () {
       issue: makeIssue(),
       knowledge: [],
       targetRealmUrl: 'https://example.test/target/',
-      testRealmUrl: 'https://example.test/target-test-artifacts/',
     });
 
     assert.deepEqual(ctx.knowledge, [], 'empty knowledge is fine');
diff --git a/packages/software-factory/tests/factory-implement.test.ts b/packages/software-factory/tests/factory-implement.test.ts
index 86b6834cc6c..b035adf166d 100644
--- a/packages/software-factory/tests/factory-implement.test.ts
+++ b/packages/software-factory/tests/factory-implement.test.ts
@@ -247,27 +247,6 @@ module('factory-implement', function () {
         ctx.targetRealmUrl,
         'http://localhost:4201/test-user/my-realm/',
       );
-      assert.strictEqual(
-        ctx.testRealmUrl,
-        'http://localhost:4201/test-user/my-realm-test-artifacts/',
-      );
-    });
-
-    test('derives test realm URL correctly', async function (assert) {
-      let agent = new MockLoopAgentForTest([{ status: 'done', toolCalls: [] }]);
-
-      let config = makeConfig({
-        agent,
-        targetRealmUrl: 'http://localhost:4201/hassan1/personal/',
-      });
-      await runFactoryImplement(config);
-
-      // The agent context should have the derived test realm URL
-      let ctx = agent.receivedContexts[0];
-      assert.strictEqual(
-        ctx.testRealmUrl,
-        'http://localhost:4201/hassan1/personal-test-artifacts/',
-      );
     });
 
     test('handles maxIterations configuration', async function (assert) {
diff --git a/packages/software-factory/tests/factory-loop.test.ts b/packages/software-factory/tests/factory-loop.test.ts
index 6ea55c7c278..a53eed2208a 100644
--- a/packages/software-factory/tests/factory-loop.test.ts
+++ b/packages/software-factory/tests/factory-loop.test.ts
@@ -2,10 +2,10 @@ import { module, test } from 'qunit';
 
 import type {
   AgentContext,
-  KnowledgeArticle,
-  ProjectCard,
+  KnowledgeArticleData,
+  ProjectData,
   TestResult,
-  IssueCard,
+  IssueData,
 } from '../scripts/lib/factory-agent';
 
 import type {
@@ -106,20 +106,18 @@ class MockFactoryAgent implements LoopAgent {
 
 class StubContextBuilder implements ContextBuilderLike {
   buildCalls: {
-    project: ProjectCard;
-    issue: IssueCard;
-    knowledge: KnowledgeArticle[];
+    project: ProjectData;
+    issue: IssueData;
+    knowledge: KnowledgeArticleData[];
     targetRealmUrl: string;
-    testRealmUrl: string;
     testResults?: TestResult;
   }[] = [];
 
   async build(params: {
-    project: ProjectCard;
-    issue: IssueCard;
-    knowledge: KnowledgeArticle[];
+    project: ProjectData;
+    issue: IssueData;
+    knowledge: KnowledgeArticleData[];
     targetRealmUrl: string;
-    testRealmUrl: string;
     testResults?: TestResult;
   }): Promise<AgentContext> {
     this.buildCalls.push(params);
@@ -129,7 +127,6 @@ class StubContextBuilder implements ContextBuilderLike {
       knowledge: params.knowledge,
       skills: [],
       targetRealmUrl: params.targetRealmUrl,
-      testRealmUrl: params.testRealmUrl,
       testResults: params.testResults,
     };
   }
@@ -139,17 +136,17 @@ class StubContextBuilder implements ContextBuilderLike {
 // Fixtures
 // ---------------------------------------------------------------------------
 
-function makeProject(overrides?: Partial<ProjectCard>): ProjectCard {
+function makeProject(overrides?: Partial<ProjectData>): ProjectData {
   return { id: 'project-1', name: 'Sticky Notes', ...overrides };
 }
 
-function makeIssue(overrides?: Partial<IssueCard>): IssueCard {
+function makeIssue(overrides?: Partial<IssueData>): IssueData {
   return { id: 'issue-1', title: 'Implement StickyNote card', ...overrides };
 }
 
 function makeKnowledge(
-  overrides?: Partial<KnowledgeArticle>,
-): KnowledgeArticle {
+  overrides?: Partial<KnowledgeArticleData>,
+): KnowledgeArticleData {
   return { id: 'ka-1', ...overrides };
 }
 
@@ -218,7 +215,6 @@ function makeLoopConfig(
     issue: makeIssue(),
     knowledge: [makeKnowledge()],
     targetRealmUrl: 'https://example.test/target/',
-    testRealmUrl: 'https://example.test/target-test-artifacts/',
     ...overrides,
   };
 }
@@ -747,7 +743,6 @@ module('factory-loop > context threading', function () {
         agent,
         contextBuilder,
         targetRealmUrl: 'https://example.test/my-realm/',
-        testRealmUrl: 'https://example.test/my-realm-test-artifacts/',
         testRunner: makeTestRunner([
           makeFailingTestResult(),
           makePassingTestResult(),
@@ -764,14 +759,6 @@ module('factory-loop > context threading', function () {
       contextBuilder.buildCalls[1].targetRealmUrl,
       'https://example.test/my-realm/',
     );
-    assert.strictEqual(
-      contextBuilder.buildCalls[0].testRealmUrl,
-      'https://example.test/my-realm-test-artifacts/',
-    );
-    assert.strictEqual(
-      contextBuilder.buildCalls[1].testRealmUrl,
-      'https://example.test/my-realm-test-artifacts/',
-    );
   });
 });
 
diff --git a/packages/software-factory/tests/factory-prompt-loader.test.ts b/packages/software-factory/tests/factory-prompt-loader.test.ts
index e875dc6699d..2464e8aab23 100644
--- a/packages/software-factory/tests/factory-prompt-loader.test.ts
+++ b/packages/software-factory/tests/factory-prompt-loader.test.ts
@@ -25,7 +25,6 @@ function makeMinimalContext(overrides?: Partial<AgentContext>): AgentContext {
     skills: [],
     tools: [],
     targetRealmUrl: 'https://realms.example.test/user/target/',
-    testRealmUrl: 'https://realms.example.test/user/target-tests/',
     ...overrides,
   };
 }
@@ -192,7 +191,6 @@ module('factory-prompt-loader > FilePromptLoader', function () {
     let loader = new FilePromptLoader();
     let result = loader.load('system', {
       targetRealmUrl: 'https://example.test/target/',
-      testRealmUrl: 'https://example.test/test/',
       skills: [],
     });
     assert.ok(
@@ -206,7 +204,6 @@ module('factory-prompt-loader > FilePromptLoader', function () {
     let loader = new FilePromptLoader();
     let vars = {
       targetRealmUrl: 'https://example.test/target/',
-      testRealmUrl: 'https://example.test/test/',
       skills: [],
     };
     let first = loader.load('system', vars);
@@ -227,7 +224,6 @@ module('factory-prompt-loader > FilePromptLoader', function () {
     let loader = new FilePromptLoader();
     let vars = {
       targetRealmUrl: 'https://example.test/target/',
-      testRealmUrl: 'https://example.test/test/',
       skills: [],
     };
     let first = loader.load('system', vars);
diff --git a/packages/software-factory/tests/factory-skill-loader.test.ts b/packages/software-factory/tests/factory-skill-loader.test.ts
index 11807bb4b33..02a63192aa8 100644
--- a/packages/software-factory/tests/factory-skill-loader.test.ts
+++ b/packages/software-factory/tests/factory-skill-loader.test.ts
@@ -5,9 +5,9 @@ import { tmpdir } from 'node:os';
 import { module, test } from 'qunit';
 
 import type {
-  ProjectCard,
+  ProjectData,
   ResolvedSkill,
-  IssueCard,
+  IssueData,
 } from '../scripts/lib/factory-agent';
 import {
   DefaultSkillResolver,
@@ -70,7 +70,7 @@ function writeSkill(
   }
 }
 
-function makeIssue(overrides?: Partial<IssueCard>): IssueCard {
+function makeIssue(overrides?: Partial<IssueData>): IssueData {
   return {
     id: 'Issues/test-issue',
     title: 'Test issue',
@@ -79,7 +79,7 @@ function makeIssue(overrides?: Partial<IssueCard>): IssueCard {
   };
 }
 
-function makeProject(overrides?: Partial<ProjectCard>): ProjectCard {
+function makeProject(overrides?: Partial<ProjectData>): ProjectData {
   return {
     id: 'Projects/test-project',
     ...overrides,

From 8d95ca43bd685aba5c93eaf4e8f98d8584b5981d Mon Sep 17 00:00:00 2001
From: Hassan Abdel-Rahman <hassan.abdelrahman@gmail.com>
Date: Wed, 8 Apr 2026 16:27:24 -0400
Subject: [PATCH 08/10] Remove {{testRealmUrl}} from system.md template, fix
 KnowledgeArticleData comment

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 packages/software-factory/prompts/system.md                | 1 -
 packages/software-factory/scripts/lib/factory-implement.ts | 2 +-
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/packages/software-factory/prompts/system.md b/packages/software-factory/prompts/system.md
index bef657082a8..e75cbf16f05 100644
--- a/packages/software-factory/prompts/system.md
+++ b/packages/software-factory/prompts/system.md
@@ -23,7 +23,6 @@ inspect existing state before making changes — do not guess.
 # Realms
 
 - Target realm: {{targetRealmUrl}}
-- Test realm: {{testRealmUrl}}
 
 {{#each skills}}
 
diff --git a/packages/software-factory/scripts/lib/factory-implement.ts b/packages/software-factory/scripts/lib/factory-implement.ts
index 9b2d81d2310..88ae31a3a36 100644
--- a/packages/software-factory/scripts/lib/factory-implement.ts
+++ b/packages/software-factory/scripts/lib/factory-implement.ts
@@ -730,7 +730,7 @@ const BASE_CARD_TYPES: { module: string; name: string }[] = [
 
 /**
  * Fetch JSON schemas for card types the factory uses. Includes both
- * DarkFactory types (Project, Issue, KnowledgeArticleData) from the target
+ * DarkFactory types (Project, Issue, KnowledgeArticle) from the target
  * realm and base types (Spec) from the base realm. Returns a Map
  * suitable for passing to ToolBuilderConfig.cardTypeSchemas.
  */

From 1683336ac014919bb9f90cab2765884e6bf01ac0 Mon Sep 17 00:00:00 2001
From: Hassan Abdel-Rahman <hassan.abdelrahman@gmail.com>
Date: Wed, 8 Apr 2026 16:34:18 -0400
Subject: [PATCH 09/10] Remove testRealmUrl from tool executor, test-run infra,
 and all remaining consumers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 .../scripts/lib/factory-implement.ts               |  5 -----
 .../scripts/lib/factory-tool-executor.ts           | 10 +---------
 .../software-factory/scripts/lib/test-run-cards.ts | 10 +++++++---
 .../scripts/lib/test-run-execution.ts              | 14 +++++++-------
 .../software-factory/scripts/lib/test-run-types.ts |  2 +-
 .../scripts/smoke-tests/factory-tools-smoke.ts     |  3 ---
 .../tests/factory-entrypoint.test.ts               |  4 ----
 .../tests/factory-test-realm.spec.ts               |  2 +-
 .../tests/factory-test-realm.test.ts               |  2 +-
 .../factory-tool-executor.integration.test.ts      | 12 ------------
 .../tests/factory-tool-executor.spec.ts            | 13 -------------
 .../tests/factory-tool-executor.test.ts            |  1 -
 12 files changed, 18 insertions(+), 60 deletions(-)

diff --git a/packages/software-factory/scripts/lib/factory-implement.ts b/packages/software-factory/scripts/lib/factory-implement.ts
index 88ae31a3a36..23f74290c51 100644
--- a/packages/software-factory/scripts/lib/factory-implement.ts
+++ b/packages/software-factory/scripts/lib/factory-implement.ts
@@ -133,10 +133,6 @@ export async function runFactoryImplement(
   let realmServerUrl = ensureTrailingSlash(config.realmServerUrl);
   let fetchImpl = config.fetch ?? globalThis.fetch;
 
-  // Derive the test-artifacts realm URL from the target realm URL.
-  // e.g., "http://localhost:4201/user/my-realm/" -> "http://localhost:4201/user/my-realm-test-artifacts/"
-  let testRealmUrl = targetRealmUrl.replace(/\/$/, '-test-artifacts/');
-
   // 1. Auth: get Matrix auth, server token, and per-realm JWTs
   let { serverToken, realmTokens } = await resolveAuth(config);
 
@@ -156,7 +152,6 @@ export async function runFactoryImplement(
   let toolExecutor = new ToolExecutor(toolRegistry, {
     packageRoot: PACKAGE_ROOT,
     targetRealmUrl,
-    testRealmUrl,
     fetch: fetchImpl,
     authorization: config.authorization,
   });
diff --git a/packages/software-factory/scripts/lib/factory-tool-executor.ts b/packages/software-factory/scripts/lib/factory-tool-executor.ts
index fc7f66beba8..daab6729c1b 100644
--- a/packages/software-factory/scripts/lib/factory-tool-executor.ts
+++ b/packages/software-factory/scripts/lib/factory-tool-executor.ts
@@ -51,8 +51,6 @@ export interface ToolExecutorConfig {
   packageRoot: string;
   /** Target realm URL — tools may only target this realm. */
   targetRealmUrl: string;
-  /** Test realm URL — tools may also target this realm. */
-  testRealmUrl: string;
   /** Additional scratch realm URL prefixes that are allowed. */
   allowedRealmPrefixes?: string[];
   /** Source realm URL — tools must NEVER target this realm. */
@@ -280,10 +278,9 @@ export class ToolExecutor {
   private validateRealmTarget(toolName: string, realmUrl: string): void {
     let normalized = ensureTrailingSlash(realmUrl);
     let target = ensureTrailingSlash(this.config.targetRealmUrl);
-    let test = ensureTrailingSlash(this.config.testRealmUrl);
 
     // Exact realm matches (with trailing slash normalization)
-    let exactAllowed = [target, test];
+    let exactAllowed = [target];
 
     // Prefix matches (no trailing slash — these are URL path prefixes)
     let prefixAllowed = this.config.allowedRealmPrefixes ?? [];
@@ -320,11 +317,6 @@ export class ToolExecutor {
     } catch {
       // skip invalid
     }
-    try {
-      allowedOrigins.add(new URL(this.config.testRealmUrl).origin);
-    } catch {
-      // skip invalid
-    }
     for (let prefix of this.config.allowedRealmPrefixes ?? []) {
       try {
         allowedOrigins.add(new URL(prefix).origin);
diff --git a/packages/software-factory/scripts/lib/test-run-cards.ts b/packages/software-factory/scripts/lib/test-run-cards.ts
index 151329a339c..7ad735367b4 100644
--- a/packages/software-factory/scripts/lib/test-run-cards.ts
+++ b/packages/software-factory/scripts/lib/test-run-cards.ts
@@ -33,7 +33,7 @@ export async function createTestRun(
   );
 
   let result = await writeFile(
-    options.testRealmUrl,
+    options.targetRealmUrl,
     `${testRunId}.json`,
     JSON.stringify(document, null, 2),
     { authorization: options.authorization, fetch: options.fetch },
@@ -63,7 +63,11 @@ export async function completeTestRun(
   // may be stale causing the first fetch to fail with "fetch failed".
   let readResult: Awaited<ReturnType<typeof readFile>> | undefined;
   for (let attempt = 0; attempt < 3; attempt++) {
-    readResult = await readFile(options.testRealmUrl, testRunId, fetchOptions);
+    readResult = await readFile(
+      options.targetRealmUrl,
+      testRunId,
+      fetchOptions,
+    );
     if (readResult.ok && readResult.document) {
       break;
     }
@@ -106,7 +110,7 @@ export async function completeTestRun(
   }
 
   let writeResult = await writeFile(
-    options.testRealmUrl,
+    options.targetRealmUrl,
     `${testRunId}.json`,
     JSON.stringify(readResult.document, null, 2),
     fetchOptions,
diff --git a/packages/software-factory/scripts/lib/test-run-execution.ts b/packages/software-factory/scripts/lib/test-run-execution.ts
index 4a1b68bda04..fa10be8be13 100644
--- a/packages/software-factory/scripts/lib/test-run-execution.ts
+++ b/packages/software-factory/scripts/lib/test-run-execution.ts
@@ -32,7 +32,7 @@ export async function resolveTestRun(
   options: ExecuteTestRunOptions,
 ): Promise<TestRunHandle & { resumed: boolean; pendingTests?: string[] }> {
   let realmOptions: TestRunRealmOptions = {
-    testRealmUrl: options.targetRealmUrl,
+    targetRealmUrl: options.targetRealmUrl,
     testResultsModuleUrl: options.testResultsModuleUrl,
     authorization: options.authorization,
     fetch: options.fetch,
@@ -79,10 +79,10 @@ export async function resolveTestRun(
 async function findResumableTestRun(
   options: TestRunRealmOptions,
 ): Promise<ResumableTestRun | undefined> {
-  let testRealmUrl = ensureTrailingSlash(options.testRealmUrl);
+  let targetRealmUrl = ensureTrailingSlash(options.targetRealmUrl);
 
   let result = await searchRealm(
-    options.testRealmUrl,
+    options.targetRealmUrl,
     {
       filter: {
         on: { module: options.testResultsModuleUrl, name: 'TestRun' },
@@ -120,8 +120,8 @@ async function findResumableTestRun(
     .map((r) => r.testName ?? '');
 
   let cardId = latest.id ?? '';
-  let relativePath = cardId.startsWith(testRealmUrl)
-    ? cardId.slice(testRealmUrl.length)
+  let relativePath = cardId.startsWith(targetRealmUrl)
+    ? cardId.slice(targetRealmUrl.length)
     : cardId;
 
   return {
@@ -135,7 +135,7 @@ async function getNextSequenceNumber(
   options: TestRunRealmOptions,
 ): Promise<number> {
   let result = await searchRealm(
-    options.testRealmUrl,
+    options.targetRealmUrl,
     {
       filter: {
         on: { module: options.testResultsModuleUrl, name: 'TestRun' },
@@ -402,7 +402,7 @@ export async function executeTestRunFromRealm(
   options: ExecuteTestRunOptions,
 ): Promise<TestRunHandle> {
   let realmOptions: TestRunRealmOptions = {
-    testRealmUrl: options.targetRealmUrl,
+    targetRealmUrl: options.targetRealmUrl,
     testResultsModuleUrl: options.testResultsModuleUrl,
     authorization: options.authorization,
     fetch: options.fetch,
diff --git a/packages/software-factory/scripts/lib/test-run-types.ts b/packages/software-factory/scripts/lib/test-run-types.ts
index 0397158e3c0..25149ffeec3 100644
--- a/packages/software-factory/scripts/lib/test-run-types.ts
+++ b/packages/software-factory/scripts/lib/test-run-types.ts
@@ -31,7 +31,7 @@ export interface RunRealmTestsFailure {
 
 /** Realm connection options for TestRun card operations. */
 export interface TestRunRealmOptions {
-  testRealmUrl: string;
+  targetRealmUrl: string;
   /** URL to the test-results module in the source realm. Required, never inferred. */
   testResultsModuleUrl: string;
   authorization?: string;
diff --git a/packages/software-factory/scripts/smoke-tests/factory-tools-smoke.ts b/packages/software-factory/scripts/smoke-tests/factory-tools-smoke.ts
index 3ea188dbf7f..70f07d61dba 100644
--- a/packages/software-factory/scripts/smoke-tests/factory-tools-smoke.ts
+++ b/packages/software-factory/scripts/smoke-tests/factory-tools-smoke.ts
@@ -131,7 +131,6 @@ async function main(): Promise<void> {
   let executor = new ToolExecutor(registry, {
     packageRoot: process.cwd(),
     targetRealmUrl: 'https://realms.example.test/user/target/',
-    testRealmUrl: 'https://realms.example.test/user/target-tests/',
     sourceRealmUrl: 'https://realms.example.test/user/source/',
     allowedRealmPrefixes: ['https://realms.example.test/user/scratch-'],
   });
@@ -178,7 +177,6 @@ async function main(): Promise<void> {
   let mockExecutor = new ToolExecutor(registry, {
     packageRoot: process.cwd(),
     targetRealmUrl: 'https://realms.example.test/user/target/',
-    testRealmUrl: 'https://realms.example.test/user/target-tests/',
     fetch: (async (input: RequestInfo | URL, init?: RequestInit) => {
       mockCallCount++;
       let url = String(input);
@@ -245,7 +243,6 @@ async function main(): Promise<void> {
   let toolBuilderExecutor = new ToolExecutor(registry, {
     packageRoot: process.cwd(),
     targetRealmUrl: 'https://realms.example.test/user/target/',
-    testRealmUrl: 'https://realms.example.test/user/target-tests/',
     fetch: toolBuilderFetch,
   });
 
diff --git a/packages/software-factory/tests/factory-entrypoint.test.ts b/packages/software-factory/tests/factory-entrypoint.test.ts
index c698dae40c0..a7a55696274 100644
--- a/packages/software-factory/tests/factory-entrypoint.test.ts
+++ b/packages/software-factory/tests/factory-entrypoint.test.ts
@@ -195,8 +195,6 @@ module('factory-entrypoint', function (hooks) {
           iterations: 1,
           toolCallLog: [],
           issueId: 'Issues/sticky-note-define-core',
-          testRealmUrl:
-            'https://realms.example.test/hassan/personal-test-artifacts/',
         }),
         fetch: async (_input, init) => {
           assert.strictEqual(
@@ -269,8 +267,6 @@ module('factory-entrypoint', function (hooks) {
           iterations: 1,
           toolCallLog: [],
           issueId: 'Issues/sticky-note-define-core',
-          testRealmUrl:
-            'https://realms.example.test/app/hassan/personal-test-artifacts/',
         }),
         fetch: async () =>
           new Response(
diff --git a/packages/software-factory/tests/factory-test-realm.spec.ts b/packages/software-factory/tests/factory-test-realm.spec.ts
index e8bef031e64..9e092d43776 100644
--- a/packages/software-factory/tests/factory-test-realm.spec.ts
+++ b/packages/software-factory/tests/factory-test-realm.spec.ts
@@ -215,7 +215,7 @@ test.describe('factory-test-realm e2e', () => {
 
   test('error path: unreachable realm returns error immediately', async () => {
     let options: TestRunRealmOptions = {
-      testRealmUrl: 'http://localhost:1/',
+      targetRealmUrl: 'http://localhost:1/',
       testResultsModuleUrl: 'http://localhost:1/software-factory/test-results',
       fetch: globalThis.fetch,
     };
diff --git a/packages/software-factory/tests/factory-test-realm.test.ts b/packages/software-factory/tests/factory-test-realm.test.ts
index 2c3338121c0..4d3157a06cb 100644
--- a/packages/software-factory/tests/factory-test-realm.test.ts
+++ b/packages/software-factory/tests/factory-test-realm.test.ts
@@ -19,7 +19,7 @@ import { pullRealmFiles } from '../scripts/lib/realm-operations';
 // ---------------------------------------------------------------------------
 
 const testRealmOptions = {
-  testRealmUrl: 'https://realms.example.test/user/personal-tests/',
+  targetRealmUrl: 'https://realms.example.test/user/personal-tests/',
   testResultsModuleUrl:
     'https://realms.example.test/software-factory/test-results',
   realmServerUrl: 'https://realms.example.test/',
diff --git a/packages/software-factory/tests/factory-tool-executor.integration.test.ts b/packages/software-factory/tests/factory-tool-executor.integration.test.ts
index 5dd2b600b1a..6c8b958772a 100644
--- a/packages/software-factory/tests/factory-tool-executor.integration.test.ts
+++ b/packages/software-factory/tests/factory-tool-executor.integration.test.ts
@@ -90,7 +90,6 @@ module('factory-tool-executor integration > realm-api requests', function () {
       let executor = new ToolExecutor(registry, {
         packageRoot: '/fake',
         targetRealmUrl: realmUrl,
-        testRealmUrl: `${origin}/user/target-tests/`,
         authorization: 'Bearer realm-jwt-for-user',
       });
 
@@ -129,7 +128,6 @@ module('factory-tool-executor integration > realm-api requests', function () {
       let executor = new ToolExecutor(registry, {
         packageRoot: '/fake',
         targetRealmUrl: realmUrl,
-        testRealmUrl: `${origin}/user/target-tests/`,
         authorization: 'Bearer realm-jwt-for-user',
       });
 
@@ -173,7 +171,6 @@ module('factory-tool-executor integration > realm-api requests', function () {
       let executor = new ToolExecutor(registry, {
         packageRoot: '/fake',
         targetRealmUrl: realmUrl,
-        testRealmUrl: `${origin}/user/target-tests/`,
         authorization: 'Bearer realm-jwt-for-user',
       });
 
@@ -208,7 +205,6 @@ module('factory-tool-executor integration > realm-api requests', function () {
       let executor = new ToolExecutor(registry, {
         packageRoot: '/fake',
         targetRealmUrl: realmUrl,
-        testRealmUrl: `${origin}/user/target-tests/`,
         authorization: 'Bearer realm-jwt-for-user',
       });
 
@@ -254,7 +250,6 @@ module('factory-tool-executor integration > realm-api requests', function () {
       let executor = new ToolExecutor(registry, {
         packageRoot: '/fake',
         targetRealmUrl: `${origin}/user/target/`,
-        testRealmUrl: `${origin}/user/target-tests/`,
         authorization: 'Bearer realm-server-jwt-xyz',
       });
 
@@ -289,7 +284,6 @@ module('factory-tool-executor integration > realm-api requests', function () {
       let executor = new ToolExecutor(registry, {
         packageRoot: '/fake',
         targetRealmUrl: `${origin}/user/target/`,
-        testRealmUrl: `${origin}/user/target-tests/`,
         authorization: 'Bearer realm-server-jwt-minted',
       });
 
@@ -341,7 +335,6 @@ module('factory-tool-executor integration > realm-api requests', function () {
       let executor = new ToolExecutor(registry, {
         packageRoot: '/fake',
         targetRealmUrl: `${origin}/user/target/`,
-        testRealmUrl: `${origin}/user/target-tests/`,
       });
 
       let result = await executor.execute('realm-server-session', {
@@ -401,7 +394,6 @@ module('factory-tool-executor integration > realm-api requests', function () {
       let sessionExecutor = new ToolExecutor(registry, {
         packageRoot: '/fake',
         targetRealmUrl: serverUrl,
-        testRealmUrl: `${origin}/user/target-tests/`,
       });
 
       let sessionResult = await sessionExecutor.execute(
@@ -420,7 +412,6 @@ module('factory-tool-executor integration > realm-api requests', function () {
       let createExecutor = new ToolExecutor(registry, {
         packageRoot: '/fake',
         targetRealmUrl: serverUrl,
-        testRealmUrl: `${origin}/user/target-tests/`,
         authorization: jwt,
       });
 
@@ -466,7 +457,6 @@ module('factory-tool-executor integration > safety constraints', function () {
       let executor = new ToolExecutor(registry, {
         packageRoot: '/fake',
         targetRealmUrl: `${origin}/user/target/`,
-        testRealmUrl: `${origin}/user/target-tests/`,
       });
 
       try {
@@ -501,7 +491,6 @@ module('factory-tool-executor integration > safety constraints', function () {
       let executor = new ToolExecutor(registry, {
         packageRoot: '/fake',
         targetRealmUrl: `${origin}/user/target/`,
-        testRealmUrl: `${origin}/user/target-tests/`,
         sourceRealmUrl: sourceUrl,
       });
 
@@ -536,7 +525,6 @@ module('factory-tool-executor integration > safety constraints', function () {
       let executor = new ToolExecutor(registry, {
         packageRoot: '/fake',
         targetRealmUrl: `${origin}/user/target/`,
-        testRealmUrl: `${origin}/user/target-tests/`,
       });
 
       try {
diff --git a/packages/software-factory/tests/factory-tool-executor.spec.ts b/packages/software-factory/tests/factory-tool-executor.spec.ts
index fed21fb9f5b..e31a1a27dd9 100644
--- a/packages/software-factory/tests/factory-tool-executor.spec.ts
+++ b/packages/software-factory/tests/factory-tool-executor.spec.ts
@@ -38,7 +38,6 @@ test('realm-read fetches .realm.json from the test realm', async ({
   let executor = new ToolExecutor(registry, {
     packageRoot: process.cwd(),
     targetRealmUrl: realm.realmURL.href,
-    testRealmUrl: realm.realmURL.href,
     allowedRealmPrefixes: [realm.realmURL.origin + '/'],
     authorization: `Bearer ${realm.ownerBearerToken}`,
   });
@@ -57,7 +56,6 @@ test('realm-search returns results from the test realm', async ({ realm }) => {
   let executor = new ToolExecutor(registry, {
     packageRoot: process.cwd(),
     targetRealmUrl: realm.realmURL.href,
-    testRealmUrl: realm.realmURL.href,
     allowedRealmPrefixes: [realm.realmURL.origin + '/'],
     authorization: `Bearer ${realm.ownerBearerToken}`,
   });
@@ -87,7 +85,6 @@ test('realm-write creates a card and realm-read retrieves it', async ({
   let executor = new ToolExecutor(registry, {
     packageRoot: process.cwd(),
     targetRealmUrl: realm.realmURL.href,
-    testRealmUrl: realm.realmURL.href,
     allowedRealmPrefixes: [realm.realmURL.origin + '/'],
     authorization: `Bearer ${realm.ownerBearerToken}`,
   });
@@ -133,7 +130,6 @@ test('realm-delete removes a card from the test realm', async ({ realm }) => {
   let executor = new ToolExecutor(registry, {
     packageRoot: process.cwd(),
     targetRealmUrl: realm.realmURL.href,
-    testRealmUrl: realm.realmURL.href,
     allowedRealmPrefixes: [realm.realmURL.origin + '/'],
     authorization: `Bearer ${realm.ownerBearerToken}`,
   });
@@ -184,7 +180,6 @@ test('unregistered tool is rejected without reaching the server', async ({
   let executor = new ToolExecutor(registry, {
     packageRoot: process.cwd(),
     targetRealmUrl: realm.realmURL.href,
-    testRealmUrl: realm.realmURL.href,
     authorization: `Bearer ${realm.ownerBearerToken}`,
   });
 
@@ -211,7 +206,6 @@ async function buildToolsForRealm(realm: {
   let executor = new ToolExecutor(registry, {
     packageRoot: process.cwd(),
     targetRealmUrl: realm.realmURL.href,
-    testRealmUrl: realm.realmURL.href,
     allowedRealmPrefixes: [realm.realmURL.origin + '/'],
     authorization: `Bearer ${realm.ownerBearerToken}`,
   });
@@ -408,7 +402,6 @@ test.describe('realm-search with seeded fixture data', () => {
     let executor = new ToolExecutor(registry, {
       packageRoot: process.cwd(),
       targetRealmUrl: realm.realmURL.href,
-      testRealmUrl: realm.realmURL.href,
       allowedRealmPrefixes: [realm.realmURL.origin + '/'],
       authorization: `Bearer ${realm.ownerBearerToken}`,
     });
@@ -493,7 +486,6 @@ test.describe('realm-search on a private realm', () => {
     let ownerExecutor = new ToolExecutor(registry, {
       packageRoot: process.cwd(),
       targetRealmUrl: realm.realmURL.href,
-      testRealmUrl: realm.realmURL.href,
       allowedRealmPrefixes: [realm.realmURL.origin + '/'],
       authorization: `Bearer ${realm.ownerBearerToken}`,
     });
@@ -537,7 +529,6 @@ test.describe('realm-search on a private realm', () => {
     let noAuthExecutor = new ToolExecutor(registry, {
       packageRoot: process.cwd(),
       targetRealmUrl: realm.realmURL.href,
-      testRealmUrl: realm.realmURL.href,
       allowedRealmPrefixes: [realm.realmURL.origin + '/'],
       // No authorization — simulates unauthenticated access
     });
@@ -556,7 +547,6 @@ test.describe('realm-search on a private realm', () => {
     let unauthorizedExecutor = new ToolExecutor(registry, {
       packageRoot: process.cwd(),
       targetRealmUrl: realm.realmURL.href,
-      testRealmUrl: realm.realmURL.href,
       allowedRealmPrefixes: [realm.realmURL.origin + '/'],
       authorization: `Bearer ${unauthorizedToken}`,
     });
@@ -638,7 +628,6 @@ test.describe('realm-create against a live realm server', () => {
     let sessionExecutor = new ToolExecutor(registry, {
       packageRoot: process.cwd(),
       targetRealmUrl: realm.realmURL.href,
-      testRealmUrl: realm.realmURL.href,
       allowedRealmPrefixes: [realm.realmURL.origin + '/'],
     });
 
@@ -659,7 +648,6 @@ test.describe('realm-create against a live realm server', () => {
     let createExecutor = new ToolExecutor(registry, {
       packageRoot: process.cwd(),
       targetRealmUrl: realm.realmURL.href,
-      testRealmUrl: realm.realmURL.href,
       allowedRealmPrefixes: [realm.realmURL.origin + '/'],
       authorization: serverJwt,
     });
@@ -689,7 +677,6 @@ test.describe('realm-create against a live realm server', () => {
     let verifyExecutor = new ToolExecutor(registry, {
       packageRoot: process.cwd(),
       targetRealmUrl: newRealmUrl,
-      testRealmUrl: realm.realmURL.href,
       allowedRealmPrefixes: [realm.realmURL.origin + '/'],
       authorization: newRealmToken,
     });
diff --git a/packages/software-factory/tests/factory-tool-executor.test.ts b/packages/software-factory/tests/factory-tool-executor.test.ts
index 60c6ea048c8..fa32cc64b6a 100644
--- a/packages/software-factory/tests/factory-tool-executor.test.ts
+++ b/packages/software-factory/tests/factory-tool-executor.test.ts
@@ -24,7 +24,6 @@ function makeConfig(
   return {
     packageRoot: '/fake/software-factory',
     targetRealmUrl: 'https://realms.example.test/user/target/',
-    testRealmUrl: 'https://realms.example.test/user/target-tests/',
     ...overrides,
   };
 }

From ff8ecc6d1f1cb25e8bb8ef70b3eccbcebb983b9d Mon Sep 17 00:00:00 2001
From: Hassan Abdel-Rahman <hassan.abdelrahman@gmail.com>
Date: Wed, 8 Apr 2026 16:36:43 -0400
Subject: [PATCH 10/10] Remove test realm test case and fix tool executor
 allowed list

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>
---
 .../tests/factory-tool-executor.test.ts          | 16 ----------------
 1 file changed, 16 deletions(-)

diff --git a/packages/software-factory/tests/factory-tool-executor.test.ts b/packages/software-factory/tests/factory-tool-executor.test.ts
index fa32cc64b6a..c4af568a1bd 100644
--- a/packages/software-factory/tests/factory-tool-executor.test.ts
+++ b/packages/software-factory/tests/factory-tool-executor.test.ts
@@ -138,22 +138,6 @@ module('factory-tool-executor > source realm protection', function () {
     assert.strictEqual(result.exitCode, 0);
   });
 
-  test('allows tool targeting test realm', async function (assert) {
-    let registry = new ToolRegistry();
-    let config = makeConfig({
-      sourceRealmUrl: 'https://realms.example.test/user/source/',
-      fetch: createMockFetch(200, { data: [] }),
-    });
-    let executor = new ToolExecutor(registry, config);
-
-    let result = await executor.execute('realm-read', {
-      'realm-url': 'https://realms.example.test/user/target-tests/',
-      path: 'Test/spec.ts',
-    });
-
-    assert.strictEqual(result.exitCode, 0);
-  });
-
   test('rejects realm-api tool targeting unknown realm', async function (assert) {
     let registry = new ToolRegistry();
     let executor = new ToolExecutor(