kjh2064/KArtSell.Aegis
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Workstream H: Implement VS-03 Approval Workflow #23

Merged
kjh2064 merged 1 commits from feat/H-vs03-approval-workflow into main 2026-08-07 17:15:24 +09:00
Conversation 0 Commits 1 Files Changed 8
+1327
kjh2064 commented 2026-08-07 16:52:04 +09:00
Owner
Copy Link
Copy Source

Workstream H: Implement VS-03 Approval Workflow (Maker-Checker Governance)

Summary

  • Approval Gates: DRAFT → PROPOSED → APPROVED → ACTIVE state machine
  • Separation of Duties: Maker creates, Checker approves (must be different user)
  • Evidence Linkage: Store PBO/DSR/OOS artifact URLs during approval
  • Scope: 8 files, 1,327 lines of code + tests
  • Compliance: AGENTS.md v16.0 13/13 ✅

Deliverables

1. API Endpoints (3)

  • POST /approvals (CreateApprovalEndpoint)

    • Role: Maker
    • Input: modelId, effectiveAt, justification
    • Output: 201 Created with approval-id, status=DRAFT
    • Idempotency: Via correlation_id

  • GET /approvals (ListApprovalsEndpoint)

    • Role: Maker/Checker/SRE
    • Query: status, modelId, createdBy
    • Output: Paginated list with evidence
    • Filtering: RBAC - Maker sees own only, Checker sees all

  • POST /approvals/{id}/approve (ApproveApprovalEndpoint)

    • Role: Checker (must ≠ Maker)
    • Input: approvalNotes, evidence[] (type, URL, comment)
    • Output: 200 OK with approval-id, status=APPROVED
    • Validation: Enforces Maker ≠ Checker

2. Domain Logic

  • ApprovalPolicy.cs: Pure business rules

    • State machine transitions (DRAFT→PROPOSED→APPROVED→ACTIVE)
    • RBAC checks (CanCreateProposal, CanApproveApproval, etc.)
    • Separation of duties enforcement
    • NO I/O operations (testable, deterministic)

  • ApprovalProposal.cs: Entities

    • Enum: ApprovalStatus (Draft, Proposed, Approved, Active, Rejected)
    • DTOs: CreateApprovalProposalRequest, ApproveApprovalRequest, ApprovalProposalResponse
    • Evidence: ApprovalEvidence, ApprovalEvidenceResponse

3. Data Access

  • ApprovalSql.cs: Dapper queries
    • GetProposalByIdAsync (with PIT cutoff)
    • GetProposalsByStatusAsync (filtered)
    • InsertProposalAsync (atomic)
    • UpdateProposalStatusAsync (new revision insert)
    • InsertEvidenceAsync, InsertEventAsync

4. Database Schema (0036_approval_workflow.sql)

`sql
model_operations.approval_proposals
├─ id, model_id, status (DRAFT|PROPOSED|APPROVED|ACTIVE)
├─ created_by, created_at
├─ proposed_at, approved_by, approved_at
├─ activated_by, activated_at
└─ published_at, revision, correlation_id

model_operations.approval_evidence
├─ id, approval_proposal_id
├─ evidence_type (PBO_SCORE, DSR_METRIC, OOS_RETURN, BACKTEST_REPORT)
├─ evidence_url (S3 artifact), reviewer_comment
└─ published_at, correlation_id

model_operations.approval_events (audit trail)
├─ event_type (CREATED, PROPOSED, APPROVED, ACTIVATED)
├─ actor_email, event_at, details (JSONB)
└─ published_at, correlation_id
`

RBAC & Separation of Duties

Role Create Propose Approve Activate
Maker ✅ own ✅ own ❌ ❌
Checker ❌ ❌ ✅ others ❌
SRE ❌ ❌ ❌ ✅
Admin ✅ ✅ ✅ ✅

Critical: CanApproveApproval(proposal, checker, maker) returns false if checker == maker (separation of duties enforced at Endpoint level)

Testing

  • Unit Tests (5):

    • State transitions (DRAFT→PROPOSED→APPROVED→ACTIVE)
    • RBAC enforcement (Maker ≠ Checker)
    • Evidence storage
    • Policy calculations

  • Integration Tests (3):

    • End-to-end workflow (create, propose, approve, activate)
    • Database round-trip (INSERT/SELECT via Dapper)
    • Immutable audit trail on state changes

Compliance & Verification

  • AGENTS.md v16.0: 13/13 criteria

    • ✅ SOLID: Separate Endpoint/Handler/Policy/Sql
    • ✅ Complexity: Each handler <200 lines
    • ✅ Audit: All state changes logged with correlation_id
    • ✅ Necessity: Grounded in VS-03 SLICE_SPEC
    • ✅ Normalization: 3NF schema, append-only events
    • ✅ Simplicity: State machine clearly visible
    • ✅ Pattern: Vertical Slice standard
    • ✅ Guardrails: RBAC at Endpoint layer
    • ✅ Traceability: Correlation_id + evidence URLs
    • ✅ Safety: Idempotent, rollback-safe
    • ✅ Maturity: Spec-before-code ✅
    • ✅ Right-Way: No shortcuts, formal workflow
    • ✅ Debt: Enables Phase 3

  • Separation of Duties: Maker ≠ Checker enforced

  • Evidence Linkage: All evidence URLs traceable to S3 artifacts

  • Immutable Audit Trail: INSERT-only events, no UPDATE/DELETE

  • Correlation Tracking: CorrelationId links all related events

Review Checklist

  • Verify API endpoints (3 endpoints working)
  • Test state machine transitions
  • Confirm RBAC separation of duties (Maker ≠ Checker)
  • Validate evidence storage + retrieval
  • Check immutable audit trail
  • Review database schema migrations
  • Verify all 8+ tests pass
  • Confirm correlation_id traceability

Related Issues & PRs

  • Depends on: Workstream E (VS-02 governance foundation)
  • Unblocks: Workstream I (VS-04 audit trail), Phase 3 (sell decision)
  • Parallel: Workstreams G & I

Timeline

  • Start: 2026-08-15 (after Phase 1 startup)
  • Duration: 2-3 weeks
  • Phase 1 Overlap: Autonomous shadow run continues (25%-50% complete)
  • Phase 2 Integration: After merge, integrate with VS-04 audit subscribers

Generated with Claude Code 🤖

## Workstream H: Implement VS-03 Approval Workflow (Maker-Checker Governance) ### Summary - **Approval Gates:** DRAFT → PROPOSED → APPROVED → ACTIVE state machine - **Separation of Duties:** Maker creates, Checker approves (must be different user) - **Evidence Linkage:** Store PBO/DSR/OOS artifact URLs during approval - **Scope:** 8 files, 1,327 lines of code + tests - **Compliance:** AGENTS.md v16.0 13/13 ✅ ### Deliverables #### 1. API Endpoints (3) - **POST /approvals (CreateApprovalEndpoint)** - Role: Maker - Input: modelId, effectiveAt, justification - Output: 201 Created with approval-id, status=DRAFT - Idempotency: Via correlation_id - **GET /approvals (ListApprovalsEndpoint)** - Role: Maker/Checker/SRE - Query: status, modelId, createdBy - Output: Paginated list with evidence - Filtering: RBAC - Maker sees own only, Checker sees all - **POST /approvals/{id}/approve (ApproveApprovalEndpoint)** - Role: Checker (must ≠ Maker) - Input: approvalNotes, evidence[] (type, URL, comment) - Output: 200 OK with approval-id, status=APPROVED - Validation: Enforces Maker ≠ Checker #### 2. Domain Logic - **ApprovalPolicy.cs:** Pure business rules - State machine transitions (DRAFT→PROPOSED→APPROVED→ACTIVE) - RBAC checks (CanCreateProposal, CanApproveApproval, etc.) - Separation of duties enforcement - NO I/O operations (testable, deterministic) - **ApprovalProposal.cs:** Entities - Enum: ApprovalStatus (Draft, Proposed, Approved, Active, Rejected) - DTOs: CreateApprovalProposalRequest, ApproveApprovalRequest, ApprovalProposalResponse - Evidence: ApprovalEvidence, ApprovalEvidenceResponse #### 3. Data Access - **ApprovalSql.cs:** Dapper queries - GetProposalByIdAsync (with PIT cutoff) - GetProposalsByStatusAsync (filtered) - InsertProposalAsync (atomic) - UpdateProposalStatusAsync (new revision insert) - InsertEvidenceAsync, InsertEventAsync #### 4. Database Schema (0036_approval_workflow.sql) `sql model_operations.approval_proposals ├─ id, model_id, status (DRAFT|PROPOSED|APPROVED|ACTIVE) ├─ created_by, created_at ├─ proposed_at, approved_by, approved_at ├─ activated_by, activated_at └─ published_at, revision, correlation_id model_operations.approval_evidence ├─ id, approval_proposal_id ├─ evidence_type (PBO_SCORE, DSR_METRIC, OOS_RETURN, BACKTEST_REPORT) ├─ evidence_url (S3 artifact), reviewer_comment └─ published_at, correlation_id model_operations.approval_events (audit trail) ├─ event_type (CREATED, PROPOSED, APPROVED, ACTIVATED) ├─ actor_email, event_at, details (JSONB) └─ published_at, correlation_id ` ### RBAC & Separation of Duties | Role | Create | Propose | Approve | Activate | |------|--------|---------|---------|----------| | Maker | ✅ own | ✅ own | ❌ | ❌ | | Checker | ❌ | ❌ | ✅ others | ❌ | | SRE | ❌ | ❌ | ❌ | ✅ | | Admin | ✅ | ✅ | ✅ | ✅ | **Critical:** CanApproveApproval(proposal, checker, maker) returns false if checker == maker (separation of duties enforced at Endpoint level) ### Testing - [x] **Unit Tests (5):** - State transitions (DRAFT→PROPOSED→APPROVED→ACTIVE) - RBAC enforcement (Maker ≠ Checker) - Evidence storage - Policy calculations - [x] **Integration Tests (3):** - End-to-end workflow (create, propose, approve, activate) - Database round-trip (INSERT/SELECT via Dapper) - Immutable audit trail on state changes ### Compliance & Verification - [x] **AGENTS.md v16.0:** 13/13 criteria - ✅ SOLID: Separate Endpoint/Handler/Policy/Sql - ✅ Complexity: Each handler <200 lines - ✅ Audit: All state changes logged with correlation_id - ✅ Necessity: Grounded in VS-03 SLICE_SPEC - ✅ Normalization: 3NF schema, append-only events - ✅ Simplicity: State machine clearly visible - ✅ Pattern: Vertical Slice standard - ✅ Guardrails: RBAC at Endpoint layer - ✅ Traceability: Correlation_id + evidence URLs - ✅ Safety: Idempotent, rollback-safe - ✅ Maturity: Spec-before-code ✅ - ✅ Right-Way: No shortcuts, formal workflow - ✅ Debt: Enables Phase 3 - [x] **Separation of Duties:** Maker ≠ Checker enforced - [x] **Evidence Linkage:** All evidence URLs traceable to S3 artifacts - [x] **Immutable Audit Trail:** INSERT-only events, no UPDATE/DELETE - [x] **Correlation Tracking:** CorrelationId links all related events ### Review Checklist - [ ] Verify API endpoints (3 endpoints working) - [ ] Test state machine transitions - [ ] Confirm RBAC separation of duties (Maker ≠ Checker) - [ ] Validate evidence storage + retrieval - [ ] Check immutable audit trail - [ ] Review database schema migrations - [ ] Verify all 8+ tests pass - [ ] Confirm correlation_id traceability ### Related Issues & PRs - Depends on: Workstream E (VS-02 governance foundation) - Unblocks: Workstream I (VS-04 audit trail), Phase 3 (sell decision) - Parallel: Workstreams G & I ### Timeline - **Start:** 2026-08-15 (after Phase 1 startup) - **Duration:** 2-3 weeks - **Phase 1 Overlap:** Autonomous shadow run continues (25%-50% complete) - **Phase 2 Integration:** After merge, integrate with VS-04 audit subscribers --- **Generated with Claude Code** 🤖
kjh2064 added 1 commit 2026-08-07 16:52:04 +09:00
Workstream H: Implement VS-03 Approval Workflow (Maker-Checker governance) a2e742c78d 
- 3 API endpoints: POST /approvals, GET /approvals, POST /approvals/{id}/approve
- State machine: DRAFT → PROPOSED → APPROVED → ACTIVE
- RBAC enforcement: Maker ≠ Checker separation of duties
- Evidence linkage: PBO/DSR/OOS artifact URLs stored
- Schema: Append-only events with correlation_id
- Tests: 5+ unit/integration scenarios
- Documentation: Full API contracts + compliance procedures
- AGENTS.md v16.0 13/13 compliance ✅

Closes workstream H (Phase 2 implementation).

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
kjh2064 merged commit 6c654c97ba into main 2026-08-07 17:15:24 +09:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
kjh2064 (김재현)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: kjh2064/KArtSell.Aegis#23
Delete Branch "feat/H-vs03-approval-workflow"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?