docs(phase-5): complete Employee Design phase execution
This commit is contained in:
@@ -122,7 +122,7 @@ Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5
|
||||
| 2. Agent Features | 6/6 | Complete | 2026-03-24 |
|
||||
| 3. Operator Experience | 5/5 | Complete | 2026-03-24 |
|
||||
| 4. RBAC | 3/3 | Complete | 2026-03-24 |
|
||||
| 5. Employee Design | 4/4 | Complete | 2026-03-25 |
|
||||
| 5. Employee Design | 4/4 | Complete | 2026-03-25 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ milestone: v1.0
|
||||
milestone_name: milestone
|
||||
status: completed
|
||||
stopped_at: Completed 05-04 RBAC gap closure and wizard error fix
|
||||
last_updated: "2026-03-25T02:52:23.275Z"
|
||||
last_updated: "2026-03-25T02:54:38.350Z"
|
||||
last_activity: 2026-03-23 — Completed 03-02 onboarding wizard, Slack OAuth, BYO API keys
|
||||
progress:
|
||||
total_phases: 5
|
||||
|
||||
186
.planning/phases/05-employee-design/05-VERIFICATION.md
Normal file
186
.planning/phases/05-employee-design/05-VERIFICATION.md
Normal file
@@ -0,0 +1,186 @@
|
||||
---
|
||||
phase: 05-employee-design
|
||||
verified: 2026-03-24T12:00:00Z
|
||||
status: human_needed
|
||||
score: 11/11 must-haves verified
|
||||
re_verification:
|
||||
previous_status: gaps_found
|
||||
previous_score: 9/11
|
||||
gaps_closed:
|
||||
- "Only platform_admin and customer_admin can access creation paths"
|
||||
- "Wizard auto-generates system prompt (hidden from user) with AI transparency clause"
|
||||
gaps_remaining: []
|
||||
regressions: []
|
||||
human_verification:
|
||||
- test: "Verify visual appearance of three-option entry screen"
|
||||
expected: "Templates card has Recommended badge and primary border emphasis; all three cards render correctly at mobile and desktop widths"
|
||||
why_human: "CSS layout and visual emphasis cannot be verified programmatically"
|
||||
- test: "Verify template preview dialog shows full configuration"
|
||||
expected: "Preview dialog shows persona paragraph, escalation rules list, model preference; Deploy Now button inside dialog also triggers deploy"
|
||||
why_human: "Dialog open/close behavior and rendering requires visual inspection"
|
||||
- test: "Verify wizard step navigation works correctly with Back button"
|
||||
expected: "Back button navigates to previous step and pre-fills data entered in that step"
|
||||
why_human: "State retention across back-navigation requires interactive testing"
|
||||
- test: "Verify channels step empty state message"
|
||||
expected: "When no channels are connected, step-channels shows info message and still allows proceeding"
|
||||
why_human: "Requires dev environment with no channels configured"
|
||||
---
|
||||
|
||||
# Phase 5: Employee Design Verification Report
|
||||
|
||||
**Phase Goal:** Operators and customer admins can create AI employees through a guided wizard or deploy from pre-built templates
|
||||
**Verified:** 2026-03-24
|
||||
**Status:** human_needed — all automated checks pass; 4 items require human verification
|
||||
**Re-verification:** Yes — after gap closure (05-04 fixes applied)
|
||||
|
||||
---
|
||||
|
||||
## Re-Verification Summary
|
||||
|
||||
Previous score: 9/11 (gaps_found)
|
||||
Current score: 11/11 (human_needed)
|
||||
|
||||
### Gaps Closed
|
||||
|
||||
**Gap 1 — Frontend RBAC (EMPL-04):** Closed. `/agents/new` added to `CUSTOMER_OPERATOR_RESTRICTED` array in `proxy.ts` at line 23. The existing `startsWith(`${prefix}/`)` logic at line 59 extends this restriction to all three sub-paths (`/agents/new/templates`, `/agents/new/wizard`, `/agents/new/advanced`) without requiring them to be listed individually. The New Employee button in `agents/page.tsx` is also hidden via `{role && role !== "customer_operator" && ...}` at line 77 — both UI and route layers now enforce the restriction.
|
||||
|
||||
**Gap 2 — Wizard deploy error handling:** Closed. `step-review.tsx` catch block now re-throws (`throw err` at line 52) after logging. Because `mutateAsync` throws on rejection and the error propagates out of the catch block, TanStack Query's mutation state sets `isError = true` and populates `error`. The error display div at line 142 (`{createAgent.error && ...}`) will now render when deploy fails.
|
||||
|
||||
### Regressions
|
||||
|
||||
None. All 9 previously verified truths remain intact — spot-checked:
|
||||
- `templates.py` RBAC guards and endpoints unchanged
|
||||
- `system-prompt-builder.ts` transparency clause present
|
||||
- `useTemplates` and `useDeployTemplate` hooks at lines 404 and 411 of `queries.ts` unchanged
|
||||
|
||||
---
|
||||
|
||||
## Goal Achievement
|
||||
|
||||
### Observable Truths
|
||||
|
||||
| # | Truth | Status | Evidence |
|
||||
|---|-------|--------|---------|
|
||||
| 1 | GET /api/portal/templates returns 7+ pre-built agent templates | VERIFIED | templates.py list_templates; migration 007 seeds 7 templates |
|
||||
| 2 | POST /api/portal/templates/{id}/deploy creates independent agent snapshot with is_active=True | VERIFIED | deploy_template creates Agent snapshot, no FK back to template |
|
||||
| 3 | Template deploy is blocked for customer_operator (403) | VERIFIED | require_tenant_admin called; integration test test_deploy_template_rbac confirms 403 |
|
||||
| 4 | System prompt builder produces coherent prompt with AI transparency clause | VERIFIED | build_system_prompt() always appends AI_TRANSPARENCY_CLAUSE; 17 unit tests pass |
|
||||
| 5 | New Employee button presents three options: Templates, Guided Setup, Advanced | VERIFIED | /agents/new/page.tsx renders three Cards with correct labels, icons, and routes |
|
||||
| 6 | Template gallery shows card grid with name, role, tools — one-click deploy creates agent | VERIFIED | TemplateGallery uses useTemplates hook, Deploy button calls useDeployTemplate mutation |
|
||||
| 7 | Wizard walks through 5 steps: Role, Persona, Tools, Channels, Escalation + Review | VERIFIED | EmployeeWizard renders all 6 step components (5 steps + review), all substantive |
|
||||
| 8 | Wizard auto-generates system prompt (hidden from user) with AI transparency clause | VERIFIED | buildSystemPrompt called in step-review.tsx; catch block re-throws so createAgent.error surfaces to user |
|
||||
| 9 | Advanced option opens existing Agent Designer with full control | VERIFIED | /agents/new/advanced/page.tsx renders AgentDesigner component in create mode |
|
||||
| 10 | Wizard-created and template-deployed agents appear in Agent Designer for editing | VERIFIED | Both paths redirect to /agents/{id}?tenant={tenantId} on success |
|
||||
| 11 | Only platform_admin and customer_admin can access creation paths | VERIFIED | proxy.ts CUSTOMER_OPERATOR_RESTRICTED includes /agents/new (covers all sub-paths via startsWith); agents/page.tsx New Employee button gated on role !== "customer_operator" |
|
||||
|
||||
**Score:** 11/11 truths verified
|
||||
|
||||
---
|
||||
|
||||
## Gap Closure Detail
|
||||
|
||||
### Gap 1: proxy.ts — /agents/new restriction
|
||||
|
||||
**File:** `packages/portal/proxy.ts`
|
||||
|
||||
Before (previous state): `/agents/new` absent from `CUSTOMER_OPERATOR_RESTRICTED`. Operators could navigate into all three creation sub-paths and only learned of the restriction when the final API call returned 403.
|
||||
|
||||
After (current state): `/agents/new` present in `CUSTOMER_OPERATOR_RESTRICTED` at line 23:
|
||||
|
||||
```typescript
|
||||
const CUSTOMER_OPERATOR_RESTRICTED = ["/billing", "/settings/api-keys", "/users", "/admin", "/agents/new"];
|
||||
```
|
||||
|
||||
The restriction check at line 59 uses `pathname.startsWith(`${prefix}/`)`, so `/agents/new/templates`, `/agents/new/wizard`, and `/agents/new/advanced` are all covered by the single entry. Operators are redirected to `/agents` on approach.
|
||||
|
||||
### Gap 1b: agents/page.tsx — New Employee button gating
|
||||
|
||||
**File:** `packages/portal/app/(dashboard)/agents/page.tsx`
|
||||
|
||||
Before: Button rendered unconditionally for all roles.
|
||||
|
||||
After: `useSession` imported and role extracted at lines 66-67. Button renders only when `role && role !== "customer_operator"` at line 77. Operators see no button entry point.
|
||||
|
||||
### Gap 2: step-review.tsx — error re-throw
|
||||
|
||||
**File:** `packages/portal/components/wizard-steps/step-review.tsx`
|
||||
|
||||
Before: catch block called `console.error` only; `mutateAsync` error was absorbed, mutation stayed in success state, error div never rendered.
|
||||
|
||||
After: catch block at lines 50-52 logs then re-throws:
|
||||
```typescript
|
||||
console.error("Failed to deploy agent:", err);
|
||||
throw err;
|
||||
```
|
||||
|
||||
`createAgent.isError` is now set on deploy failure and the error div at line 142 renders with `createAgent.error.message`.
|
||||
|
||||
---
|
||||
|
||||
## Required Artifacts (Regression Check)
|
||||
|
||||
| Artifact | Status | Notes |
|
||||
|----------|--------|-------|
|
||||
| `packages/portal/proxy.ts` | VERIFIED | /agents/new now in CUSTOMER_OPERATOR_RESTRICTED |
|
||||
| `packages/portal/app/(dashboard)/agents/page.tsx` | VERIFIED | Role check gates New Employee button |
|
||||
| `packages/portal/components/wizard-steps/step-review.tsx` | VERIFIED | catch re-throws; error div renders on failure |
|
||||
| `packages/shared/shared/api/templates.py` | VERIFIED (no change) | RBAC guards intact |
|
||||
| `packages/portal/lib/system-prompt-builder.ts` | VERIFIED (no change) | Transparency clause present |
|
||||
| `packages/portal/lib/queries.ts` | VERIFIED (no change) | useTemplates at 404, useDeployTemplate at 411 |
|
||||
|
||||
---
|
||||
|
||||
## Requirements Coverage
|
||||
|
||||
| Requirement | Description | Status | Evidence |
|
||||
|-------------|-------------|--------|----------|
|
||||
| EMPL-01 | Multi-step wizard guides user through AI employee creation without knowledge of system prompt format | VERIFIED | 5-step wizard (Role, Persona, Tools, Channels, Escalation) + Review; system prompt auto-generated, hidden |
|
||||
| EMPL-02 | Pre-built agent templates for one-click deployment | VERIFIED | 7 templates in migration 007; GET /api/portal/templates; TemplateGallery card grid |
|
||||
| EMPL-03 | Template-deployed agents immediately functional | VERIFIED | Agent snapshot created with is_active=True; human verification in 05-03 confirmed |
|
||||
| EMPL-04 | Wizard and templates accessible to platform admins and customer admins (RBAC-enforced, not operators) | VERIFIED | Backend: require_tenant_admin (403 on operator). Frontend: proxy.ts blocks /agents/new; button hidden for customer_operator |
|
||||
| EMPL-05 | Agents created via wizard or template appear in Agent Designer for customization | VERIFIED | Both paths redirect to /agents/{id} on success |
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns Found
|
||||
|
||||
None remaining from previous gaps. Previously flagged items resolved:
|
||||
|
||||
| File | Previous Issue | Resolution |
|
||||
|------|---------------|-----------|
|
||||
| `proxy.ts` | /agents/new missing from restricted list | Fixed — added to CUSTOMER_OPERATOR_RESTRICTED |
|
||||
| `agents/page.tsx` | New Employee button had no role check | Fixed — gated with role !== "customer_operator" |
|
||||
| `step-review.tsx` | catch block swallowed deploy errors | Fixed — catch re-throws after console.error |
|
||||
|
||||
---
|
||||
|
||||
## Human Verification Required
|
||||
|
||||
### 1. Three-Option Entry Screen Visual
|
||||
|
||||
**Test:** Load /agents/new and inspect card rendering at mobile (375px) and desktop (1280px) widths
|
||||
**Expected:** Templates card has "Recommended" badge and primary-colored border; all three cards are legible and buttons navigable
|
||||
**Why human:** CSS grid layout, badge positioning, and responsive breakpoints cannot be verified programmatically
|
||||
|
||||
### 2. Template Preview Dialog
|
||||
|
||||
**Test:** Click "Preview" on any template card in /agents/new/templates
|
||||
**Expected:** Dialog opens showing role, persona, model preference, tool badges, and escalation rules list; "Deploy Now" inside dialog triggers deploy and redirects to /agents/{id}
|
||||
**Why human:** Dialog open/close interaction and content rendering require visual inspection
|
||||
|
||||
### 3. Wizard Back-Navigation State Retention
|
||||
|
||||
**Test:** Complete steps 1-3 in wizard, click Back from step 3 to step 2, then Back to step 1
|
||||
**Expected:** Each step pre-fills with previously entered data; no data loss
|
||||
**Why human:** React state retention across back-navigation requires interactive testing
|
||||
|
||||
### 4. Channels Step Empty State
|
||||
|
||||
**Test:** Open wizard with a tenant that has no active channel connections
|
||||
**Expected:** Step 4 shows "No channels connected yet. Your employee will be deployed and can be assigned to channels later." message, and Next button is still clickable
|
||||
**Why human:** Requires dev environment configured with no active channel connections
|
||||
|
||||
---
|
||||
|
||||
_Verified: 2026-03-24_
|
||||
_Verifier: Claude (gsd-verifier)_
|
||||
Reference in New Issue
Block a user