Add ContextBuilder for AgentContext assembly (CS-10567)

[habdelra]

Note: This PR is based on #4292 (worktree-cs-10560-cache-prepare), which needs to be reviewed and merged first.

Summary

• Add scripts/lib/factory-context-builder.ts — assembles a complete AgentContext from ticket, project, knowledge articles, and resolved skills
• Aligned with CS-10566's executable tool functions model: tools are no longer in AgentContext (provided separately as FactoryTool[] to agent.run())
• AgentContext.tools marked optional/deprecated; toolResults, previousActions, iteration no longer set by the builder
• Supports testResults threading for iteration passes after failed test runs
• Skill budget enforcement via enforceSkillBudget() when maxSkillTokens is configured
• Guard context.tools access in factory-prompt-loader.ts with ?? [] for backward compat
• Add tests/factory-context-builder.test.ts with 14 tests covering skill resolution, budget enforcement, tool exclusion, test results threading, and core fields
• Add scripts/factory-context-smoke.ts — exercises the full pipeline with real skill files from disk

Try it out

From packages/software-factory/:

# Basic run — exercises skill resolution, loading, context assembly
pnpm factory:context-smoke

Expected output:

=== Context Builder Smoke Test ===

--- Card definition (.gts work) ---
  Ticket: Define StickyNote card

  First pass (no test results):
  ✓ project.id set
  ✓ ticket.id set
  ✓ knowledge: 2 article(s)
  ✓ skills: 3 loaded
  ✓ tools not set (provided separately as FactoryTool[])
  ✓ testResults not set
  ✓ targetRealmUrl set
  ✓ testRealmUrl set
  Skill breakdown (~69269 total tokens):
    - boxel-development: ~6969 tokens + 5 ref(s)
    - boxel-file-structure: ~1964 tokens
    - ember-best-practices: ~60336 tokens + 1 ref(s)

  Iteration pass (with failed test results):
  ✓ testResults.status = failed
  ✓ testResults.failedCount = 1
  ✓ testResults.failures[0] has error
  ✓ skills still loaded on iteration
  ✓ deprecated fields not set

--- Factory workflow ticket ---
  Ticket: Improve factory delivery pipeline

  ... (same checks, different skills resolved) ...

--- Minimal ticket (base case) ---
  Ticket: Add timestamp fields

  ... (same checks, fewer skills for a generic ticket) ...

===========================
  39 passed, 0 failed
===========================

With skill token budget enforcement:

pnpm factory:context-smoke --max-tokens 8000

This trims skills to fit within the budget. You'll see [SkillBudget] Dropping skill ... warnings as skills are trimmed, and a budget verification section at the end:

[SkillBudget] Dropping skill "boxel-file-structure" (1964 tokens) — would exceed budget of 8000 (used: 6969)
[SkillBudget] Dropping skill "ember-best-practices" (60336 tokens) — would exceed budget of 8000 (used: 6969)
  First pass (no test results):
  ✓ project.id set
  ...
  ✓ skills: 1 loaded
  ...
  Skill breakdown (~6969 total tokens):
    - boxel-development: ~6969 tokens + 5 ref(s)

  ... (more tickets, some fit within budget without trimming) ...

--- Budget enforcement (8000 tokens) ---

[SkillBudget] Dropping skill "boxel-file-structure" (1964 tokens) — would exceed budget of 8000 (used: 6969)
[SkillBudget] Dropping skill "ember-best-practices" (60336 tokens) — would exceed budget of 8000 (used: 6969)
  ✓ 1 skills within budget (~6969 tokens <= 8000)
    - boxel-development: ~6969 tokens

===========================
  40 passed, 0 failed
===========================

Test plan

• pnpm test:node — all 321 tests pass (14 new)
• pnpm lint — clean (only pre-existing ../base/ glint errors)
• pnpm factory:context-smoke — 39 passed, 0 failed
• pnpm factory:context-smoke --max-tokens 8000 — 40 passed, 0 failed

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[Copilot]

Pull request overview

Adds a reusable ContextBuilder to assemble full AgentContext objects (skills, tools, iteration state, and core ticket/project fields) and extends the software-factory harness to be more self-sufficient in fresh worktrees (auto-building/symlinking dist assets, improving cached-context validation, and adding indexing progress output).

Changes:

• Add ContextBuilder (factory-context-builder.ts) plus comprehensive QUnit coverage for skill resolution/budgeting, tool manifests, and iteration-state threading.
• Update harness startup to auto-ensure host/boxel-ui/boxel-icons build artifacts exist (symlink from root checkout when possible; otherwise build).
• Improve harness/template build ergonomics: remove worker-manager env port plumbing in tests, add worker-manager port override support, and print indexing progress by polling /_indexing-status.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/software-factory/scripts/lib/factory-context-builder.ts	New ContextBuilder for assembling AgentContext (skills/tools + iteration state).
packages/software-factory/tests/factory-context-builder.test.ts	New test suite (17 tests) covering context assembly behavior.
packages/software-factory/src/harness/support-services.ts	Auto-ensure/build/symlink host + boxel-ui + boxel-icons dist artifacts; manage icon server lifecycle.
packages/software-factory/src/harness/database.ts	Add indexing progress reporter; adjust PG connection behavior for existence checks.
packages/software-factory/src/harness/isolated-realm-stack.ts	Allow explicit worker-manager port (used for progress polling).
packages/software-factory/src/harness/shared.ts	Remove exported default worker-manager port env constant.
packages/software-factory/tests/fixtures.ts	Remove stable worker-manager port allocation/env wiring for Playwright harness; shift prerender port.
packages/software-factory/src/cli/cache-realm.ts	Validate cached support context URLs (host + matrix) before reuse.

Comments suppressed due to low confidence (1)

packages/software-factory/src/harness/isolated-realm-stack.ts:304

• actualWorkerManagerPort and actualRealmServerPort can be derived from separate findAvailablePort() calls without reserving either port. This can (rarely but definitively) result in the same port being selected for both processes, causing one to fail to bind. Consider ensuring uniqueness (e.g., if the second selection equals the first, pick again) or switching to a port-allocation helper that reserves ports until the child processes are listening.

  let actualWorkerManagerPort =
    explicitWorkerManagerPort ?? (await findAvailablePort());
  let actualRealmServerPort =
    DEFAULT_REALM_SERVER_PORT === 0
      ? await findAvailablePort()
      : DEFAULT_REALM_SERVER_PORT;
  let actualRealmServerURL = withPort(realmServerURL, actualRealmServerPort);

---

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