[Phase 5.1] Settings page: PROOF9 defaults and workspace config

[frankbria]

Goal

Complete the Settings page with PROOF9 gate defaults and workspace configuration tabs.

Background

Gate strictness and workspace paths are currently config-file-only. Surfacing them in the UI removes the last CLI-only onboarding steps.

Scope

PROOF9 Defaults tab:

• Checkbox list of all 9 gates — check = enabled by default for new projects
• Strictness selector: strict (fail on any open non-waived REQ) vs warn (allow merge with warnings)
• Calls GET/PUT /api/v2/proof/config (add if missing)

Workspace Config tab:

• Workspace root path (text input with directory browser or manual entry)
• Default branch (text input, default main)
• Tech-stack auto-detection toggle (on/off) + manual override field
• Calls GET/PUT /api/v2/workspace/config (add if missing)

Both tabs use save/discard pattern consistent with Agent tab.

Acceptance criteria

• PROOF9 gate defaults load, toggle, and persist
• Strictness setting persists and is respected by gate runs
• Workspace config loads and persists
• npm test and npm run build pass

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

The active frontend is web-ui/ — a Next.js 16 + React 19 app using @radix-ui/react-tabs, @radix-ui/react-checkbox, @radix-ui/react-select, Tailwind, axios, and swr. The /settings route is already excluded from the PipelineProgressBar but the page itself doesn't exist yet. The backend has FastAPI routers in codeframe/ui/routers/; proof_v2.py and workspace_v2.py exist but lack GET/PUT /api/v2/proof/config and GET/PUT /api/v2/workspace/config endpoints. The 9 gates are the Gate enum in codeframe/core/proof/models.py.

Approach

Add the two missing backend config endpoints first (they're the data contract), then add TypeScript types, API client methods, and finally the Settings page with two tab components. This ordering ensures each layer has its dependency before it's needed.

---

Implementation Steps

1. Backend — PROOF9 Config Endpoint

In file:codeframe/ui/routers/proof_v2.py, add two new Pydantic models and two new route handlers at the bottom of the file:

New Pydantic models:

• ProofConfigResponse — fields: enabled_gates: list[str], strictness: Literal["strict", "warn"]
• UpdateProofConfigRequest — same fields, all optional

New endpoints:

• GET /api/v2/proof/config — reads proof config from the workspace's .codeframe/proof_config.json (create with defaults if absent). Defaults: all 9 gates enabled, strictness "strict".
• PUT /api/v2/proof/config — writes the updated config back to .codeframe/proof_config.json. Validate that all gate names in enabled_gates are valid Gate enum values.

Both endpoints accept workspace: Workspace = Depends(get_v2_workspace) and apply @rate_limit_standard().

The config file path should be workspace.state_dir / "proof_config.json". Use json.loads / json.dumps for persistence (consistent with the existing SQLite-based workspace pattern — no new dependencies needed).

---

2. Backend — Workspace Config Endpoint

In file:codeframe/ui/routers/workspace_v2.py, add two new Pydantic models and two new route handlers:

New Pydantic models:

• WorkspaceConfigResponse — fields: workspace_root: str, default_branch: str, auto_detect_tech_stack: bool, tech_stack_override: str | None
• UpdateWorkspaceConfigRequest — same fields, all optional

New endpoints:

• GET /api/v2/workspace/config — reads from .codeframe/workspace_config.json. Defaults: workspace_root = str(workspace.repo_path), default_branch = "main", auto_detect_tech_stack = True, tech_stack_override = None.
• PUT /api/v2/workspace/config — writes updated config back to .codeframe/workspace_config.json.

Note the route prefix is /api/v2/workspace/config (singular), distinct from the existing /api/v2/workspaces (plural) prefix.

---

3. Register New Routes in the FastAPI App

Locate the main FastAPI application file (likely codeframe/ui/app.py or similar) and confirm both routers are already included. The new endpoints are added to existing routers so no new router registration is needed.

---

4. Frontend — TypeScript Types

In file:web-ui/src/types/index.ts, append:

ProofConfigResponse       { enabled_gates: string[]; strictness: 'strict' | 'warn' }
UpdateProofConfigRequest  { enabled_gates?: string[]; strictness?: 'strict' | 'warn' }
WorkspaceConfigResponse   { workspace_root: string; default_branch: string; auto_detect_tech_stack: boolean; tech_stack_override: string | null }
UpdateWorkspaceConfigRequest  { workspace_root?: string; default_branch?: string; auto_detect_tech_stack?: boolean; tech_stack_override?: string | null }

Also add a constant PROOF9_GATES (ordered array of the 9 gate names matching the backend Gate enum values: unit, contract, e2e, visual, a11y, perf, sec, demo, manual) — place it in a new file:web-ui/src/lib/proof.ts constants file.

---

5. Frontend — API Client Methods

In file:web-ui/src/lib/api.ts, add a new proofConfigApi object and extend workspaceApi:

proofConfigApi:

• getConfig(workspacePath: string): Promise<ProofConfigResponse> — GET /api/v2/proof/config
• updateConfig(workspacePath: string, body: UpdateProofConfigRequest): Promise<ProofConfigResponse> — PUT /api/v2/proof/config

workspaceConfigApi:

• getConfig(workspacePath: string): Promise<WorkspaceConfigResponse> — GET /api/v2/workspace/config
• updateConfig(workspacePath: string, body: UpdateWorkspaceConfigRequest): Promise<WorkspaceConfigResponse> — PUT /api/v2/workspace/config

Both pass workspace_path as a query param, consistent with all other methods in the file.

---

6. Frontend — Settings Page Route

Create file:web-ui/src/app/settings/page.tsx as a 'use client' Next.js page component. It should:

• Read workspacePath from localStorage (same pattern used by other pages in the app — check file:web-ui/src/hooks/useWorkspacePath.ts or equivalent for the exact key name).
• Render a page heading "Settings" and a Tabs component from @radix-ui/react-tabs with three tabs: Agent, PROOF9 Defaults, Workspace Config.
• The Agent tab content can be a placeholder or re-use any existing agent settings component if one exists.

---

7. Frontend — PROOF9 Defaults Tab Component

Create file:web-ui/src/components/settings/Proof9DefaultsTab.tsx as a 'use client' component:

State:

• draft — local copy of ProofConfigResponse (initialized from SWR fetch)
• isDirty — boolean, true when draft differs from fetched data
• isSaving — boolean

Data fetching: Use useSWR with proofConfigApi.getConfig(workspacePath) as the fetcher.

UI layout:

┌─────────────────────────────────────────────────────┐
│  PROOF9 Gate Defaults                               │
│  ─────────────────────────────────────────────────  │
│  Gates enabled for new projects:                    │
│  ☑ unit      ☑ contract   ☑ e2e                    │
│  ☑ visual    ☑ a11y       ☑ perf                   │
│  ☑ sec       ☑ demo       ☑ manual                 │
│                                                     │
│  Strictness                                         │
│  ○ strict  Fail on any open non-waived REQ          │
│  ○ warn    Allow merge with warnings                │
│                                                     │
│  [Discard]  [Save Changes]                          │
└─────────────────────────────────────────────────────┘

• Each gate is a Checkbox from @radix-ui/react-checkbox (already in package.json).
• Strictness uses two radio buttons (or a Select from @radix-ui/react-select).
• Save: calls proofConfigApi.updateConfig(workspacePath, draft), then calls mutate() to revalidate SWR cache.
• Discard: resets draft to the last fetched value.
• Both buttons are disabled when !isDirty or isSaving.
• Show a sonner toast on success/error (already in package.json).

---

8. Frontend — Workspace Config Tab Component

Create file:web-ui/src/components/settings/WorkspaceConfigTab.tsx as a 'use client' component:

State: Same save/discard pattern as above, using workspaceConfigApi.getConfig.

UI layout:

┌─────────────────────────────────────────────────────┐
│  Workspace Configuration                            │
│  ─────────────────────────────────────────────────  │
│  Workspace Root Path                                │
│  [/path/to/repo                              ]      │
│                                                     │
│  Default Branch                                     │
│  [main                                       ]      │
│                                                     │
│  Tech-Stack Auto-Detection  [toggle on/off]         │
│                                                     │
│  Manual Tech-Stack Override (optional)              │
│  [Python with uv, FastAPI, pytest            ]      │
│  (disabled when auto-detect is on)                  │
│                                                     │
│  [Discard]  [Save Changes]                          │
└─────────────────────────────────────────────────────┘

• Workspace root path: <input type="text"> (no directory browser API available in Next.js without native file picker; use plain text input).
• Default branch: <input type="text">.
• Auto-detect toggle: a <button role="switch"> styled as a toggle (or a Checkbox).
• Tech-stack override: <input type="text"> disabled when auto_detect_tech_stack is true.
• Save: calls workspaceConfigApi.updateConfig(workspacePath, draft), then mutate().
• Discard: resets draft.

Use Card, Button, Label from @/components/ui/ consistent with file:web-ui/src/components/blockers/BlockerCard.tsx.

---

9. Wire Tabs into the Settings Page

Update file:web-ui/src/app/settings/page.tsx to import and render Proof9DefaultsTab and WorkspaceConfigTab inside the appropriate TabsContent panels. Use @radix-ui/react-tabs (Tabs, TabsList, TabsTrigger, TabsContent) — already in package.json.

---

10. Strictness Enforcement in Gate Runner

In file:codeframe/core/proof/runner.py, update run_proof() to:

1. Load proof_config.json from the workspace state dir (if it exists).
2. Filter the gates to run based on enabled_gates.
3. After the run, if strictness == "strict" and any open non-waived requirement remains, return a failure signal (or raise an exception that the caller can inspect). If strictness == "warn", log a warning but return success.

This ensures the strictness setting is respected by gate runs as required by the acceptance criteria.

---

Data Flow Summary

sequenceDiagram
    participant UI as Settings Page
    participant API as api.ts
    participant BE as FastAPI Router
    participant FS as .codeframe/

    UI->>API: proofConfigApi.getConfig(workspacePath)
    API->>BE: GET /api/v2/proof/config?workspace_path=...
    BE->>FS: read proof_config.json (or defaults)
    FS-->>BE: config data
    BE-->>API: ProofConfigResponse
    API-->>UI: render checkboxes + strictness

    UI->>API: proofConfigApi.updateConfig(workspacePath, draft)
    API->>BE: PUT /api/v2/proof/config
    BE->>FS: write proof_config.json
    BE-->>API: ProofConfigResponse
    API-->>UI: toast success, mutate SWR

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The active frontend is `web-ui/` — a Next.js 16 + React 19 app using `@radix-ui/react-tabs`, `@radix-ui/react-checkbox`, `@radix-ui/react-select`, Tailwind, `axios`, and `swr`. The `/settings` route is already excluded from the `PipelineProgressBar` but the page itself doesn't exist yet. The backend has FastAPI routers in `codeframe/ui/routers/`; `proof_v2.py` and `workspace_v2.py` exist but lack `GET/PUT /api/v2/proof/config` and `GET/PUT /api/v2/workspace/config` endpoints. The 9 gates are the `Gate` enum in `codeframe/core/proof/models.py`.

## Approach

Add the two missing backend config endpoints first (they're the data contract), then add TypeScript types, API client methods, and finally the Settings page with two tab components. This ordering ensures each layer has its dependency before it's needed.

---

## Implementation Steps

### 1. Backend — PROOF9 Config Endpoint

In `file:codeframe/ui/routers/proof_v2.py`, add two new Pydantic models and two new route handlers at the bottom of the file:

**New Pydantic models:**
- `ProofConfigResponse` — fields: `enabled_gates: list[str]`, `strictness: Literal["strict", "warn"]`
- `UpdateProofConfigRequest` — same fields, all optional

**New endpoints:**
- `GET /api/v2/proof/config` — reads proof config from the workspace's `.codeframe/proof_config.json` (create with defaults if absent). Defaults: all 9 gates enabled, strictness `"strict"`.
- `PUT /api/v2/proof/config` — writes the updated config back to `.codeframe/proof_config.json`. Validate that all gate names in `enabled_gates` are valid `Gate` enum values.

Both endpoints accept `workspace: Workspace = Depends(get_v2_workspace)` and apply `@rate_limit_standard()`.

The config file path should be `workspace.state_dir / "proof_config.json"`. Use `json.loads` / `json.dumps` for persistence (consistent with the existing SQLite-based workspace pattern — no new dependencies needed).

---

### 2. Backend — Workspace Config Endpoint

In `file:codeframe/ui/routers/workspace_v2.py`, add two new Pydantic models and two new route handlers:

**New Pydantic models:**
- `WorkspaceConfigResponse` — fields: `workspace_root: str`, `default_branch: str`, `auto_detect_tech_stack: bool`, `tech_stack_override: str | None`
- `UpdateWorkspaceConfigRequest` — same fields, all optional

**New endpoints:**
- `GET /api/v2/workspace/config` — reads from `.codeframe/workspace_config.json`. Defaults: `workspace_root` = `str(workspace.repo_path)`, `default_branch` = `"main"`, `auto_detect_tech_stack` = `True`, `tech_stack_override` = `None`.
- `PUT /api/v2/workspace/config` — writes updated config back to `.codeframe/workspace_config.json`.

Note the route prefix is `/api/v2/workspace/config` (singular), distinct from the existing `/api/v2/workspaces` (plural) prefix.

---

### 3. Register New Routes in the FastAPI App

Locate the main FastAPI application file (likely `codeframe/ui/app.py` or similar) and confirm both routers are already included. The new endpoints are added to existing routers so no new router registration is needed.

---

### 4. Frontend — TypeScript Types

In `file:web-ui/src/types/index.ts`, append:

```
ProofConfigResponse       { enabled_gates: string[]; strictness: 'strict' | 'warn' }
UpdateProofConfigRequest  { enabled_gates?: string[]; strictness?: 'strict' | 'warn' }
WorkspaceConfigResponse   { workspace_root: string; default_branch: string; auto_detect_tech_stack: boolean; tech_stack_override: string | null }
UpdateWorkspaceConfigRequest  { workspace_root?: string; default_branch?: string; auto_detect_tech_stack?: boolean; tech_stack_override?: string | null }
```

Also add a constant `PROOF9_GATES` (ordered array of the 9 gate names matching the backend `Gate` enum values: `unit`, `contract`, `e2e`, `visual`, `a11y`, `perf`, `sec`, `demo`, `manual`) — place it in a new `file:web-ui/src/lib/proof.ts` constants file.

---

### 5. Frontend — API Client Methods

In `file:web-ui/src/lib/api.ts`, add a new `proofConfigApi` object and extend `workspaceApi`:

**`proofConfigApi`:**
- `getConfig(workspacePath: string): Promise<ProofConfigResponse>` — `GET /api/v2/proof/config`
- `updateConfig(workspacePath: string, body: UpdateProofConfigRequest): Promise<ProofConfigResponse>` — `PUT /api/v2/proof/config`

**`workspaceConfigApi`:**
- `getConfig(workspacePath: string): Promise<WorkspaceConfigResponse>` — `GET /api/v2/workspace/config`
- `updateConfig(workspacePath: string, body: UpdateWorkspaceConfigRequest): Promise<WorkspaceConfigResponse>` — `PUT /api/v2/workspace/config`

Both pass `workspace_path` as a query param, consistent with all other methods in the file.

---

### 6. Frontend — Settings Page Route

Create `file:web-ui/src/app/settings/page.tsx` as a `'use client'` Next.js page component. It should:

- Read `workspacePath` from `localStorage` (same pattern used by other pages in the app — check `file:web-ui/src/hooks/useWorkspacePath.ts` or equivalent for the exact key name).
- Render a page heading "Settings" and a `Tabs` component from `@radix-ui/react-tabs` with three tabs: **Agent**, **PROOF9 Defaults**, **Workspace Config**.
- The Agent tab content can be a placeholder or re-use any existing agent settings component if one exists.

---

### 7. Frontend — PROOF9 Defaults Tab Component

Create `file:web-ui/src/components/settings/Proof9DefaultsTab.tsx` as a `'use client'` component:

**State:**
- `draft` — local copy of `ProofConfigResponse` (initialized from SWR fetch)
- `isDirty` — boolean, true when `draft` differs from fetched data
- `isSaving` — boolean

**Data fetching:** Use `useSWR` with `proofConfigApi.getConfig(workspacePath)` as the fetcher.

**UI layout:**

```
┌─────────────────────────────────────────────────────┐
│  PROOF9 Gate Defaults                               │
│  ─────────────────────────────────────────────────  │
│  Gates enabled for new projects:                    │
│  ☑ unit      ☑ contract   ☑ e2e                    │
│  ☑ visual    ☑ a11y       ☑ perf                   │
│  ☑ sec       ☑ demo       ☑ manual                 │
│                                                     │
│  Strictness                                         │
│  ○ strict  Fail on any open non-waived REQ          │
│  ○ warn    Allow merge with warnings                │
│                                                     │
│  [Discard]  [Save Changes]                          │
└─────────────────────────────────────────────────────┘
```

- Each gate is a `Checkbox` from `@radix-ui/react-checkbox` (already in `package.json`).
- Strictness uses two radio buttons (or a `Select` from `@radix-ui/react-select`).
- **Save**: calls `proofConfigApi.updateConfig(workspacePath, draft)`, then calls `mutate()` to revalidate SWR cache.
- **Discard**: resets `draft` to the last fetched value.
- Both buttons are disabled when `!isDirty` or `isSaving`.
- Show a `sonner` toast on success/error (already in `package.json`).

---

### 8. Frontend — Workspace Config Tab Component

Create `file:web-ui/src/components/settings/WorkspaceConfigTab.tsx` as a `'use client'` component:

**State:** Same save/discard pattern as above, using `workspaceConfigApi.getConfig`.

**UI layout:**

```
┌─────────────────────────────────────────────────────┐
│  Workspace Configuration                            │
│  ─────────────────────────────────────────────────  │
│  Workspace Root Path                                │
│  [/path/to/repo                              ]      │
│                                                     │
│  Default Branch                                     │
│  [main                                       ]      │
│                                                     │
│  Tech-Stack Auto-Detection  [toggle on/off]         │
│                                                     │
│  Manual Tech-Stack Override (optional)              │
│  [Python with uv, FastAPI, pytest            ]      │
│  (disabled when auto-detect is on)                  │
│                                                     │
│  [Discard]  [Save Changes]                          │
└─────────────────────────────────────────────────────┘
```

- Workspace root path: `<input type="text">` (no directory browser API available in Next.js without native file picker; use plain text input).
- Default branch: `<input type="text">`.
- Auto-detect toggle: a `<button role="switch">` styled as a toggle (or a `Checkbox`).
- Tech-stack override: `<input type="text">` disabled when `auto_detect_tech_stack` is `true`.
- **Save**: calls `workspaceConfigApi.updateConfig(workspacePath, draft)`, then `mutate()`.
- **Discard**: resets draft.

Use `Card`, `Button`, `Label` from `@/components/ui/` consistent with `file:web-ui/src/components/blockers/BlockerCard.tsx`.

---

### 9. Wire Tabs into the Settings Page

Update `file:web-ui/src/app/settings/page.tsx` to import and render `Proof9DefaultsTab` and `WorkspaceConfigTab` inside the appropriate `TabsContent` panels. Use `@radix-ui/react-tabs` (`Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`) — already in `package.json`.

---

### 10. Strictness Enforcement in Gate Runner

In `file:codeframe/core/proof/runner.py`, update `run_proof()` to:
1. Load `proof_config.json` from the workspace state dir (if it exists).
2. Filter the gates to run based on `enabled_gates`.
3. After the run, if `strictness == "strict"` and any open non-waived requirement remains, return a failure signal (or raise an exception that the caller can inspect). If `strictness == "warn"`, log a warning but return success.

This ensures the strictness setting is respected by gate runs as required by the acceptance criteria.

---

## Data Flow Summary

```mermaid
sequenceDiagram
    participant UI as Settings Page
    participant API as api.ts
    participant BE as FastAPI Router
    participant FS as .codeframe/

    UI->>API: proofConfigApi.getConfig(workspacePath)
    API->>BE: GET /api/v2/proof/config?workspace_path=...
    BE->>FS: read proof_config.json (or defaults)
    FS-->>BE: config data
    BE-->>API: ProofConfigResponse
    API-->>UI: render checkboxes + strictness

    UI->>API: proofConfigApi.updateConfig(workspacePath, draft)
    API->>BE: PUT /api/v2/proof/config
    BE->>FS: write proof_config.json
    BE-->>API: ProofConfigResponse
    API-->>UI: toast success, mutate SWR
```

---

Execution Information

Branch: main
Commit: 3f14270

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

🔗 Related PRs

#461 - feat(web-ui): PROOF9 requirements list, detail, and dashboard widget (#458) [merged]
#491 - feat(web-ui): surface PROOF9 gate link in execution completion banner (#469) [merged]
#496 - feat(web-ui): link failed tasks to PROOF9 gate failure for root cause (#474) [merged]
#526 - feat(web-ui): sort and filter controls for Proof requirements table [merged]
#528 - feat(web-ui): filter, search, and sort for proof evidence history table [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!