cve-dashboard/.kiro/specs/remediation-plan-history/requirements.md

Requirements Document

Introduction

Historical tracking for resolution dates and remediation plans on compliance items. When a user changes the resolution_date or remediation_plan for a device, the previous value is preserved as an audit trail entry with a timestamp and the identity of the user who made the change. The most recent values remain directly queryable on the compliance_items table so existing VCL reporting queries continue to work without modification.

Glossary

• Compliance_Item: A row in the compliance_items table representing a single non-compliant device/metric pair.
• Resolution_Date: A DATE field on a compliance item indicating when remediation is expected to complete.
• Remediation_Plan: A TEXT field (max 2000 characters) describing the planned remediation approach.
• History_Entry: A row in the compliance_item_history table capturing a previous value of resolution_date or remediation_plan before it was overwritten.
• Change_Reason: An optional text field on a History_Entry describing why the change was made.
• Detail_Panel: The ComplianceDetailPanel UI component that displays device-level compliance information and allows editing of metadata fields.
• VCL_Report: The multi-vertical compliance reporting system that uses resolution_date for burndown forecasts and blocked/in-progress donut charts.
• Current_Value: The value stored directly on the compliance_items row, representing the most recent resolution_date or remediation_plan.

Requirements

Requirement 1: Persist History on Field Change

User Story: As a compliance analyst, I want previous resolution dates and remediation plans to be preserved when I make changes, so that I have an audit trail of what was planned and when plans changed.

Acceptance Criteria

1. WHEN a user updates the resolution_date for a hostname via the metadata PATCH endpoint, THE History_Service SHALL insert a History_Entry containing the previous resolution_date value, the field name, the hostname, the timestamp of the change, the username of the user who made the change, and the change_reason if provided.
2. WHEN a user updates the remediation_plan for a hostname via the metadata PATCH endpoint, THE History_Service SHALL insert a History_Entry containing the previous remediation_plan value, the field name, the hostname, the timestamp of the change, the username of the user who made the change, and the change_reason if provided.
3. WHEN the previous value is NULL and the user sets a new value, THE History_Service SHALL insert a History_Entry with the old_value recorded as NULL.
4. WHEN the new value is identical to the current value, THE History_Service SHALL NOT create a History_Entry.
5. WHEN a bulk update changes resolution_date or remediation_plan for multiple hostnames, THE History_Service SHALL insert one History_Entry per hostname per changed field.
6. THE History_Service SHALL accept an optional change_reason field in the metadata PATCH request body.

Requirement 2: History Storage Schema

User Story: As a system administrator, I want history entries stored in a dedicated table with proper indexing, so that history queries are fast and do not impact existing compliance_items queries.

Acceptance Criteria

1. THE Database SHALL store history entries in a compliance_item_history table with columns: id (serial primary key), hostname (text, not null), field_name (text, not null), old_value (text), new_value (text), change_reason (text), changed_by (text, not null), changed_at (timestamptz, default NOW()).
2. THE Database SHALL index the compliance_item_history table on (hostname, field_name) for efficient per-device history lookups.
3. THE Database SHALL index the compliance_item_history table on (changed_at) for chronological queries.
4. THE compliance_items table SHALL continue to store the current resolution_date and remediation_plan directly as columns, unchanged from the existing schema.

Requirement 3: Reporting Isolation

User Story: As a VCL report consumer, I want burndown forecasts and donut charts to use only the current resolution_date, so that historical changes do not cause double-counting or incorrect projections.

Acceptance Criteria

1. THE VCL_Report SHALL read resolution_date exclusively from the compliance_items table for burndown and donut calculations.
2. THE VCL_Report SHALL NOT join or reference the compliance_item_history table for any reporting query.
3. WHEN multiple History_Entries exist for a hostname, THE VCL_Report SHALL use only the Current_Value from compliance_items.resolution_date for forecasting.

Requirement 4: History Retrieval API

User Story: As a compliance analyst, I want to retrieve the change history for a device's resolution date and remediation plan, so that I can see who changed what and when.

Acceptance Criteria

1. WHEN a client requests the detail for a hostname, THE Compliance_API SHALL return the history of resolution_date and remediation_plan changes alongside the current values and notes.
2. THE Compliance_API SHALL return history entries sorted by changed_at in descending order (most recent first).
3. THE Compliance_API SHALL return a maximum of 10 history entries per hostname.
4. THE Compliance_API SHALL include the fields: field_name, old_value, new_value, change_reason, changed_by, and changed_at for each History_Entry.
5. IF no history entries exist for a hostname, THE Compliance_API SHALL return an empty array for the history field.

Requirement 5: History Display in Detail Panel

User Story: As a compliance analyst, I want to see the history of changes to resolution date and remediation plan in the device detail panel, so that I can understand how plans have evolved over time.

Acceptance Criteria

1. THE Detail_Panel SHALL display a "Change History" section showing all History_Entries for the selected hostname.
2. WHEN a History_Entry exists, THE Detail_Panel SHALL display the field that changed, the old value, the new value, who made the change, when the change occurred, and the change reason if one was provided.
3. THE Detail_Panel SHALL display history entries in reverse chronological order (most recent change at the top).
4. WHEN no history entries exist, THE Detail_Panel SHALL display a message indicating no changes have been recorded.
5. THE Detail_Panel SHALL format resolution_date values as YYYY-MM-DD and remediation_plan values as truncated text with a tooltip or expandable view for long entries.
6. THE Detail_Panel SHALL include a text input for change_reason when saving resolution_date or remediation_plan changes.

Requirement 6: Bulk Update History Tracking

User Story: As a compliance analyst, I want bulk xlsx updates to also track history, so that mass changes to resolution dates and remediation plans are auditable.

Acceptance Criteria

1. WHEN the bulk update commit endpoint applies changes to resolution_date or remediation_plan, THE History_Service SHALL create History_Entries for each hostname where the value changed.
2. THE History_Service SHALL record the changed_by as the username of the user who initiated the bulk update.
3. WHEN a bulk update row contains the same value as the current value for a hostname, THE History_Service SHALL NOT create a History_Entry for that field.

Requirement 7: Database Migration

User Story: As a developer, I want the history table created via a standard migration script, so that it can be applied to existing deployments without manual intervention.

Acceptance Criteria

1. THE Migration SHALL create the compliance_item_history table if it does not already exist.
2. THE Migration SHALL create the required indexes on the compliance_item_history table.
3. THE Migration SHALL be idempotent and safe to run multiple times without error.
4. THE Migration SHALL NOT modify the existing compliance_items table structure.