docs: classify Amare MVP Linear issues vs Gitea main (MAN-135)

Co-authored-by: Cursor <cursoragent@cursor.com>
docs: require Linear issues and auto-ship PRs (#4 )
2026-08-13 13:40:09 -03:00 · 2026-08-13 11:46:36 +00:00 · 2026-08-12 21:23:28 +00:00
5 changed files with 182 additions and 2 deletions
--- a/.gitea/PULL_REQUEST_TEMPLATE.md
+++ b/.gitea/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,19 @@
+## WHAT
+
+<!-- What changed? -->
+
+## WHY
+
+<!-- Why this change? -->
+
+## HOW
+
+<!-- How was it implemented? Include verification. -->
+
+## Linear Issue
+
+<!-- Required. Identifier + URL, e.g. MAN-133 https://linear.app/maneco-workspace/issue/MAN-133 -->
+
+## Comments
+
+<!-- Notes for reviewers. Screenshots, follow-ups, out of scope. -->
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -0,0 +1,19 @@
+## WHAT
+
+<!-- What changed? -->
+
+## WHY
+
+<!-- Why this change? -->
+
+## HOW
+
+<!-- How was it implemented? Include verification. -->
+
+## Linear Issue
+
+<!-- Required. Identifier + URL, e.g. MAN-133 https://linear.app/maneco-workspace/issue/MAN-133 -->
+
+## Comments
+
+<!-- Notes for reviewers. Screenshots, follow-ups, out of scope. -->
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -18,7 +18,19 @@ Feature and browser tests require the `amare_test` PostgreSQL database configure

 ## Worktrees

-Always work in a git worktree created from the `main` ref — never modify `main` directly and never commit from the primary working tree. Create a dedicated worktree per feature/branch with `git worktree add -b <branch> <path> main`. On finishing work, create a PR, watch CI until green, then merge it. Clean up the worktree with `git worktree remove` after merge.
+Always work in a git worktree created from the `main` ref — never modify `main` directly and never commit from the primary working tree. Create a dedicated worktree per feature/branch with `git worktree add -b <branch> <path> main`. Include the Linear identifier in the branch name (e.g. `docs/man-132-…`). When the SDLC gate below is green, commit and open the PR without asking. Watch CI until green, then merge. Clean up the worktree with `git worktree remove` after merge.
+
+## Agent SDLC (do not ask)
+
+Never ask whether to commit or open a PR. After each complete slice of work, ship it:
+
+1. **Work is done** in a Linear-linked worktree.
+2. **Tests are written or updated** for the changed layer. Skip new tests only when the change has no runtime impact (docs, templates, static config).
+3. **Pre-commit passes** (`composer pint:check` and `composer phpstan`). Do not `--no-verify`. If the hook fails, fix and rerun.
+4. **Commit** with Conventional Commits. Cite the Linear identifier.
+5. **Push and open the Gitea PR** (`tea pulls create`) using `.gitea/PULL_REQUEST_TEMPLATE.md` (WHAT / WHY / HOW / Linear Issue / Comments). Attach the PR URL on the Linear issue via `save_issue` `links`. GitHub is the legacy mirror only.
+
+Do not wait for "pode commitar?" or "abre o PR?".

 ## Git Hooks (husky)

@@ -41,7 +53,7 @@ Tests use Pest 4; browser coverage uses Pest Browser/Playwright. Tests are verif

 ## Commit & Pull Request Guidelines

-History follows Conventional Commit-style subjects, for example `feat: Fase 0 — Fundação`. Use `<type>: <imperative summary>` (`feat`, `fix`, `docs`, `test`, `chore`) and keep commits focused. Pull requests should explain scope, link the relevant issue or OpenSpec requirement, list verification commands, and include screenshots for UI changes. Ensure all CI jobs pass.
+History follows Conventional Commit-style subjects, for example `feat: Fase 0 — Fundação`. Use `<type>: <imperative summary>` (`feat`, `fix`, `docs`, `test`, `chore`) and keep commits focused. Fill the PR template (WHAT / WHY / HOW / Linear Issue / Comments). **Linear Issue is required** (identifier + URL). An OpenSpec change is extra context, not a substitute. Include verification commands and screenshots for UI changes. Ensure all CI jobs pass. After pre-commit is green, commit and open the PR — do not ask.

 ## Security & Configuration

@@ -59,6 +71,8 @@ The design system lives in `DESIGN.md` (palette, typography, layout, do's and do

 Issues live in Linear, driven through the Linear MCP tools. See `docs/agents/issue-tracker.md` for workspace, team, and tool conventions. The repo ships no `.mcp.json`, so the Linear MCP has to be enabled for the session before those tools exist — if it isn't, report that instead of silently falling back to another tracker.

+**Every piece of work and every PR must be tied to a Linear issue.** Do not create a branch, worktree, or PR until an issue exists (identifier like `MAN-132`). If the user did not give one, search Linear first; if none fits, create it with `save_issue` on team `Maneco-workspace` before starting. Put the identifier in the branch name. Cite identifier + URL in the PR body. After opening the PR, attach the PR URL on the issue via `save_issue` `links`. Do not start untracked work.
+
 ### Triage labels

 Default vocabulary: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. See `docs/agents/triage-labels.md`.
--- a/docs/agents/issue-tracker.md
+++ b/docs/agents/issue-tracker.md
@@ -17,6 +17,16 @@ Issues and specs for this repo live in Linear. Use the Linear MCP tools for all
 - **Link work**: `save_issue` with `project`, `cycle`, `parentId`, `blocks` / `blockedBy` (relations are append-only).
 - **Cross-link to a PR**: attach the PR URL via `save_issue` `links`.

+## Required: issue before work and before PR
+
+Every branch, worktree, and pull request in this repo must be tied to a Linear issue.
+
+1. **Starting work:** require an identifier (e.g. `MAN-132`). If the user did not give one, search Linear. If none fits, create the issue with `save_issue` on team `Maneco-workspace` *before* creating a branch or worktree.
+2. **Branch:** include the identifier (`docs/man-132-…`, `feat/man-126-…`).
+3. **PR:** cite identifier + URL in the body. An OpenSpec change is extra context, not a substitute.
+4. **After the PR exists:** attach the PR URL on the issue via `save_issue` `links`. Do this as part of the automatic SDLC in `AGENTS.md` — do not ask before opening the PR.
+5. If Linear MCP is unavailable, stop and report — do not start untracked work.
+
 ## When a skill says "publish to the issue tracker"

 Create a Linear issue with `save_issue` on team `Maneco-workspace`.
--- a/docs/research/man-135-classify-amare-mvp.md
+++ b/docs/research/man-135-classify-amare-mvp.md
@@ -0,0 +1,118 @@
+# MAN-135 — Classificar issues Amare MVP vs Gitea `main`
+
+**Issue:** [Research: classificar issues Amare MVP vs Gitea main](https://linear.app/maneco-workspace/issue/MAN-135/research-classificar-issues-amare-mvp-vs-gitea-main)  
+**Mapa:** [MAN-134](https://linear.app/maneco-workspace/issue/MAN-134/mapa-classificar-amare-mvp-linear-gitea)  
+**Branch:** `research/man-135-classify-amare-mvp`  
+**HEAD canônico inventariado:** `origin/main` @ `93b680c` (`docs: require Linear issues and auto-ship PRs (#4)`)  
+**Data:** 2026-08-13  
+
+## Regras (de MAN-134)
+
+| Regra | Aplicação |
+| --- | --- |
+| Code truth | Gitea `origin/main` (`manoel-freitas/amare`) |
+| Done = shipped | commit presente em `origin/main` |
+| GitHub | só pista (`amore-site`); não canônico |
+| Pós-MVP | fora de escopo: MAN-111, 112, 113, 114, 115, 131 |
+| Status Linear | **não** alterados neste research (exceto fechar MAN-135) |
+
+## Fontes
+
+| Fonte | Uso |
+| --- | --- |
+| Linear MCP `list_issues` / `get_issue` project **Amare — Lançamento MVP** | universo, status, labels, ACs |
+| `git fetch origin` + `git log origin/main` | evidência shipped |
+| `tea pr list --state all` (0 open; #1–#4 merged) | PRs Gitea |
+| `gh pr list` / `gh pr view` (GitHub mirror) | pistas #63, #64 |
+| Branches `origin/*` | trabalho em voo |
+| Cross-check | [MAN-136 orphans](https://linear.app/maneco-workspace/issue/MAN-136/research-inventariar-merges-orfaos-no-gitea), [MAN-137 MAN-126 state](https://linear.app/maneco-workspace/issue/MAN-137/research-estado-real-de-casamentos-corporate-man-126) (branches locais; **não** em `main` ainda) |
+
+## Contagens (36 issues in-scope)
+
+| Bucket | Count |
+| --- | ---: |
+| **shipped** | 14 |
+| **em voo** | 5 |
+| **não começou** | 12 |
+| · cliente | 5 |
+| · engenharia | 5 |
+| · ops-lançamento | 2 |
+| **Linear podre** | 5 |
+| **Total classificado** | **36** |
+| Excluídos Pós-MVP | 6 |
+| Issues no projeto | 42 |
+
+---
+
+## Tabela canônica
+
+| Issue | Linear status | Bucket | Evidência / nota |
+| --- | --- | --- | --- |
+| [Implementar Home e páginas institucionais do MVP](https://linear.app/maneco-workspace/issue/MAN-102/implementar-home-e-paginas-institucionais-do-mvp) | Done | **shipped** | Site público + home editorial em `main` (ex. `#53`, heros, `/sobre`, `/servicos`) |
+| [Implementar portfólio e depoimentos](https://linear.app/maneco-workspace/issue/MAN-103/implementar-portfolio-e-depoimentos) | Done | **shipped** | Portfólio/depoimentos + seed fix `49fbc0f` (MAN-103) |
+| [Implementar formulário de solicitação de proposta](https://linear.app/maneco-workspace/issue/MAN-104/implementar-formulario-de-solicitacao-de-proposta) | Done | **shipped** | Briefing/contato em `main` (ex. `eed8240`) |
+| [Implementar tracking simples da origem dos leads](https://linear.app/maneco-workspace/issue/MAN-105/implementar-tracking-simples-da-origem-dos-leads) | Done | **shipped** | `37296f7` (MAN-105) / GH #37 |
+| [Definir e implementar atualização simples de conteúdo](https://linear.app/maneco-workspace/issue/MAN-106/definir-e-implementar-atualizacao-simples-de-conteudo) | Done | **shipped** | `4001cd0` (MAN-106 AC4) / GH #33 |
+| [Finalizar SEO técnico e metadados sociais](https://linear.app/maneco-workspace/issue/MAN-107/finalizar-seo-tecnico-e-metadados-sociais) | Done | **shipped** | SEO desde ship público (`3dc1f44` et al.) |
+| [Rodar auditoria Lighthouse e corrigir performance do site público](https://linear.app/maneco-workspace/issue/MAN-109/rodar-auditoria-lighthouse-e-corrigir-performance-do-site-publico) | Done | **shipped** | `0ecae4c` (MAN-109) / GH #43 |
+| [Auditar se Vue + Livewire faz sentido na arquitetura atual](https://linear.app/maneco-workspace/issue/MAN-117/auditar-se-vue-livewire-faz-sentido-na-arquitetura-atual) | Done | **shipped** | `2e28603` reconcilia stack declarada |
+| [Portar identidade visual do site público para o admin em Filament](https://linear.app/maneco-workspace/issue/MAN-118/portar-identidade-visual-do-site-publico-para-o-admin-em-filament) | Done | **shipped** | `63c0269` (MAN-118) / GH #40 |
+| [Estabilizar baselines de regressão visual no CI (paridade local×CI)](https://linear.app/maneco-workspace/issue/MAN-119/estabilizar-baselines-de-regressao-visual-no-ci-paridade-localci) | Done | **shipped** | Trabalho de baselines chegou em `main`; remoção posterior `#44` é resolução intencional, não “Done sem merge” |
+| [Fechar portões de qualidade e deploy da Fase 0 antes do lançamento](https://linear.app/maneco-workspace/issue/MAN-120/fechar-portoes-de-qualidade-e-deploy-da-fase-0-antes-do-lancamento) | Done | **shipped** | `7e68c0e` (MAN-120) / GH #39 |
+| [Reencodar imagens de marca e regerar baselines visuais](https://linear.app/maneco-workspace/issue/MAN-122/reencodar-imagens-de-marca-e-regerar-baselines-visuais) | Done | **shipped** | Era de baselines/imagem em `main` (série #24/#7 + follow-ups) |
+| [Deploy de staging falha no Dokploy desde 08/08 — causa server-side, sem log acessível](https://linear.app/maneco-workspace/issue/MAN-123/deploy-de-staging-falha-no-dokploy-desde-0808-causa-server-side-sem) | Done | **shipped** | Pipeline/fixes Dokploy+staging em `main` (ex. `#6`–`#9`, `ac08b5f`, `26a68e1`) |
+| [Reconciliar documentação e changes OpenSpec após os PRs #41–#49](https://linear.app/maneco-workspace/issue/MAN-124/reconciliar-documentacao-e-changes-openspec-apos-os-prs-41-49) | Done | **shipped** | `213d684` (MAN-124) / GH #50 |
+| [Reestruturar jornada pública em Amare Casamentos e Amare Corporate](https://linear.app/maneco-workspace/issue/MAN-126/reestruturar-jornada-publica-em-amare-casamentos-e-amare-corporate) | In Progress | **em voo** | `origin/feat/man-126-casamentos-corporate` (1 commit ahead, não em `main`); GH PR [#63](https://github.com/manoel-freitas/amore-site/pull/63) open; **0** PR Gitea. Ver MAN-137 |
+| [Executar QA de responsividade e acessibilidade](https://linear.app/maneco-workspace/issue/MAN-108/executar-qa-de-responsividade-e-acessibilidade) | In Progress | **em voo** | Status coerente com QA aberto; PRs de suporte (#44–#49) já em `main`, ACs manuais não fechados; sem PR Gitea aberto só desta issue |
+| [Configurar domínio, ambiente de produção e checklist de lançamento](https://linear.app/maneco-workspace/issue/MAN-110/configurar-dominio-ambiente-de-producao-e-checklist-de-lancamento) | In Progress | **em voo** | Ops de lançamento em curso (staging/deploy em `main`; produção/DNS/checklist incompletos) |
+| [Ajustar CTAs consultivos no WhatsApp e briefing comercial](https://linear.app/maneco-workspace/issue/MAN-127/ajustar-ctas-consultivos-no-whatsapp-e-briefing-comercial) | Todo | **em voo** | Fluxo 1 parcial em `main` via Gitea [#2](https://git.hellomanoel.com/manoel-freitas/amare/pulls/2) (`e2af1f6`); Fluxo 2 (indecisos) + fechamento de ACs ainda abertos; Linear Todo atrasa vs código parcial |
+| [Research: classificar issues Amare MVP vs Gitea main](https://linear.app/maneco-workspace/issue/MAN-135/research-classificar-issues-amare-mvp-vs-gitea-main) | Backlog→Done* | **em voo** | Este arquivo / branch `research/man-135-classify-amare-mvp` — **ainda não** em `origin/main` (*Done só no Linear após resolução; ver podre se Done sem merge) |
+| [Exigir issue Linear em todo trabalho e PR](https://linear.app/maneco-workspace/issue/MAN-132/exigir-issue-linear-em-todo-trabalho-e-pr) | In Progress | **Linear podre** | Conteúdo em `main` via Gitea [#4](https://git.hellomanoel.com/manoel-freitas/amare/pulls/4) (`93b680c`); Linear ainda In Progress. GH [#64](https://github.com/manoel-freitas/amore-site/pull/64) open = mirror stale |
+| [Adicionar PR template no Gitea e no GitHub](https://linear.app/maneco-workspace/issue/MAN-133/adicionar-pr-template-no-gitea-e-no-github) | In Progress | **Linear podre** | `.gitea/PULL_REQUEST_TEMPLATE.md` + `.github/pull_request_template.md` em `origin/main` (mesmo PR #4); Linear In Progress |
+| [Fechar arquitetura e copy final do MVP](https://linear.app/maneco-workspace/issue/MAN-97/fechar-arquitetura-e-copy-final-do-mvp) | In Progress | **Linear podre** | In Progress sem branch/PR abertos; arquitetura/home editorial já em `main` (#46–#53, #52…). Residual de copy/conteúdo vive em tickets cliente (MAN-98…) e MAN-126 |
+| [Research: inventariar merges órfãos no Gitea](https://linear.app/maneco-workspace/issue/MAN-136/research-inventariar-merges-orfaos-no-gitea) | Done | **Linear podre** | Done no Linear; deliverable em `origin/research/man-136-orphan-gitea-merges` — **não** merged em `main` |
+| [Research: estado real de Casamentos × Corporate (MAN-126)](https://linear.app/maneco-workspace/issue/MAN-137/research-estado-real-de-casamentos-corporate-man-126) | Done | **Linear podre** | Done no Linear; `docs/research/man-137-man-126-state.md` em branch local ahead — **não** em `origin/main` |
+| [Receber e consolidar conteúdo institucional e serviços da Michelle](https://linear.app/maneco-workspace/issue/MAN-98/receber-e-consolidar-conteudo-institucional-e-servicos-da-michelle) | Todo | **não começou · cliente** | Labels Conteúdo/Cliente; sem branch/PR |
+| [Fechar portfólio e banco de imagens do lançamento](https://linear.app/maneco-workspace/issue/MAN-99/fechar-portfolio-e-banco-de-imagens-do-lancamento) | Todo | **não começou · cliente** | Labels Conteúdo/Cliente; sem branch/PR |
+| [Consolidar depoimentos reais para o MVP](https://linear.app/maneco-workspace/issue/MAN-100/consolidar-depoimentos-reais-para-o-mvp) | Todo | **não começou · cliente** | Labels Conteúdo/Cliente; sem branch/PR |
+| [Confirmar WhatsApp Business e canais de contato](https://linear.app/maneco-workspace/issue/MAN-101/confirmar-whatsapp-business-e-canais-de-contato) | Todo | **não começou · cliente** | Labels Conteúdo/Cliente; sem branch/PR |
+| [Aplicar identidade visual oficial e rodada de revisão da cliente](https://linear.app/maneco-workspace/issue/MAN-128/aplicar-identidade-visual-oficial-e-rodada-de-revisao-da-cliente) | Todo | **não começou · cliente** | Labels Cliente/Design; sem branch/PR |
+| [Papel Assistant não tem nenhuma permissão funcional](https://linear.app/maneco-workspace/issue/MAN-121/papel-assistant-nao-tem-nenhuma-permissao-funcional) | Backlog | **não começou · engenharia** | Enum `Assistant` existe; permissões funcionais não entregues; sem branch |
+| [Provar falha dos gates e rollback antes de arquivar complete-foundation-parity](https://linear.app/maneco-workspace/issue/MAN-125/provar-falha-dos-gates-e-rollback-antes-de-arquivar-complete) | Todo | **não começou · engenharia** | ACs de prova controlada abertos; experiência **não** deve mergear em `main` |
+| [Revisar privacidade, LGPD e consentimentos do MVP](https://linear.app/maneco-workspace/issue/MAN-116/revisar-privacidade-lgpd-e-consentimentos-do-mvp) | Todo | **não começou · engenharia** | Página privacidade existe; revisão/consentimentos ACs abertos; sem branch |
+| [Mapa: classificar Amare MVP (Linear × Gitea)](https://linear.app/maneco-workspace/issue/MAN-134/mapa-classificar-amare-mvp-linear-gitea) | Todo | **não começou · engenharia** | Wayfinder map — inventário ainda em research filhos |
+| [Grilling: lista de ações de sync após inventário](https://linear.app/maneco-workspace/issue/MAN-138/grilling-lista-de-acoes-de-sync-apos-inventario) | Backlog | **não começou · engenharia** | Depende do inventário (este + MAN-136/137) |
+| [Configurar Search Console, Meta Pixel e mensuração de lançamento](https://linear.app/maneco-workspace/issue/MAN-129/configurar-search-console-meta-pixel-e-mensuracao-de-lancamento) | Todo | **não começou · ops-lançamento** | Mensuração de go-live; sem branch |
+| [Preparar acesso e treinamento do painel administrativo](https://linear.app/maneco-workspace/issue/MAN-130/preparar-acesso-e-treinamento-do-painel-administrativo) | Todo | **não começou · ops-lançamento** | Acesso/treino go-live (label Cliente+Engenharia); sem branch |
+
+### Fora de escopo (Pós-MVP)
+
+| Issue | Nota |
+| --- | --- |
+| [MAN-111](https://linear.app/maneco-workspace/issue/MAN-111/pos-mvp-produzir-pdf-comercial-estatico-de-servicos) … [MAN-115](https://linear.app/maneco-workspace/issue/MAN-115/pos-mvp-mapear-convivencia-com-o-assessoria-vip), [MAN-131](https://linear.app/maneco-workspace/issue/MAN-131/pos-mvp-formulario-para-fornecedores-e-parcerias) | Não classificados (mapa Out of scope) |
+
+---
+
+## Hints verificados
+
+| Hint | Resultado |
+| --- | --- |
+| MAN-132 + MAN-133 via Gitea PR #4, Linear In Progress | **Confirmado → Linear podre** (código shipped; status podre). Também GH #64 ainda open |
+| MAN-126: GH #63 + branch, sem PR Gitea | **Confirmado → em voo** |
+| Gitea 0 open PRs; #1–#4 merged | **Confirmado** (`tea pr list`) |
+
+## Ações de sync sugeridas (não executadas aqui)
+
+1. Marcar **Done** no Linear: MAN-132, MAN-133 (e fechar GH #64 stale).  
+2. Reavaliar MAN-97 → Done ou decompor residual em tickets cliente/MAN-126.  
+3. Abrir **PR Gitea** para `feat/man-126-casamentos-corporate`; fechar ou ignorar GH #63 após mirror.  
+4. MAN-127: mover para In Progress; fechar Fluxo 2 / ACs restantes ou fatiar ticket.  
+5. Mergear (ou aceitar exceção) branches de research MAN-136/137/135 se “Done” exigir `main`.  
+6. Lista priorizada fica para [MAN-138](https://linear.app/maneco-workspace/issue/MAN-138/grilling-lista-de-acoes-de-sync-apos-inventario).
+
+## Ambiguidades
+
+- **Wayfinder research Done:** mapa diz Done = `main`; prática atual marca Done após comentário Linear com arquivo só na branch → classificado **Linear podre** para MAN-136/137.  
+- **MAN-119/122:** remoção de regressão visual (`#44`) após estabilizar — tratados como shipped (resolução chegou em `main`).  
+- **MAN-127:** bucket **em voo** (parcial shipped + resto aberto); alternativa seria “não começou” só do residual — preferimos um bucket por issue.  
+- **MAN-108/110:** sem branch dedicada; “em voo” = processo In Progress, não PR aberta.