# Change Request: CR-003

> Created: 2026-03-14
> Status: Approved
> Classification: Modification to FEATURE-041-E
> Related Feature: FEATURE-041-E (Deliverable Tagging & Action Context Schema)

## Request Details

**Requestor:** End User (via UIUX Feedback-20260314-152441)
**Date Received:** 2026-03-14
**Priority:** Medium

## Description

Update the deliverable tag system to support **multiple output files per tag**. Currently, each deliverable tag (`$output:tag-name`) maps to a single file path string. This CR introduces array-value support so that a tag can hold multiple file paths.

**Concrete example:** The `compose_idea` action produces:
- `new idea.md` (the idea document)
- `生成温故而知新图片.png` (uploaded reference image)
- `生成背景图.png` (uploaded reference image)

Currently, only `new idea.md` appears in the deliverables. The two uploaded PNGs are in the ideas folder but not individually listed. After this CR, all three files should appear as deliverable cards.

**Tag rename:** `$output:raw-idea` (singular) → `$output:raw-ideas` (plural) to indicate multi-value support.

## Business Justification

- Users upload reference images alongside idea documents during compose_idea
- These uploaded files are invisible in the deliverables section, making them hard to discover
- Downstream actions (refine_idea) should be aware of ALL inputs from compose_idea
- Improves workflow transparency and traceability

## Impact Analysis

### Classification

**Type:** Modification to FEATURE-041-E

**Reasoning:**
- Extends the existing deliverable tag data model (no new data model)
- Works within current system boundaries (deliverable storage + resolution + rendering)
- Same users, extended functionality
- No new screens or API endpoints needed — extends existing `/api/workflow/{name}/deliverables`

### Comparison Matrix

| Aspect | CR Requirement | Existing Feature(s) |
|--------|---------------|---------------------|
| Users | Same workflow users | Same |
| Workflow | compose_idea stores multiple files per tag | compose_idea stores single file per tag |
| Data Model | `{ "raw-ideas": ["path1", "path2", ...] }` (array value) | `{ "raw-idea": "path" }` (string value) |
| UI Elements | Multiple cards per array tag, same deliverables section | One card per tag |
| API Endpoints | Same `/api/workflow/{name}/deliverables` — returns more items | Same endpoint |

### Conflict Analysis

**Conflicts Found:** Yes

| # | Type | Affected Feature | Severity | Classification | Description |
|---|------|-----------------|----------|----------------|-------------|
| 1 | specification | FEATURE-041-E | High | expected | AC-3 defines instance deliverables as `{ tagName: path }` (string). Must support `{ tagName: [path1, path2] }` (array). |
| 2 | specification | FEATURE-042-A | Medium | expected | AC-042.3 resolves `$output:raw-idea$` to single path. Array tags need a resolution strategy (e.g., first element for prompt, full array for rendering). |
| 3 | design | FEATURE-041-E | Medium | expected | Technical design defines deliverable dict type as `Dict[str, str]`. Must change to `Dict[str, Union[str, List[str]]]`. |
| 4 | dependency | copilot-prompt.json | Medium | expected | All `$output:raw-idea$` references in prompt templates must update to `$output:raw-ideas$`. |
| 5 | dependency | Tests | Low | expected | ~30+ test references to `$output:raw-idea` need updating across multiple test files. |

**Unexpected Conflict Resolution:** N/A — all conflicts are expected consequences of the chosen approach.

**Mitigation Strategy:**
- **Backward compatibility:** Support both string and array values in storage/resolution. If value is a string, treat as single-element array internally.
- **Template resolution:** For prompt templates (`$output:raw-ideas$`), resolve to the **first element** (primary file). Skills receive the primary file path as before.
- **Deliverable rendering:** For the UI, expand array into individual cards (one per file).
- **Schema versioning:** Bump to v4.0 when array values are first stored.

### Affected Components

| Component | Impact Level | Details |
|-----------|--------------|---------|
| `workflow-template.json` (×2) | Medium | Rename `$output:raw-idea` → `$output:raw-ideas` in compose_idea deliverables |
| `copilot-prompt.json` (×2) | Medium | Update all `$output:raw-idea$` tokens to `$output:raw-ideas$` |
| `workflow_manager_service.py` | High | `resolve_deliverables()`: expand arrays into individual entries. `validate_action_deliverables()`: accept array values. `_get_instance_deliverable()`: return first element for candidates resolution. |
| `workflow-stage.js` | Medium | `_renderDeliverables()`: render each array element as separate card |
| `action-execution-modal.js` | Medium | `_resolveTemplate()`: for array-valued tags, use first element for prompt substitution |
| `action_context` in template | Low | Rename `raw-idea` → `raw-ideas` in `refine_idea.action_context` |
| Test files | Low | Update ~30+ references across `tests/frontend-js/action-execution-modal-*.test.js` and `tests/test_feature_041e.py` |

### Dependencies

- compose_idea skill (ideation) must store deliverables as arrays when multiple files produced
- Existing workflow instances with `{"raw-idea": "path"}` must continue to work (backward compat)

## Proposed Approach

1. **Template changes:** Rename tag in `workflow-template.json` and `copilot-prompt.json`
2. **Backend (storage):** Accept both `str` and `list[str]` values in deliverable dicts
3. **Backend (resolution):** When resolving for UI, expand arrays into individual entries. When resolving for templates/candidates, use first element.
4. **Frontend (rendering):** Render each array element as its own deliverable card
5. **Frontend (templates):** `_resolveTemplate` uses first element of array for substitution
6. **Validation:** Accept both string and array values; validate each array element
7. **Migration:** Duck-type existing instances — string values treated as single-element array

## Mockup Impact

**UI/UX Change:** Yes — deliverable cards section will show more items for compose_idea
**Existing Mockups Referenced:** None found in FEATURE-041-E/mockups/

## Approval

- [x] Classification approved by human
- [x] Conflict analysis reviewed by human
- [x] Approach approved by human
- [x] Ready for execution

## Execution

**Classification Result:** modification
**Conflicts Resolution:** all_expected

**Actions Taken:**
- [x] CR document created in feature folder
- [x] Conflict analysis completed and documented
- [x] Specification Version History updated with CR link
- [ ] [Next] Feature refinement to update specification ACs
- [ ] [Next] Technical design update
- [ ] [Next] Code implementation

## Links

- Feature Specification: [specification.md](./specification.md)
- UIUX Feedback: [Feedback-20260314-152441](../../../uiux-feedback/Feedback-20260314-152441/feedback.md)
- Related EPIC-042 Spec: [FEATURE-042-A/specification.md](../../EPIC-042/FEATURE-042-A/specification.md)

---

## Change History

| Date | Change | By |
|------|--------|----|
| 2026-03-14 | CR created from UIUX feedback | Bolt ⚡ (AI Agent) |
