Artifacts Page Improvements

Exec Summary

*Pending rewrite after problem statement is approved.*

1. Problem Statement and Goal

Problems

1. I can't tell what's relevant without opening every artifact. The artifacts page is a flat list of 24 items. There's no visual signal for whether something is a current draft I need to act on, a completed deliverable, or a stale plan that was superseded months ago. I have to click into each one and read the frontmatter to figure out if it matters right now. That means the page fails at its most basic job: helping me find what I need quickly.

2. I lose time scanning past artifacts that no longer matter. Three artifacts are superseded, one is archived, and several are completed. They sit alongside active drafts with equal visual weight. When I'm looking for the spec I need to review, I'm mentally filtering out noise every time. The page gets worse as more artifacts accumulate because the ratio of current-to-stale keeps dropping.

3. I can't see how artifacts connect to the work they support. Artifacts are created for tasks (a spec for JAM-18, a research brief for JAM-17), but that relationship only exists as a markdown link I manually pasted into a task's Details field. From the artifacts page, there's no way to see which task an artifact belongs to. From a task, there's no structured link back. I end up holding the mapping in my head or searching chat history.

4. Navigating between related artifacts and tasks requires too many steps. If I'm reviewing a task and want to read its spec, I scroll through the Details field looking for a link. If I'm reading an artifact and want to check the task status, I have to go back to the board and find the right card. There's no two-way navigation. This friction compounds when tasks have multiple artifacts (a spec and a research brief) or when an artifact informs multiple tasks.

5. The type system has drifted and the page doesn't help me see that. We decided on two artifact types (spec, research-brief), but the existing collection uses eight different types from before that decision. The page treats all types identically, so there's no prompt to clean up inconsistencies and no way to scan by type.

Goal

The artifacts page should help me answer three questions in under 10 seconds:

1. What artifacts need my attention right now?
2. What artifact(s) belong to a specific task, and vice versa?
3. Where did we land on a past decision? (finding a completed artifact quickly)

2. Success Metric

• Pete can identify all active/draft artifacts without scrolling past stale ones
• Pete can filter by type (spec vs. research-brief) in one click
• Pete can see which task an artifact belongs to directly from the list
• Superseded/archived artifacts are hidden by default but accessible

3. Current State

• 24 artifacts in artifacts/ directory
• Statuses: 7 draft, 3 completed, 3 superseded, 1 archived, 1 active, 1 approved, 8 with no status
• Types: 7 spec, 7 research-brief, 5 implementation-plan, plus 5 other types
• Artifacts page renders a flat list sorted by filename
• Each list item shows title and type badge; clicking opens the full rendered artifact
• No filtering, grouping, search, or status indicators on the list view
• Some artifacts are linked from task descriptions (as markdown links in Details), but there's no reverse link from artifact to task

4. Platform Capabilities

Mission Control already:

• Reads artifact frontmatter (title, type, status, tags)
• Renders markdown to HTML
• Has a task system with a Details field that can contain artifact links

What's missing:

• No structured artifact-to-task relationship (just freeform markdown links)
• No UI components for filtering or grouping
• No concept of "pinned" or "archived" in the artifact display logic

5. Community Patterns

Linear's docs section groups by project and shows status. Notion databases let you toggle between views (table, gallery, board). The common pattern for document management in productivity tools: default view hides archived/completed items, with a toggle to show all.

6. Options

Option A: Status Groups + Type Filter (minimal)

Group artifacts by status (Active/Draft, Completed, Archived/Superseded). Add a type filter dropdown (All, Spec, Research Brief). Archived/Superseded collapsed by default.

Pros: Solves the core scanning problem. Low build effort. Cons: No task linkage. No project grouping (depends on JAM-25).

Option B: Option A + Task Linkage

Add a task field to frontmatter. Show the associated task ID (e.g. "JAM-18") as a clickable badge on each artifact card. Add a reverse link on the task detail view.

Pros: Connects artifacts to their context. Two-way navigation. Cons: Requires updating all existing artifact frontmatter. Medium build effort.

Option C: Option B + Smart Default View

Same as B, plus: default view only shows active/draft artifacts. A toggle reveals completed/archived. Pinned artifacts always show at top regardless of status.

Pros: Best scanning experience. Pete sees what matters immediately. Cons: Slightly more UI complexity.

7. Recommendation

Option C. The whole point is making the page scannable. Hiding stale artifacts by default and connecting artifacts to tasks are both necessary for that.

Proposed layout

Header: "Artifacts" title + filter bar

• Type filter: All | Specs | Research Briefs
• Status toggle: "Show archived" (off by default)

Pinned section (if any pinned artifacts exist):

• Horizontal row of pinned artifact cards at the top

Active section (default view):

• Cards grouped by status: Draft, Active/Approved, Completed
• Each card shows: title, type badge (colored), status badge, task link (if any), updated date
• Cards are sorted by updated date within each group

Archived section (hidden by default, revealed by toggle):

• Superseded and archived artifacts
• Visually muted (lower opacity or gray text)

Artifact card design

┌─────────────────────────────────────────┐
│ ● Spec                        JAM-18 →  │
│ Workspace Backup & Version Control      │
│ Draft · Updated Apr 3                   │
└─────────────────────────────────────────┘

• Type badge: colored dot + label (spec=purple, research-brief=blue)
• Task link: displayed as "JAM-XX →" badge, clickable to task detail
• Status: text label
• Title: primary text, clickable to open artifact

Frontmatter additions

Add to artifact frontmatter schema:

• task: string, optional. The displayId of the associated task (e.g. "JAM-18")
• pinned: boolean, optional. Pinned artifacts always show at top of the page.

Data migration

Update existing artifacts to add task field where applicable:

• spec_workspace_backup.md → task: JAM-18
• spec_mc_board_phase1.md → task: JAM-11
• spec_mc_kanban_board.md → task: JAM-11
• spec_uas_intelligence_platform.md → task: JAM-15
• research_linear_ui_deconstruction.md → task: JAM-11
• research_linear_mobile_patterns.md → task: JAM-7

Status normalization

Reduce to 4 statuses (map existing values):

• draft (includes "active", "approved" since they're pre-completion states)
• completed
• archived (includes "superseded")
• pinned (special, always visible)

8. Security Considerations

No new security concerns. Artifacts are already readable by anyone with MC access. No new data exposure.

9. Pete's Setup Checklist

None. This is a build task with no external dependencies.

10. Implementation Scope

David builds:

1. Artifact list component rewrite (components/artifacts/ArtifactList.tsx or equivalent):

• Read frontmatter from all artifacts
• Group by status (draft → completed → archived)
• Filter by type
• Show/hide archived toggle
• Pinned section at top

1. Artifact card component (components/artifacts/ArtifactCard.tsx):

• Type badge (colored dot)
• Task link badge (clickable)
• Status label
• Updated date
• Click to open artifact

1. Frontmatter parser update:

• Support task and pinned fields
• Map old statuses to normalized set

1. Data migration script:

• Add task field to applicable artifacts
• Normalize inconsistent statuses

1. Artifact detail view:

• Add "← Back to artifacts" link at top
• Show task link badge if task field present

11. Validation Criteria

• Default view shows only draft/active/completed artifacts (not archived/superseded)
• "Show archived" toggle reveals archived artifacts with muted styling
• Type filter correctly filters between specs and research briefs
• Task badges are clickable and navigate to the correct task
• Pinned artifacts appear at top regardless of status
• All 24 existing artifacts render correctly after migration

12. Test Plan

Test 1: Default view

• Load /artifacts
• Count visible artifacts; should exclude the 3 superseded + 1 archived = 20 visible
• Pass: Only non-archived artifacts shown

Test 2: Archive toggle

• Click "Show archived"
• All 24 artifacts should now be visible
• Archived artifacts should have muted styling
• Pass: Toggle works, all artifacts accessible

Test 3: Type filter

• Select "Specs" filter
• Only spec-type artifacts should show
• Select "Research Briefs" filter
• Only research-brief-type artifacts should show
• Pass: Filter correctly isolates types

Test 4: Task linkage

• Find artifact "Workspace Backup & Version Control"
• Should show "JAM-18" badge
• Click the badge
• Should navigate to task detail for JAM-18
• Pass: Two-way navigation works

Test 5: Card information

• Each card shows: title, type badge, status, updated date
• Task-linked artifacts show task badge
• Pass: All card elements render

13. Category

Tool - UI improvement to existing Mission Control feature

14. Context Loading

• Build time: this spec + current artifact frontmatter schema + existing MC component structure
• Runtime: artifacts directory scan (already happens)

15. Guardrails

• Do not change artifact file content or rendering. Only the list/index view changes.
• Do not delete or rename artifact files during migration. Only add/update frontmatter fields.
• Preserve all existing frontmatter fields when adding new ones.
• Back up artifacts directory before running migration script.

16. Handoff

• David builds the UI components and runs the frontmatter migration
• Vinny validates by checking the page and running through the test plan
• Vinny moves to needs-review, assigns to Pete