docs: inventariar merges órfãos Gitea (MAN-136)

Co-authored-by: Cursor <cursoragent@cursor.com>
docs: require Linear issues and auto-ship PRs (#4 )
2026-08-13 13:37:14 -03:00 · 2026-08-13 11:46:36 +00:00 · 2026-08-12 21:23:28 +00:00
5 changed files with 156 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-136-orphan-gitea-merges.md
+++ b/docs/research/man-136-orphan-gitea-merges.md
@@ -0,0 +1,92 @@
+# MAN-136 — Inventário de merges órfãos no Gitea
+
+**Issue:** [MAN-136](https://linear.app/maneco-workspace/issue/MAN-136/research-inventariar-merges-orfaos-no-gitea)  
+**Branch:** `research/man-136-orphan-gitea-merges`  
+**HEAD inventariado:** `origin/main` @ `93b680c`  
+**Data:** 2026-08-13  
+**Escopo:** inventário only — **não** criar issues Linear retroativas.
+
+## Critério de janela
+
+**Início inclusivo:** commit `84f6d7c` (`ci: migrate GitHub Actions para Gitea Actions`, 2026-08-12).  
+**Fim:** `HEAD` de `origin/main` (`93b680c`).
+
+Justificativa: primeiro commit que troca CI/registry/docs para Gitea (`git.hellomanoel.com`). Commits anteriores (GitHub PR #5–#60 era) ficam fora. A fronteira é o SHA da migração de Actions, não a data de criação do repo Gitea.
+
+## Critério de “issue correspondente”
+
+Um merge/commit **tem** issue Linear correspondente no projeto **Amare — Lançamento MVP** se **qualquer** for verdade:
+
+1. Body/assunto do PR ou commit cita identifier `MAN-xxx` desse projeto; ou
+2. Existe issue no projeto cujo título + critérios de aceite descrevem de forma única a mudança shipped (match funcional 1:1).
+
+**Não conta como correspondente:**
+
+- Epic/issue já **Done** antes do merge que “poderia” cobrir trabalho novo (ex.: MAN-102 Done em 2026-08-08 vs remodel `/sobre` em 2026-08-12).
+- Issue ampla de copy/arquitetura sem AC específico para o ship (ex.: MAN-97).
+- Mencionar “Gitea” só em issues de template (MAN-133) não cobre a migração de CI.
+
+Classificação pedida: **órfão shipped** = chegou em `main` sem issue correspondente. Sem criar tickets.
+
+## Fontes
+
+| Fonte | Uso |
+| --- | --- |
+| `git log origin/main` (`84f6d7c^..HEAD`) | commits da janela |
+| `tea pr list --state all` + API Gitea `/pulls/{1..4}` | PRs Gitea merged |
+| Linear `list_issues` project `Amare — Lançamento MVP` (incl. archived) | universo de issues |
+
+## Matriz PRs Gitea #1–#4
+
+| PR | Título | Merge SHA | Issue Linear? | Classificação |
+| --- | --- | --- | --- | --- |
+| [#1](https://git.hellomanoel.com/manoel-freitas/amare/pulls/1) | feat: remodelar `/sobre` conforme mock editorial | `fc1c617` | Nenhuma (sem citação; MAN-102 já Done; sem issue dedicada) | **órfão shipped** |
+| [#2](https://git.hellomanoel.com/manoel-freitas/amare/pulls/2) | fix: CTAs de modalidades em `/servicos` via WhatsApp | `e2af1f6` | [MAN-127](https://linear.app/maneco-workspace/issue/MAN-127/ajustar-ctas-consultivos-no-whatsapp-e-briefing-comercial) (Fluxo 1 — CTAs WhatsApp nos cards de modalidade; PR não cita, match por AC) | matched (não órfão) |
+| [#3](https://git.hellomanoel.com/manoel-freitas/amare/pulls/3) | fix(about): alinhar layout `/sobre` ao ritmo editorial | `ba38894` | Nenhuma (follow-up de #1; sem citação) | **órfão shipped** |
+| [#4](https://git.hellomanoel.com/manoel-freitas/amare/pulls/4) | docs: require Linear issues and auto-ship PRs | `93b680c` | [MAN-132](https://linear.app/maneco-workspace/issue/MAN-132/exigir-issue-linear-em-todo-trabalho-e-pr) + [MAN-133](https://linear.app/maneco-workspace/issue/MAN-133/adicionar-pr-template-no-gitea-e-no-github) (citados no body) | matched (não órfão) |
+
+## Órfãos shipped (tabela canônica)
+
+| Nome descritivo | Evidência | Link |
+| --- | --- | --- |
+| Remodelar `/sobre` conforme mock editorial | Gitea PR #1 merged | https://git.hellomanoel.com/manoel-freitas/amare/pulls/1 |
+| Alinhar layout `/sobre` ao ritmo editorial | Gitea PR #3 merged | https://git.hellomanoel.com/manoel-freitas/amare/pulls/3 |
+| Migração CI GitHub → Gitea Actions (+ follow-ups de runner/registry/staging) | 10 commits direct-push em `main`, **sem** PR Gitea | sem PR — ver série abaixo |
+
+### Série vizinha sem PR (direct push)
+
+Todos sem citação `MAN-*` e sem issue de migração Gitea no projeto Amare MVP:
+
+| SHA | Assunto |
+| --- | --- |
+| `84f6d7c` | ci: migrate GitHub Actions para Gitea Actions |
+| `716196d` | fix: owner path manoel-freitas/amare no registry Gitea |
+| `1e215ac` | docs: alinhar remotes e registry para Gitea |
+| `f730e76` | fix: secrets de registry sem prefixo GITEA_ |
+| `1468a23` | fix: remover actions/cache no Gitea Actions |
+| `87a0191` | fix: CI Postgres via hostname, sem bind :5432 no host |
+| `dd82ca2` | fix: paralelizar CI no act_runner |
+| `91c0d41` | fix: nomes únicos para containers CI no docker.sock compartilhado |
+| `ac08b5f` | fix: staging deploy via needs no CI, não workflow_run |
+| `26a68e1` | fix: restaurar deploy-staging via workflow_run (Gitea ≥1.25) |
+
+Tratados como **um** órfão shipped agregado (mesmo tema ops/CI), não dez tickets potenciais.
+
+## Não-órfãos na janela (referência)
+
+- PR #2 → MAN-127 (parcial; issue ainda Todo no Linear — status Linear ≠ presença de issue).
+- PR #4 → MAN-132 + MAN-133.
+
+## Ambiguidades registradas
+
+1. **PR #2 sem citação explícita:** match por AC de MAN-127 (Fluxo 1). Se o inventário MAN-135 exigir citação literal, reclassificar #2 como órfão — este doc **não** faz isso.
+2. **`/sobre` vs MAN-97 / MAN-98 / MAN-102:** rejeitado como correspondente (Done prévio ou escopo sem AC de remodel layout).
+3. **Merge commits vs squash:** PR #1 landa como `fc1c617` (sem merge commit separado); PR #3 tem merge `ba38894`. Ambos contam como merges shipped.
+
+## Resumo executivo
+
+**3 órfãos shipped** na era pós-migração Gitea:
+
+1. Remodelar `/sobre` — [PR #1](https://git.hellomanoel.com/manoel-freitas/amare/pulls/1)
+2. Fix layout `/sobre` — [PR #3](https://git.hellomanoel.com/manoel-freitas/amare/pulls/3)
+3. Migração CI/Gitea Actions (+ follow-ups) — direct push, sem PR