review-state: Artifacts accumulate with duplicates and lack relevance ordering #200

New issue

Open

opened 2026-02-13 23:07:27 +00:00 by mprihoda · 0 comments

mprihoda commented

2026-02-13 23:07:27 +00:00

(Migrated from github.com)

Problem

The review-state update --append-artifact mechanism has two issues that degrade the dashboard experience during multi-phase workflows:

1. Duplicate artifacts from blind append

ReviewStateUpdater.mergeArray with ArrayMergeMode.Append blindly concatenates new items — no deduplication by path. The ag-implement workflow appends the same artifact from multiple transition points:

"Implementation Log" gets appended in refactoring completion (Step 5.4) AND final completion (Step 10)
"Phase N Context" gets appended in ag-implement Step 6a AND ag-implementation-workflow Step 5.5
Actions like "implement:Start Implementation:ag-implement" get appended every phase in Step 6b

After a few phases, the artifacts array has multiple identical entries.

2. No relevance signal — current phase artifacts buried at bottom

Even without duplicates, a 5-phase issue accumulates ~15+ artifacts in chronological order. The artifacts the reviewer needs NOW (current phase context, review packet) are at the bottom, requiring scrolling past all historical artifacts.

Proposed Solution

Part 1: Upsert semantics for append

Change --append-artifact (and --append-badge, --append-action) to deduplicate by natural key:

Artifacts: deduplicate by path
Actions: deduplicate by id
Badges: deduplicate by label

When an item with the same key already exists, replace it in-place rather than creating a duplicate.

Part 2: Attention artifacts

Add a separate top-level attention_artifacts array (2-3 items) to review-state.json alongside the full artifacts array. This separates "what you should look at now" from "full history":

Dashboard renders attention_artifacts prominently at the top
Full artifacts list available for browsing (collapsed or secondary)
Workflow replaces attention_artifacts at each phase transition with only the current phase's key documents

New CLI flags: --attention-artifact "label:path" (replace mode) to set the current attention set.

Affected Code

.iw/core/model/ReviewStateUpdater.scala — mergeArray function (line 166-186)
.iw/commands/review-state/update.scala — CLI flag parsing
schemas/review-state.schema.json — add attention_artifacts field
Dashboard rendering (artifact display logic)
Plugin workflow skills (ag-implement, ag-implementation-workflow) — update to set attention_artifacts at transition points

Notes

The upsert change (Part 1) is backward-compatible — existing --append-artifact calls just stop producing duplicates
Part 2 requires schema version bump and dashboard changes
The full artifacts array accumulation is intentional for reviewer context — we're adding a relevance layer on top, not removing the history

## Problem The `review-state update --append-artifact` mechanism has two issues that degrade the dashboard experience during multi-phase workflows: ### 1. Duplicate artifacts from blind append `ReviewStateUpdater.mergeArray` with `ArrayMergeMode.Append` blindly concatenates new items — no deduplication by path. The ag-implement workflow appends the same artifact from multiple transition points: - **"Implementation Log"** gets appended in refactoring completion (Step 5.4) AND final completion (Step 10) - **"Phase N Context"** gets appended in ag-implement Step 6a AND ag-implementation-workflow Step 5.5 - **Actions** like `"implement:Start Implementation:ag-implement"` get appended every phase in Step 6b After a few phases, the artifacts array has multiple identical entries. ### 2. No relevance signal — current phase artifacts buried at bottom Even without duplicates, a 5-phase issue accumulates ~15+ artifacts in chronological order. The artifacts the reviewer needs NOW (current phase context, review packet) are at the bottom, requiring scrolling past all historical artifacts. ## Proposed Solution ### Part 1: Upsert semantics for append Change `--append-artifact` (and `--append-badge`, `--append-action`) to deduplicate by natural key: - **Artifacts**: deduplicate by `path` - **Actions**: deduplicate by `id` - **Badges**: deduplicate by `label` When an item with the same key already exists, replace it in-place rather than creating a duplicate. ### Part 2: Attention artifacts Add a separate top-level `attention_artifacts` array (2-3 items) to `review-state.json` alongside the full `artifacts` array. This separates "what you should look at now" from "full history": - Dashboard renders `attention_artifacts` prominently at the top - Full `artifacts` list available for browsing (collapsed or secondary) - Workflow replaces `attention_artifacts` at each phase transition with only the current phase's key documents New CLI flags: `--attention-artifact "label:path"` (replace mode) to set the current attention set. ## Affected Code - `.iw/core/model/ReviewStateUpdater.scala` — `mergeArray` function (line 166-186) - `.iw/commands/review-state/update.scala` — CLI flag parsing - `schemas/review-state.schema.json` — add `attention_artifacts` field - Dashboard rendering (artifact display logic) - Plugin workflow skills (ag-implement, ag-implementation-workflow) — update to set attention_artifacts at transition points ## Notes - The upsert change (Part 1) is backward-compatible — existing `--append-artifact` calls just stop producing duplicates - Part 2 requires schema version bump and dashboard changes - The full `artifacts` array accumulation is intentional for reviewer context — we're adding a relevance layer on top, not removing the history