/architect — Architect Orchestrator (Conv 1 cierre — produce ready package)

Agent({
  description: "Architect Story {id} {scope}",
  subagent_type: "architect-orchestrator",
  prompt: "<brand>: {brand}                          # ★ REQUIRED — single-project scope
           <pr_folder>: docs/product/stories/{id}/
           story_type: {ui-story|service-story|agentic-story}
           surfaces: {BE | FE | AGENTIC | combinaciones}
           mode: SINGLE-SHOT FULL-STACK

           PRIORITY READ:
           1. docs/product/stories/{id}/checkpoint.md (state=refined required)
           2. docs/product/stories/{id}/01-spec.md ratificada por Chris
           3. docs/product/stories/{id}/02-design-agentic.md si agentic-story
           4. docs/product/stories/{id}/00-story.md / delta-spec.md si existen
           5. docs/product/outcomes/{outcome-id}.md
           6. docs/product/modules/{m}.md
           7. Stories archivadas relacionadas (predecesores) en docs/archive/

           LOAD SKILLS contextualmente según surface:
           - BE: backend-expert + tessl__fastapi + tessl__pytest-api-testing
           - FE: frontend-expert + tessl__react-patterns + tessl__zod + tessl__shadcn-ui + tessl__tailwind + tessl__vitest + tessl__nextjs-app-router-modularization
           - AGENTIC: sales-agent-expert / copilot-expert + tessl__langgraph + claude-api
           - Cross-cutting: tessl__graceful-degradation + domain skills (brand/offer/preset/metrics)

           DELIVERABLES (4-5 files, todos bajo docs/product/stories/{id}/):
           1. 03-arch.md (consolidado, secciones por surface — incluye § Test Construction Plan ★ v4.1)
           2. 03-arch-{be,fe,agentic}.md per surface tocado (opcional, si arch es complejo per-surface)
           3. 04-validators.yaml (5 categories — non_functional / functional / visual / agentic_eval / architectural_validation ★ v4.1 — scenario_coverage 100%, must_pass:true, test_construction_plan completo)
           4. 05-guidelines.md (must_load_skills enforceable ★ v4.1 + patterns required/forbidden + files in scope)
           5. 06-tickets.yaml (atomic, R23 marked AGENTIC, owner_eligibility, DAG, gherkin_coverage per ticket)

           CRITICAL CONSTRAINTS:
           - Cross-module audit anti-duplication.md (no mirror shared abstractions cross-module)
           - R23: AGENTIC tickets production_code:true → claude_opus_required:true
           - AGENTIC tickets SEPARADOS de BE/FE (R23 enforcement)
           - Tickets > 10 → split story
           - Each ticket: acceptance.validator_ids + DAG + gherkin_coverage (post 2026-05-18)
           - Hot-fix: repro_verified field si aplica (R26)
           - Engine boundaries: NUNCA proponer tickets que editen `core/luana-core-*/src/` directamente. Si scope requiere editar engine → escalá `/pm` (promotion gate) ANTES de cerrar package.
           - Brand-extension agentic: `backend/src/modules/{copilot,sales_agent}/{tools,extractors,workflows,personas,goldens,kb}/` SÍ es editable.
           - ★ v4.1 Playwright mandatory para surface funcional: test_construction_plan.playwright_required=true SIEMPRE que story sea ui-story o ui-mixed
           - ★ v4.1 must_load_skills enforceable: dev-team builder spawn cita lista verbatim
           - ★ v4.1 architectural_validation category con sub-tests (DDD/FSD boundaries, tenant_isolation grep, anti-dup scan, cross-module audit)
           - ★ v4.1 sub-categorías scenarios obligatorias: race conditions, concurrent users, network failures, empty states, large datasets, accessibility, i18n (heredadas de /po-ux refused refined sin ellas)

           After writing all files, transition checkpoint.md state: refined → ready.

           LAST LINE: done -> docs/product/stories/{id}/06-tickets.yaml"
})

# 03-arch.md — Story {id}

## Surfaces involved
- BE: yes (3 endpoints, 2 SQLA models, 1 migration)
- FE: yes (1 page route, 2 components, 1 RHF form)
- AGENTIC: no

## BE arch (full detail in 03-arch-be.md)
... summary + key decisions ...

## FE arch (full detail in 03-arch-fe.md)
... summary + key decisions ...

## Cross-cutting decisions
- Tenant isolation strategy: ...
- Currency handling: ...
- PII fields: ...

# docs/product/stories/{story-id}/04-validators.yaml
# v4 schema: 4 categories — non_functional / functional / visual / agentic_eval
# NOTE: validator cmds usan paths relativos al workspace root. `${WS}` o `git rev-parse --show-toplevel`
# debe ser resuelto por gate-runner antes de ejecutar.

validators:
  # ─── NON-FUNCTIONAL (lint, arch fitness, type-check, format) ───
  - id: be_arch_fitness
    category: non_functional
    type: pytest
    cmd: "cd backend && ../../.venv/bin/pytest tests/architecture/ -x -q --override-ini='addopts='"
    must_pass: true
    timeout_sec: 120

  - id: be_lint
    category: non_functional
    type: shell
    cmd: "cd backend && ../../.venv/bin/ruff check src/modules/{m}/ tests/modules/{m}/ --no-cache && ../../.venv/bin/ruff format --check src/modules/{m}/ tests/modules/{m}/"
    must_pass: true
    timeout_sec: 30

  - id: fe_typecheck
    category: non_functional
    type: shell
    cmd: "cd frontend && npx tsc --noEmit"
    must_pass: true
    timeout_sec: 90

  # ─── FUNCTIONAL (Gherkin scenarios — happy/negative/edge/adversarial) ───
  - id: be_unit_create_endpoint
    category: functional
    type: pytest
    cmd: "cd backend && ../../.venv/bin/pytest tests/modules/{m}/test_create.py -v --tb=short"
    must_pass: true
    timeout_sec: 60

  - id: fe_unit
    category: functional
    type: shell
    cmd: "cd frontend && npx vitest run src/features/{m}/"
    must_pass: true
    timeout_sec: 60

  - id: e2e_happy
    category: functional
    type: playwright
    cmd: "cd frontend && E2E_BASE_URL=http://localhost:300X npx playwright test --project=smoke e2e/regression/{m}-{story}.spec.ts"
    must_pass: true
    timeout_sec: 180

  # ─── VISUAL (responsive + visual fidelity Playwright + screenshots) ───
  - id: visual_fidelity
    category: visual
    type: playwright
    cmd: "cd frontend && npx playwright test e2e/visual/{story}.spec.ts --update-snapshots=false"
    capture: screenshots
    must_pass: true
    timeout_sec: 240

  - id: responsive_breakpoints
    category: visual
    type: playwright
    cmd: "cd frontend && npx playwright test e2e/visual/{story}-responsive.spec.ts --project=mobile,tablet,desktop"
    must_pass: true
    timeout_sec: 240

  # ─── AGENTIC EVAL (pass^k, rubrics, trajectory, cost/latency budgets) ───
  # Solo si story toca backend/src/modules/{copilot,sales_agent}/ brand-extension surface
  # (engine `core/luana-core-{copilot,sales-agent}/` requiere /pm — NO se edita en story brand)
  - id: agentic_pass_k
    category: agentic_eval
    type: shell
    cmd: "cd backend && ../../.venv/bin/python scripts/run_agent_evals.py --story={story-id} --personas=A,B,C"
    rubrics: [voice-fidelity, goal-completion, tool-call-accuracy]
    pass_k:
      trials: 3
      per_trial_threshold: 0.66
      pass_k_threshold: 0.5
    must_pass: true
    timeout_sec: 600

  - id: agentic_trajectory
    category: agentic_eval
    type: shell
    cmd: "cd backend && ../../.venv/bin/python scripts/run_trajectory_eval.py --expected=docs/specs/trajectories/{story-id}.yaml"
    must_pass: true
    timeout_sec: 300

  - id: agentic_cost_budget
    category: agentic_eval
    type: shell
    cmd: "cd backend && ../../.venv/bin/python scripts/check_cost_budget.py --story={story-id}"
    threshold: { cost_usd_max: 0.50, tokens_max: 6000, latency_p95_max: 8.0 }
    must_pass: true
    timeout_sec: 60

  # ─── ARCHITECTURAL VALIDATION (★ v4.1 — separada de non_functional) ───
  # Verificación arquitectónica explícita: DDD/FSD boundaries, anti-dup scan, tenant isolation grep, cross-module audit
  - id: arch_ddd_boundaries
    category: architectural_validation
    type: pytest
    cmd: "cd backend && ../../.venv/bin/pytest tests/architecture/test_ddd_boundaries.py -v"
    must_pass: true
    timeout_sec: 30
    description: "DDD layers domain→infra→app→api boundary enforcement"

  - id: arch_tenant_isolation_grep
    category: architectural_validation
    type: shell
    cmd: "! grep -rn 'select.*Model)' backend/src/modules/{m}/ | grep -v 'tenant_id' | grep -v test_"
    must_pass: true
    timeout_sec: 10
    description: "Cada query debe filtrar tenant_id (regex scan + auditor doble check)"

  - id: arch_anti_duplication_scan
    category: architectural_validation
    type: shell
    cmd: "scripts/scan_cross_brand_mirror.sh {brand} {m}"
    must_pass: true
    timeout_sec: 30
    description: "Detecta mirrors cross-module del módulo. Match → spawn promotion proposal."

  - id: arch_fsd_boundaries
    category: architectural_validation
    type: shell
    cmd: "cd frontend && npx vitest run src/__tests__/architecture/test_fsd_boundaries.test.ts"
    must_pass: true
    timeout_sec: 60
    description: "FSD-Lite boundaries — feature → feature own/shared/lib only"

scenario_coverage:
  - scenario_id: happy
    validators: [be_unit_create_endpoint, fe_unit, e2e_happy]
  - scenario_id: negative
    validators: [be_unit_create_endpoint, fe_unit]
  - scenario_id: edge
    validators: [be_unit_create_endpoint, e2e_edge_race]
  - scenario_id: adversarial
    validators: [be_unit_create_endpoint, e2e_adversarial]
  - scenario_id: empty_state
    validators: [fe_unit, e2e_empty_state]
  - scenario_id: network_failure
    validators: [fe_unit, e2e_network_failure]
  - scenario_id: concurrent_users
    validators: [be_unit_create_endpoint, e2e_concurrent]
  - scenario_id: large_dataset
    validators: [fe_unit, e2e_large_dataset]
  - scenario_id: accessibility
    validators: [a11y_axe]
  - scenario_id: i18n
    validators: [fe_unit_voseo_check, e2e_locale_AR_MX_CL]

# ★ v4.1 cement 2026-05-19 — Test Construction Plan (mandatory para stories con surface funcional)
test_construction_plan:
  # Architect dicta el orden + estructura. Dev-team CONSTRUYE siguiendo este plan, no inventa.

  playwright_required: true     # toda story funcional MUST tener Playwright behavior tests
  base_path: "frontend/e2e/regression/{story-id}/"

  # Orden de creación (dependencias entre tests)
  creation_order:
    - step: 1
      file: "frontend/e2e/fixtures/{story-id}.fixture.ts"
      content: "Fixtures compartidos — tenant setup, Clerk auth state, DB seed minimal"
      depends_on: []
    - step: 2
      file: "frontend/e2e/regression/{story-id}/poms/{m}-list-page.pom.ts"
      content: "Page Object Model para lista {m}"
      depends_on: [1]
    - step: 3
      file: "frontend/e2e/regression/{story-id}/poms/{m}-detail-page.pom.ts"
      content: "Page Object Model para detail {m}"
      depends_on: [1]
    - step: 4
      file: "frontend/e2e/regression/{story-id}/{m}-happy.spec.ts"
      content: "Scenario happy — usa POMs"
      depends_on: [2, 3]
    - step: 5
      file: "frontend/e2e/regression/{story-id}/{m}-negative.spec.ts"
      content: "Scenario negative — input inválido"
      depends_on: [2, 3]
    - step: 6
      file: "frontend/e2e/regression/{story-id}/{m}-edge.spec.ts"
      content: "Scenarios edge (race, concurrent, empty, large, network failure)"
      depends_on: [2, 3]
    - step: 7
      file: "frontend/e2e/regression/{story-id}/{m}-adversarial.spec.ts"
      content: "Scenarios adversarial (cross-tenant, XSS, prompt injection si aplica)"
      depends_on: [2, 3]
    - step: 8
      file: "frontend/e2e/a11y/{story-id}.spec.ts"
      content: "Accessibility axe-core scan"
      depends_on: [4]

  # Mapping explícito scenario Gherkin (01-spec.md) → spec.ts file → assertions
  scenario_to_test:
    - gherkin_scenario: "Scenario 1 — happy-path"
      test_file: "frontend/e2e/regression/{story-id}/{m}-happy.spec.ts"
      test_function: "test('user creates {entity} successfully'"
      assertions:
        - "expect(toast).toContainText('{entity} guardada')"
        - "expect(page.url()).toContain('/detail/')"
        - "DB check: SELECT * FROM {table} WHERE tenant_id={tid} AND ... returns 1 row"
    - gherkin_scenario: "Scenario 2 — negative invalid input"
      test_file: "frontend/e2e/regression/{story-id}/{m}-negative.spec.ts"
      test_function: "test('rejects empty required field'"
      assertions:
        - "expect(form errors).toContainText('Campo requerido')"
        - "DB check: NO row inserted"
    - gherkin_scenario: "Scenario 3 — edge concurrent"
      test_file: "frontend/e2e/regression/{story-id}/{m}-edge.spec.ts"
      test_function: "test('handles concurrent create same slug'"
      assertions:
        - "expect(second request).toHaveStatus(409 or 422)"
        - "DB check: only 1 row exists with that slug"
    - gherkin_scenario: "Scenario 4 — adversarial cross-tenant"
      test_file: "frontend/e2e/regression/{story-id}/{m}-adversarial.spec.ts"
      test_function: "test('rejects cross-tenant access'"
      assertions:
        - "expect(request as tenant B for tenant A resource).toHaveStatus(404 or 403)"
        - "NO leak en error body"

  # POMs requeridos (Page Object Models) — qué métodos exponen
  poms_required:
    - file: "{m}-list-page.pom.ts"
      methods:
        - "goto()"
        - "filterBy(criteria)"
        - "clickCreateButton()"
        - "getRowCount() → number"
        - "getRowByName(name)"
    - file: "{m}-detail-page.pom.ts"
      methods:
        - "goto(id)"
        - "fillForm(data)"
        - "submit()"
        - "getErrorMessage() → string|null"

  # Fixtures compartidos requeridos
  fixtures_required:
    - name: "authedAs(role: 'admin' | 'user')"
      content: "Clerk storage state + tenant setup"
    - name: "dbSeed({m}: count)"
      content: "Insert N rows in {table} para el tenant del test"
    - name: "networkFailure(endpoint)"
      content: "Mock route con 500/503 para simular network failure"

iteration:
  max_iterations: 10
  on_fail: "fix targeted file based on test output, re-run failing validator only"
  on_all_pass: "set state=developing→developed, append iteration_log to T-{n}-impl-log.md"
  on_cap_reached: "set state=developing→blocked, escalate to Chris with last error trace"

# 05-guidelines.md — Story {id}

## Patterns required
- SQLAlchemy 2.0 `select(Model).where(...)` — NO `session.query()`
- All DB queries filter `tenant_id` (incluye `get_by_id`)
- Soft deletes only (`deleted_at`)
- Pydantic v2 `model_config = ConfigDict(...)` — NO inner `class Config`
- `structlog` logging — NO `print` / `logging`
- Migrations idempotentes (`IF NOT EXISTS` / `IF EXISTS`)
- FastAPI endpoints `response_model=` mandatory (PII allowlist)
- Use `datetime` fields with `timezone=True`
- Use `utc_now()` from `shared/domain/datetime_utils.py` (no `datetime.utcnow()`)
- React Server Components default; `"use client"` solo cuando necesario
- React Query (TanStack) para data fetching
- RHF + Zod para forms
- Tailwind utility classes con tokens semánticos (no hex literals)
- Spanish neutro LatAm en TODA UI string (no voseo, no léxico regional)

## Patterns forbidden
- `datetime.utcnow()` — use `utc_now()`
- Hardcoded `'USD'` en monetary fields — use `tenant.currency`
- Cross-module imports (excepto `copilot`)
- `session.query()` (SA 1.x)
- `sa.Enum()` en `op.create_table()` (broken SA 2.0.27)
- `op.create_table()` / `add_column()` / `create_index()` no idempotente
- `// eslint-disable` sin justification comment
- `any` en TypeScript (use `unknown` + type guards)
- Default exports (excepto Next.js pages)
- Hex colors hardcoded en components/styles

## Files in scope (Sonnet edits ONLY these — todos brand-scoped bajo )
- backend/src/modules/{m}/api/routes.py
- backend/src/modules/{m}/application/services/...
- backend/src/modules/{m}/domain/...
- backend/src/modules/{m}/infrastructure/...
- backend/alembic/versions/{timestamp}_{slug}.py (NEW migration brand-scoped)
- backend/tests/modules/{m}/test_{name}.py
- frontend/src/features/{m}/...
- frontend/src/app/{m}/page.tsx
- frontend/e2e/regression/{m}-{story}.spec.ts

## Files Sonnet NEVER touches (escalate to Chris / /pm)
- (N/A single-brand — was Luana engine)** (engine — requires lift via /pm promotion gate; NUNCA en story brand-específica)
- backend/src/modules/{copilot,sales_agent}/** runtime (agentic — solo via builder-agentic Opus; brand-extension surface OK con R23 check)
- {other_brand}/** (cross-module edit — escalate /pm outcome platform)
- backend/src/core/config.py (default flag flips require R31 anti-default-flip-audit)
- frontend/src/components/ui/** (Shadcn primitives per-project — extend via wrappers, no edit; cross-module reuse = promotion candidate /pm)
- frontend/src/lib/api/fetchClient.ts (cross-cutting per-project — escalate)
- .claude/** y .claude/** (skill/rule edits — manual only)

## must_load_skills (★ v4.1 enforceable — builder MUST cargar todas + reportar "Skills consulted" en T-{n}-result.md)
required:
  # Skills core obligatorios por surface
  - id: backend-expert
    when: "surface=BE o BE-test"
    purpose: "DDD patterns, arch fitness, currency, master-data, currency-handling"
  - id: frontend-expert
    when: "surface=FE"
    purpose: "FSD-Lite, Shadcn reuse, form-runtime, tailwind tokens"
  - id: "{domain}-expert"
    when: "module touched (brand-expert / offer-expert / metrics-expert / copilot-expert / sales-agent-expert)"
    purpose: "Domain invariants + reference docs por módulo"
  - id: playwright-expert
    when: "test_construction_plan.playwright_required=true"
    purpose: "POM patterns, Clerk auth fixture, network mocking, smoke debugging"

  # Rules obligatorias siempre
  - id: ".claude/rules/tenant-isolation.md"
    purpose: "Every query filter tenant_id"
  - id: ".claude/rules/backend-ddd.md o frontend-fsd.md"
    purpose: "Layer boundaries"
  - id: ".claude/rules/spanish-text.md"
    purpose: "Voseo glosario + magic comment escape"
  - id: ".claude/rules/anti-duplication.md"
    purpose: "cross-module mirror ban + shared abstractions inventory"
  - id: ".claude/rules/tdd-mandatory.md"
    purpose: "TDD RED→GREEN→REFACTOR discipline"
  - id: ".claude/rules/auditor-self-fix-policy.md"
    purpose: "Conocer qué findings auditor self-fix vs spawn dev-team (forward motion)"

  # Tessl skills (versioned canonical docs) si aplica
  - id: "tessl__fastapi"
    when: "BE endpoint nuevo"
  - id: "tessl__pytest-api-testing"
    when: "BE tests nuevos"
  - id: "tessl__react-patterns + tessl__shadcn-ui + tessl__tailwind"
    when: "FE component nuevo"
  - id: "tessl__zod"
    when: "FE form con validation"
  - id: "tessl__vitest"
    when: "FE tests nuevos"
  - id: "tessl__langgraph + claude-api"
    when: "AGENTIC surface"

reference_artifacts:
  # Documentos del ready package que builder re-lee mid-build cuando surge ambigüedad
  - "docs/product/stories/{story-id}/01-spec.md" (re-read Gherkin scenarios)
  - "docs/product/stories/{story-id}/03-arch.md" (re-read decisiones técnicas)
  - "docs/product/stories/{story-id}/04-validators.yaml § test_construction_plan" (re-read orden + POMs + fixtures)

- id: T-1 (BE endpoint)
  depends_on: []
  blocks: [T-2, T-3]
- id: T-2 (agentic tool wire)
  depends_on: [T-1]
  blocks: [T-3]
- id: T-3 (FE button)
  depends_on: [T-2]
  blocks: []

acceptance:
  - validator_ids: [be_unit_create_endpoint, be_arch_fitness, be_lint]

T-1 (BE endpoint, owner: opencode/sonnet):
  ...
  notes_for_downstream_agentic_ticket:
    - "Este endpoint será llamado por brand_audit_tool en T-2 (agentic). NO cambiar response shape sin coordinar."
    - "Response model: BrandAuditResponse(gaps: list[Gap], priorities: dict)"
    - "Latencia p95 < 500ms (agentic budget total $0.50)"

repro_verified: true
repro_evidence:
  command: "cd backend && ../../.venv/bin/pytest <paths brand-scoped> -v"
  output: |
    <verbatim error/traceback first 5-10 lines>
  diagnosis_validates_handoff: <true|false>

brand: {brand}        # ★ REQUIRED — single-project scope
state: ready          # ★ TRANSITION ★ refined → ready
phase: READY_PACKAGE_CLOSED
last_artifact: 06-tickets.yaml
last_modified: 2026-05-06T...
next_action: "/dev-team <brand>: {brand} starts Conv 2 autonomous build (toma T-1 first, iterate vs 04-validators.yaml)"

Ready package cerrado para story {id}.

Artifacts (en docs/product/stories/{id}/):
- 03-arch.md (consolidado, secciones por surface inline)
- 03-arch-{be,fe,agentic}.md OPCIONAL (orchestrator decide si arch es complejo per-surface)
- 04-validators.yaml ({N} validators, scenario coverage 4/4)
- 05-guidelines.md
- 06-tickets.yaml ({N} tickets)

Owner mix:
- T-1 (BE, qwen/sonnet, 2h)
- T-2 (AGENTIC, opus-only, 3h)
- T-3 (FE, qwen/sonnet, 2h)

Dependencies: T-2 depends T-1; T-3 depends T-2.

Story state: refined → ready.
WIP cap check: ready (was N) now N+1 / cap 5.

Próximo: Conv 2 (autonomous build). /dev-team <brand>: {brand} toma T-1 (state: ready → developing).