From 5335f69b43dc56d740e67f19799b79e57f789b19 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Sun, 2 Aug 2026 23:02:53 +0000
Subject: [PATCH 1/6] =?UTF-8?q?B134=20=E2=80=94=20motivo=20opcional=20(ten?=
 =?UTF-8?q?d=C3=AAncia=20+=20n=C3=ADvel);=20remove=20reversalSignals?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Make engagement level note optional in schema and UI
- Remove reversalSignals field from popover, action snapshot and DB
- Add data migration to strip reversalSignals from movimento snapshots
- Wizard trend note step no longer requires text; labels show (opcional)

Co-authored-by: Francisco Solla <fsolla@users.noreply.github.com>
---
 .../motivo-opcional-tendencia-e-nivel-impl.md | 64 +++++++++++++++++++
 .../campanha/actions/municipality.ts          |  5 +-
 .../MunicipalityListLevelControl.tsx          | 29 ++-------
 .../municipality/WizardTrendNoteStep.tsx      |  3 +-
 src/lib/schemas/municipality.ts               |  8 +--
 ...30000_strip_engagement_reversal_signals.ts | 23 +++++++
 src/migrations/index.ts                       |  6 ++
 ...ignMunicipalityEngagementLevel.int.spec.ts | 44 ++++++++++---
 ...ementReversalSignalsMigration.unit.spec.ts | 23 +++++++
 9 files changed, 162 insertions(+), 43 deletions(-)
 create mode 100644 docs/plans/motivo-opcional-tendencia-e-nivel-impl.md
 create mode 100644 src/migrations/20260802_230000_strip_engagement_reversal_signals.ts
 create mode 100644 tests/unit/stripEngagementReversalSignalsMigration.unit.spec.ts

diff --git a/docs/plans/motivo-opcional-tendencia-e-nivel-impl.md b/docs/plans/motivo-opcional-tendencia-e-nivel-impl.md
new file mode 100644
index 00000000..48e5a9db
--- /dev/null
+++ b/docs/plans/motivo-opcional-tendencia-e-nivel-impl.md
@@ -0,0 +1,64 @@
+# Impl: Motivo opcional — tendência (wizard) + nível; remover voltar atrás do DB (B134)
+
+Status: aprovado
+Atualizado em: 2026-08-02
+Issue: #288
+Intenção: docs/plans/motivo-opcional-tendencia-e-nivel.md
+Appetite restante: herdado (~1 dia eng)
+
+## Leitura da intenção
+
+- **Outcome:** staff grava tendência ou nível sem texto obrigatório; Motivo permanece opcional nos dois ritos; `reversalSignals` some da UI, write path e snapshots persistidos.
+- **O que NÃO negociar:** histerese/override/choque triangulado intactos; `leader` lockdown; sem auto-save no nível; motivo vazio grava `null` (não preserva anterior); dados históricos de `reversalSignals` apagados do DB.
+- **O que reavaliar:** não há coluna dedicada — `reversalSignals` vive só no JSON `allocation_decision.snapshot`; migration é data-only, sem alterar `AllocationDecision` config.
+
+## Abordagem recomendada
+
+```mermaid
+flowchart LR
+  UI[Popover / wizard] --> schema[municipalityEngagementLevelSchema]
+  schema --> action[setMunicipalityEngagementLevelRecord]
+  action --> mun[municipality.levelNote nullable]
+  action --> ad[allocationDecision snapshot sem reversalSignals]
+  mig[migration SQL] --> ad
+```
+
+**Opções consideradas:** A remover só da UI/schema | B migration JSON strip + schema/UI/action  
+**Recomendação:** B — aceite exige apagar do banco, não só esconder.  
+**Rejeitadas:** A (órfãos no snapshot); tornar `rationale` opcional na collection (escopo desnecessário — string vazia basta quando motivo ausente).
+
+### Componentes / mudanças
+
+- **`municipalityEngagementLevelSchema`** (`src/lib/schemas/municipality.ts`): `note` → `trimmedNullableText`; remover `reversalSignals`.
+- **`setMunicipalityEngagementLevelRecord`** (`actions/municipality.ts`): snapshot sem `reversalSignals`; `rationale: note ?? ''`.
+- **`MunicipalityListLevelControl`**: um campo Motivo (opcional); `canSubmit` só exige movimento + override quando violações.
+- **`WizardTrendNoteStep`**: remover `required`; label com “(opcional)”.
+- **Migration:** `20260802_*_strip_engagement_reversal_signals` — `UPDATE allocation_decision SET snapshot = snapshot - 'reversalSignals' WHERE …`.
+- **Access / Consent:** inalterado (`canManageMunicipalityEngagementLevel`).
+
+### Dados → forma
+
+- Tendência: schema já usa `trimmedNullableText` — só UI wizard tinha `required` HTML.
+- Nível: `levelNote` nullable no município; `allocationDecision.rationale` string (vazia se sem motivo).
+
+## Fases verificáveis
+
+1. **Schema+server** — schema, action, migration, int test com motivo vazio + snapshot sem reversalSignals.
+2. **UI** — labels “(opcional)”, remover segundo textarea.
+3. **Gates** — `pnpm gate:fast`; push via `pnpm push`.
+
+## Rabbit holes / Não escopo (engenharia)
+
+- Alterar copy do glossário `campaignIntelligenceConcepts` (prosa conceitual, não o campo).
+- `rationale` required na collection — string vazia, não relaxar schema Payload.
+
+## Riscos e mitigação
+
+- **Rationale vazio rejeitado pelo Payload:** int test com `note` omitido; se falhar, usar `''` explicitamente (textarea required aceita vazio).
+- **Migration idempotente:** operador JSONB `-` só onde chave existe; log de row count.
+
+## Aceite de engenharia
+
+- [x] Aceite de produto da intenção ainda coberto
+- [x] Invariantes AGENTS/engineering-standards
+- [x] Testes de domínio previstos (int engagement level + migration unit)
diff --git a/src/app/(campaign)/campanha/actions/municipality.ts b/src/app/(campaign)/campanha/actions/municipality.ts
index 229d1ef8..79e8c596 100644
--- a/src/app/(campaign)/campanha/actions/municipality.ts
+++ b/src/app/(campaign)/campanha/actions/municipality.ts
@@ -149,7 +149,7 @@ export const setMunicipalityEngagementLevelRecord = async (
   actor: CampaignUser,
   input: MunicipalityEngagementLevelInput,
 ) => {
-  const { municipality, level, note, reversalSignals, triangulatedShock, override } =
+  const { municipality, level, note, triangulatedShock, override } =
     municipalityEngagementLevelSchema.parse(input)
 
   return withPayloadTransaction(
@@ -203,13 +203,12 @@ export const setMunicipalityEngagementLevelRecord = async (
           municipality,
           patternId: ENGAGEMENT_LEVEL_PATTERN_ID,
           outcome: 'movimento',
-          rationale: note,
+          rationale: note ?? '',
           // Only the values the decision was taken on — no document dumps
           // (the collection caps the serialized snapshot at 16 KB).
           snapshot: {
             from,
             to: level,
-            reversalSignals,
             triangulatedShock,
             violations: violations.map((violation) => violation.id),
             overridden: violations.length > 0,
diff --git a/src/components/campaign/municipality/MunicipalityListLevelControl.tsx b/src/components/campaign/municipality/MunicipalityListLevelControl.tsx
index c40cd2de..e1fa9abc 100644
--- a/src/components/campaign/municipality/MunicipalityListLevelControl.tsx
+++ b/src/components/campaign/municipality/MunicipalityListLevelControl.tsx
@@ -45,9 +45,9 @@ type MunicipalityListLevelControlProps = {
 
 /**
  * E14 — unlike the trend and estimate cells next to it, this one submits
- * explicitly: a movement carries a motivo AND the signals that would reverse
- * it, and it may need an override. Auto-saving half of that would file an
- * incomplete decision under the coordinator's name.
+ * explicitly: a movement may need an override, and the motivo is optional.
+ * Auto-saving half of that would file an incomplete decision under the
+ * coordinator's name.
  */
 export const MunicipalityListLevelControl = ({
   municipalityID,
@@ -73,7 +73,6 @@ export const MunicipalityListLevelControl = ({
   // with it the select — is not mounted.
   const [draftLevel, setDraftLevel] = useState<EngagementLevel | ''>('')
   const [note, setNote] = useState('')
-  const [reversalSignals, setReversalSignals] = useState('')
   const [triangulatedShock, setTriangulatedShock] = useState(false)
   const [override, setOverride] = useState(false)
   const [isPending, setIsPending] = useState(false)
@@ -142,7 +141,6 @@ export const MunicipalityListLevelControl = ({
   const resetDraft = () => {
     setDraftLevel(currentLevel ?? '')
     setNote('')
-    setReversalSignals('')
     setTriangulatedShock(false)
     setOverride(false)
     setErrorMessage(null)
@@ -174,7 +172,6 @@ export const MunicipalityListLevelControl = ({
           municipalityId: municipalityID,
           level: draftLevel,
           note,
-          reversalSignals,
           triangulatedShock,
           override,
         },
@@ -205,11 +202,7 @@ export const MunicipalityListLevelControl = ({
     }
   }
 
-  const canSubmit =
-    isMovement &&
-    note.trim().length > 0 &&
-    reversalSignals.trim().length > 0 &&
-    (violations.length === 0 || override)
+  const canSubmit = isMovement && (violations.length === 0 || override)
   const fieldId = (suffix: string) => `municipality-list-level-${suffix}-${municipalityID}`
   const isSheet = variant === 'sheet'
   const submitButton = (
@@ -283,7 +276,7 @@ export const MunicipalityListLevelControl = ({
           </NativeSelect>
         </Field>
         <Field>
-          <FieldLabel htmlFor={fieldId('note')}>Motivo</FieldLabel>
+          <FieldLabel htmlFor={fieldId('note')}>Motivo (opcional)</FieldLabel>
           <Textarea
             id={fieldId('note')}
             value={note}
@@ -294,18 +287,6 @@ export const MunicipalityListLevelControl = ({
             placeholder="O que mudou para justificar este nível?"
           />
         </Field>
-        <Field>
-          <FieldLabel htmlFor={fieldId('reversal')}>O que faria voltar atrás</FieldLabel>
-          <Textarea
-            id={fieldId('reversal')}
-            value={reversalSignals}
-            onChange={(event) => setReversalSignals(event.target.value)}
-            maxLength={ENGAGEMENT_LEVEL_TEXT_MAX_LENGTH}
-            rows={2}
-            className="min-h-16 resize-y"
-            placeholder="Sinais que fariam rever esta decisão."
-          />
-        </Field>
         {isJump ? (
           <Field orientation="horizontal" className={isSheet ? 'min-h-11' : undefined}>
             <Checkbox
diff --git a/src/components/campaign/municipality/WizardTrendNoteStep.tsx b/src/components/campaign/municipality/WizardTrendNoteStep.tsx
index 7d69edf9..05fb00f4 100644
--- a/src/components/campaign/municipality/WizardTrendNoteStep.tsx
+++ b/src/components/campaign/municipality/WizardTrendNoteStep.tsx
@@ -97,7 +97,7 @@ export const WizardTrendNoteStep = ({
 
         <div className="flex flex-col gap-2">
           <label htmlFor="wizard-trend-note" className="text-sm font-medium">
-            Por que mudar a tendência?
+            Por que mudar a tendência? (opcional)
           </label>
           <Textarea
             id="wizard-trend-note"
@@ -106,7 +106,6 @@ export const WizardTrendNoteStep = ({
             onChange={(event) => setNote(event.target.value)}
             rows={5}
             maxLength={2000}
-            required
             disabled={isPending}
             autoFocus
             className="min-h-28"
diff --git a/src/lib/schemas/municipality.ts b/src/lib/schemas/municipality.ts
index dcd68a2b..c67c056b 100644
--- a/src/lib/schemas/municipality.ts
+++ b/src/lib/schemas/municipality.ts
@@ -89,15 +89,13 @@ export const MUNICIPALITY_ENGAGEMENT_LEVEL_UNRESTRICTED_MESSAGE =
   'Somente a coordenação geral ou o candidato move o nível de envolvimento.'
 
 /**
- * E14 — a movement is never just the new level: the motivo and the signals
- * that would reverse it are what make the decision auditable later, so both
- * are required by the schema rather than by the form alone.
+ * E14 — a movement records the new level plus an optional motivo; hysteresis,
+ * triangulated shock and override stay on the write path (B134).
  */
 export const municipalityEngagementLevelSchema = z.object({
   municipality: positiveRelationshipId,
   level: z.enum(engagementLevels),
-  note: z.string().trim().min(1).max(ENGAGEMENT_LEVEL_TEXT_MAX_LENGTH),
-  reversalSignals: z.string().trim().min(1).max(ENGAGEMENT_LEVEL_TEXT_MAX_LENGTH),
+  note: trimmedNullableText(ENGAGEMENT_LEVEL_TEXT_MAX_LENGTH),
   /** Licenses a two-level jump (research §6.8). */
   triangulatedShock: z.boolean().default(false),
   /** Accepts the listed violations knowingly; recorded in the decision snapshot. */
diff --git a/src/migrations/20260802_230000_strip_engagement_reversal_signals.ts b/src/migrations/20260802_230000_strip_engagement_reversal_signals.ts
new file mode 100644
index 00000000..564a3440
--- /dev/null
+++ b/src/migrations/20260802_230000_strip_engagement_reversal_signals.ts
@@ -0,0 +1,23 @@
+import { MigrateDownArgs, MigrateUpArgs, sql } from '@payloadcms/db-postgres'
+
+export async function up({ db }: MigrateUpArgs): Promise<void> {
+  await db.execute(sql`
+    DO $$
+    DECLARE
+      affected integer;
+    BEGIN
+      UPDATE allocation_decision
+      SET snapshot = snapshot - 'reversalSignals'
+      WHERE outcome = 'movimento'
+        AND snapshot ? 'reversalSignals';
+
+      GET DIAGNOSTICS affected = ROW_COUNT;
+      RAISE NOTICE 'strip_engagement_reversal_signals: removed reversalSignals from % row(s)', affected;
+    END $$;
+  `)
+}
+
+export async function down({ db }: MigrateDownArgs): Promise<void> {
+  // Historical reversal text was deliberately dropped (B134); it cannot be restored.
+  await db.execute(sql`SELECT 1`)
+}
diff --git a/src/migrations/index.ts b/src/migrations/index.ts
index d0719b74..ffff7333 100644
--- a/src/migrations/index.ts
+++ b/src/migrations/index.ts
@@ -38,6 +38,7 @@ import * as migration_20260730_010601_simplify_municipality_signal_fields from '
 import * as migration_20260730_043306_simplify_leadership_fields from './20260730_043306_simplify_leadership_fields';
 import * as migration_20260731_014319_add_campaign_notifications from './20260731_014319_add_campaign_notifications';
 import * as migration_20260801_062558_add_campaign_vote_summary_snapshot from './20260801_062558_add_campaign_vote_summary_snapshot';
+import * as migration_20260802_230000_strip_engagement_reversal_signals from './20260802_230000_strip_engagement_reversal_signals';
 
 export const migrations = [
   {
@@ -240,4 +241,9 @@ export const migrations = [
     down: migration_20260801_062558_add_campaign_vote_summary_snapshot.down,
     name: '20260801_062558_add_campaign_vote_summary_snapshot'
   },
+  {
+    up: migration_20260802_230000_strip_engagement_reversal_signals.up,
+    down: migration_20260802_230000_strip_engagement_reversal_signals.down,
+    name: '20260802_230000_strip_engagement_reversal_signals',
+  },
 ];
diff --git a/tests/int/campaignMunicipalityEngagementLevel.int.spec.ts b/tests/int/campaignMunicipalityEngagementLevel.int.spec.ts
index 92ea937a..00b1864e 100644
--- a/tests/int/campaignMunicipalityEngagementLevel.int.spec.ts
+++ b/tests/int/campaignMunicipalityEngagementLevel.int.spec.ts
@@ -41,7 +41,6 @@ describe('municipality engagement level (E14)', () => {
       municipality: municipality.id,
       level: 'n3',
       note: 'Prefeitura aliada e duas lideranças novas.',
-      reversalSignals: 'Rompimento do prefeito ou pledges abaixo de 40% da meta.',
     })
     fixtures.touchMunicipality(municipality.id)
 
@@ -61,10 +60,42 @@ describe('municipality engagement level (E14)', () => {
     expect(decision.snapshot).toMatchObject({
       from: null,
       to: 'n3',
-      reversalSignals: 'Rompimento do prefeito ou pledges abaixo de 40% da meta.',
       violations: [],
       overridden: false,
     })
+    expect(decision.snapshot).not.toHaveProperty('reversalSignals')
+  })
+
+  it('records a movement with an empty motivo (B134)', async () => {
+    const fixtures = campaignFixtures()
+    const coordinator = await fixtures.createCampaignUser('coordinator')
+    const municipality = await fixtures.getMunicipality()
+
+    await payload.update({
+      collection: 'municipality',
+      id: municipality.id,
+      data: { engagementLevel: 'n1', levelNote: 'Nota anterior.' },
+      depth: 0,
+    })
+    fixtures.touchMunicipality(municipality.id)
+
+    const updated = await setMunicipalityEngagementLevelRecord(payload, coordinator, {
+      municipality: municipality.id,
+      level: 'n2',
+      note: null,
+    })
+    fixtures.touchMunicipality(municipality.id)
+
+    expect(updated.engagementLevel).toBe('n2')
+    expect(updated.levelNote).toBeNull()
+
+    const decisions = await findDecisions(municipality.id)
+    expect(decisions.docs).toHaveLength(1)
+    const decision = decisions.docs[0]!
+    fixtures.own('allocationDecision', decision.id)
+    expect(decision.rationale).toBe('')
+    expect(decision.snapshot).toMatchObject({ from: 'n1', to: 'n2' })
+    expect(decision.snapshot).not.toHaveProperty('reversalSignals')
   })
 
   it('holds a movement that breaks the rules and writes nothing', async () => {
@@ -76,7 +107,6 @@ describe('municipality engagement level (E14)', () => {
       municipality: municipality.id,
       level: 'n1',
       note: 'Entrada no mapa como presença de mandato.',
-      reversalSignals: 'Nenhuma agenda executada no trimestre.',
     })
     fixtures.touchMunicipality(municipality.id)
 
@@ -86,7 +116,6 @@ describe('municipality engagement level (E14)', () => {
       municipality: municipality.id,
       level: 'n3',
       note: 'Achismo da semana.',
-      reversalSignals: 'Nada.',
     }).catch((error: unknown) => error)
 
     expect(blocked).toBeInstanceOf(EngagementLevelBlockedError)
@@ -115,7 +144,6 @@ describe('municipality engagement level (E14)', () => {
       municipality: municipality.id,
       level: 'n1',
       note: 'Entrada no mapa.',
-      reversalSignals: 'Agenda vazia por um trimestre.',
     })
     fixtures.touchMunicipality(municipality.id)
 
@@ -123,7 +151,6 @@ describe('municipality engagement level (E14)', () => {
       municipality: municipality.id,
       level: 'n2',
       note: 'Adversário abriu comitê e o prefeito pediu presença.',
-      reversalSignals: 'Comitê adversário fechar.',
       override: true,
     })
     expect(moved.engagementLevel).toBe('n2')
@@ -141,6 +168,7 @@ describe('municipality engagement level (E14)', () => {
       // against undoing a decision, not against deepening it.
       violations: ['dois-movimentos-no-mes'],
     })
+    expect(latest.snapshot).not.toHaveProperty('reversalSignals')
   })
 
   it('accepts a two-level jump when a triangulated shock is declared', async () => {
@@ -164,7 +192,6 @@ describe('municipality engagement level (E14)', () => {
       municipality: municipality.id,
       level: 'n3',
       note: 'Três sinais independentes de invasão na mesma semana.',
-      reversalSignals: 'Adversário recuar do território.',
       triangulatedShock: true,
     })
     expect(moved.engagementLevel).toBe('n3')
@@ -178,6 +205,7 @@ describe('municipality engagement level (E14)', () => {
       triangulatedShock: true,
       overridden: false,
     })
+    expect(decisions.docs[0]!.snapshot).not.toHaveProperty('reversalSignals')
   })
 
   it('keeps the ladder with unrestricted staff — the advisor proposes, it does not move', async () => {
@@ -191,7 +219,6 @@ describe('municipality engagement level (E14)', () => {
         municipality: municipality.id,
         level: 'n2',
         note: 'Quero subir o meu município.',
-        reversalSignals: 'Nada.',
       }),
     ).rejects.toThrow('coordenação geral ou o candidato')
 
@@ -218,7 +245,6 @@ describe('municipality engagement level (E14)', () => {
       municipality: municipality.id,
       level: 'n4',
       note: 'Prioridade máxima do ciclo.',
-      reversalSignals: 'Queda de captura por dois meses.',
     })
     fixtures.touchMunicipality(municipality.id)
     const decisions = await findDecisions(municipality.id)
diff --git a/tests/unit/stripEngagementReversalSignalsMigration.unit.spec.ts b/tests/unit/stripEngagementReversalSignalsMigration.unit.spec.ts
new file mode 100644
index 00000000..49ed38ba
--- /dev/null
+++ b/tests/unit/stripEngagementReversalSignalsMigration.unit.spec.ts
@@ -0,0 +1,23 @@
+// @vitest-environment node
+
+import { readFileSync } from 'node:fs'
+import { describe, expect, it } from 'vitest'
+
+const migration = readFileSync(
+  new URL('../../src/migrations/20260802_230000_strip_engagement_reversal_signals.ts', import.meta.url),
+  'utf8',
+)
+
+describe('strip engagement reversal signals migration (B134)', () => {
+  it('removes reversalSignals only from movimento snapshots', () => {
+    expect(migration).toContain("snapshot = snapshot - 'reversalSignals'")
+    expect(migration).toContain("outcome = 'movimento'")
+    expect(migration).toContain("snapshot ? 'reversalSignals'")
+    expect(migration).toContain('GET DIAGNOSTICS affected = ROW_COUNT')
+  })
+
+  it('does not attempt to restore dropped data on down', () => {
+    const down = migration.indexOf('export async function down')
+    expect(migration.indexOf('reversalSignals', down)).toBe(-1)
+  })
+})

From f40957f101d6d700a33214237c00cfcadea492c0 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Sun, 2 Aug 2026 23:08:52 +0000
Subject: [PATCH 2/6] =?UTF-8?q?B134=20=E2=80=94=20allow=20empty=20rational?=
 =?UTF-8?q?e=20on=20movimento=20allocation=20decisions?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Relax AllocationDecision.rationale required flag; validate in hook
- Fix empty-motivo int test to use first movement from null

Co-authored-by: Francisco Solla <fsolla@users.noreply.github.com>
---
 src/collections/AllocationDecision.ts              | 10 +++++++++-
 ...campaignMunicipalityEngagementLevel.int.spec.ts | 14 +++-----------
 2 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/src/collections/AllocationDecision.ts b/src/collections/AllocationDecision.ts
index ea83bbf0..9cec5aac 100644
--- a/src/collections/AllocationDecision.ts
+++ b/src/collections/AllocationDecision.ts
@@ -32,6 +32,13 @@ const validateAllocationDecision: CollectionBeforeValidateHook = ({
     throw new APIError('Informe a leitura alternativa ao descartar a sugestão.', 400)
   }
 
+  if (
+    nextData.outcome !== 'movimento' &&
+    (typeof nextData.rationale !== 'string' || !nextData.rationale.trim())
+  ) {
+    throw new APIError('Informe a justificativa.', 400)
+  }
+
   try {
     const serializedSnapshot = JSON.stringify(nextData.snapshot)
     if (
@@ -116,7 +123,8 @@ export const AllocationDecision: CollectionConfig = {
       name: 'rationale',
       type: 'textarea',
       label: 'Justificativa',
-      required: true,
+      // E14 movimento may omit motivo (B134); triage outcomes validate in beforeValidate.
+      required: false,
       maxLength: 2000,
     },
     {
diff --git a/tests/int/campaignMunicipalityEngagementLevel.int.spec.ts b/tests/int/campaignMunicipalityEngagementLevel.int.spec.ts
index 00b1864e..79df08b0 100644
--- a/tests/int/campaignMunicipalityEngagementLevel.int.spec.ts
+++ b/tests/int/campaignMunicipalityEngagementLevel.int.spec.ts
@@ -71,22 +71,14 @@ describe('municipality engagement level (E14)', () => {
     const coordinator = await fixtures.createCampaignUser('coordinator')
     const municipality = await fixtures.getMunicipality()
 
-    await payload.update({
-      collection: 'municipality',
-      id: municipality.id,
-      data: { engagementLevel: 'n1', levelNote: 'Nota anterior.' },
-      depth: 0,
-    })
-    fixtures.touchMunicipality(municipality.id)
-
     const updated = await setMunicipalityEngagementLevelRecord(payload, coordinator, {
       municipality: municipality.id,
-      level: 'n2',
+      level: 'n1',
       note: null,
     })
     fixtures.touchMunicipality(municipality.id)
 
-    expect(updated.engagementLevel).toBe('n2')
+    expect(updated.engagementLevel).toBe('n1')
     expect(updated.levelNote).toBeNull()
 
     const decisions = await findDecisions(municipality.id)
@@ -94,7 +86,7 @@ describe('municipality engagement level (E14)', () => {
     const decision = decisions.docs[0]!
     fixtures.own('allocationDecision', decision.id)
     expect(decision.rationale).toBe('')
-    expect(decision.snapshot).toMatchObject({ from: 'n1', to: 'n2' })
+    expect(decision.snapshot).toMatchObject({ from: null, to: 'n1' })
     expect(decision.snapshot).not.toHaveProperty('reversalSignals')
   })
 

From 974907f02393c367acd7123a6aaa92791860a832 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Sun, 2 Aug 2026 23:10:20 +0000
Subject: [PATCH 3/6] Format migration unit spec

---
 .../stripEngagementReversalSignalsMigration.unit.spec.ts     | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/tests/unit/stripEngagementReversalSignalsMigration.unit.spec.ts b/tests/unit/stripEngagementReversalSignalsMigration.unit.spec.ts
index 49ed38ba..29cbd5b9 100644
--- a/tests/unit/stripEngagementReversalSignalsMigration.unit.spec.ts
+++ b/tests/unit/stripEngagementReversalSignalsMigration.unit.spec.ts
@@ -4,7 +4,10 @@ import { readFileSync } from 'node:fs'
 import { describe, expect, it } from 'vitest'
 
 const migration = readFileSync(
-  new URL('../../src/migrations/20260802_230000_strip_engagement_reversal_signals.ts', import.meta.url),
+  new URL(
+    '../../src/migrations/20260802_230000_strip_engagement_reversal_signals.ts',
+    import.meta.url,
+  ),
   'utf8',
 )
 

From 0dc3d226468e2e12ded48d9b674272e4289ec950 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Sun, 2 Aug 2026 23:13:34 +0000
Subject: [PATCH 4/6] =?UTF-8?q?feat(nav):=20add=20Organiza=C3=A7=C3=B5es?=
 =?UTF-8?q?=20to=20staff=20sidebar=20(B144,=20#313)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Insert Organizações after Lideranças in staffNav so staff can discover
the existing /campanha/organizacoes list from the structural nav.
Leaders remain on leaderNav; isCampaignNavActive already covers list,
detail, and /nova paths.

Co-authored-by: Francisco Solla <fsolla@users.noreply.github.com>
---
 docs/plans/sidebar-organizacoes-impl.md | 61 +++++++++++++++++++++++++
 src/components/campaign/shell/nav.ts    |  2 +
 tests/unit/campaignNav.unit.spec.ts     | 38 +++++++++++++++
 3 files changed, 101 insertions(+)
 create mode 100644 docs/plans/sidebar-organizacoes-impl.md
 create mode 100644 tests/unit/campaignNav.unit.spec.ts

diff --git a/docs/plans/sidebar-organizacoes-impl.md b/docs/plans/sidebar-organizacoes-impl.md
new file mode 100644
index 00000000..54837e0a
--- /dev/null
+++ b/docs/plans/sidebar-organizacoes-impl.md
@@ -0,0 +1,61 @@
+# Impl: Sidebar — entrada para Organizações
+
+Status: aprovado
+Atualizado em: 2026-08-02
+Issue: #313
+Intenção: docs/plans/sidebar-organizacoes.md
+Appetite restante: ~0,25 dia eng (um item de nav; sem migration)
+
+## Leitura da intenção
+
+- **Outcome:** Staff (coordenador, assessor, candidato) descobre `/campanha/organizacoes` pela sidebar desktop e Sheet mobile; liderança não vê o item; destino ativo em lista, detalhe e `/nova`.
+- **O que NÃO negociar:** lockdown de `leader`; não redesenhar sidebar; não duplicar lista; href canônico `/campanha/organizacoes`.
+- **O que reavaliar:** hipótese de importar `ORGANIZATIONS_LIST_PATH` — `nav.ts` usa literais (precedente Conceitos) para não puxar módulos ao client bundle; manter literal.
+
+## Abordagem recomendada
+
+```mermaid
+flowchart LR
+  staffNav["staffNav + Organizações"] --> getCampaignNav
+  getCampaignNav --> CampaignSidebar
+  getCampaignNav --> MobileSheet["Sheet mobile"]
+  isCampaignNavActive --> Active["lista / slug / nova"]
+```
+
+**Opções consideradas:** A) item após Lideranças | B) após Dobradinhas | C) antes de Apoiadores  
+**Recomendação:** **A** — afinidade domínio orgs ↔ lideranças; alinhado à recomendação da intenção.  
+**Rejeitadas:** B/C — sem ganho de descoberta; A é o modelo mental acordado.
+
+### Componentes / mudanças
+
+- **`staffNav`** (`src/components/campaign/shell/nav.ts`): inserir `{ title: 'Organizações', href: '/campanha/organizacoes', icon: LandmarkIcon }` logo após Lideranças; import `LandmarkIcon` de lucide-react (instituições — distinto de `HandshakeIcon` e `Building2` usado em município no dashboard).
+- **Migration:** sem migration
+- **Access / Consent:** nenhum — `getCampaignNav` já exclui `leader`; staff vê por default (mesmo que Lideranças/Demandas)
+- **UI:** Impeccable B — encaixe no shell existente; `CampaignSidebar` e Sheet já consomem `getCampaignNav`; `isCampaignNavActive` já cobre paths aninhados (`/nova`, `[slug]`)
+
+### Dados → forma
+
+N/A — só navegação.
+
+## Fases verificáveis
+
+1. **Nav** — uma linha em `staffNav` + ícone
+2. **Testes** — unit: href presente para staff, ausente para leader; `isCampaignNavActive` em lista/detalhe/nova
+3. **Gates** — `pnpm gate:fast`; entrega `pnpm push`
+
+## Rabbit holes / Não escopo (engenharia)
+
+- Reordenar demais itens além do encaixe após Lideranças
+- Exportar constante de href (só `MUNICIPALITY_NAV_HREF` tem consumidor especial B18)
+- `staffSecondaryNav` — destino de trabalho, não referência
+
+## Riscos e mitigação
+
+- **Leader vê link:** mitigado — `getCampaignNav('leader')` retorna `leaderNav` separado
+- **Active state em `/nova`:** mitigado — `isCampaignNavActive` usa `pathname.startsWith(\`${href}/\`)`
+
+## Aceite de engenharia
+
+- [x] Aceite de produto da intenção ainda coberto
+- [x] Invariantes AGENTS/engineering-standards
+- [x] Testes de domínio previstos (unit) para nav + active state
diff --git a/src/components/campaign/shell/nav.ts b/src/components/campaign/shell/nav.ts
index d40aa546..63bf5a9f 100644
--- a/src/components/campaign/shell/nav.ts
+++ b/src/components/campaign/shell/nav.ts
@@ -4,6 +4,7 @@ import {
   HandshakeIcon,
   HomeIcon,
   InboxIcon,
+  LandmarkIcon,
   LayoutDashboardIcon,
   MapIcon,
   MapPinIcon,
@@ -37,6 +38,7 @@ const staffNav: CampaignNavItem[] = [
   { title: 'Municípios', href: MUNICIPALITY_NAV_HREF, icon: MapPinIcon },
   { title: 'Territórios', href: '/campanha/territorios', icon: MapIcon },
   { title: 'Lideranças', href: '/campanha/liderancas', icon: HandshakeIcon },
+  { title: 'Organizações', href: '/campanha/organizacoes', icon: LandmarkIcon },
   { title: 'Dobradinhas', href: '/campanha/dobradinhas', icon: Users2Icon },
   { title: 'Atividades', href: '/campanha/atividades', icon: CalendarDaysIcon },
   { title: 'Demandas', href: '/campanha/demandas', icon: InboxIcon },
diff --git a/tests/unit/campaignNav.unit.spec.ts b/tests/unit/campaignNav.unit.spec.ts
new file mode 100644
index 00000000..ac85f5f5
--- /dev/null
+++ b/tests/unit/campaignNav.unit.spec.ts
@@ -0,0 +1,38 @@
+// @vitest-environment node
+
+import { describe, expect, it } from 'vitest'
+
+import {
+  getCampaignNav,
+  isCampaignNavActive,
+} from '@/components/campaign/shell/nav'
+
+const ORGANIZATIONS_LIST_PATH = '/campanha/organizacoes'
+
+describe('organizations sidebar entry', () => {
+  it('is offered to staff after Lideranças', () => {
+    const hrefs = getCampaignNav('coordinator').map((item) => item.href)
+    const leadershipIndex = hrefs.indexOf('/campanha/liderancas')
+    const organizationsIndex = hrefs.indexOf(ORGANIZATIONS_LIST_PATH)
+
+    expect(organizationsIndex).toBeGreaterThan(-1)
+    expect(organizationsIndex).toBe(leadershipIndex + 1)
+  })
+
+  it('is visible to advisor and candidate', () => {
+    expect(getCampaignNav('advisor').map((item) => item.href)).toContain(ORGANIZATIONS_LIST_PATH)
+    expect(getCampaignNav('candidate').map((item) => item.href)).toContain(ORGANIZATIONS_LIST_PATH)
+  })
+
+  it('is hidden from leaders', () => {
+    expect(getCampaignNav('leader').map((item) => item.href)).not.toContain(ORGANIZATIONS_LIST_PATH)
+  })
+
+  it('marks list, detail, and nova as active', () => {
+    expect(isCampaignNavActive(ORGANIZATIONS_LIST_PATH, ORGANIZATIONS_LIST_PATH)).toBe(true)
+    expect(isCampaignNavActive('/campanha/organizacoes/sindmed', ORGANIZATIONS_LIST_PATH)).toBe(
+      true,
+    )
+    expect(isCampaignNavActive('/campanha/organizacoes/nova', ORGANIZATIONS_LIST_PATH)).toBe(true)
+  })
+})

From ea6641071ece8173a1d1498fabd5073eb83a5f25 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Sun, 2 Aug 2026 23:14:38 +0000
Subject: [PATCH 5/6] test(nav): reuse ORGANIZATIONS_LIST_PATH in sidebar spec

Co-authored-by: Francisco Solla <fsolla@users.noreply.github.com>
---
 tests/unit/campaignNav.unit.spec.ts | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/tests/unit/campaignNav.unit.spec.ts b/tests/unit/campaignNav.unit.spec.ts
index ac85f5f5..fa645355 100644
--- a/tests/unit/campaignNav.unit.spec.ts
+++ b/tests/unit/campaignNav.unit.spec.ts
@@ -2,12 +2,8 @@
 
 import { describe, expect, it } from 'vitest'
 
-import {
-  getCampaignNav,
-  isCampaignNavActive,
-} from '@/components/campaign/shell/nav'
-
-const ORGANIZATIONS_LIST_PATH = '/campanha/organizacoes'
+import { getCampaignNav, isCampaignNavActive } from '@/components/campaign/shell/nav'
+import { ORGANIZATIONS_LIST_PATH } from '@/lib/campaignQuickActionPaths'
 
 describe('organizations sidebar entry', () => {
   it('is offered to staff after Lideranças', () => {

From 7fe42a5fa5e1c12d4ddd03a08e90dec56fdc53cb Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Sun, 2 Aug 2026 23:25:50 +0000
Subject: [PATCH 6/6] test(omnibox): cover search-only helpers for knip graph
 (#313)

Knip could not see exports only referenced from client filter components;
extend B128 unit spec so CI knip stays green.
---
 tests/unit/listOmniboxB128.unit.spec.ts | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/tests/unit/listOmniboxB128.unit.spec.ts b/tests/unit/listOmniboxB128.unit.spec.ts
index 02ab4b39..9320e25e 100644
--- a/tests/unit/listOmniboxB128.unit.spec.ts
+++ b/tests/unit/listOmniboxB128.unit.spec.ts
@@ -3,6 +3,9 @@ import { describe, expect, it } from 'vitest'
 import {
   applySearchOnlyOmniboxSuggestion,
   buildSearchOnlyOmniboxChips,
+  buildSearchOnlyOmniboxSuggestions,
+  clearSearchOnlyOmnibox,
+  removeSearchOnlyOmniboxChip,
 } from '@/lib/searchOnlyListOmnibox'
 import {
   applyActivityOmniboxSuggestion,
@@ -144,5 +147,20 @@ describe('list omnibox adapters (B128)', () => {
       withPageReset: (next) => ({ ...next, page: 1 }),
     })
     expect(applied).toEqual({ kind: 'url', state: { page: 1, q: 'ana' } })
+
+    expect(buildSearchOnlyOmniboxSuggestions('x')[0]?.id).toBe('q:x')
+
+    const removed = removeSearchOnlyOmniboxChip({
+      state: { q: 'sindicato', page: 2 },
+      chipId: 'q',
+      withPageReset: (next) => ({ ...next, page: 1 }),
+    })
+    expect(removed).toEqual({ kind: 'url', state: { page: 1, q: undefined } })
+
+    const cleared = clearSearchOnlyOmnibox({
+      state: { q: 'sindicato' },
+      cleared: {},
+    })
+    expect(cleared).toEqual({ kind: 'clear', state: {} })
   })
 })