@polymorphism-tech/morph-spec 8.32.0 → 8.34.2

package/framework/standards/ai-agents/sweet-spot.md

@@ -1,109 +1,109 @@
-# Sweet Spot — When to use what in MAF
-
-> **Scope:** stacks=["dotnet"]
-> **Layer:** 0 (always-load via persona maf-expert)
-> **Keywords:** sweet spot, when to use agent, agent vs workflow, when not to use workflow, MAF decision, simple agent
-> **Read by Claude in:** plan (decide arquitetura da feature antes de quebrar em tasks) + implement (validar que a arquitetura ainda é a mais simples possível)
-
-**Verified against:** MAF Tier List research (2026-05-18) + Microsoft Learn docs. Last-verified: 2026-05-19.
-
----
-
-## The 4-feature rule
-
-```
-95% of production AI agents need ONLY:
-
-  1. Chat (the LLM call)
-  2. Structured Output (typed records, not free text)
-  3. Tools (typed functions the agent can call)
-  4. RAG Custom (pgvector tool, not hosted RAG)
-
-If your feature needs ONLY these 4 → use a single agent. Don't reach for workflows.
-```
-
-Apply this rule before deciding multi-agent or workflow. Most of the time the answer is "single agent".
-
----
-
-## Decision tree (Claude reads this in plan phase)
-
-```
-Step 1 — Does the task even need an LLM?
-├─ "Can a deterministic function solve this?" → YES → write the function, no agent
-└─ NO → continue
-
-Step 2 — Single agent vs multi-agent?
-├─ One topic + one decision → single agent (DEFAULT)
-├─ Multiple specialized topics with clear handoff → multi-agent
-│   └─ Prefer Agent-as-Tool pattern (one agent uses another as a tool)
-│   └─ See ai-agents-multi-agent-patterns
-└─ "I'm not sure" → start with single agent, escalate if needed
-
-Step 3 — Need a Workflow?
-├─ The feature has fan-in/out (many inputs aggregated) → maybe workflow
-│   └─ Confirm: can you write it as a foreach + LINQ aggregate?
-│       └─ YES → write the foreach, NO workflow
-│       └─ NO → workflow may help
-├─ Long-running with human-in-the-loop checkpoints → maybe workflow
-│   └─ See ai-agents-workflows (Onda 2)
-└─ Otherwise → NO workflow
-
-Step 4 — Which provider?
-├─ ALWAYS direct models — never a hosted agent service
-├─ Provider choice (OpenAI / Google / Anthropic / Ollama) lives in the
-│  project's Model Registry, not hardcoded → see ai-agents-providers-model-registry
-└─ Hosted services (Foundry Agent Service, Vertex AI hosted) → NOT used
-
-Step 5 — RAG approach?
-├─ Need control over chunking/embedding/storage? → RAG custom (pgvector)
-│   └─ See ai-agents-rag-custom-pgvector (Onda 2)
-└─ Don't reach for hosted RAG — loses control
-```
-
----
-
-## Anti-patterns (what Claude should NOT do)
-
-| Anti-pattern | Why it's wrong | What to do instead |
-|--------------|----------------|---------------------|
-| Reach for Workflow when a function does the job | "Tudo que Workflows fazem, código C# normal faz com menos complexidade" — pesquisa | Write the function. Wrap in a tool if an agent needs to call it. |
-| Use a hosted agent service | Hosted is "always 6-9 months behind" on models + removes control | Direct models always (OpenAI / Google / Anthropic / Ollama) |
-| Upload PDFs to a hosted RAG | Loses control of chunking + embedding + storage | Custom RAG with pgvector. See ai-agents-rag-custom-pgvector |
-| Add Memory/Session because "agents need state" | If not building a chatbot, don't add chat state | Skip. Add when a real chat UI exists. |
-| Use Semantic Kernel for new features | SK is superseded by MAF | Use Microsoft.Agents.AI. See ai-agents-setup |
-| Return free text and parse it downstream | LLM output is non-deterministic | Structured Output. See ai-agents-structured-output (Onda 2) |
-
----
-
-## When the 4-feature rule does NOT apply
-
-You may need to step outside the sweet spot when:
-- The feature genuinely fans-out (e.g., monthly report aggregating N items) → workflow with fan-in
-- The feature needs vision/audio/image-gen → modality-specific standards (see ai-agents-modalities-* — Onda 3)
-
-**Even in these cases:** the core of the agent still follows the 4-feature rule. Only the orchestration layer changes.
-
----
-
-## Checklist (verifiable by morph-eval)
-
-- [ ] Was each agent designed as single-agent BEFORE reaching for multi-agent? (Check `decisions.md`.)
-- [ ] If a Workflow is used, is fan-in/out or HITL checkpointing genuinely present? Or could `foreach + LINQ` replace it?
-- [ ] Are the 4 features (Chat, Structured Output, Tools, RAG Custom) all present where applicable?
-- [ ] Are hosted agent services avoided?
-
----
-
-## References
-
-- `ai-agents-setup` — packages and DI
-- `ai-agents-providers-model-registry` — provider-agnostic config
-- `ai-agents-structured-output` (Onda 2)
-- `ai-agents-multi-agent-patterns` (Onda 2)
-- `ai-agents-workflows` (Onda 2, reframed)
-- `ai-agents-rag-custom-pgvector` (Onda 2)
-
----
-
-*MORPH-SPEC by Polymorphism Tech — ai-agents/sweet-spot.md v1.0 (2026-05-19)*
+# Sweet Spot — When to use what in MAF
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 0 (always-load via persona maf-expert)
+> **Keywords:** sweet spot, when to use agent, agent vs workflow, when not to use workflow, MAF decision, simple agent
+> **Read by Claude in:** plan (decide arquitetura da feature antes de quebrar em tasks) + implement (validar que a arquitetura ainda é a mais simples possível)
+
+**Verified against:** MAF Tier List research (2026-05-18) + Microsoft Learn docs. Last-verified: 2026-05-19.
+
+---
+
+## The 4-feature rule
+
+```
+95% of production AI agents need ONLY:
+
+  1. Chat (the LLM call)
+  2. Structured Output (typed records, not free text)
+  3. Tools (typed functions the agent can call)
+  4. RAG Custom (pgvector tool, not hosted RAG)
+
+If your feature needs ONLY these 4 → use a single agent. Don't reach for workflows.
+```
+
+Apply this rule before deciding multi-agent or workflow. Most of the time the answer is "single agent".
+
+---
+
+## Decision tree (Claude reads this in plan phase)
+
+```
+Step 1 — Does the task even need an LLM?
+├─ "Can a deterministic function solve this?" → YES → write the function, no agent
+└─ NO → continue
+
+Step 2 — Single agent vs multi-agent?
+├─ One topic + one decision → single agent (DEFAULT)
+├─ Multiple specialized topics with clear handoff → multi-agent
+│   └─ Prefer Agent-as-Tool pattern (one agent uses another as a tool)
+│   └─ See ai-agents-multi-agent-patterns
+└─ "I'm not sure" → start with single agent, escalate if needed
+
+Step 3 — Need a Workflow?
+├─ The feature has fan-in/out (many inputs aggregated) → maybe workflow
+│   └─ Confirm: can you write it as a foreach + LINQ aggregate?
+│       └─ YES → write the foreach, NO workflow
+│       └─ NO → workflow may help
+├─ Long-running with human-in-the-loop checkpoints → maybe workflow
+│   └─ See ai-agents-workflows (Onda 2)
+└─ Otherwise → NO workflow
+
+Step 4 — Which provider?
+├─ ALWAYS direct models — never a hosted agent service
+├─ Provider choice (OpenAI / Google / Anthropic / Ollama) lives in the
+│  project's Model Registry, not hardcoded → see ai-agents-providers-model-registry
+└─ Hosted services (Foundry Agent Service, Vertex AI hosted) → NOT used
+
+Step 5 — RAG approach?
+├─ Need control over chunking/embedding/storage? → RAG custom (pgvector)
+│   └─ See ai-agents-rag-custom-pgvector (Onda 2)
+└─ Don't reach for hosted RAG — loses control
+```
+
+---
+
+## Anti-patterns (what Claude should NOT do)
+
+| Anti-pattern | Why it's wrong | What to do instead |
+|--------------|----------------|---------------------|
+| Reach for Workflow when a function does the job | "Tudo que Workflows fazem, código C# normal faz com menos complexidade" — pesquisa | Write the function. Wrap in a tool if an agent needs to call it. |
+| Use a hosted agent service | Hosted is "always 6-9 months behind" on models + removes control | Direct models always (OpenAI / Google / Anthropic / Ollama) |
+| Upload PDFs to a hosted RAG | Loses control of chunking + embedding + storage | Custom RAG with pgvector. See ai-agents-rag-custom-pgvector |
+| Add Memory/Session because "agents need state" | If not building a chatbot, don't add chat state | Skip. Add when a real chat UI exists. |
+| Use Semantic Kernel for new features | SK is superseded by MAF | Use Microsoft.Agents.AI. See ai-agents-setup |
+| Return free text and parse it downstream | LLM output is non-deterministic | Structured Output. See ai-agents-structured-output (Onda 2) |
+
+---
+
+## When the 4-feature rule does NOT apply
+
+You may need to step outside the sweet spot when:
+- The feature genuinely fans-out (e.g., monthly report aggregating N items) → workflow with fan-in
+- The feature needs vision/audio/image-gen → modality-specific standards (see ai-agents-modalities-* — Onda 3)
+
+**Even in these cases:** the core of the agent still follows the 4-feature rule. Only the orchestration layer changes.
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Was each agent designed as single-agent BEFORE reaching for multi-agent? (Check `decisions.md`.)
+- [ ] If a Workflow is used, is fan-in/out or HITL checkpointing genuinely present? Or could `foreach + LINQ` replace it?
+- [ ] Are the 4 features (Chat, Structured Output, Tools, RAG Custom) all present where applicable?
+- [ ] Are hosted agent services avoided?
+
+---
+
+## References
+
+- `ai-agents-setup` — packages and DI
+- `ai-agents-providers-model-registry` — provider-agnostic config
+- `ai-agents-structured-output` (Onda 2)
+- `ai-agents-multi-agent-patterns` (Onda 2)
+- `ai-agents-workflows` (Onda 2, reframed)
+- `ai-agents-rag-custom-pgvector` (Onda 2)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/sweet-spot.md v1.0 (2026-05-19)*

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

@@ -0,0 +1,88 @@
+# Local Compose Isolation Standard
+
+> **Scope:** any stack that runs `docker compose` locally (Next.js + Neon, .NET)
+> **Layer:** 2 (on keyword)
+> **Keywords:** docker compose, worktree, ports, container_name, POSTGRES_PORT, COMPOSE_PROJECT_NAME, local dev, e2e stack
+> **Load When:** a compose file, a dev-server port, or a worktree stack is being written or debugged
+
+**Verified against:** Docker Compose v2 + morph-spec 8.34 (dedicated stack per worktree). Last-verified: 2026-09-07.
+
+---
+
+## Why this exists
+
+Every feature worktree runs its **own** compose stack — its own project, its own postgres, its own volumes. That only holds if the compose file lets the harness pick the host ports and the project name. A file that hardcodes either one looks isolated and collides the moment a second worktree starts: `container_name` is never prefixed by the project, and a fixed `5432:5432` is one host port for everybody.
+
+The harness gives each worktree a **block of 10 ports** (`.morph/worktree.env`, written by `morph-spec worktree setup|provision`, regenerated by `worktree link --all`). The same values reach `docker compose` through the `verify` e2e node, `morph-spec e2e up`, the `PreToolUse:Bash` hook (which prefixes `npm run dev` / `dotnet run` / `docker compose` with them) and `morph-spec env` for a plain shell.
+
+## Port layout (one contract, everywhere)
+
+| Offset | Variable | Compose mapping |
+|---|---|---|
+| +0 | `PORT` | `"${PORT:-3000}:3000"` — web / dev server |
+| +1 | `API_PORT` (and `ASPNETCORE_URLS=http://localhost:<+1>` on .NET) | `"${API_PORT:-5000}:8080"` |
+| +2 | `POSTGRES_PORT` | `"${POSTGRES_PORT:-5432}:5432"` |
+| +3 | `REDIS_PORT` | `"${REDIS_PORT:-6379}:6379"` (reserved) |
+| +4..+9 | free | project-specific services |
+
+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>`.
+
+## Core Rules
+
+- NEVER set `container_name` — Compose already names containers `<project>-<service>-1`, and an explicit name is shared by every worktree
+- ALWAYS publish host ports through a variable with a default: `"${PORT:-3000}:3000"`, never `"3000:3000"` nor `published: 3000`
+- ALWAYS keep the database name stable (`POSTGRES_DB: ${POSTGRES_DB:-app}`) — the project name already namespaces the container and the volume; baking a feature name into the DB name outlives the feature that scaffolded it
+- ALWAYS declare a healthcheck on every service — `docker compose up --wait` (what the e2e node runs) is meaningless without one
+- 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`
+
+## What the harness enforces
+
+- Inside a secondary worktree, a compose with a fixed host port or a `container_name` **fails the `verify` e2e node** (`compose-not-isolable`) — Gate 3 cannot pass on a stack that cannot run beside its siblings. At the primary root the same finding is a warning.
+- `morph-spec finish` tears the stack down **with volumes** (`--keep-volumes` opts out) and deletes the freshness stamp; `morph-spec worktree remove` tears it down without volumes (the feature is still open).
+- Two worktrees never share `POSTGRES_PORT`: the block is allocated first-free-index per feature and released only when the worktree is removed.
+
+## Minimal compose skeleton
+
+```yaml
+services:
+  app:
+    build: { context: ., dockerfile: Dockerfile.dev }
+    ports:
+      - "${PORT:-3000}:3000"
+    environment:
+      - DATABASE_URL=${DATABASE_URL:-postgresql://postgres:postgres@postgres:5432/${POSTGRES_DB:-app}}
+    depends_on:
+      postgres: { condition: service_healthy }
+    healthcheck:
+      test: ["CMD-SHELL", "node -e \"fetch('http://localhost:3000/').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\""]
+      interval: 10s
+      timeout: 5s
+      retries: 12
+  postgres:
+    image: postgres:15-alpine
+    ports:
+      - "${POSTGRES_PORT:-5432}:5432"
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: ${POSTGRES_DB:-app}
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d ${POSTGRES_DB:-app}"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+volumes:
+  postgres-data:
+```
+
+## Running it by hand
+
+```bash
+# inside the worktree, outside Claude Code
+eval "$(morph-spec env)"        # PowerShell: morph-spec env --powershell | Invoke-Expression
+docker compose up -d --wait     # lands in project morph-{feature}, on the block's ports
+```