Formation v1 (#26)

* feat(phase-67): ship factions v1 flows and governance surface polish

* feat(formation): wire Phase 71 milestone vote + proposer finish flow

- add API client methods for formation.milestone.vote and formation.project.finish
- extend formation DTO with projectState, pendingMilestoneIndex, nextMilestoneIndex
- update ProposalFormation UI action gating by lifecycle state
- add/update DTO parser test coverage for new formation fields

Author: Cyber-preacher

src/lib/apiClient.ts

@@ -533,6 +533,74 @@ export async function apiFormationMilestoneRequestUnlock(input: {
   );
 }
 
+export async function apiFormationMilestoneVote(input: {
+  proposalId: string;
+  milestoneIndex: number;
+  choice: "yes" | "no" | "abstain";
+  score?: number;
+  idempotencyKey?: string;
+}): Promise<{
+  ok: true;
+  type: "formation.milestone.vote";
+  proposalId: string;
+  milestoneIndex: number;
+  choice: "yes" | "no" | "abstain";
+  counts: { yes: number; no: number; abstain: number };
+  outcome: "pending" | "accepted" | "rejected";
+  projectState:
+    | "active"
+    | "awaiting_milestone_vote"
+    | "suspended"
+    | "ready_to_finish"
+    | "completed";
+  pendingMilestoneIndex: number | null;
+  milestones: { completed: number; total: number };
+}> {
+  return await apiPost(
+    "/api/command",
+    {
+      type: "formation.milestone.vote",
+      payload: {
+        proposalId: input.proposalId,
+        milestoneIndex: input.milestoneIndex,
+        choice: input.choice,
+        ...(input.choice === "yes" && typeof input.score === "number"
+          ? { score: input.score }
+          : {}),
+      },
+      idempotencyKey: input.idempotencyKey,
+    },
+    input.idempotencyKey
+      ? { headers: { "idempotency-key": input.idempotencyKey } }
+      : undefined,
+  );
+}
+
+export async function apiFormationProjectFinish(input: {
+  proposalId: string;
+  idempotencyKey?: string;
+}): Promise<{
+  ok: true;
+  type: "formation.project.finish";
+  proposalId: string;
+  projectState: "completed";
+  milestones: { completed: number; total: number };
+}> {
+  return await apiPost(
+    "/api/command",
+    {
+      type: "formation.project.finish",
+      payload: {
+        proposalId: input.proposalId,
+      },
+      idempotencyKey: input.idempotencyKey,
+    },
+    input.idempotencyKey
+      ? { headers: { "idempotency-key": input.idempotencyKey } }
+      : undefined,
+  );
+}
+
 export async function apiProposalChamberPage(
   id: string,
 ): Promise<ChamberProposalPageDto> {

src/pages/proposals/ProposalFormation.tsx

@@ -12,8 +12,9 @@ import {
 } from "@/components/ProposalSections";
 import {
   apiFormationJoin,
-  apiFormationMilestoneRequestUnlock,
   apiFormationMilestoneSubmit,
+  apiFormationMilestoneVote,
+  apiFormationProjectFinish,
   apiProposalFormationPage,
   apiProposalTimeline,
 } from "@/lib/apiClient";
@@ -100,8 +101,32 @@ const ProposalFormation: React.FC = () => {
   };
 
   const milestones = parseRatio(project.milestones);
-  const nextMilestone =
-    milestones.total > 0 ? milestones.filled + 1 : undefined;
+  const nextMilestone = project.nextMilestoneIndex ?? undefined;
+  const pendingMilestone = project.pendingMilestoneIndex ?? undefined;
+  const isProposer =
+    Boolean(auth.address) &&
+    auth.address?.trim().toLowerCase() ===
+      project.proposer.trim().toLowerCase();
+  const canSubmitMilestone =
+    auth.authenticated &&
+    auth.eligible &&
+    !actionBusy &&
+    project.projectState === "active" &&
+    typeof nextMilestone === "number" &&
+    nextMilestone > 0 &&
+    nextMilestone <= milestones.total;
+  const canVoteMilestone =
+    auth.authenticated &&
+    auth.eligible &&
+    !actionBusy &&
+    project.projectState === "awaiting_milestone_vote" &&
+    typeof pendingMilestone === "number" &&
+    pendingMilestone > 0;
+  const canFinishProject =
+    auth.authenticated &&
+    isProposer &&
+    !actionBusy &&
+    project.projectState === "ready_to_finish";
 
   const runAction = async (fn: () => Promise<void>) => {
     setActionError(null);
@@ -156,13 +181,7 @@ const ProposalFormation: React.FC = () => {
               type="button"
               size="lg"
               variant="outline"
-              disabled={
-                !auth.authenticated ||
-                !auth.eligible ||
-                actionBusy ||
-                !nextMilestone ||
-                nextMilestone > milestones.total
-              }
+              disabled={!canSubmitMilestone}
               onClick={() =>
                 void runAction(async () => {
                   if (!id || !nextMilestone) return;
@@ -180,24 +199,53 @@ const ProposalFormation: React.FC = () => {
               type="button"
               size="lg"
               variant="outline"
-              disabled={
-                !auth.authenticated ||
-                !auth.eligible ||
-                actionBusy ||
-                !nextMilestone ||
-                nextMilestone > milestones.total
+              disabled={!canVoteMilestone}
+              onClick={() =>
+                void runAction(async () => {
+                  if (!id || !pendingMilestone) return;
+                  await apiFormationMilestoneVote({
+                    proposalId: id,
+                    milestoneIndex: pendingMilestone,
+                    choice: "yes",
+                  });
+                })
               }
+            >
+              Vote Yes M{pendingMilestone ?? "—"}
+            </Button>
+
+            <Button
+              type="button"
+              size="lg"
+              variant="outline"
+              disabled={!canVoteMilestone}
               onClick={() =>
                 void runAction(async () => {
-                  if (!id || !nextMilestone) return;
-                  await apiFormationMilestoneRequestUnlock({
+                  if (!id || !pendingMilestone) return;
+                  await apiFormationMilestoneVote({
                     proposalId: id,
-                    milestoneIndex: nextMilestone,
+                    milestoneIndex: pendingMilestone,
+                    choice: "no",
                   });
                 })
               }
             >
-              Unlock M{nextMilestone ?? "—"}
+              Vote No M{pendingMilestone ?? "—"}
+            </Button>
+
+            <Button
+              type="button"
+              size="lg"
+              variant="outline"
+              disabled={!canFinishProject}
+              onClick={() =>
+                void runAction(async () => {
+                  if (!id) return;
+                  await apiFormationProjectFinish({ proposalId: id });
+                })
+              }
+            >
+              Finish Project
             </Button>
           </div>
 

src/types/api.ts

@@ -479,6 +479,14 @@ export type FormationProposalPageDto = {
   chamber: string;
   proposer: string;
   proposerId: string;
+  projectState:
+    | "active"
+    | "awaiting_milestone_vote"
+    | "suspended"
+    | "ready_to_finish"
+    | "completed";
+  pendingMilestoneIndex: number | null;
+  nextMilestoneIndex: number | null;
   budget: string;
   timeLeft: string;
   teamSlots: string;

tests/unit/dto-parsers.test.ts

@@ -70,6 +70,9 @@ test("formation progress mapping uses ratios", () => {
     chamber: "General chamber",
     proposer: "Alice",
     proposerId: "0xalice",
+    projectState: "active",
+    pendingMilestoneIndex: null,
+    nextMilestoneIndex: 2,
     budget: "0 HMND",
     timeLeft: "—",
     teamSlots: "2/5",