1  # X002-acdc-forge.plan.cspec
  2  # Implementation Plan for ACDC Forge Source Code Management Platform
  3  # Schema: plan-schema.cspec v1.1.0
  4  
  5  plan_metadata:
  6    component_id: X002
  7    component_ref: components/frontend/X002-acdc-forge.cspec
  8    plan_version: 1.0.0
  9    plan_status: complete
 10    created: 2026-01-15
 11    updated: 2026-01-16
 12  
 13  wave_context:
 14    topological_level: 5
 15    is_root: false
 16    upstream_components: [A007, D-GOV, ENS]
 17    downstream_components: []
 18    critical_path: false
 19    cascade_group: frontend
 20  
 21  # === PHASES ===
 22  phases:
 23    - phase_id: phase_1
 24      name: "Core Platform"
 25      status: complete
 26      tasks:
 27        - task_id: X002-T001
 28          name: "Repository structure"
 29          description: "Create acdc-forge with programs/, frontend/, backend/, mobile/"
 30          target_files:
 31            - path: acdc-forge/
 32              action: create
 33          estimate:
 34            effort: small
 35            confidence: high
 36  
 37        - task_id: X002-T002
 38          name: "On-chain programs"
 39          description: "forge.alpha and forge.delta ADL programs"
 40          target_files:
 41            - path: programs/forge_alpha/src/main.adl
 42              action: create
 43            - path: programs/forge_delta/src/main.adl
 44              action: create
 45          estimate:
 46            effort: large
 47            confidence: medium
 48  
 49        - task_id: X002-T003
 50          name: "Frontend foundation"
 51          description: "Vite + React 18 + TypeScript + Tailwind + TanStack Query"
 52          target_files:
 53            - path: frontend/package.json
 54              action: create
 55            - path: frontend/src/App.tsx
 56              action: create
 57          estimate:
 58            effort: medium
 59            confidence: high
 60  
 61        - task_id: X002-T004
 62          name: "Backend foundation"
 63          description: "FastAPI thin cache + Radicle proxy"
 64          target_files:
 65            - path: backend/main.py
 66              action: create
 67            - path: backend/services/radicle.py
 68              action: create
 69          estimate:
 70            effort: medium
 71            confidence: high
 72  
 73        - task_id: X002-T005
 74          name: "Wallet authentication"
 75          description: "SDK integration for wallet connect"
 76          target_files:
 77            - path: frontend/src/components/auth/WalletConnect.tsx
 78              action: create
 79            - path: frontend/src/services/wallet.ts
 80              action: create
 81          estimate:
 82            effort: medium
 83            confidence: high
 84  
 85      deliverables:
 86        - deliverable_id: X002-D001
 87          name: "Core platform foundation"
 88          type: code
 89          verification: "Frontend builds, backend starts, programs compile"
 90  
 91      success_criteria:
 92        - "Frontend builds with npm run build"
 93        - "Backend starts with uvicorn"
 94        - "ADL programs compile"
 95        - "Wallet connect flow works"
 96  
 97    - phase_id: phase_2
 98      name: "Voting System"
 99      status: complete
100      blocked_by:
101        - dependency_ref: X002.phase_1
102          reason: "Requires core platform"
103          wait_for: complete
104  
105      tasks:
106        - task_id: X002-T006
107          name: "PR sponsorship workflow"
108          description: "Tech Governor can sponsor PRs for voting"
109          target_files:
110            - path: frontend/src/components/pr/SponsorButton.tsx
111              action: create
112          estimate:
113            effort: medium
114            confidence: high
115  
116        - task_id: X002-T007
117          name: "Vote lifecycle"
118          description: "7-day voting period with deadline tracking"
119          target_files:
120            - path: frontend/src/components/voting/VotePanel.tsx
121              action: create
122            - path: frontend/src/components/voting/VoteProgress.tsx
123              action: create
124          estimate:
125            effort: large
126            confidence: high
127  
128        - task_id: X002-T008
129          name: "Flag system"
130          description: "Security, political, economic flags for PRs"
131          target_files:
132            - path: frontend/src/components/pr/FlagSelector.tsx
133              action: create
134          estimate:
135            effort: small
136            confidence: high
137  
138      deliverables:
139        - deliverable_id: X002-D002
140          name: "Voting system"
141          type: code
142          verification: "Full vote lifecycle works"
143  
144      success_criteria:
145        - "PR can be sponsored"
146        - "7-day countdown displays"
147        - "Votes can be cast with flags"
148        - "67% threshold enforced"
149  
150    - phase_id: phase_3
151      name: "Governance Integration"
152      status: complete
153      blocked_by:
154        - dependency_ref: X002.phase_2
155          reason: "Requires voting system"
156          wait_for: complete
157  
158      tasks:
159        - task_id: X002-T009
160          name: "Auto-proposal generation"
161          description: "Create governance proposals from merged PRs"
162          target_files:
163            - path: frontend/src/services/governance.ts
164              action: create
165          estimate:
166            effort: medium
167            confidence: medium
168  
169        - task_id: X002-T010
170          name: "Executive summary workflow"
171          description: "Sponsor writes summary for governance proposal"
172          target_files:
173            - path: frontend/src/components/pr/ExecutiveSummary.tsx
174              action: create
175          estimate:
176            effort: small
177            confidence: high
178  
179        - task_id: X002-T011
180          name: "Resubmission cooldown"
181          description: "7-day cooldown, 90% override"
182          target_files:
183            - path: frontend/src/services/cooldown.ts
184              action: create
185          estimate:
186            effort: small
187            confidence: high
188  
189      deliverables:
190        - deliverable_id: X002-D003
191          name: "Governance integration"
192          type: code
193          verification: "Merged PRs create governance proposals"
194  
195      success_criteria:
196        - "Proposals auto-created on merge"
197        - "Executive summary captures"
198        - "Cooldown enforced"
199  
200    - phase_id: phase_4
201      name: "Delta Integration"
202      status: complete
203      blocked_by:
204        - dependency_ref: X002.phase_3
205          reason: "Requires governance integration"
206          wait_for: complete
207  
208      tasks:
209        - task_id: X002-T012
210          name: "DX staking verification"
211          description: "Verify 10k+ DX stake for Code Governors"
212          target_files:
213            - path: frontend/src/services/staking.ts
214              action: create
215          estimate:
216            effort: medium
217            confidence: medium
218  
219        - task_id: X002-T013
220          name: "Delta Code Governor registration"
221          description: "Registration flow for DX stakers"
222          target_files:
223            - path: frontend/src/components/auth/DeltaRegistration.tsx
224              action: create
225          estimate:
226            effort: medium
227            confidence: high
228  
229        - task_id: X002-T014
230          name: "Parallel voting"
231          description: "Shared components need both chain approvals"
232          target_files:
233            - path: frontend/src/components/voting/ParallelVoting.tsx
234              action: create
235          estimate:
236            effort: large
237            confidence: medium
238  
239      deliverables:
240        - deliverable_id: X002-D004
241          name: "Delta integration"
242          type: code
243          verification: "Delta governors can vote"
244  
245      success_criteria:
246        - "DX stake verified"
247        - "50-voter minimum enforced"
248        - "Parallel voting works"
249  
250    - phase_id: phase_5
251      name: "Rollback System"
252      status: complete
253      blocked_by:
254        - dependency_ref: X002.phase_4
255          reason: "Requires Delta integration"
256          wait_for: complete
257  
258      tasks:
259        - task_id: X002-T015
260          name: "Safe rollback calculation"
261          description: "Determine which PRs can be safely rolled back"
262          target_files:
263            - path: frontend/src/services/rollback.ts
264              action: create
265          estimate:
266            effort: large
267            confidence: medium
268  
269        - task_id: X002-T016
270          name: "Dependency tracking"
271          description: "Track which PRs depend on others"
272          target_files:
273            - path: frontend/src/services/dependencies.ts
274              action: create
275          estimate:
276            effort: medium
277            confidence: medium
278  
279        - task_id: X002-T017
280          name: "Rollback UI"
281          description: "UI for proposing and viewing rollbacks"
282          target_files:
283            - path: frontend/src/components/rollback/RollbackPanel.tsx
284              action: create
285          estimate:
286            effort: medium
287            confidence: high
288  
289      deliverables:
290        - deliverable_id: X002-D005
291          name: "Rollback system"
292          type: code
293          verification: "Safe rollbacks can be proposed"
294  
295      success_criteria:
296        - "Safe rollbacks calculated"
297        - "Dependencies tracked"
298        - "Rollback UI functional"
299  
300    - phase_id: phase_6
301      name: "Emergency Systems"
302      status: complete
303      blocked_by:
304        - dependency_ref: X002.phase_5
305          reason: "Requires rollback system"
306          wait_for: complete
307  
308      tasks:
309        - task_id: X002-T018
310          name: "DEQ keypair generation"
311          description: "Generate and store emergency signing keypairs"
312          target_files:
313            - path: frontend/src/services/emergency.ts
314              action: create
315            - path: frontend/src/types/emergency.ts
316              action: create
317          estimate:
318            effort: medium
319            confidence: medium
320  
321        - task_id: X002-T019
322          name: "Offline signing tool"
323          description: "CLI commands for air-gapped signing"
324          target_files:
325            - path: frontend/src/components/emergency/OfflineSigningTool.tsx
326              action: create
327          estimate:
328            effort: large
329            confidence: medium
330  
331        - task_id: X002-T020
332          name: "Emergency UI"
333          description: "EmergencyPanel, DEQMemberList, ActionHistory"
334          target_files:
335            - path: frontend/src/components/emergency/EmergencyPanel.tsx
336              action: create
337            - path: frontend/src/components/emergency/DEQMemberList.tsx
338              action: create
339            - path: frontend/src/components/emergency/EmergencyActionHistory.tsx
340              action: create
341          estimate:
342            effort: medium
343            confidence: high
344  
345      deliverables:
346        - deliverable_id: X002-D006
347          name: "Emergency systems"
348          type: code
349          verification: "DEQ signing flow works"
350  
351      success_criteria:
352        - "DEQ keypairs generated"
353        - "Offline signing tool functional"
354        - "Emergency UI complete"
355        - "commit: 78b590b"
356  
357    - phase_id: phase_7
358      name: "Polish"
359      status: complete
360      blocked_by:
361        - dependency_ref: X002.phase_6
362          reason: "Requires emergency systems"
363          wait_for: complete
364  
365      tasks:
366        - task_id: X002-T021
367          name: "Notifications system"
368          description: "WebSocket notifications with preferences"
369          target_files:
370            - path: frontend/src/types/notification.ts
371              action: create
372            - path: frontend/src/services/notification.ts
373              action: create
374            - path: frontend/src/components/notifications/NotificationBell.tsx
375              action: create
376            - path: frontend/src/components/notifications/NotificationCenter.tsx
377              action: create
378          estimate:
379            effort: medium
380            confidence: high
381  
382        - task_id: X002-T022
383          name: "Analytics dashboard"
384          description: "Metrics, charts, activity tracking"
385          target_files:
386            - path: frontend/src/types/analytics.ts
387              action: create
388            - path: frontend/src/services/analytics.ts
389              action: create
390            - path: frontend/src/components/analytics/Charts.tsx
391              action: create
392            - path: frontend/src/components/analytics/AnalyticsDashboard.tsx
393              action: create
394          estimate:
395            effort: medium
396            confidence: high
397  
398        - task_id: X002-T023
399          name: "Mobile app"
400          description: "React Native + Expo with full functionality"
401          target_files:
402            - path: mobile/package.json
403              action: create
404            - path: mobile/app/_layout.tsx
405              action: create
406            - path: mobile/app/(tabs)/index.tsx
407              action: create
408            - path: mobile/app/vote/[id].tsx
409              action: create
410            - path: mobile/src/store/auth.ts
411              action: create
412          estimate:
413            effort: large
414            confidence: medium
415  
416      deliverables:
417        - deliverable_id: X002-D007
418          name: "Notifications and analytics"
419          type: code
420          verification: "Notifications work, analytics display"
421  
422        - deliverable_id: X002-D008
423          name: "Mobile app"
424          type: code
425          verification: "Expo app runs on iOS/Android"
426  
427      success_criteria:
428        - "Notifications with WebSocket"
429        - "Analytics dashboard with charts"
430        - "Mobile app with full functionality"
431        - "commit: 85b712c"
432  
433  # === PARALLEL WORKSTREAMS ===
434  parallel_workstreams:
435    testing:
436      strategy: test_alongside
437      coverage_targets:
438        unit_minimum: 80
439        integration_required: true
440      per_phase_requirements:
441        - phase_ref: phase_1
442          unit_tests: [wallet_auth, radicle_proxy]
443          integration_tests: [full_auth_flow]
444        - phase_ref: phase_2
445          unit_tests: [vote_casting, threshold_calc]
446          integration_tests: [vote_lifecycle]
447      ci_test_gates:
448        - gate_id: frontend_build
449          command: "npm run build"
450          required: true
451        - gate_id: frontend_lint
452          command: "npm run lint"
453          required: true
454  
455    ci_workflows:
456      affected_workflows:
457        - workflow_file: .forgejo/workflows/ci.yml
458          repo: acdc-forge
459          triggers: [phase_1]
460      required_ci_checks:
461        - check_name: build
462          check_type: build
463          blocking: true
464        - check_name: lint
465          check_type: lint
466          blocking: true
467  
468    documentation:
469      cspec_update_policy: on_interface_change
470      component_cspec_updates:
471        - cspec_file: components/frontend/X002-acdc-forge.cspec
472          update_triggers:
473            - phase_ref: phase_7
474              fields_to_update: [status, implementation_notes]
475              description: "Mark complete with implementation details"
476      session_logging:
477        required: true
478        log_location: sessions/
479        log_format: cspec
480        log_triggers: [phase_complete, major_decision]
481      changelog_policy:
482        update_frequency: per_phase
483        required_fields: [version, date, type, description]
484  
485  # === INTERFACE COMMITMENTS ===
486  interface_commitments:
487    provides:
488      - interface_id: interface_forge_voting
489        name: "Forge Voting API"
490        stability: stable
491        available_from: phase_2
492        stable_from: phase_4
493        consumers: [A007, D-GOV]
494  
495      - interface_id: interface_forge_proposals
496        name: "Forge Auto-Proposal Generation"
497        stability: stable
498        available_from: phase_3
499        stable_from: phase_4
500        consumers: [A007, D-GOV]
501  
502    requires:
503      - interface_ref: A007.interface_governance
504        minimum_stability: stable
505        required_from: phase_3
506  
507      - interface_ref: ENS.interface_name_service
508        minimum_stability: stable
509        required_from: phase_1
510  
511  # === REPOSITORY TARGETS ===
512  repository_targets:
513    primary_repo:
514      name: acdc-forge
515      branch_strategy: feature_branch
516  
517    file_manifest:
518      - path: programs/forge_alpha/src/main.adl
519        action: create
520        purpose: "Alpha chain voting program"
521        phase: phase_1
522      - path: programs/forge_delta/src/main.adl
523        action: create
524        purpose: "Delta chain voting program"
525        phase: phase_1
526      - path: frontend/src/App.tsx
527        action: create
528        purpose: "Main React application"
529        phase: phase_1
530      - path: backend/main.py
531        action: create
532        purpose: "FastAPI backend"
533        phase: phase_1
534      - path: mobile/app/_layout.tsx
535        action: create
536        purpose: "Mobile app root layout"
537        phase: phase_7
538  
539  # === COMPLEXITY ASSESSMENT ===
540  complexity_assessment:
541    overall_complexity: high
542  
543    risk_summary:
544      - risk_id: RISK-001
545        description: "On-chain voting correctness"
546        likelihood: low
547        impact: critical
548        mitigation: "Extensive testing, formal verification"
549  
550      - risk_id: RISK-002
551        description: "DEQ offline signing security"
552        likelihood: low
553        impact: critical
554        mitigation: "Air-gap design, multi-sig requirement"
555  
556      - risk_id: RISK-003
557        description: "Mobile app compatibility"
558        likelihood: medium
559        impact: medium
560        mitigation: "Expo managed workflow, gradual rollout"
561  
562  # === DEPENDENCIES SUMMARY ===
563  dependencies_summary:
564    blocks: []
565    blocked_by: [A007, D-GOV, ENS]
566    parallel_candidates: []
567  
568  # === CHANGELOG ===
569  changelog:
570    - version: 1.0.0
571      date: 2026-01-16
572      type: complete
573      description: "Full MVP implementation complete - all 7 phases"
574  
575    - version: 0.7.0
576      date: 2026-01-16
577      type: status_update
578      description: "Phase 7 complete - notifications, analytics, mobile app"
579  
580    - version: 0.6.0
581      date: 2026-01-16
582      type: status_update
583      description: "Phase 6 complete - emergency systems, DEQ, offline signing"
584  
585    - version: 0.1.0
586      date: 2026-01-15
587      type: initial
588      description: "Initial plan from X002 specification"