Add comments support to Issue schema (CS-10724) by habdelra · Pull Request #4395 · cardstack/boxel

habdelra · 2026-04-13T20:56:20Z

Depends on: #4394 (must be reviewed and merged first)

Summary

Define Comment FieldDef with body (MarkdownField), author (StringField), and datetime (DateTimeField) fields
Add containsMany(Comment) field to the Issue card schema
Render comments in the Issue card's isolated template (conditional on comments existing)
Add add_comment agent tool that appends structured comments to issues via read-modify-write pattern
Make issue descriptions immutable — update_issue strips description, orchestrator uses comments for max-iteration blocking
Centralize comment logic in addCommentToIssue() in realm-operations.ts (used by both agent tool and orchestrator)
Update skills, prompts, and phase-2-plan.md to document the immutable description rule

Comment rendering preview (isolated template)

Design decisions

Append-only: Comments are an append-only log. The add_comment tool only adds — it cannot edit or delete existing comments.
Descriptions are immutable: Issue descriptions capture original intent and must never be modified after creation. All post-creation context goes through comments. Enforced at the tool level (update_issue strips description), the IssueStore interface (no description in updateIssue), and in skills/prompts.
Centralized comment logic: addCommentToIssue() in realm-operations.ts is the single implementation. Both the agent's add_comment tool and the orchestrator's IssueStore.addComment() delegate to it.
Max-iteration blocking uses comments: When the orchestrator blocks an issue for exhausting iterations, the validation failure context is added as a comment (author: orchestrator) instead of overwriting the description.

Test plan

Closes CS-10724

🤖 Generated with Claude Code

- Define Comment FieldDef with body (markdown), author (string), datetime - Add containsMany(Comment) field to Issue card - Render comments in Issue isolated template - Add add_comment agent tool with read-modify-write pattern - Update phase-2-plan.md to document comments support - 5 new tests for the add_comment tool Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The image is still accessible via the branch ref in the PR description. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6778fffe3a

ℹ️ About Codex in GitHub

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

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

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

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

packages/software-factory/src/factory-tool-builder.ts

packages/software-factory/src/issue-loop.ts

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

Copilot

Pull request overview

Adds structured, append-only comments to the Software Factory Issue model and updates the agent/orchestrator loop to treat issue descriptions as immutable, using comments for ongoing context (including max-iteration blocking). This supports better auditability and avoids clobbering issue intent during automated updates.

Changes:

Extend the darkfactory Issue schema with comments: containsMany(Comment) and render comments in Issue templates.
Add add_comment tool and centralized addCommentToIssue() read-modify-write helper; make update_issue strip description and restrict agent-set statuses.
Update orchestrator loop behavior: set in_progress on pickup, auto-mark done only on signal_done + passing validation, and log max-iteration failures as comments; update docs/prompts/skills accordingly.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/software-factory/tests/issue-scheduler.test.ts	Updates MockIssueStore to satisfy new `addComment()` interface method.
packages/software-factory/tests/issue-loop.test.ts	Expands mocks and adds coverage for orchestrator-owned transitions, comment logging, and project completion updates.
packages/software-factory/tests/factory-tool-executor.spec.ts	Adds integration coverage for `add_comment` and updates tooling config (`darkfactoryModuleUrl`).
packages/software-factory/tests/factory-tool-builder.test.ts	Adds read-patch-write tests, `add_comment` tool tests, and removes `run_tests` tool assertions.
packages/software-factory/src/test-run-execution.ts	Fixes Playwright `waitForFunction` arg placement and increases timeout for QUnit completion.
packages/software-factory/src/realm-operations.ts	Introduces `ensureJsonExtension()` and central `addCommentToIssue()` helper.
packages/software-factory/src/issue-scheduler.ts	Extends `IssueStore` with `addComment()` and optional `updateProjectStatus()`, normalizes `.json` paths, adds project completion update implementation.
packages/software-factory/src/issue-loop.ts	Implements orchestrator-owned status transitions, uses comments for max-iteration blocking context, and updates project completion logic.
packages/software-factory/src/factory-tool-builder.ts	Adds `darkfactoryModuleUrl` to config, implements read-patch-write updates, adds `add_comment`, removes `run_tests`.
packages/software-factory/src/factory-issue-loop-wiring.ts	Threads `darkfactoryModuleUrl` through ToolBuilderConfig.
packages/software-factory/src/darkfactory-schemas.ts	Adjusts `buildCardDocument()` to accept the darkfactory module URL (not derived from target realm).
packages/software-factory/scripts/smoke-tests/issue-loop-smoke.ts	Updates smoke-test mock store with `addComment()`.
packages/software-factory/scripts/smoke-tests/factory-tools-smoke.ts	Provides `darkfactoryModuleUrl` in smoke tool builder config.
packages/software-factory/realm/test-results.gts	Improves TestRun UI: empty status and module count styling tweaks.
packages/software-factory/realm/darkfactory.gts	Adds `Comment` FieldDef, `Issue.comments`, comment rendering, and status badges in Issue/Project templates.
packages/software-factory/prompts/ticket-implement.md	Reorders implementation steps; reinforces orchestrator-managed completion flow.
packages/software-factory/prompts/system.md	Documents immutable descriptions and clarifies validation pipeline behavior.
packages/software-factory/prompts/bootstrap-implement.md	Updates bootstrap naming conventions and completion signaling (`signal_done` instead of setting status).
packages/software-factory/docs/phase-2-plan.md	Documents comment system, immutable descriptions, orchestrator-owned transitions, project completion, and tooling behaviors.
packages/software-factory/.agents/skills/software-factory-operations/SKILL.md	Updates skill guidance for immutable descriptions and adds `add_comment` usage.
packages/software-factory/.agents/skills/software-factory-bootstrap/SKILL.md	Updates bootstrap conventions (project path/name, issue naming) and completion flow.

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

packages/software-factory/src/realm-operations.ts

packages/software-factory/src/issue-loop.ts

packages/software-factory/src/factory-tool-builder.ts

…n context - Add addCommentToIssue() to realm-operations.ts as centralized comment logic - Add addComment() to IssueStore interface; remove description from updateIssue - Refactor max-iteration blocking to use addComment instead of overwriting description - Strip description from update_issue agent tool (like status stripping) - Update skills, system prompt, and SKILL.md to document the rule - Add unit test for description stripping in update_issue - Add Playwright integration test for add_comment tool - Update phase-2-plan.md with immutable description design principle Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…ndling - Use Array.isArray() in addCommentToIssue to handle corrupt/non-array comments field gracefully - Separate try/catch blocks for addComment and updateIssue in the max-iteration blocking path so a comment write failure doesn't prevent the critical status transition to blocked Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

burieberry · 2026-04-14T14:32:19Z

packages/software-factory/src/realm-operations.ts

+/**
+ * Ensure a card instance path ends with `.json`. The realm API uses
+ * `card+source` content negotiation which requires the full file path
+ * including extension.
+ */
+export function ensureJsonExtension(path: string): string {
+  if (!path.endsWith('.json')) {
+    return `${path}.json`;
+  }
+  return path;
+}


runtime-common/url.ts seems to contain related json extension trimming, so maybe this could go there. up to you. ensureTrailingSlash above exists in runtime-common

habdelra and others added 2 commits April 13, 2026 16:55

Remove PR preview image from repo

0003649

The image is still accessible via the branch ref in the PR description. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chatgpt-codex-connector bot reviewed Apr 13, 2026

View reviewed changes

packages/software-factory/src/factory-tool-builder.ts Outdated Show resolved Hide resolved

packages/software-factory/src/issue-loop.ts Show resolved Hide resolved

habdelra and others added 2 commits April 13, 2026 17:02

Add comments preview image for PR

dc80893

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

Remove PR preview image from repo

9af9ac9

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

habdelra requested a review from Copilot April 13, 2026 21:21

Copilot started reviewing on behalf of habdelra April 13, 2026 21:22 View session

Copilot AI reviewed Apr 13, 2026

View reviewed changes

packages/software-factory/src/realm-operations.ts Show resolved Hide resolved

packages/software-factory/src/issue-loop.ts Show resolved Hide resolved

packages/software-factory/src/factory-tool-builder.ts Show resolved Hide resolved

habdelra force-pushed the cs-10724-add-comments-support-to-issue-schema branch from 6b473ee to 4804a00 Compare April 13, 2026 21:26

habdelra requested a review from a team April 13, 2026 21:40

burieberry reviewed Apr 14, 2026

View reviewed changes

burieberry approved these changes Apr 14, 2026

View reviewed changes

Merge main into cs-10724-add-comments-support-to-issue-schema

8098c3c

habdelra merged commit 4a77365 into main Apr 14, 2026
24 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add comments support to Issue schema (CS-10724)#4395

Add comments support to Issue schema (CS-10724)#4395
habdelra merged 7 commits intomainfrom
cs-10724-add-comments-support-to-issue-schema

habdelra commented Apr 13, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

burieberry Apr 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

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

Uh oh!

Summary

Comment rendering preview (isolated template)

Design decisions

Test plan

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

burieberry Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

habdelra commented Apr 13, 2026 •

edited

Loading