# Auth/Admin Bootstrap Workflow Simulation

## Summary

This is a deterministic workflow simulation for auth/admin bootstrap. It starts
from explicit fixture inputs and traces each simulated workflow output back to
those fixtures.

This is not approved product requirements. No product implementation was
performed.

Fixture sources:

- `ai/fixtures/requirements/auth-admin-bootstrap/rough-idea.md`
- `ai/fixtures/requirements/auth-admin-bootstrap/clarification-answers.md`

## Fixture Input

### Rough Idea Fixture

Source: `ai/fixtures/requirements/auth-admin-bootstrap/rough-idea.md`

Traceable raw inputs:

- first admin existence is unclear.
- possible first-user self-bootstrap is mentioned but undecided.
- setup screen versus another bootstrap mechanism is undecided.
- random public admin registration must be prevented.
- local testing and deployed environments both matter.
- admins may create or invite users, but invite/email behavior is undecided.
- frontend admin menu/area should appear only for admins.
- standard users should not see admin controls.
- login/logout must keep working.
- tests must be local/dev safe and must not leave fake users around.
- backend/API tests and later browser smoke are desired.

### Clarification Answers Fixture

Source: `ai/fixtures/requirements/auth-admin-bootstrap/clarification-answers.md`

Traceable decisions:

- public registration is not allowed for the admin-capable path.
- first-user self-bootstrap is local/dev/test only and only when no admin exists.
- production bootstrap requires explicit operator action.
- bootstrap is disabled after the first admin exists.
- first implementation uses admin-created users, not email invites.
- use existing `ADMIN`/`STD` role semantics if available; otherwise use the
  smallest later model/schema change.
- password reset and MFA are out of scope.
- generated local/dev/test users use deterministic prefixes and cleanup.
- frontend admin navigation is visible only to admins.
- backend/API checks are required for bootstrap, user creation, login, and
  currentUser role behavior.
- frontend component tests are required for role visibility.
- browser smoke is desired after Playwright setup exists.

## Simulated Requirements Intake Output

### User Perspective

Derived from rough idea lines about first admin, admins creating/inviting users,
frontend admin menu behavior, and local/deployed safety.

- Primary users: product operator, admin user, standard user, Developer, QA.
- Operator wants a safe way to establish the first admin without exposing
  secrets or enabling public admin registration.
- Admin wants to create users and see role/permission state.
- Standard user wants login/logout to keep working without seeing admin controls.
- Developer/QA need deterministic local validation and cleanup.

### User Workflows

Derived from rough idea plus clarification decisions.

1. Operator checks whether an admin exists.
2. In local/dev/test only, if no admin exists, the first user may bootstrap as
   admin.
3. In production, operator uses an explicit approved bootstrap mechanism.
4. After an admin exists, bootstrap is disabled.
5. Admin logs in and sees admin navigation.
6. Admin creates a standard user.
7. Standard user logs in and does not see admin controls.
8. Tests clean up generated local/dev/test users.

### Functional Requirements

- Detect whether an admin exists.
- Support local/dev/test first-admin bootstrap only when no admin exists.
- Require a separate production operator decision before production bootstrap is
  implemented.
- Disable bootstrap after first admin exists.
- Let admins create users in the first implementation.
- Preserve login/logout for admins and standard users.
- Expose current user role for UI and API validation.
- Hide admin controls from standard users.

### Out Of Scope

Directly from clarification fixture:

- email invitations.
- password reset.
- MFA.
- full production secret-management implementation.
- broad admin dashboard features beyond first-admin bootstrap and user creation.

## Simulated Clarification Questions

These questions are traceable to missing details in the rough idea fixture.

1. Is public registration allowed for admin-capable user flows?
2. Can the first user self-bootstrap as admin?
3. Is self-bootstrap allowed in production or only local/dev/test?
4. Should bootstrap disable itself after the first admin exists?
5. Are users created directly by admins or invited by email?
6. Does the current role model already support `ADMIN` and `STD`?
7. Are password reset or MFA in scope?
8. What local/dev/test prefixes and cleanup rules are required?
9. What admin UI visibility must be tested?
10. What production bootstrap mechanism is approved?

## Simulated Clarification Answers

Answers come from
`ai/fixtures/requirements/auth-admin-bootstrap/clarification-answers.md`.

- Public admin-capable registration: not allowed.
- First-user self-bootstrap: local/dev/test only, only when no admin exists.
- Production bootstrap: requires explicit operator action and remains a human
  decision.
- Bootstrap after first admin exists: disabled.
- User provisioning: admin-created users first; email invites out of scope.
- Roles: use `ADMIN` and `STD` if existing role support allows it.
- Password reset/MFA: out of scope.
- Test data: use `scenario-`, `e2e-`, or `smoke-` prefixes and cleanup.
- Frontend: admin navigation only for admins.
- Browser smoke: desired after Playwright setup, not a blocker for initial
  backend/API work if documented as follow-up.

## Simulated Requirements Review

### Pre-Clarification Review

- Verdict: BLOCKED.
- Reason: the rough idea does not decide public registration, first-user
  self-bootstrap, production bootstrap mechanism, user invite/create behavior,
  role model assumptions, password reset/MFA scope, or cleanup rules.
- Recommended action: ask the clarification questions above.

### Post-Clarification Review

- Verdict: PASS for planning readiness only.
- Product approval: not granted by this simulation.
- Remaining human decision: exact production operator bootstrap mechanism.
- Planning can proceed because the unresolved production mechanism is explicitly
  isolated into a first requirements/finalization chunk before implementation.

Gate assessment:

- Intake Gate: PASS.
- Functional Completeness Gate: PASS for planning.
- Data And Permissions Gate: PASS with production mechanism isolated.
- UI / UX Gate: PASS for planning.
- Runtime And Testability Gate: PASS.
- Risk Gate: PASS with human-decision risk documented.

## Simulated Chunk Plan

This plan is derived from post-clarification requirements.

### Chunk 1: Auth/Admin Bootstrap Requirements Finalization

- Source requirements: production bootstrap mechanism still requires human
  decision.
- Goal: create the real requirements file and resolve production operator
  mechanism before product implementation.
- Validation: `ai/commands/requirements-state.sh <requirements-path>`.
- Runtime smoke: not applicable.

### Chunk 2: Backend Admin Bootstrap API

- Source requirements: detect admin existence, local/dev/test bootstrap,
  disabled after first admin exists, admin-created users, role behavior.
- Goal: implement backend/API behavior.
- Validation:
  - `yarn workspace backend test`
  - `yarn workspace backend test:e2e`
  - backend/API scenario checks under `apps/backend/scenarios`
- Runtime smoke: required if auth/database/dev-server behavior changes.

### Chunk 3: Frontend Admin/Auth Visibility

- Source requirements: admin navigation visible only to admins; standard users
  do not see admin controls.
- Goal: implement visible role/auth state.
- Validation:
  - `yarn workspace frontend test`
  - `yarn smoke:runtime`
  - Playwright/browser smoke after setup exists, or explicit accepted follow-up.

### Chunk 4: Auth/Admin Scenario Harness

- Source requirements: deterministic local/dev/test validation, cleanup prefixes,
  backend/API contract behavior.
- Goal: add scenario fixture/helper coverage for bootstrap and role flows.
- Validation:
  - scenario command or documented manual scenario.
  - `ai/commands/workflow-summary.sh`
  - backend e2e where database access is required.

### Chunk 5: Orchestrated Product Review

- Source requirements: full Developer -> QA loop on approved chunks.
- Goal: validate prompt synthesis, Test Impact, frontend/backend validation,
  cleanup, and handoff quality across the real product implementation.
- Validation:
  - workflow helpers.
  - relevant app tests from prior chunks.

## Simulated Orchestrator Handoff

For the current simulation chunk:

- Canonical State: ready_for_qa
- Gate Checked: `ai/commands/workflow-state.sh --ready-for-qa`
- Result: needs_review
- Recommended Next Action: run QA review
- Exact Next Command: `ai/commands/prompt-synthesize.sh qa`
- Optional Prompt Review Command: `ai/commands/prompt-synthesize.sh review qa`

For the future real requirements flow:

- Requirements state command:
  `ai/commands/requirements-state.sh ai/requirements/active/<requirements-file>`
- Requirements review prompt: `ai/commands/prompt-synthesize.sh requirements-review`
- Chunk-state command after activation: `ai/commands/workflow-state.sh`
- Developer prompt command: `ai/commands/prompt-synthesize.sh dev`
- QA prompt command when ready: `ai/commands/prompt-synthesize.sh qa`
- Summary packet: `ai/commands/workflow-summary.sh`

## Simulated Developer Prompt Synthesis

The Developer prompt for a future implementation chunk should reference:

- `ai/commands/prompt-synthesize.sh`
- `ai/standards/prompt-synthesis.md`
- `ai/standards/workflow-handoff.md`
- `ai/standards/workflow-state.md`
- approved requirements file path.
- chunk plan item.
- fixture-derived requirements decisions.
- Test Impact expectations.
- backend/API scenario expectations.
- frontend/browser smoke expectations when UI changes.
- no production credentials and no production data mutation.

Expected exact command after a real implementation chunk is active:

```sh
ai/commands/prompt-synthesize.sh dev
```

## Simulated QA Prompt Synthesis

The QA prompt for this simulation chunk should use:

```sh
ai/commands/prompt-synthesize.sh qa
```

The QA prompt should check:

- this report traces outputs to fixtures.
- pre-clarification review is BLOCKED.
- post-clarification review is planning-ready but not product-approved.
- chunk plan derives from clarified requirements.
- Test Impact covers backend/API, frontend/browser, and workflow-scenario
  considerations.
- no app source or dependency files changed.

Optional prompt review:

```sh
ai/commands/prompt-synthesize.sh review qa
```

## Test Impact

- Product behavior changed in this chunk: none.
- Fixture/workflow behavior changed: simulation now has explicit source fixtures.
- Backend/API expectations for future product chunks:
  - backend unit tests for auth/admin logic.
  - backend e2e/API tests for GraphQL/auth/currentUser/user creation.
  - backend scenario checks for bootstrap, cleanup, and role behavior.
- Frontend/browser expectations for future product chunks:
  - component tests for admin/standard role visibility.
  - `yarn smoke:runtime` for integrated auth behavior.
  - Playwright/browser smoke after setup exists.
- Requirements/workflow scenario expectations:
  - future requirements lifecycle harness should simulate rough idea through
    approved requirements.
  - prompt synthesis should eventually support requirements intake and chunk
    planning prompts directly.
- Not-applicable rationale for product implementation here:
  - this chunk validates workflow artifacts only.
  - no auth/admin product code is implemented.

## Frontend Smoke Expectations

Derived from rough idea admin menu behavior and clarification fixture role
visibility decisions.

- Admin user sees admin navigation.
- Standard user does not see admin controls.
- Login/logout remains usable.
- Component tests are required for role-visible UI.
- Runtime smoke is required when real frontend/backend auth behavior changes.
- Browser smoke is desired after Playwright setup.

## Backend/API Scenario Expectations

Derived from first-admin, admin-created users, role visibility, and cleanup
fixtures.

- Check no-admin state.
- Check local/dev/test first-admin bootstrap when no admin exists.
- Check bootstrap disabled after an admin exists.
- Check admin-created standard user flow.
- Check login/currentUser role behavior for admin and standard users.
- Use `scenario-`, `e2e-`, or `smoke-` prefixes.
- Clean up generated test users.
- Do not print tokens, secrets, database URLs, or environment values.

## Workflow Gaps Found

- Requirements lifecycle does not yet have a deterministic scenario harness from
  rough idea to reviewed requirements.
- Prompt synthesis supports requirements review, but not requirements intake or
  chunk planning as first-class modes.
- The current simulation is report-based; future workflow validation should make
  fixture evaluation executable where practical.
- Backend/API scenario and frontend browser smoke strategies are documented but
  not yet executable dedicated harnesses.
- Production first-admin bootstrap mechanism still requires human product and
  operations approval.

## Recommended Follow-Up Chunks

1. Add deterministic requirements lifecycle scenario harness coverage using this
   fixture pattern.
2. Add prompt synthesis modes for requirements intake and chunk planning.
3. Create a real auth/admin bootstrap requirements file from these fixtures for
   human review.
4. Add backend auth/admin bootstrap scenario harness with local-only fixtures and
   cleanup.
5. Add Playwright dependency/configuration and minimal frontend browser smoke.
6. Implement backend admin bootstrap only after requirements approval and human
   decision on production bootstrap policy.

## Suggested Immediate Next Step

Use the two fixture files as input to create a real requirements draft under the
requirements lifecycle, then run Requirements Review before product
implementation.