@polymorphism-tech/morph-spec 8.43.0 → 8.44.0

package/framework/standards/STANDARDS.json

@@ -2566,15 +2566,18 @@
         "POSTGRES_PORT",
         "COMPOSE_PROJECT_NAME",
         "port block",
+        "PG_PORT",
+        "portEnvNames",
         "local docker compose"
       ],
       "anchors": {
         "layout": "#port-layout-one-contract-everywhere",
+        "portNames": "#project-named-port-variables",
         "rules": "#core-rules",
         "enforcement": "#what-the-harness-enforces",
         "skeleton": "#minimal-compose-skeleton"
       },
-      "digest": "Every worktree runs its OWN compose stack (project morph-{feature}, own postgres, own volumes). Ports come from the worktree block: PORT +0, API_PORT +1 (ASPNETCORE_URLS on .NET), POSTGRES_PORT +2, REDIS_PORT +3 — publish via ${VAR:-default}:container, never a fixed host port, never container_name (not prefixed by the project → collides). Stable POSTGRES_DB, healthcheck on every service, DATABASE_URL with an in-network default, playwright.config reads PLAYWRIGHT_BASE_URL. A non-isolable compose fails the verify e2e node inside a worktree. finish tears down with volumes (--keep-volumes opts out). Cloud DB credentials go in e2e.auth.envFile, never in .morph/worktree.env.",
+      "digest": "Every worktree runs its OWN compose stack (project morph-{feature}, own postgres, own volumes). Ports come from the worktree block: PORT +0, API_PORT +1 (ASPNETCORE_URLS on .NET), POSTGRES_PORT +2, REDIS_PORT +3 — publish via ${VAR:-default}:container, never a fixed host port, never container_name (not prefixed by the project → collides). Stable POSTGRES_DB, healthcheck on every service, DATABASE_URL with an in-network default, playwright.config reads PLAYWRIGHT_BASE_URL. A non-isolable compose fails the verify e2e node inside a worktree. finish tears down with volumes (--keep-volumes opts out). Cloud DB credentials go in e2e.auth.envFile, never in .morph/worktree.env. A compose that reads a port by ANOTHER name (PG_PORT) is not fed by the block: declare it in config.json e2e.portEnvNames ({\"postgres\": \"PG_PORT\"}) and the harness exports it with the same value in worktree.env, the compose env and the hook.",
       "verifiedAgainst": "Docker Compose v2 + morph-spec 8.34 (dedicated stack per worktree).",
       "provedBy": []
     },
@@ -2851,6 +2854,47 @@
       "digest": "Default is NO comment: code explains itself through names, types and tests. Before commenting, rename, extract a function or named constant, encode the state in the type, or write a test; comment only what none of these can express: an invariant the type does not express, an order that matters, an external quirk (third-party API, library bug with its link), or the contract of a package published for consumers outside the repo. Never process history (task, UC, ADR, FR, Gate, evaluator, spec.md, mockup: commit message and decisions.md; in a test the link to the postcondition goes in the test NAME), never restate the code, no XML doc/JSDoc on application members that repeats the signature, no file headers, section banners, #region, commented-out code or loose TODOs, no claims about behavior (make them test assertions). One line is normal, ~3 is the ceiling; more than one comment line per ten code lines means the names are not doing the work. A heavily commented neighbour file is not a model. The comment-guard hook blocks an edit that ADDS process history, a banner/#region, a block over 3 lines or a doc-comment outside a published package; the verify validators node (code-budget) warns on added comments that cite process and on added comment density.",
       "verifiedAgainst": "C#, TypeScript e JavaScript (convenção de linguagem, sem pacote externo).",
       "provedBy": []
+    },
+    {
+      "id": "ai-agents-tool-adapters",
+      "name": "tool adapters",
+      "path": "ai-agents/tool-adapters.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "tools",
+        "testing"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "tool fina",
+        "adaptador de tool",
+        "Ops",
+        "Desfecho",
+        "Render",
+        "regra de negocio em tool",
+        "descricao da tool",
+        "golden de tool",
+        "refactor neutro",
+        "migracao de teste"
+      ],
+      "anchors": {
+        "fronteira": "#fronteira-com-os-outros-standards",
+        "problema": "#o-problema",
+        "padrao": "#o-padrão",
+        "exemplo": "#exemplo-c-completo",
+        "testes": "#os-testes-das-duas-camadas",
+        "migracao": "#migrar-uma-tool-que-já-tem-a-regra-no-adaptador",
+        "reais": "#exemplos-reais",
+        "regras": "#regras"
+      },
+      "digest": "A tool that carries business rule keeps apart three things that change for different reasons: the RULE (sealed class XOps(...), primary constructor, explicit AddScoped; never *Service, which the mandate bans as a layer between handler and data), the sentence the MODEL reads, and the EFFECT a human sees. Each Ops method returns a typed outcome (abstract record XDesfecho, one sealed record per case); the model-facing text (description, refusal, self-correction, success, the ToolUnavailable decision) lives in the adapter, in public static object Render(XDesfecho), while human text delivered by code (task body, note, ack) stays in Ops because it is an effect. Checkable by grep: Ops names no tool and instructs no model. The adapter (AIFunctionFactory.Create) only builds the typed request, calls Ops and returns Render: zero rule, not a line count, and a long dynamic description stays byte for byte. Two test layers: Ops tests assert outcome, calls and order on the fake, never text; contract tests assert Render's exact literal and .Description, with a golden of name, description and schema per real tenant. A neutral refactor is proven before any test moves: a proof commit with the old suite untouched and green (offline evals included), then the migration, with mutation run only against the new tests. \"Already covered\" needs proof assertion by assertion (11 of 22 such claims had lost one); the tests left at the origin must be identical to the base; mutation on the new tests found rules the old suite never protected. The C# blocks were compiled against the pin and the three xunit tests run.",
+      "verifiedAgainst": "Microsoft.Extensions.AI 10.9.0 + Microsoft.Agents.AI 1.20.0 (ai-pin 2026-09-08); os dois blocos C# abaixo foram extraídos com `scripts/extract-doc-csharp.mjs` e compilados contra o pin com `TreatWarningsAsErrors`, e os três testes do segundo bloco foram executados e passam. **A separação em si e a migração de teste são verificação documental:** vêm da feature `tools-finas` do MORPH_GHLBrain e o ai-kit não as traz.",
+      "provedBy": []
     }
   ],
   "sharedAliases": {

package/framework/standards/ai-agents/tool-adapters.md

@@ -0,0 +1,226 @@
+# Tool Adapters — a regra em `*Ops`, o texto do modelo no adaptador
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** tool, AIFunctionFactory, adaptador de tool, tool fina, Ops, Desfecho, Render, regra de negócio em tool, descrição da tool, golden de tool, refactor neutro, migração de teste
+> **Read by Claude in:** implement (ao escrever ou migrar uma tool de agente que carrega regra de negócio)
+
+**Verified against:** Microsoft.Extensions.AI 10.9.0 + Microsoft.Agents.AI 1.20.0 (ai-pin 2026-09-08); os dois blocos C# abaixo foram extraídos com `scripts/extract-doc-csharp.mjs` e compilados contra o pin com `TreatWarningsAsErrors`, e os três testes do segundo bloco foram executados e passam. **A separação em si e a migração de teste são verificação documental:** vêm da feature `tools-finas` do MORPH_GHLBrain e o ai-kit não as traz. Last-verified: 2026-09-08.
+
+---
+
+## Fronteira com os outros standards
+
+`ai-agents-mcp-tools` cobre **consumir** tools de um MCP server. `ai-agents-testing-ai` cobre **testar** um agente sem rede. `backend-dotnet-testing` é dono de xUnit, relógio falso e orçamento de teste. **Nada disso se repete aqui.**
+
+Este standard cobre uma coisa só: a tool que o agente chama **e que carrega regra**. Onde mora a regra, onde mora a frase que o modelo lê, e como se testa cada uma sem que uma mascare a outra.
+
+## O problema
+
+Uma tool nasce como uma lambda dentro do `AIFunctionFactory.Create`. Enquanto é só "chame a API e devolva", serve. Quando ganha regra, a lambda passa a misturar três coisas que mudam por motivos diferentes:
+
+| O que é | Muda quando | Quem lê |
+|---|---|---|
+| a **regra** (validar, decidir, gravar) | o negócio muda | o código e o teste |
+| a **frase para o modelo** (descrição, recusa, instrução de correção) | o prompt é ajustado | o modelo |
+| o **efeito** (task, nota, mensagem entregue por código) | o processo muda | um humano |
+
+Misturadas, o único teste possível é por string: qualquer ajuste de redação quebra o teste da regra, e qualquer refactor da regra arrisca mudar, sem ninguém ver, o que o modelo lê.
+
+## O padrão
+
+```
+   o modelo chama                                          o modelo lê
+ ┌──────────────┐    pedido tipado    ┌───────────┐  desfecho  ┌────────────────┐
+ │  Adaptador   │ ──────────────────► │   *Ops    │ ─────────► │ Render(desfecho)│
+ │ (tool fina)  │                     │ (a regra) │  tipado    │ (frase p/ modelo)│
+ └──────────────┘ ◄───────────────────────────────────────────└────────────────┘
+```
+
+1. **`Ops`, não `Service`.** Regra determinística com dependências injetadas vira `sealed class XOps(...)`, com construtor primário e um `AddScoped` explícito. `*Service` colide com a proibição de camada de Service/Manager entre handler e dados; `*Ops` é outra coisa: a regra de uma tool, não um intermediário de persistência.
+2. **Desfecho tipado, e a fronteira é quem lê o texto.** Cada método de `Ops` devolve um `abstract record XDesfecho` com um `sealed record` por caso. A frase para o **modelo** (descrição, recusa, instrução de autocorreção, sucesso, a decisão de "tool indisponível") mora no adaptador, em `public static object Render(XDesfecho)`. O texto para **humano** entregue por código (corpo de task, nota, ack) mora na `Ops`, porque é efeito. É verificável por `grep`: a `Ops` não cita o nome da tool nem dá instrução ao modelo.
+3. **Adaptador fino.** `AIFunctionFactory.Create` com a lambda montando o pedido tipado, chamando a `Ops` e devolvendo `Render(desfecho)`. A régua é **zero regra no adaptador**, não um número de linhas: uma descrição dinâmica pode ser longa e tem de continuar byte a byte.
+4. **Testes em duas camadas.** O teste da `Ops` asserta desfecho, chamadas e ordem no fake, **nunca texto**. O teste de contrato asserta o `Render` com o literal exato e a `.Description`. Um golden de nome, descrição e schema, por tenant real, protege a superfície que o modelo lê.
+5. **Refactor neutro se prova antes de migrar teste.** Primeiro um commit de prova, com a suíte antiga intocada e verde (inclusive os evals offline); só depois a migração dos testes, com mutação rodando **só** contra os testes novos.
+
+## Exemplo C# completo
+
+A regra, o desfecho, o adaptador e o registro. O pedido é tipado, então a lambda não decide nada: monta, chama, renderiza.
+
+```csharp
+using System.ComponentModel;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace Exemplo.Tools;
+
+public interface IAgendaExterna
+{
+    Task<int> CapacidadeAsync(string salaId, CancellationToken ct);
+    Task<string> GravarAsync(ReservaPedido pedido, CancellationToken ct);
+}
+
+public sealed record ReservaPedido(string SalaId, DateOnly Dia, int Pessoas);
+
+public abstract record ReservaDesfecho
+{
+    public sealed record Reservada(string ConfirmacaoId) : ReservaDesfecho;
+    public sealed record SalaCheia(int Capacidade) : ReservaDesfecho;
+    public sealed record DiaSemExpediente(DateOnly Dia) : ReservaDesfecho;
+}
+
+public sealed class ReservaOps(IAgendaExterna agenda)
+{
+    public async Task<ReservaDesfecho> ReservarAsync(ReservaPedido pedido, CancellationToken ct)
+    {
+        if (pedido.Dia.DayOfWeek is DayOfWeek.Saturday or DayOfWeek.Sunday)
+            return new ReservaDesfecho.DiaSemExpediente(pedido.Dia);
+
+        var capacidade = await agenda.CapacidadeAsync(pedido.SalaId, ct);
+        if (pedido.Pessoas > capacidade)
+            return new ReservaDesfecho.SalaCheia(capacidade);
+
+        return new ReservaDesfecho.Reservada(await agenda.GravarAsync(pedido, ct));
+    }
+}
+
+public static class ReservarSalaTool
+{
+    public const string Name = "reservar_sala";
+
+    public static AIFunction Create(ReservaOps ops) =>
+        AIFunctionFactory.Create(
+            async (
+                [Description("Identificador da sala, como listado por consultar_salas")] string salaId,
+                [Description("Dia da reserva, AAAA-MM-DD")] DateOnly dia,
+                [Description("Quantidade de pessoas")] int pessoas,
+                CancellationToken ct) =>
+                Render(await ops.ReservarAsync(new ReservaPedido(salaId, dia, pessoas), ct)),
+            Name,
+            "Reserva uma sala para um dia. Só chame depois de confirmar sala, dia e número de pessoas com o cliente.");
+
+    public static object Render(ReservaDesfecho desfecho) => desfecho switch
+    {
+        ReservaDesfecho.Reservada r => new { ok = true, confirmacao = r.ConfirmacaoId },
+        ReservaDesfecho.SalaCheia c => new { ok = false, erro = $"A sala comporta no máximo {c.Capacidade} pessoas. Ofereça outra sala ou reduza o grupo." },
+        ReservaDesfecho.DiaSemExpediente d => new { ok = false, erro = $"{d.Dia:yyyy-MM-dd} não tem expediente. Peça outro dia." },
+        _ => throw new ArgumentOutOfRangeException(nameof(desfecho)),
+    };
+}
+
+public static class ReservaToolsRegistration
+{
+    public static IServiceCollection AddReservaTools(this IServiceCollection services) =>
+        services.AddScoped<ReservaOps>();
+}
+```
+
+A checagem de fronteira é um `grep`, e tem de sair vazio: a `Ops` não conhece a tool nem fala com o modelo.
+
+```bash
+grep -rnE "reservar_sala|Ofereça|Peça|AIFunction" Features/Reservas/Ops/
+```
+
+## Os testes das duas camadas
+
+O teste da `Ops` compara **tipos e chamadas**; o de contrato compara **o texto que o modelo lê**. Trocar a redação de uma recusa quebra só o segundo.
+
+```csharp
+using System.Text.Encodings.Web;
+using System.Text.Json;
+using Exemplo.Tools;
+using Xunit;
+
+namespace Exemplo.Tools.Tests;
+
+internal sealed class AgendaFake(int capacidade) : IAgendaExterna
+{
+    public List<string> Chamadas { get; } = [];
+
+    public Task<int> CapacidadeAsync(string salaId, CancellationToken ct)
+    {
+        Chamadas.Add($"capacidade:{salaId}");
+        return Task.FromResult(capacidade);
+    }
+
+    public Task<string> GravarAsync(ReservaPedido pedido, CancellationToken ct)
+    {
+        Chamadas.Add($"gravar:{pedido.SalaId}");
+        return Task.FromResult("R-1");
+    }
+}
+
+public sealed class ReservaOpsTests
+{
+    [Fact]
+    public async Task Sala_cheia_nao_grava_e_devolve_a_capacidade()
+    {
+        var agenda = new AgendaFake(capacidade: 4);
+        var ops = new ReservaOps(agenda);
+
+        var desfecho = await ops.ReservarAsync(new ReservaPedido("s1", new DateOnly(2026, 10, 5), 6), CancellationToken.None);
+
+        Assert.Equal(new ReservaDesfecho.SalaCheia(4), desfecho);
+        Assert.Equal(["capacidade:s1"], agenda.Chamadas);
+    }
+}
+
+public sealed class ReservarSalaToolTests
+{
+    private static readonly JsonSerializerOptions Literal = new() { Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping };
+
+    [Fact]
+    public void Render_da_sala_cheia_diz_ao_modelo_o_que_fazer()
+    {
+        var json = JsonSerializer.Serialize(ReservarSalaTool.Render(new ReservaDesfecho.SalaCheia(4)), Literal);
+
+        Assert.Equal("{\"ok\":false,\"erro\":\"A sala comporta no máximo 4 pessoas. Ofereça outra sala ou reduza o grupo.\"}", json);
+    }
+
+    [Fact]
+    public void A_superficie_que_o_modelo_le_nao_mudou()
+    {
+        var tool = ReservarSalaTool.Create(new ReservaOps(new AgendaFake(capacidade: 10)));
+
+        Assert.Equal("reservar_sala", tool.Name);
+        Assert.StartsWith("Reserva uma sala para um dia.", tool.Description);
+        Assert.Contains("\"salaId\"", tool.JsonSchema.GetRawText());
+    }
+}
+```
+
+## Migrar uma tool que já tem a regra no adaptador
+
+A migração é um refactor que **não pode mudar o que o modelo lê**. Por isso ela tem ordem:
+
+1. **Commit de prova.** Extraia a `Ops` e o `Render` sem tocar nenhum teste. A suíte antiga tem de continuar verde, inclusive os evals offline. Esse commit é a âncora: prova que o refactor é neutro.
+2. **Migre os testes**, e só depois de o commit de prova estar verde.
+3. **Matriz de migração.** Liste cada asserção antiga e a asserção nova que a cobre. "Já está coberto pelo teste X" precisa de prova **asserção por asserção**: na migração que originou este standard, 11 de 22 alegações desse tipo tinham perdido alguma asserção do teste antigo.
+4. **Os testes que ficam na origem têm de ser idênticos à base.** A migração só apaga. Uma checagem byte a byte dos métodos restantes contra o commit de prova pegou (e provou corrigidos) `Edit`s que casaram no método errado.
+5. **Mutação só contra os testes novos.** Ela acha lacunas que a suíte antiga nunca protegeu: em duas das três `Ops` migradas apareceram regras sem teste algum (valor digitado pelo comercial sobrescrito pelo catálogo, campos reafirmados sumindo da falha do `PUT`, corpo de update reenviando valor igual).
+
+## Exemplos reais
+
+MORPH_GHLBrain, `src/Morph.GHLBrain/Features/Conversation/Operator/`:
+
+| Tool | Adaptador | `Ops` | Desfecho |
+|---|---|---|---|
+| `finalizar_handoff` | `Tools/FinalizarHandoffTool.cs` | `Ops/HandoffOps.cs` | `HandoffDesfecho` |
+| `atualizar_dossie` | `Tools/AtualizarDossieTool.cs` | `Ops/DossieOps.cs` | `DossieDesfecho` |
+| `set_lead_fields` | `Tools/SetLeadFieldsTool.cs` | `Ops/DossieOps.cs` | `CamposDesfecho` |
+| `route_lead` | `Tools/RouteLeadTool.cs` | `Ops/TriagemOps.cs` | `TriagemDesfecho` |
+
+As decisões estão em `.morph/features/tools-finas/2-plan/decisions.md` (ADR-1 e ADR-2) daquele repositório.
+
+## Regras
+
+- **ALWAYS** a regra de uma tool vai numa `sealed class XOps(...)` com construtor primário e `AddScoped` explícito
+- **NEVER** chame essa classe de `*Service` ou `*Manager`: o mandate proíbe essa camada entre handler e dados, e `*Ops` é a forma da casa
+- **ALWAYS** cada método de `Ops` devolve um `abstract record XDesfecho`, com um `sealed record` por caso que a regra distingue
+- **NEVER** ponha na `Ops` uma frase para o modelo, o nome da tool ou uma instrução de autocorreção. Verifique por `grep`
+- **ALWAYS** o texto para humano entregue por código (task, nota, ack) fica na `Ops`: é efeito
+- **ALWAYS** o adaptador só monta o pedido tipado, chama a `Ops` e devolve `Render(desfecho)`. Zero regra ali; descrição dinâmica longa é permitida e segue byte a byte
+- **ALWAYS** o teste da `Ops` asserta desfecho, chamadas e ordem no fake, nunca texto
+- **ALWAYS** o teste de contrato asserta o `Render` com o literal exato e a `.Description`, e há um golden de nome, descrição e schema por tenant real
+- **NEVER** declare "já coberto" sem a asserção nova que cobre cada asserção antiga
+- **NEVER** migre o teste antes do commit de prova verde, nem deixe na origem um teste diferente da base

package/framework/standards/infrastructure/docker/local-compose-isolation.md

@@ -27,6 +27,16 @@ The harness gives each worktree a **block of 10 ports** (`.morph/worktree.env`,
 
 Also exported: `COMPOSE_PROJECT_NAME=morph-{feature}` (isolates container, network and volume names), `MORPH_PORT_BASE`, `MORPH_PORT_RANGE`, `PLAYWRIGHT_BASE_URL=http://localhost:<+0>`.
 
+## Project-named port variables
+
+The harness exports only the four names above. A compose file that reads a port by another name (`"${PG_PORT:-5433}:5432"`) is **not** fed by the block: it publishes its own default, or whatever a `.env.e2e` copied from a sibling worktree carries, while `worktree.env` announces a different port. Hand-run specs then hit a closed port, or worse, seed one postgres and read another. Declare the name the project reads:
+
+```json
+{ "e2e": { "portEnvNames": { "postgres": "PG_PORT" } } }
+```
+
+Keys are `web`, `api`, `postgres` and `redis`. Each declared name carries the **same value** as the standard variable, everywhere the layout goes: `worktree.env`, the compose env of `verify`/`e2e up`/`morph-spec env`, and the `PreToolUse:Bash` hook. Being layout, it is ignored (and named on stderr) if the credentials file carries it. An entry the harness cannot honour — unknown port, invalid or reserved name, a name used twice — is dropped and named on stderr.
+
 ## Core Rules
 
 - NEVER set `container_name` — Compose already names containers `<project>-<service>-1`, and an explicit name is shared by every worktree
@@ -36,7 +46,7 @@ Also exported: `COMPOSE_PROJECT_NAME=morph-{feature}` (isolates container, netwo
 - ALWAYS give `DATABASE_URL` an in-network default so the stack comes up with no `.env`: `postgresql://postgres:postgres@postgres:5432/${POSTGRES_DB:-app}`
 - ALWAYS read the base URL from the environment in `playwright.config.ts`: `process.env.PLAYWRIGHT_BASE_URL ?? \`http://localhost:${process.env.PORT ?? 3000}\``
 - NEVER put a cloud connection string (Neon branch etc.) in `.morph/worktree.env` — it is regenerated; credentials go in the gitignored file named by `config.json → e2e.auth.envFile`
-- NEVER put a variable from the port layout table above (nor `PLAYWRIGHT_BASE_URL`) in that credentials file — the harness **ignores** it and says which key it ignored on stderr. Ports come from the allocated block; the file carries credentials. A `.env.e2e` copied from a sibling worktree carries THAT worktree's block, and before the filter existed it silently repointed this stack at the neighbour's postgres
+- NEVER put a variable from the port layout table above (nor `PLAYWRIGHT_BASE_URL`, nor a name declared in `e2e.portEnvNames`) in that credentials file — the harness **ignores** it and says which key it ignored on stderr. Ports come from the allocated block; the file carries credentials. A `.env.e2e` copied from a sibling worktree carries THAT worktree's block, and before the filter existed it silently repointed this stack at the neighbour's postgres
 
 ## What the harness enforces
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "8.43.0",
+  "version": "8.44.0",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",

package/src/commands/project/worktree.js

@@ -882,19 +882,21 @@ export async function allocateWorktreeEnv(worktreePath, root, envKey, { morphFea
     } catch { morphFeature = null; }
   }
   try {
-    const { allocateEnvBlock, resolveFleetConfig, buildEnvFileContent } =
+    const { allocateEnvBlock, resolveFleetConfig, buildEnvFileContent, resolvePortAliases } =
       await import('../../lib/worktree/env-allocator.js');
     const common = execSync('git rev-parse --git-common-dir', { cwd: root, stdio: 'pipe' }).toString().trim();
     if (!common) return null;
     const gitCommonDir = resolve(root, common);
     const block = allocateEnvBlock(envKey, { gitCommonDir, ...resolveFleetConfig(root) });
     let stack = '';
+    let aliases = {};
     try {
       const cfg = JSON.parse(readFileSync(join(root, '.morph', 'config', 'config.json'), 'utf8').replace(/^/, ''));
       stack = cfg?.project?.stack || '';
+      aliases = resolvePortAliases(cfg).aliases;
     } catch { /* fail-open — stackless env still carries PORT */ }
     mkdirSync(join(worktreePath, '.morph'), { recursive: true });
-    writeFileSync(envPath, buildEnvFileContent(envKey, block, stack, { morphFeature }), 'utf8');
+    writeFileSync(envPath, buildEnvFileContent(envKey, block, stack, { morphFeature, aliases }), 'utf8');
     excludeWorktreePaths(root, [join('.morph', 'worktree.env')]);
     return block;
   } catch {
@@ -1238,10 +1240,17 @@ export function primaryRootUnexplainedDirt(root, feature, opts = {}) {
 }
 
 /**
- * Clear the root-side `.worktree` registration for a finished feature and commit
- * that cleanup scoped to its own pathspec. Runs whenever the worktree is
- * REMOVED — including `--pr`, where no merge landed — so a stale registration
- * never trips the anti-dupe guard or the next finish's root-clean.
+ * Clear the root-side `.worktree` registration for a finished feature. Runs
+ * whenever the worktree is REMOVED — including `--pr`, where no merge landed —
+ * so a stale registration never trips the anti-dupe guard or the next finish's
+ * root-clean.
+ *
+ * A registration that was committed on the default branch is cleared by a commit
+ * scoped to the feature's own pathspec. An untracked scaffold (what
+ * `create --worktree` leaves at the root) is never committed: the branch owns
+ * the feature, and committing the skeleton would put it on the default next to
+ * the archived copy. When the feature is already archived the skeleton is shed,
+ * backup first, by the same primitive `finish` uses.
  *
  * Written DIRECTLY (never saveState, which re-persists every sibling's
  * feature.json and can dirty the root outside this command's pathspec). The thin
@@ -1250,9 +1259,12 @@ export function primaryRootUnexplainedDirt(root, feature, opts = {}) {
  *
  * @param {string} root
  * @param {string} feature
+ * @param {{ stamp?: string }} [opts] - the caller's backup stamp, for the shed
+ * @returns {Promise<{ shedBackup: string|null }>}
  */
-export async function clearRootWorktreeRegistration(root, feature) {
+export async function clearRootWorktreeRegistration(root, feature, { stamp } = {}) {
   const featPathspec = `.morph/features/${feature}`;
+  const gitOpts = { cwd: root, stdio: 'pipe' };
   try {
     const rootFjPath = join(root, '.morph', 'features', feature, 'feature.json');
     if (existsSync(rootFjPath)) {
@@ -1265,16 +1277,19 @@ export async function clearRootWorktreeRegistration(root, feature) {
     }
   } catch { /* fail-open */ }
 
-  // Clearing that field can itself dirty the root (a committed registration
-  // survives the shed's checkout and the merge). Committing is in contract —
-  // finish already writes commits — and scoped to this feature's path only.
   try {
-    const dirtyAfter = execFileSync('git', ['status', '--porcelain', '--', featPathspec], { cwd: root, stdio: 'pipe' }).toString();
-    if (dirtyAfter.trim() !== '') {
-      execFileSync('git', ['add', '--', featPathspec], { cwd: root, stdio: 'pipe' });
-      execFileSync('git', ['commit', '-m', `morph-spec finish: clear ${feature} worktree registration`, '--', featPathspec], { cwd: root, stdio: 'pipe' });
+    const tracked = execFileSync('git', ['ls-files', '--', featPathspec], gitOpts).toString().trim() !== '';
+    if (!tracked) {
+      if (!existsSync(join(root, '.morph', 'archive', feature))) return { shedBackup: null };
+      return shedRootFeatureScope(root, feature, { stamp });
+    }
+    let unchanged = true;
+    try { execFileSync('git', ['diff', '--quiet', 'HEAD', '--', featPathspec], gitOpts); } catch { unchanged = false; }
+    if (!unchanged) {
+      execFileSync('git', ['commit', '-m', `morph-spec finish: clear ${feature} worktree registration`, '--', featPathspec], gitOpts);
     }
   } catch { /* fail-open — a dirty root is a nuisance, not a reason to fail */ }
+  return { shedBackup: null };
 }
 
 /**
@@ -1423,7 +1438,7 @@ export function pickRemovalFailure(stderrs) {
  * @returns {Promise<{ worktreeRemoved: boolean, ignoredBackup: string|null, discarded: string[],
  *   blockers: string[], ignoredBlocking: string[], shieldable: string[], declineReason: string|null,
  *   relinked: boolean, refused: boolean, infraLeftUnlinked: string[],
- *   removalFailure: {kind: string, detail: string}|null }>}
+ *   removalFailure: {kind: string, detail: string}|null, rootShedBackup: string|null }>}
  */
 export async function teardownWorktree(worktreePath, { root, feature, branch, options = {}, deleteBranch = true, addressByTarget = false, relinkOnFailure = false, stamp }) {
   // Drop the infra junctions FIRST, without following them — this is what makes
@@ -1453,6 +1468,7 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
 
   let worktreeRemoved = false;
   let removalFailure = null;
+  let rootShedBackup = null;
   if (canRemove) {
     const attempt = await attemptWorktreeRemoval(worktreePath, root);
     worktreeRemoved = attempt.removed;
@@ -1473,7 +1489,7 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
       const common = execSync('git rev-parse --git-common-dir', { cwd: root, stdio: 'pipe' }).toString().trim();
       if (common) releaseEnvBlock(feature, { gitCommonDir: resolve(root, common) });
     } catch { /* fail-open */ }
-    await clearRootWorktreeRegistration(root, feature);
+    ({ shedBackup: rootShedBackup } = await clearRootWorktreeRegistration(root, feature, { stamp }));
   }
 
   // Rollback (A4) — ONLY on a REFUSAL, never on a FAILURE. The two look alike
@@ -1568,6 +1584,7 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
     refused,
     infraLeftUnlinked,
     removalFailure,
+    rootShedBackup,
   };
 }
 
@@ -1789,6 +1806,7 @@ export async function runWorktreeRemove(featureArg, options = {}) {
     if (teardown.replicable.length) out.replicatedInRoot = teardown.replicable;
     if (teardown.ignoredBackup) out.ignoredBackup = teardown.ignoredBackup;
     if (teardown.shieldable.length) out.backedUp = teardown.shieldable;
+    if (teardown.rootShedBackup) out.shedBackup = teardown.rootShedBackup;
   } else {
     out.refused = teardown.refused;
     if (teardown.blockers.length) out.reparsePoints = teardown.blockers;

package/src/commands/state/approve.js

@@ -8,6 +8,7 @@ import { unmetPrereqs } from '../../core/state/gate-order.js';
 import { evaluatorReportState, COMPOSITE_SCORE_TOKEN } from '../../lib/evaluator-report.js';
 import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
 import { uiuxAutoApprovalBlock } from '../../lib/specs/screen-checklist.js';
+import { treeMovedSince } from '../../lib/git/evidence-staleness.js';
 
 /**
  * The literal token `review-report.md` carries to declare which tree it
@@ -57,7 +58,7 @@ function reviewStaleness(featureName) {
     // of staleness — say "unstamped" rather than block on a guess.
     return { status: 'unstamped', head };
   }
-  if (reviewed === head) return { status: 'ok', reviewed, head };
+  if (!treeMovedSince(cwd, reviewed, head)) return { status: 'ok', reviewed, head };
 
   let ahead = 0;
   try {

package/src/commands/state/finish.js

@@ -65,6 +65,8 @@ export function buildPrTitle(feature, fj) {
   return prefix + (raw.length <= room ? raw : `${raw.slice(0, room - 1)}…`);
 }
 
+const MEMORY_NOTE = 'o fechamento desta feature já está registrado no repositório (commit de archive, `decisions.md`, use cases promovidos, `git log`) — memória de sessão só para o que NENHUM deles guarda: decisão do usuário, pendência a observar em produção, custo medido.';
+
 /**
  * `morph-spec finish <feature> --pr|--merge` — the single, symmetric close of a
  * feature's lifecycle, for BOTH the worktree flow and the common flow.
@@ -132,6 +134,8 @@ export async function finishCommand(feature, options = {}) {
   const emit = (obj) => {
     if (resumed) obj = { ...obj, resumed: true };
     if (obj?.finished === true) {
+      // The one path every finished:true takes; the --pr payload is built by hand, outside mergeOutput.
+      obj = { ...obj, memoryNote: MEMORY_NOTE };
       try {
         const common = execFileSync('git', ['rev-parse', '--git-common-dir'], { cwd: root, stdio: 'pipe' }).toString().trim();
         if (common) releaseClaim(feature, { gitCommonDir: resolve(root, common) });

package/src/commands/state/gate-check.js

@@ -8,6 +8,7 @@ import { collectScreenChecklist } from '../../lib/specs/screen-checklist.js';
 import { persistGateDecision, VALID_GATES, readTrustFromConfig } from './gate-decision.js';
 import { minimatch } from 'minimatch';
 import { detectDefaultBranch, getHeadSha, getDiffStat, changedPathsAgainst } from '../../lib/git/default-branch.js';
+import { treeMovedSince } from '../../lib/git/evidence-staleness.js';
 import { readMorphConfig } from '../../lib/tasks/test-runner.js';
 import { oversizedTasks } from '../../lib/tasks/tasks-json-parser.js';
 import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
@@ -283,7 +284,7 @@ function collectSignals(featureName, feature, cwd, gateName) {
   // stamp com sha null (checkout sem git) ou stamp ausente lê como NOT stale.
   signals.verification = verification;
   if (verification?.status) signals.verificationStatus = verification.status;
-  signals.verificationStale = Boolean(verification?.sha && sha && verification.sha !== sha);
+  signals.verificationStale = treeMovedSince(cwd, verification?.sha, sha);
 
   // O nó e2e, separado do rollup de propósito: um `skip` NÃO reprova
   // `verification.status`, então sem estas duas chaves o gate lê 'pass' tanto

package/src/commands/validation/verify.js

@@ -129,6 +129,13 @@ function decidePersistence({ cwd, featureName, noPersist }) {
   return { persist: false, reason: samePath(root, cwd) ? 'owner-tree-elsewhere' : 'unregistered-worktree' };
 }
 
+function baselineStampBlock(baseline) {
+  if (!baseline?.recorded) return baseline?.reason ? `record-baseline: ${baseline.reason}` : 'record-baseline';
+  const fell = baseline.updates.filter((u) => u.from !== null && u.to < u.from);
+  if (fell.length === 0) return null;
+  return `record-baseline: a contagem caiu em ${fell.map((u) => `${u.id} (${u.from} → ${u.to})`).join(', ')}`;
+}
+
 /**
  * The per-node status map, in the shape `feature.schema.json` fixes for BOTH
  * writers of it — the per-scope history entry (`verifications.*`) and the
@@ -277,30 +284,15 @@ export async function verifyCommand(featureName, taskId, options = {}) {
   });
 
   const scopeKey = taskId ? `taskVerifications.${taskId}` : 'verifications.feature';
-  // `--record-baseline` is config maintenance, not gate evidence: it measures
-  // the suite in order to write `expectedCount`. Persisting a `verification`
-  // stamp from it would let a maintenance run stand in for the proof a gate
-  // asks for — the same class of confusion as a hand-typed baseline.
-  //
-  // `--filter` at FEATURE scope is the other side of the same hole (#87): the
-  // run is narrowed to a subset of nodes, but the stamp it would write carries
-  // `scope: 'feature'` — the one scope risk-detector.js trusts unconditionally.
-  // A partial run must not stand in for the proof a gate asks for, same as
-  // `--record-baseline` above. `--skip-tests` and `--skip-build` are the same
-  // partial run through another door (#113): a skipped node never reddens the
-  // rollup, so the stamp said `pass` over a suite (or a build) that never ran,
-  // and no gate rule reads a skipped `tests`/`build`. Task scope is unaffected:
-  // that stamp already says `scope: 'task:{id}'` (which pauses the ship gate on
-  // its own), and `taskVerifications` never claimed to cover more than the
-  // task. Checked AFTER `--no-persist` (via the `!options.noPersist` guard) so
-  // an explicit `--no-persist` keeps its own reason instead of being reported
-  // as one of these — the flags are all "don't write", but decidePersistence()
-  // already owns the former's reason.
+  // A run that measured only part of the suite must not stand in for the proof a gate asks for:
+  // --filter and --skip-* at feature scope, or a --record-baseline that recorded nothing. Task scope
+  // is unaffected (its stamp already says scope 'task:{id}'); --no-persist keeps its own reason.
   const partialFeatureRun = (!options.noPersist && !taskId)
     ? PARTIAL_RUN_FLAGS.find(([flag]) => options[flag])?.[1] ?? null
     : null;
-  const { persist, reason } = options.recordBaseline
-    ? { persist: false, reason: 'record-baseline' }
+  const baselineBlock = options.recordBaseline ? baselineStampBlock(result.baseline) : null;
+  const { persist, reason } = baselineBlock
+    ? { persist: false, reason: baselineBlock }
     : partialFeatureRun
       ? { persist: false, reason: partialFeatureRun }
       : decidePersistence({ cwd: process.cwd(), featureName, noPersist: options.noPersist });

package/src/lib/e2e/compose-env.js

@@ -23,7 +23,7 @@ import { join } from 'path';
 import chalk from 'chalk';
 
 import { loadEnvFile } from '../../../framework/hooks/shared/e2e-check.js';
-import { allocateEnvBlock, portLayout, resolveFleetConfig } from '../worktree/env-allocator.js';
+import { allocateEnvBlock, portLayout, resolveFleetConfig, resolvePortAliases } from '../worktree/env-allocator.js';
 
 /**
  * Build the environment a `docker compose` invocation should carry.
@@ -69,8 +69,11 @@ export function buildComposeEnv({ cwd, config, featureName, gitCommonDir }) {
       const { basePort, blockSize } = resolveFleetConfig(cwd);
       const block = allocateEnvBlock(featureName, { gitCommonDir, basePort, blockSize });
 
+      const { aliases, problems } = resolvePortAliases(config);
+      for (const problem of problems) console.warn(chalk.yellow(`  ⚠ ${problem} — ignorado`));
+
       const layout = {
-        ...portLayout(block, { stack: config?.project?.stack ?? '', feature: featureName }),
+        ...portLayout(block, { stack: config?.project?.stack ?? '', feature: featureName, aliases }),
         PLAYWRIGHT_BASE_URL: `http://localhost:${block.base}`,
       };
       Object.assign(env, layout);

package/src/lib/git/evidence-staleness.js

@@ -0,0 +1,39 @@
+import { execFileSync } from 'child_process';
+import { isDeepStrictEqual } from 'node:util';
+import { getHeadSha } from './default-branch.js';
+
+const MORPH_DIR = '.morph/';
+const CONFIG_PATH = '.morph/config/config.json';
+
+const gitOut = (cwd, args) => execFileSync('git', args, { cwd, stdio: 'pipe', maxBuffer: 64 * 1024 * 1024 }).toString();
+
+function withoutBaseline(text) {
+  const config = JSON.parse(text);
+  if (Array.isArray(config?.project?.tests)) {
+    for (const node of config.project.tests) delete node?.expectedCount;
+  }
+  return config;
+}
+
+function configMoved(cwd, sha, head) {
+  try {
+    const before = withoutBaseline(gitOut(cwd, ['show', `${sha}:${CONFIG_PATH}`]));
+    const after = withoutBaseline(gitOut(cwd, ['show', `${head}:${CONFIG_PATH}`]));
+    return !isDeepStrictEqual(before, after);
+  } catch {
+    return true;
+  }
+}
+
+// `.morph/` is bookkeeping, except the config: it names the test commands, and only its
+// expectedCount is something a baseline run writes.
+export function treeMovedSince(cwd, sha, head = getHeadSha(cwd)) {
+  if (!sha || !head || sha === head) return false;
+  let changed;
+  try {
+    changed = gitOut(cwd, ['diff', '--name-only', '--no-renames', '-z', sha, head]).split('\0').filter(Boolean);
+  } catch {
+    return true;
+  }
+  return changed.some((path) => !path.startsWith(MORPH_DIR) || (path === CONFIG_PATH && configMoved(cwd, sha, head)));
+}