# openspec/changes/wf-audit-evidence/proposal.md

## Why

Auditors ask for logs of what AI systems did and proof that people oversaw them. Teams export them by hand, every year. The evidence collects itself as the work happens, so the audit is a review instead of a scramble.

## What Changes

- Add the `audit-evidence` workflow to the PromptReports workflow library, run by the workflow runner as an agent acting for a person.
- PromptCompute: Read the signed approval ledger (today: Built).
- RepoOps: Read tasks, events and outcomes (today: Built).
- PromptReports: Map events to controls (today: Planned).
- PromptCompute: A person approves the export (today: Built).
- AI Source of Truth: Record the export's hash (today: Proposed).
- Gate `data.export.bulk` through PromptCompute approvals; each gated step runs only after `verifyResume` passes, with `final_args`.
- Write a signed record at the end of each run and count one workflow request.

## Impact

- Products: PromptCompute, RepoOps, AI Source of Truth, PromptReports.
- Outside the family: Your auditor's evidence portal (optional).
- State: Planned. In the plan as compliance-mapping (LDG-2289). The mappings to SOC 2 change management and EU AI Act Articles 12, 19 and 50 are Planned. This is evidence for an auditor, not a certification.
- Plan row: LDG-2289.

# openspec/changes/wf-audit-evidence/tasks.md

## 1. Connect and authorize

- [ ] 1.1 Confirm the org has a connection for each of: PromptCompute, RepoOps, AI Source of Truth, PromptReports. Stop and tell the user which is missing.
- [ ] 1.2 Get a PromptReports ID agent token for each product the run calls (RFC 8693 exchange). Where a product does not accept ID tokens yet, use its connect key.
- [ ] 1.3 Register policy for `data.export.bulk` with `require_approval` as the default.

## 2. Build the steps

- [ ] 2.1 PromptCompute: Read the signed approval ledger.
- [ ] 2.2 RepoOps: Read tasks, events and outcomes.
- [ ] 2.3 PromptReports: Map events to controls. Blocked: this part is Planned; until it ships, record the step's evidence as `missing` and continue.
- [ ] 2.4 PromptCompute: A person approves the export.
- [ ] 2.5 AI Source of Truth: Record the export's hash. Blocked: this part is Proposed; until it ships, record the step's evidence as `missing` and continue.

## 3. Verify and record

- [ ] 3.1 Run a dry run with the user's inputs: Framework = SOC 2 change management; Period = 2026 Q4.
- [ ] 3.2 Run it once for real; approve each gate as the user.
- [ ] 3.3 Measure the outcomes: Controls with evidence attached; Hours of manual evidence collection per audit.
- [ ] 3.4 Confirm the run left a signed record with a task id and one workflow request counted.

# openspec/changes/wf-audit-evidence/specs/workflow-audit-evidence/spec.md

## ADDED Requirements

### Requirement: Each control cites events

Each mapped control SHALL list the signed events that support it, or say none.

#### Scenario: Each control cites events

- **WHEN** a control has no supporting events
- **THEN** the export lists it as a gap, not as passed

### Requirement: Evidence stays honest

Each step SHALL report what it saw as measured, inferred or missing, and SHALL never report missing as measured.

#### Scenario: A product part is not built

- **WHEN** a step depends on a part that is Planned or Proposed
- **THEN** the step records `missing`, names the part, and the approval card shows the gap

### Requirement: One run is one workflow request

The runner SHALL count one workflow request when the first step starts, and SHALL NOT count retries, resumes or dry runs.

#### Scenario: A gated step resumes after two days

- **WHEN** a person approves a step and the run resumes
- **THEN** the org's usage does not change