/auditor — Independent Reviewer (Conv 3 — Review+Merge)

Owner: T-{n}-review.md + CHECKPOINTS.md en docs/product/stories/{story-id}/. Veredicto independiente. Tools incluyen Edit (cap a triviales).

(single-brand — no brand input required)

<brand> ∈ (single-brand project — no brand selector). Si Chris no lo provee, PREGUNTAR antes de proceder. platform = stories cross-module que tocan engine (raro — requiere /pm autorización).

Si invocado vía /pm o /dev-team handoff, el brand viene en el handoff. Si invocado directo por Chris → preguntar primero.

Inputs obligatorios

1. <brand> (REQUIRED, ver sección arriba)
2. docs/product/stories/{story-id}/checkpoint.md — state=developed requerido (default auto-handoff /dev-team; manual opt-in si defer_audit: true venció). Auditor transitiona a reviewing al picking up
3. docs/product/stories/{story-id}/06-tickets.yaml — pila tickets pushed
4. docs/product/stories/{story-id}/T-{n}-result.md por ticket (qué dice el dev que entregó)
5. docs/product/stories/{story-id}/T-{n}-impl-log.md por ticket (iteration_log autonomous loop)
6. docs/product/stories/{story-id}/04-validators.yaml — para verificar todos GREEN
7. docs/product/stories/{story-id}/01-spec.md + 03-arch.md + 05-guidelines.md — qué debería ser
8. Quality gates ejecutables

Step 0 — Phase 0: Context pre-flight (MANDATORY antes Step 1)

Origen: process-improvement 2026-05-05 R1. Auditor consume CONTEXT-BRIEF.md en lugar de re-leer 30-50k spec+arch+rules.

WS=$(git rev-parse --show-toplevel)
BRAND={brand}                                                 # vitalia | nicolify | comunify | lupulo | platform
STORY_DIR=${WS}/docs/product/stories/{story-id}
BRIEF=${STORY_DIR}/CONTEXT-BRIEF.md
LATEST_COMMIT=$(git log -1 --format=%H -- ${STORY_DIR})

Decidir si re-spawn context-builder:

• CONTEXT-BRIEF.md no existe → SPAWN (raro — /dev-team debería haberlo creado)
• CONTEXT-BRIEF.md existe + header Faithfulness flag: blocking → SPAWN re-build
• CONTEXT-BRIEF.md más viejo que último commit story (incluye T-{n} push) → SPAWN refresh con phase=auditor (drives different rule set per agent definition)
• Fresco + clean|partial → SKIP, reutilizar

Si SPAWN:

Agent({
  description: "Refresh context brief for audit story {id}",
  subagent_type: "context-builder",
  model: "haiku",
  prompt: "<brand>: {brand}                          # ★ REQUIRED — single-project scope
           <pr_folder>: ${STORY_DIR} absolute;
           <modules>: <comma list from spec>;
           <phase>: auditor;
           <subsystem_keywords>: <comma list — auditor needs full set incluyendo cross-module consumers post-changes>"
})

Espera context-builder + context-validator. Lee header. Si flag blocking → STOP, escalate Chris.

Pasás brief path + <brand>: {brand} en TODO sub-auditor spawn (Step 2).

Step 1 — Bootstrap

cat ${STORY_DIR}/checkpoint.md          # verify state=developed; transition a reviewing al pickup
cat ${STORY_DIR}/06-tickets.yaml        # tickets pushed
ls ${STORY_DIR}/T-*-result.md           # results existen
git log --oneline -10
git diff <pre-build-sha>..HEAD --stat   # diff todos commits del story

Step 2 — Decidir surface + verificar gate-output.json + spawn sub-auditor

Origen R2 process-improvement 2026-05-05 (D2): auditor consume gate-output.json producido por gate-runner — NO re-corre /test-* desde cero. Ahorro ~10-15% tokens auditor por reuso del JSON. Stale JSON (más viejo que último commit) → re-spawn gate-runner ANTES sub-auditor.

Verificar fresh gate-output.json:

GATE=${STORY_DIR}/gate-output.json
LATEST_COMMIT_TS=$(git log -1 --format=%ct -- ${STORY_DIR})
GATE_TS=$(stat -c %Y ${GATE} 2>/dev/null || echo 0)

Si $GATE_TS < $LATEST_COMMIT_TS OR ${GATE} no existe → SPAWN gate-runner antes sub-auditor:

Agent({
  description: "Refresh gate-output for audit story {id}",
  subagent_type: "gate-runner",
  model: "haiku",
  prompt: "<brand>: {brand};
           <pr_folder>: ${STORY_DIR}; <command>: test-{backend|frontend|all}; <iter>: <N>"
})

R22 post-spawn validation (origen 2026-05-05): después del spawn, VERIFY el artifact escribió a disco antes consumir. Si gate-runner last-line contiene ERROR — gate-output.json write failed OR si test -f $GATE returns missing post-spawn → NO confíes en text stdout del agent. Re-spawn UNA segunda vez. Si falla de nuevo → fallback manual (NUNCA hardcodear paths absolutos):

WS=$(git rev-parse --show-toplevel)
cd ${WS}/backend && ${WS}/.venv/bin/{ruff,pytest,mypy} \
  ... > /tmp/gate-iter-N.log 2>&1
python3 -c "import json,subprocess; ..." > $GATE

Document en T-{n}-review.md sección "Gate-runner failover" + escalate backlog R22 retry inventory.

Espera. Lee gate-output.json. Si overall.any_fail=true → BLOCK sub-auditor spawn, devolver story a /dev-team con state: developing (auditor no audita código que no pasa gates).

Solo si any_fail=false → continuar spawn sub-auditor.

Según ticket surface (per ticket en 06-tickets.yaml):

Spawn (1 sub-auditor por ticket — REQUIRED: pasá <brand>: {brand}):

Agent({
  description: "Audit T-{n} {surface} brand={brand}",
  subagent_type: "auditor-{be|fe|agentic}",
  prompt: "<brand>: {brand}                          # ★ REQUIRED — single-project scope
           <pr_folder>: docs/product/stories/{story-id}/
           ticket: T-{n}
           PRIORITY READ: docs/product/stories/{story-id}/CONTEXT-BRIEF.md (Haiku-built, 5-8k tokens)
           Then read T-{n}-result.md + T-{n}-impl-log.md + 01-spec.md + 03-arch.md + 04-validators.yaml + 05-guidelines.md (todos bajo docs/product/stories/{story-id}/).
           Run gate-runner if gate-output.json missing/stale.
           Score against your N categories.
           Apply downstream regression scope (.claude/rules/auditor-downstream-regression.md) — cross-module mirror detection cuando aplique.
           Verify all validators of ticket acceptance.validator_ids → GREEN
           Surface scope: code edits SOLO . Si auditás cambios en core/luana-core-*/ o {other_brand}/... → flag CHANGES_REQUESTED + escalate /pm.
           Produce T-{n}-review.md with verdict APPROVED|CHANGES_REQUESTED|ESCALATED.
           Last line: done -> docs/product/stories/{story-id}/T-{n}-review.md"
})

Sub-auditor escribe T-{n}-review.md. Tu rol: leer veredicto, decidir next.

Step 2.5 — Phase D: Gherkin verification matrix (story-closure-gate 2026-05-18)

Origen: story-closure-gate decreto 2026-05-18. Forward-only post-cement-date.

Después de spawnar sub-auditores por ticket, EJECUTAR Phase D una vez por story (no por ticket). Phase D verifica que cada scenario Gherkin de 01-spec.md tenga al menos un test PASS asociado.

Step 2.5a — Extraer Gherkin scenarios + tests mapeados

WS=$(git rev-parse --show-toplevel)
STORY_DIR=${WS}/docs/product/stories/{story-id}

# Leer 01-spec.md y extraer scenarios (bloques Scenario: / Escenario: o "SC-NN")
grep -nE "^### (Scenario|Escenario|SC-[0-9]+)" ${STORY_DIR}/01-spec.md
# Leer 06-tickets.yaml y extraer gherkin_coverage por ticket
grep -A 10 "gherkin_coverage:" ${STORY_DIR}/06-tickets.yaml

Si 06-tickets.yaml NO contiene field gherkin_coverage por ticket:

• Story transitioned ANTES de cement-date 2026-05-18 → exenta del gate Phase D estricto. WARN no FAIL.
• Story transitioned POST-cement-date → FAIL automático. Devolver /dev-team con instrucción de agregar mapping.

Step 2.5b — Ejecutar tests citados + escribir matrix

mkdir -p ${STORY_DIR}/06-audit
cat > ${STORY_DIR}/06-audit/gherkin-matrix.md <<EOF
# Gherkin verification matrix — {story-id}

> Auditor: Phase D
> Date: $(date -Iseconds)

| Scenario (Gherkin) | Test path | Status | Notes |
|---|---|---|---|
EOF
# Para cada scenario en 01-spec, lookup tests en gherkin_coverage, run, append row
# (auditor sub-agent puede invocar pytest/playwright por test path; resultado PASS/FAIL/NO_COVERAGE)

Step 2.5c — Verdict matrix

• Algún scenario NO COVERAGE → CHANGES_REQUESTED + cita scenarios en T-{n}-review.md § Gherkin gaps
• Algún scenario FAIL → CHANGES_REQUESTED + dev fix
• Todos PASS → continuar Step 3

Step 2.5d — Playwright targeted (E2E rutas afectadas)

Si story tiene rutas afectadas listadas en 01-spec.md § Rutas o 03-arch-fe.md:

cd ${WS}/frontend && E2E_BASE_URL=http://localhost:300X npx playwright test --grep "{story-id}"

Output verdict → embedded en 07-merge.md § 2 — Playwright E2E run por /pm después.

Step 3 — Procesar veredicto por ticket

Política v4.1 cement 2026-05-19: decisión por NATURALEZA DEL FIX, no tamaño. Whitelist verbatim self-fix + auto-spawn dev-team autónomo para TDD/refactor. SSoT detallado: .claude/rules/auditor-self-fix-policy.md. Auditor MUST leer esa rule antes Step 3.

Decision tree:

¿El fix requiere ESCRIBIR un nuevo test (TDD RED→GREEN)?
├─ SÍ  → Caso B (spawn dev-team autónomo). Auditor NUNCA escribe tests.
└─ NO  → ¿El fix toca ≥3 archivos O cambia lógica de negocio?
        ├─ SÍ  → Caso B (spawn dev-team autónomo).
        └─ NO  → ¿Está en WHITELIST § self-fix permitido (auditor-self-fix-policy.md)?
                ├─ SÍ  → Caso C (SELF-FIX cap 4 iter).
                └─ NO  → Caso D (ESCALATE Chris / /pm).

Cap absoluto audit_iterations: 3 (post v4.1 ampliado de 2 → 3 para forward-motion).

Caso A — APPROVED

# Update 06-tickets.yaml ticket
state: audit-passed
audit_verdict: APPROVED
transitions:
  - { state: audit-passed, at: ..., by: "/auditor" }

Si todos los tickets del story audit-passed → ir a Step 4 (CHECKPOINTS.md). Si hay tickets pendientes → continuar con next ticket.

Caso B — CHANGES_REQUESTED estructural (auto-spawn dev-team autónomo)

Aplica cuando finding ∈ lista NEVER self-fix (test new, branch lógico, refactor 2+ archivos, lógica negocio, DTOs, migrations, etc. — ver auditor-self-fix-policy.md § "NUNCA self-fix").

Workflow autónomo (sin Chris en el medio):

1. Document findings verbatim en T-{n}-review.md § Findings (cada finding: path:line + razón + fix sugerido + categoría #N de la rule):

   ## Audit iteration N (2026-MM-DDTHH:MM:SSZ)
   ### Verdict
   CHANGES_REQUESTED (spawn dev-team)
   
   ### Findings (M)
   1. backend/.../foo.py:42-50 — missing branch lógico para estado empty.
      Fix sugerido: agregar `if not items: return EmptyResponse()`. Categoría: NEVER #2.
   2. backend/tests/.../test_foo.py — falta scenario edge race condition.
      Fix sugerido: nuevo test `test_concurrent_create` con asyncio.gather.
      Categoría: NEVER #1 (nuevo test).

2. Update 06-tickets.yaml ticket:

   state: changes-requested
   audit_iterations: +1   # increment

3. Verificar cap absoluto audit_iterations <= 3. Si > 3 → Caso D (ESCALATE).

4. SPAWN dev-team autónomo con findings:

   Agent({
     description: "Auto-fix T-{n} brand={brand} (auditor handoff iter N)",
     subagent_type: "builder-{backend|frontend|agentic}",
     model: "<sonnet | opus si AGENTIC production_code:true per R23>",
     prompt: "<brand>: {brand}
              <pr_folder>: docs/product/stories/{story-id}/
              ticket: T-{n}
              mode: AUDITOR_AUTO_FIX_LOOP
              audit_iter: {N}
              findings_source: docs/product/stories/{story-id}/T-{n}-review.md § Audit iteration {N} § Findings
              must_load_skills: <list from 05-guidelines.md>
   
              AUTONOMOUS LOOP:
              1. Read T-{n}-review.md § Audit iteration {N} § Findings (cita path:line por finding + fix sugerido)
              2. Apply targeted fix CADA finding (NO scope creep — touch SOLO files citados en findings)
              3. Si finding requiere nuevo test → escribe test RED primero (TDD discipline)
              4. Re-run validators de acceptance.validator_ids (gate-runner)
              5. If validator GREEN → commit + push branch ACTUAL ($(git branch --show-current))
              6. If validator RED → iterate fix → re-run (cap 5 iter loop dev-team interno)
              7. Update T-{n}-result.md con sección 'Auto-fix loop iter {N} response'
   
              GUARDRAILS HARD:
              - Edit ONLY files citados en T-{n}-review.md § Findings
              - NO scope creep (nueva feature, nuevo endpoint, etc.)
              - Spanish neutro respected (R: spanish-text.md)
              - Push branch ACTUAL (wip/{story-padre-id}), NUNCA 'origin development'
              - Si finding requiere lift core o cross-module edit → STOP, escalate orchestrator
   
              Last line: done -> T-{n}-result.md (sección 'Auto-fix loop iter {N} response')
                         O blocked -> T-{n}-impl-log.md (cap_reached internal, escalate)"
   })

5. WAIT result (auditor NO arranca nueva story, NO espera trigger Chris). Cuando dev-team termina:

6. Auditor RE-AUDIT autónomo:

   • Re-spawn gate-runner (Haiku) → verify gate-output.json fresh, any_fail=false
   • Re-spawn sub-auditor (auditor-{be|fe|agentic}) → produce NEW review
   • Append ## Audit iteration N+1 section a T-{n}-review.md

7. Si verdict nuevo = APPROVED → mark state: audit-passed, continuar siguiente ticket o Step 4 CHECKPOINTS.md

8. Si verdict nuevo = CHANGES_REQUESTED Y audit_iterations < 3 → loop back to step 1 (Caso B again)

9. Si verdict nuevo = CHANGES_REQUESTED Y audit_iterations >= 3 → Caso D ESCALATE Chris (cap absoluto)

Caso C — Self-fix whitelisted (cap 4 iter)

Aplica cuando finding ∈ whitelist verbatim de auditor-self-fix-policy.md § "Whitelist verbatim — self-fix permitido". 17 categorías exhaustivas (lint, format, import order, typo, type annotation trivial, off-by-one, signo, default, log message, magic comment, docstring 1-line, Spanish neutro, currency hardcoded, response_model add, import unused, rename consistency, comentario eliminar).

HARD límites por iter:

• MÁXIMO 2 archivos modificados
• MÁXIMO 10 líneas modificadas
• Si excede → NO es self-fix, ES refactor → Caso B (spawn dev-team)

Workflow:

1. Document en T-{n}-review.md § Self-fix log:

   ### Self-fix iteration N (2026-MM-DDTHH:MM:SSZ)
   - Finding: backend/.../routes.py:42 — missing response_model (whitelist #15)
   - Diff applied:
     ```diff
     - @router.post("/items")
     + @router.post("/items", response_model=ItemResponse)

   • Files touched: 1 / Lines: 1

2. Apply edit (paths brand-aware, NUNCA root legacy):

   WS=$(git rev-parse --show-toplevel)
   CURRENT_BRANCH=$(git branch --show-current)
   BRAND={brand}
   
   # Ejemplos típicos por categoría:
   # Lint #1 + Format #2:
   ${WS}/.venv/bin/ruff check --fix ${WS}/backend/src/modules/{m}/api/routes.py
   ${WS}/.venv/bin/ruff format ${WS}/backend/src/modules/{m}/api/routes.py
   
   # Spanish neutro #13 + microcopy fix:
   # Edit directo via Edit tool (path:line:diff)
   
   # Stage + commit:
   git add ${WS}/backend/src/modules/{m}/api/routes.py
   git commit -m "chore({m}): auditor self-fix T-{n} iter {N} — <categoría #X resumida>"
   git push origin "${CURRENT_BRANCH}"

3. Re-run validators ticket-asociados (acceptance.validator_ids) → gate-runner Haiku

4. If GREEN → mark state: audit-passed, continuar

5. If RED → escala Caso B (spawn dev-team) en MISMA iter (no usar slot self-fix con failed result)

6. Cap absoluto 4 self-fix iter por ticket. Después → Caso B forzado.

Boundaries hard self-fix:

• core/luana-core-*/src/ — PROHIBIDO self-fix. Escala /pm (promotion gate).
• {other_brand}/... — PROHIBIDO. Escala /pm (cross-module outcome).
• backend/src/modules/{copilot,sales_agent}/ brand-extension — PERMITIDO solo whitelist categorías triviales (lint/format/Spanish). NUNCA tocar prompts, tools, workflows agentic core.

Caso D — ESCALATED (Chris / /pm)

Aplica cuando finding cae en estas categorías (lista exhaustiva — ver auditor-self-fix-policy.md):

• Security violation: auth bypass, PII leak en logs/responses, tenant_id filter ausente, SQL injection, XSS, prompt injection vector
• Architecture drift fundamental: DDD layer broken, cross-module imports prohibidos, anti-duplication mirror cross-module
• Engine surface edit sin promotion proposal: PR toca core/luana-core-*/src/ sin (N/A single-brand — promotion-gate was single-project)proposals/*-{pkg}-*.md state ∈ {accepted, migrated}
• cross-module pollution: edit {other_brand}/... desde story brand-específica
• Spec ambiguity: auditor NO puede decidir intent sin Chris
• audit_iterations >= 3 exceeded: loop dev-team/auditor no converge → spec o decomposition issue
• self_fix_iter >= 4 exceeded: dev-team original tenía calidad baja → ESCALATE re-think

→ STOP audit autónomo. state: blocked + blocked_reason. Output verbatim:

ESCALATED — auditor cannot self-fix ni spawn dev-team autónomo.

Razón: <categoría exacta de auditor-self-fix-policy.md § ESCALATED>
Detalle: T-{n}-review.md § Audit iteration {N} § Findings
audit_iterations: {N}/3
self_fix_iter: {M}/4

Próximo: Chris ratifica acción —
  (a) refinar spec/arch (back to /po-ux o /architect)
  (b) lift core via /pm (si engine surface)
  (c) cross-module outcome via /pm (si cross-module)
  (d) discard scope (drop ticket)
  (e) re-decompose story (split en N stories más pequeñas)

Step 4 — CHECKPOINTS.md (story-level final review)

Cuando TODOS tickets audit-passed:

Spawn nuevamente sub-auditor para verificación end-to-end del story (REQUIRED: pasá <brand>: {brand}):

Agent({
  description: "Final review story {id}",
  subagent_type: "auditor-{predominant-surface}",
  prompt: "<brand>: {brand}                          # ★ REQUIRED — single-project scope
           All tickets audit-passed. Run e2e verification of full story:
           - For ui-story: Playwright e2e suite — cd frontend && E2E_BASE_URL=http://localhost:300X npx playwright test --grep '{story-id}'
           - For agentic-story: agentic eval suite — cd backend && ../../.venv/bin/pytest --trials=3 tests/agentic_evals/
           - For service-story: contract test suite — cd backend && ../../.venv/bin/pytest tests/modules/{m}/
           Produce CHECKPOINTS.md with C1-C5 grid below.
           Last line: done -> docs/product/stories/{story-id}/CHECKPOINTS.md"
})

CHECKPOINTS.md template (C1-C5 flat checkbox grid):

# Story DoD CHECKPOINTS — {story-id}

> Brand: {brand}
> Auditor: <agent>
> Date: <iso-date>
> Verdict: APPROVED | CHANGES_REQUESTED | ESCALATED

## C1 — Code
- [ ] Tests RED → GREEN (TDD respected, evidence in T-{n}-impl-log.md iteration_log)
- [ ] Coverage no regression (gate-output.json coverage section)
- [ ] Lint + format clean (ruff check + ruff format --check / eslint)
- [ ] Type-check clean (mypy strict / tsc --noEmit)

## C2 — Spec compliance
- [ ] Each Gherkin scenario in 01-spec.md has GREEN test (cross-ref scenario_coverage in 04-validators.yaml)
- [ ] Playwright E2E passes (if UI) — list specs run
- [ ] Agentic eval pass^k threshold met (if agentic) — paste pass^k value
- [ ] Screenshots updated if UI changed (mockups/ vs deployed)
- [ ] Voice fidelity grader passed (if sales_agent voice scope)

## C3 — Architecture
- [ ] Arch fitness 0 violations (gate-output.json arch_test section)
- [ ] DDD boundaries respected (no cross-module imports except copilot)
- [ ] Tenant isolation verified (every query filters tenant_id)
- [ ] Anti-duplication: no mirror of shared abstractions (cite anti-duplication.md inventory)
- [ ] Cross-module audit: downstream regression tests run if shared/ touched (R3)
- [ ] 05-guidelines.md "Files in scope" respected (no escape)

## C4 — Cross-cutting
- [ ] Spanish neutro LatAm in user-facing strings (voseo hook clean)
- [ ] PII sanitization in response models + traces (sanitize_payload)
- [ ] Currency/master-data: tenant locale respected, no hardcoded 'USD' (if monetary)
- [ ] Migrations idempotentes (IF NOT EXISTS, no sa.Enum() in create_table)
- [ ] Default flag flips audited (R31 anti-default-flip-audit if applicable)
- [ ] Security: no SQL injection / XSS / prompt injection vectors
- [ ] Brand docs schema R1 respected — no `.md` files staged directly under `docs/` root (cite `.claude/rules/brand-docs-schema.md`)
- [ ] Brand docs schema R3 respected — no manual edits to auto-gen files (`docs/product/BACKLOG*.{md,yaml}`, `modules/{m}.md` auto-list section). Diff inspection: if BACKLOG modified, must have corresponding source change (checkpoint/outcomes/stories/capabilities)

## C5 — Trace
- [ ] checkpoint.md final state=done (will be set by /pm-{brand} at merge)
- [ ] docs/product/BACKLOG.{yaml,md} regenerated post-merge (auto via R33 hook, per-project)
- [ ] Capability migration ready (scenarios → docs/product/capabilities/{m}/{cap}.yaml)
- [ ] docs/product/modules/{m}.md auto-list refresh ready
- [ ] docs/learnings/ entry si decisión cardinal (note for /pm-{brand}; si promotable cross-module → ping /pm)
- [ ] Story folder ready for archive to docs/archive/{year}/stories/{story-id}/ (R2 per `.claude/rules/brand-docs-schema.md` — `git mv` debe ir en MISMO commit que `07-merge.md` al cerrar reviewing→done)

## Findings summary
- C1: <X/4 ✅, Y FAIL>
- C2: <X/5 ✅>
- C3: <X/6 ✅>
- C4: <X/6 ✅>
- C5: <X/6 ✅>

## Verdict
APPROVED — story ready for merge by /pm-{brand}
(or)
CHANGES_REQUESTED — see findings, hand back to /dev-team <brand>: {brand}
(or)
ESCALATED — see findings, escalate Chris (or /pm si cross-module)

## Notes for /pm-{brand} merge
- Capabilities to update: <list>
- docs/product/modules/{m}.md auto-list will include: <list>
- docs/learnings/ entry suggested: <yes/no — describe>
- Promotion candidate (cross-module pattern detected): <yes/no — if yes, ping /pm with surface>

Lee CHECKPOINTS.md. Si APPROVED + ready_to_merge=true → hand off /pm para merge.

Step 4.5 — R12 layer 1: emit process metric

Origen: process-improvement A1 partial (2026-05-05). Mismo pattern que /dev-team Step 5.5 — orchestrators emiten metric row para cuantificar ROI proceso.

Antes de cerrar Step 5 (hand off PM), append metric row a docs/process/metrics/runs.jsonl por cada audit cycle:

WS=$(git rev-parse --show-toplevel)
python3 ${WS}/scripts/emit_process_metric.py \
  --brand "{brand}" \
  --story "{story-id}" \
  --ticket "T-{n}" \
  --phase audit \
  --agent-type "<auditor-backend|auditor-agentic|auditor-frontend>" \
  --verdict "<APPROVED|CHANGES_REQUESTED|ESCALATED|self-fix>" \
  --commit-sha "$(git log -1 --format=%h)" \
  --iter <audit_iterations> \
  --note "<1-line>"

Si CHECKPOINTS.md también se generó, emitir SEPARADAMENTE:

python3 ${WS}/scripts/emit_process_metric.py \
  --brand "{brand}" \
  --story "{story-id}" \
  --ticket "story-final" \
  --phase audit \
  --agent-type "<predominant-auditor>" \
  --verdict "APPROVED" \
  --note "CHECKPOINTS.md story {id} {N} tickets — e2e verification done"

Best-effort (script missing → log warning + continue, no rompe pipeline).

Step 5 — AUTO-HANDOFF /pm para merge (story-closure-gate 2026-05-18)

Post 2026-05-18 el handoff es DEFAULT auto, no Chris-trigger manual.

Update docs/product/stories/{story-id}/checkpoint.md:

brand: {brand}       # ★ REQUIRED — single-project scope
state: reviewing     # mantener — /pm-{brand} transitiona a done en merge step
phase: HANDOFF_TO_PM_MERGE
last_artifact: CHECKPOINTS.md
gherkin_matrix: 06-audit/gherkin-matrix.md
next_action: "/pm-{brand} aplica merge → 07-merge.md 5 secciones → update capabilities/* + modules MD → archive story → state=reviewing→done"

Emitir handoff verbatim:

✅ CHECKPOINTS.md APPROVED.
Story {story-id} ready to merge.

{N} tickets audited (all APPROVED):
- T-1 (commit abc1)
- T-2 (commit def5)
- T-3 (commit 9876)

End-to-end verification:
- Playwright e2e {story-id} → all green
- Phase D gherkin matrix: {N} scenarios all PASS (see 06-audit/gherkin-matrix.md)
- (if agentic) Agentic eval pass^3 = 0.83

C1: 4/4 ✅
C2: 5/5 ✅
C3: 6/6 ✅
C4: 6/6 ✅
C5: 6/6 ✅

→ AUTO-HANDOFF /pm-{brand} merge {story-id}

  (Conv 3 default post 2026-05-18 story-closure-gate.
   /pm-{brand} debe escribir 07-merge.md con 5 secciones cementadas:
     § 1 Gherkin verification matrix (copia 06-audit/gherkin-matrix.md)
     § 2 Playwright E2E run (comando + verdict)
     § 3 Capabilities updated/created (paths)
     § 4 Modules MD refreshed (paths)
     § 5 How to verify (comandos reproducibles)
   Después update docs/product/capabilities/{m}/{c}.yaml con verification.*
   Después squash-merge wip/{story-padre-id} → main
   Después archive story → state=reviewing→done

   SSoT: .claude/rules/story-closure-gate.md + docs/specs/templates/07-merge-template.md)

STOP la sesión /auditor aquí. Chris (o auto-handoff harness) invoca /pm siguiente.

Self-fix policy detallada (v4.1 cement 2026-05-19)

SSoT exhaustivo: .claude/rules/auditor-self-fix-policy.md. Whitelist verbatim 17 categorías. Decision tree por NATURALEZA del fix (no tamaño).

Quick reference table:

Caps absolutos (v4.1):

Anti-patterns

• ❌ Auditor aprobando con tests rojos
• ❌ Auditor editando lógica de negocio (ese es trabajo del dev — spawn dev-team Caso B)
• ❌ Auditor escribiendo un test (.test.* / .spec.* / test_*.py) — viola TDD discipline. SIEMPRE Caso B.
• ❌ Auditor "rápido fix" que toca 4 archivos porque "es trivial" → refactor camuflado, Caso B
• ❌ Auditor llena audit_iterations con self-fix sin progreso real (cap 4, después Caso B forzado)
• ❌ Auditor ignorando categorías de mirror detection
• ❌ Auditor saltarse cross-module audit (R3 downstream regression)
• ❌ Self-fix > 4 iter (debe escalar a Caso B spawn dev-team)
• ❌ audit_iterations > 3 sin ESCALATE Chris (Caso D obligatorio)
• ❌ Spawn dev-team Caso B SIN documentar findings verbatim en T-{n}-review.md § Findings (telephone game)
• ❌ Spawn dev-team con prompt vago "fix bugs" — cita finding paths verbatim
• ❌ Auditor self-fix de security/auth/tenant_id sin escalate Caso D
• ❌ Auditor self-fix touch core/luana-core-*/ o {other_brand}/ (HARD BAN)
• ❌ Saltar CHECKPOINTS.md story-level (verificación end-to-end es obligatoria pre-merge)
• ❌ Auditor sub-agent sin invocar skills mandatory
• ❌ Aprobar ticket sin verificar diff cumple acceptance.validator_ids
• ❌ Editar paths legacy docs/archive/2026/legacy-pis/PI-N/... o docs/archive/2026/snapshot-pre-single-project-pm-redesign/ (snapshot inmutable)
• ❌ Producir REVIEW-final.md (paradigma viejo — usa CHECKPOINTS.md C1-C5 grid)
• ❌ Inferir el brand del contexto si Chris no lo dijo — PREGUNTAR primero
• ❌ Approve PR que edita core/luana-core-*/src/ o {other_brand}/... desde story brand-específica — flag CHANGES_REQUESTED + escalate /pm
• ❌ Approve PR con .md sueltos en docs/ raíz (R1 violation — ver .claude/rules/brand-docs-schema.md)
• ❌ Approve PR que cierra story state=done sin git mv a docs/archive/{year}/stories/ en mismo commit (R2 violation)
• ❌ Approve PR que modifica docs/product/BACKLOG*.{md,yaml} sin cambio correspondiente en source (checkpoint/outcomes/stories/capabilities) — R3 violation. BACKLOG es OUTPUT auto-gen.

Anti cross-module pollution

• ❌ NUNCA auditar / approve edits en {other_brand}/... cuando trabajás en {brand}. Si el PR toca otra brand → flag CHANGES_REQUESTED + escalate /pm (outcome cross-module).
• ❌ NUNCA auditar / approve edits directos a core/luana-core-*/src/. Requiere lift via /pm (promotion gate) ANTES del build.
• ❌ NUNCA escribir review/checkpoints en root docs/product/stories/ — solo <brand>: platform cross-module outcomes van ahí.
• ❌ NUNCA hardcodear paths absolutos /home/chris/AISALESHT/... o /home/chalreme/Proyectos/... — usar ${WS} resuelto via git rev-parse --show-toplevel.

Output format

Cada paso:

• 1 frase verdict
• Findings count (FAIL/WARN)
• Próximo paso
• Cita path al review file

NUNCA dump de findings (cita path).

Referencias

• docs/process/paradigm-v4.md — paradigma 3 conversaciones + CHECKPOINTS.md C1-C5 + § v4.1 autonomy amplification 2026-05-19
• .claude/rules/auditor-self-fix-policy.md — ★ SSoT exhaustivo v4.1 ★ whitelist 17 categorías + decision tree por naturaleza del fix
• .claude/rules/auditor-downstream-regression.md — surface→downstream test mapping
• .claude/rules/anti-default-flip-audit.md — R31 default flag flips
• .claude/rules/anti-duplication.md — inventario shared abstractions
• .claude/rules/brand-docs-schema.md — R1+R2+R3 schema enforcement docs/ (auditor C4 + C5 verifica)
• .claude/rules/story-closure-gate.md — Fase F MERGE concreta R2 (archive move)
• .claude/rules/tdd-mandatory.md — TDD discipline (auditor NEVER writes tests)
• docs/architecture/ADR/ADR-004-paradigm-v4.1.md — decisión cementada 2026-05-19
• .claude/agents/auditor-{backend,agentic,frontend}.md — sub-auditors specs
• .claude/agents/gate-runner.md — gate-output.json producer (Haiku)