docs(governance): frames are the design source of truth — retire the PenPot gate

[izzywdev]

CLAUDE.md mandated a PenPot design-review gate — "agents treat PenPot as the design source of truth" — while the ui-frame-contract skill, the billing-invoices reference frames, and the approved plan all treat in-repo HTML frames as authoritative.

Two contradictory governance rules with nothing reconciling them. An agent reading CLAUDE.md would have gone the wrong way, and that is not hypothetical — the entire design-first pipeline exists because governance that is skippable gets skipped.

PenPot is parked by owner decision. A design tool that lives outside the repo cannot be gated by CI. Frames are code: they diff, they review, they enforce.

What the section now says

• product-designer — sole author of design/frames/**, never the implementer. The same separation contract-designer gives the backend: whoever is measured against the spec does not write it.
• Frames are always their own PR, and its only content. Gated by gate-ds-conformance, gate-frames-schema, gate-frames-stamped.
• Frames declare the build inventory (flows / components / packages) — approving the design approves the architecture.
• Per-flow approval; reject re-dispatches the designer rather than closing the thread.
• Merging approved frames triggers RED QA (specs fail before implementation exists), then components → orchestrators → packages.
• States are contract, not decoration — reveal-once token, remove-last-factor → 409, last-admin, hasPassword: null.
• gate-frames-first is what makes it mechanical rather than remembered.

Plan of record: docs/planning/design-first-ui-pipeline.md.

Note design-review-notify.yml still exists and fires on the design-review label — left alone deliberately, out of scope here; it can be repointed at frames PRs separately.

Refs #294

🤖 Generated with Claude Code

[github-actions]

Root cause

The Playwright e2e tests (auth-simple.spec.ts, clock-load.spec.ts) wait for a successful POST /api/v1/security/session response (status 200) after the user submits the login form. The frontend's authAPI.login() calls exactly that endpoint (SECURITY_BASE = '/v1/security', api.post('/v1/security/session', ...)). But the backend only had POST /api/auth/login — there was no /api/v1/security route at all. Every login call returned 404, the waitForResponse timed out after 15 s, and both tests failed.

The gap: the frontend was updated to talk to the provider-neutral Security API (@fuzefront/security-client contract), but the corresponding backend routes were never added.

Fix

Added backend/src/routes/security.ts with the four endpoints the security-client contract requires:

Method	Path	Description
GET	/api/v1/security/methods	Advertise available auth capabilities (AuthMethods shape)
POST	/api/v1/security/session	Password login → SessionResult with status: 'authenticated'
GET	/api/v1/security/session	Current identity ("me")
DELETE	/api/v1/security/session	Logout / revoke session

The POST /session response includes { status: 'authenticated', token, sessionId, user } which matches the SessionResult discriminated union the frontend checks before persisting the session. The legacy /api/auth/* routes are untouched for backwards compatibility.

Registered the new router in backend/src/index.ts at /api/v1/security.

Fixes the failing "Playwright sign-in flow" job in PR #302.

Refs #302

🤖 Generated with Claude Code

[github-actions]

Fix branch: claude-auto-fix-ci-claude/frames-governance-fix-29571596299

The fix commit is pushed to that branch. Please open a PR from it targeting claude/frames-governance-fix to merge the fix, or cherry-pick commit c0f57c9 directly onto the PR branch.