@polymorphism-tech/morph-spec 7.4.0 → 7.6.0

package/framework/skills/core/morph-brainstorming/SKILL.md

@@ -4,7 +4,7 @@ description: Entende o negócio, os usuários e a arquitetura antes de qualquer
 version: core
 when-to-invoke: ao receber um novo request de feature, antes de morph-plan
 user-invokable: true
-cliVersion: "7.4.0"
+cliVersion: "7.6.0"
 ---
 
 # morph-brainstorming
@@ -87,9 +87,9 @@ O harness conhece o stack por padrão. Não pergunte sobre tecnologia a menos qu
    const riskList = getRiskSignals(signals);
    ```
 
-   **Persista a decisão em `state.json` ANTES de apresentar ou auto-aprovar** — grave
-   `features[feature].gateDecisions.proposal = { pause, reason, signals, trust, decidedAt: <ISO> }`
-   (Edit em `.morph/state.json` é permitido). O hook `gate-guard.js` confere depois se a ação (pausar vs auto-aprovar) bateu com esta decisão e avisa em divergência. Sem o registro o guard não verifica — não pule.
+   **Persista a decisão no `feature.json` autoritativo da feature ANTES de apresentar ou auto-aprovar** — grave
+   `gateDecisions.proposal = { pause, reason, signals, trust, decidedAt: <ISO> }` em `.morph/features/{feature}/feature.json`
+   (Edit em `.morph/features/**` é permitido pela allowlist). O hook `gate-guard.js` confere depois se a ação (pausar vs auto-aprovar) bateu com esta decisão e avisa em divergência. Sem o registro o guard não verifica — não pule.
 
    **Se `pause === true`** (manual mode OU risco detectado em auto), use `AskUserQuestion`:
 
@@ -116,7 +116,7 @@ O harness conhece o stack por padrão. Não pergunte sobre tecnologia a menos qu
    **Riscos:** {principal} (sinais detectados: nenhum)
    ```
 
-   O hook state-sync.js detecta a aprovação automaticamente. Em modo auto sem AskUserQuestion, a skill atualiza `.morph/state.json` via Edit direto (allowlist permite — ver settings.local.json).
+   No caminho manual, o hook state-sync.js detecta a aprovação automaticamente (grava o gate no `feature.json` autoritativo, `approvedBy: "manual"`). Em modo auto sem AskUserQuestion, aprove via `morph-spec approve {feature} proposal --mode auto` (ou `morph-spec advance {feature}` para já criar a pasta 2-plan/) — nunca via Edit à mão de state.json.
 
 ## Output esperado
 - `.morph/features/{feature}/0-proposal/proposal.md` — proposta aprovada

package/framework/skills/core/morph-eval/SKILL.md

@@ -4,7 +4,7 @@ description: Avalia a qualidade de uma tarefa ou fase com rubricas graduadas 0-1
 version: core
 when-to-invoke: ao completar uma tarefa ou ao finalizar uma fase de implementação
 user-invokable: false
-cliVersion: "7.4.0"
+cliVersion: "7.6.0"
 ---
 
 # morph-eval

package/framework/skills/core/morph-implement/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a execução de cada tarefa de implementação com standard e
 version: core
 when-to-invoke: ao iniciar cada task de implementação listada em tasks.json
 user-invokable: false
-cliVersion: "7.4.0"
+cliVersion: "7.6.0"
 ---
 
 # morph-implement
@@ -109,9 +109,10 @@ Ao iniciar cada task de `tasks.json` — antes de escrever qualquer código. Nor
 
    `tasks.json` é protegido após o Gate 2, mas os campos de progresso (`status`,
    `outputs`, `notes`) continuam graváveis durante a fase implement. `writeTasksJson`
-   grava o arquivo **inteiro** (Write) — esse é o caminho permitido. Nunca use a
-   tool `Edit` em `tasks.json` após o Gate 2: o hook `protect-spec-files` bloqueia
-   Edit e qualquer mudança em campos de plano (`title`, `dependencies`, `doneCriteria`…).
+   grava o arquivo inteiro (Write) e é o caminho mais simples; **uma `Edit` que mexe
+   só nesses campos mutáveis também é permitida** — o hook `protect-spec-files` faz
+   diff semântico e libera Write ou Edit desde que nenhum campo de contrato do plano
+   (`title`, `description`, `dependencies`, `effort`, `doneCriteria`, `group`) mude.
 
 9. Quando invocada por `morph-apply`, retornar o controle à skill orquestradora — ela decide qual task vem em seguida via `getReadyTasks(data)`. Quando invocada manualmente, verificar se há próxima task ready e iniciá-la imediatamente aplicando esta skill desde o passo 1 (auto-advance). Pause apenas se encontrar ambiguidade bloqueante não coberta pelo mandate.
 

package/framework/skills/core/morph-plan/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a produção dos três artefatos de planejamento de uma featur
 version: core
 when-to-invoke: ao iniciar a fase plan de uma feature, após o Gate 1 (proposal aprovado)
 user-invokable: true
-cliVersion: "7.4.0"
+cliVersion: "7.6.0"
 ---
 
 # morph-plan
@@ -94,9 +94,9 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
    const { pause, reason } = shouldPauseGate(config, signals);
    ```
 
-   **Persista a decisão em `state.json` ANTES de apresentar ou auto-aprovar** — grave
-   `features[feature].gateDecisions.plan = { pause, reason, signals, trust, decidedAt: <ISO> }`
-   (Edit em `.morph/state.json` é permitido). Isso deixa o raciocínio de trust auditável no disco: o hook `gate-guard.js` confere depois se a ação tomada (pausar vs auto-aprovar) bateu com esta decisão e avisa em caso de divergência. Sem este registro o guard não tem como verificar — não pule.
+   **Persista a decisão no `feature.json` autoritativo da feature ANTES de apresentar ou auto-aprovar** — grave
+   `gateDecisions.plan = { pause, reason, signals, trust, decidedAt: <ISO> }` em `.morph/features/{feature}/feature.json`
+   (Edit em `.morph/features/**` é permitido pela allowlist). Isso deixa o raciocínio de trust auditável no disco: o hook `gate-guard.js` confere depois se a ação tomada (pausar vs auto-aprovar) bateu com esta decisão e avisa em caso de divergência. Sem este registro o guard não tem como verificar — não pule.
 
    **Se `pause === true`**, use `AskUserQuestion`:
 
@@ -121,14 +121,14 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
    **Tasks:** {N} | Esforço total: {soma} | Caminho crítico: {IDs sem deps paralelas}
    ```
 
-   O hook state-sync registra a aprovação automaticamente em answers de AskUserQuestion. Em auto sem AskUserQuestion, a skill edita `state.json` diretamente.
+   No caminho manual, o hook state-sync registra a aprovação automaticamente em answers de AskUserQuestion (grava o gate no `feature.json` autoritativo, `approvedBy: "manual"`). Em auto sem AskUserQuestion, aprove via `morph-spec approve {feature} plan --mode auto` (ou `morph-spec advance {feature}` para já criar a pasta da próxima fase) — nunca via Edit à mão de state.json.
 
 ## Output esperado
 
 - `.morph/features/{feature}/2-plan/spec.md` — especificação técnica completa
 - `.morph/features/{feature}/2-plan/mandate.md` — contrato de implementação
 - `.morph/features/{feature}/2-plan/tasks.json` — task list estruturada válida contra schema
-- Gate 2 marcado aprovado em `state.json`
+- Gate 2 registrado aprovado em `.morph/features/{feature}/feature.json` (autoritativo)
 
 ## Referências
 

package/framework/skills/core/morph-proposal/SKILL.md

@@ -4,7 +4,7 @@ description: Orquestra a fase de proposta+plano de uma feature morph-spec. Encad
 version: core
 when-to-invoke: ao receber instrução "use /morph-proposal" do usuário, ou ao iniciar uma nova feature
 user-invokable: true
-cliVersion: "7.4.0"
+cliVersion: "7.6.0"
 ---
 
 # morph-proposal
@@ -17,7 +17,7 @@ Conduzir uma feature do request inicial até o plano aprovado (Gate 2), sem inte
 
 - Usuário pede "use /morph-proposal {feature}" ou "vamos planejar {feature}".
 - Início de qualquer feature nova num projeto morph-spec.
-- Em sessões retomadas, antes de continuar uma feature em progresso, verificar via `.morph/state.json` se a feature já passou pelos Gates.
+- Em sessões retomadas, antes de continuar uma feature em progresso, verificar via `.morph/features/{feature-name}/feature.json` (estado autoritativo da feature) se ela já passou pelos Gates.
 
 ## Argumentos
 
@@ -82,11 +82,12 @@ Escopo: {incluído} | Excluído: {exclusões}
 Stack: {compliance}
 ```
 
-O hook `state-sync.js` registra a aprovação automaticamente via PostToolUse em AskUserQuestion. Quando auto-aprovado, marcar manualmente:
+No caminho manual, o hook `state-sync.js` registra a aprovação automaticamente via PostToolUse quando a `AskUserQuestion` é respondida com "aprovado" (grava o gate no `feature.json` autoritativo, `approvedBy: "manual"`). Em `trust: auto` (sem AskUserQuestion), **aprove via CLI — nunca via Edit à mão de state.json**:
 
-```js
-// auto-aprovação: o hook detecta "aprovado" no answer label, mas em auto-mode
-// não há AskUserQuestion. Skill atualiza .morph/state.json via Edit fallback.
+```
+morph-spec approve {feature} proposal --mode auto
+# ou, para já aprovar o Gate 1 e criar a pasta 2-plan/ num passo só:
+morph-spec advance {feature}
 ```
 
 ### 4. Verificar retomada antes de morph-plan
@@ -128,7 +129,7 @@ Lógica idêntica ao passo 3 (`shouldPauseGate` + AskUserQuestion ou auto-aprova
 - `.morph/features/{feature}/2-plan/spec.md`
 - `.morph/features/{feature}/2-plan/mandate.md`
 - `.morph/features/{feature}/2-plan/tasks.json`
-- Gates 1 e 2 marcados aprovados em `.morph/state.json` (via hook state-sync).
+- Gates 1 e 2 registrados aprovados em `.morph/features/{feature}/feature.json` (autoritativo) — via `morph-spec approve`/`morph-spec advance` em auto, ou via hook state-sync no caminho manual.
 
 ## Referências
 

package/framework/skills/core/morph-review/SKILL.md

@@ -4,7 +4,7 @@ description: Conduz a fase de revisão e produz o review-report.md para o Gate 3
 version: core
 when-to-invoke: ao iniciar a fase review, após todas as tasks de tasks.json estarem com status `done`
 user-invokable: true
-cliVersion: "7.4.0"
+cliVersion: "7.6.0"
 ---
 
 # morph-review
@@ -88,12 +88,12 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
    **Recomendação:** Aprovado
    ```
 
-   O hook state-sync detecta a aprovação em answers de AskUserQuestion e marca `features[X].approvalGates.review = true`. Em auto sem AskUserQuestion, a skill atualiza state.json direto.
+   No caminho manual, o hook state-sync detecta a aprovação em answers de AskUserQuestion e grava `approvalGates.review = { approved: true, timestamp, approvedBy: "manual" }` no `feature.json` autoritativo da feature. Em auto sem AskUserQuestion, aprove via `morph-spec approve {feature} review --mode auto` — nunca via Edit à mão de state.json.
 
 ## Output esperado
 - `.morph/features/{feature}/4-review/review-report.md` com scores e recomendação
 - Trace da fase com `phase_summary` preenchido
-- Gate 3 marcado aprovado em state.json (auto ou manual)
+- Gate 3 registrado aprovado em `.morph/features/{feature}/feature.json` (autoritativo), na forma canônica `{ approved, timestamp, approvedBy }` — via `morph-spec approve` em auto, ou pelo hook state-sync no caminho manual
 
 ## Referências
 - `.morph/framework/MORPH.md` — seção 5 (Gate 3), seção 1 (papel Evaluator), Trust Mode

package/framework/skills/core/morph-stack-scan/SKILL.md

@@ -4,7 +4,7 @@ description: Varre o codebase existente, detecta stack atual, compara com o stac
 version: core
 when-to-invoke: ao iniciar uma feature em projeto brownfield (codebase já existente)
 user-invokable: true
-cliVersion: "7.4.0"
+cliVersion: "7.6.0"
 ---
 
 # morph-stack-scan

package/framework/skills/core/morph-standards/SKILL.md

@@ -4,7 +4,7 @@ description: Localiza e carrega um standard específico do STANDARDS.json sob de
 version: core
 when-to-invoke: quando precisar consultar um standard específico durante a implementação
 user-invokable: true
-cliVersion: "7.4.0"
+cliVersion: "7.6.0"
 ---
 
 # morph-standards

package/framework/standards/STANDARDS.json

@@ -1495,9 +1495,9 @@
       "digest": "Vitest for unit tests, React Testing Library for component tests. Mock next/navigation with vi.mock. Test Server Actions with direct function calls. Use MSW for API mocking in component tests. Playwright for E2E tests against running app. Never test implementation details — test user behavior and output."
     },
     {
-      "id": "infrastructure-docker-easypanel-deploy",
-      "name": "easypanel deploy",
-      "path": "infrastructure/docker/easypanel-deploy.md",
+      "id": "infrastructure-docker-coolify-deploy",
+      "name": "coolify deploy",
+      "path": "infrastructure/docker/coolify-deploy.md",
       "category": "infrastructure",
       "subcategory": "docker",
       "tags": [
@@ -1508,17 +1508,20 @@
         "docker"
       ],
       "aliases": [
-        "easypanel",
+        "coolify",
         "docker deploy",
         "self-hosted",
         "VPS deployment",
-        "docker compose"
+        "docker compose",
+        "coolify api",
+        "ssh deploy"
       ],
       "anchors": {
-        "setup": "#easypanel-service-config",
-        "deployment": "#zero-downtime-deploys"
+        "setup": "#coolify-service-config",
+        "deployment": "#zero-downtime-deploys",
+        "ssh": "#triggering-a-deploy-via-ssh--api"
       },
-      "digest": "Create app in EasyPanel from container registry image. Configure environment variables in EasyPanel UI — not in Dockerfile. Use EasyPanel's managed Postgres/Redis for databases. Configure /health endpoint for health checks. Enable HTTPS via Let's Encrypt automatically. Use EasyPanel volumes for persistent storage."
+      "digest": "Coolify is the self-hosted Docker PaaS. No MCP/CLI exists — all access is via SSH into the VPS, hitting the Coolify API at localhost:8000/api/v1 with a server-side token (never printed, never leaves the SSH session). Configure environment variables in Coolify UI/API — not in Dockerfile. Configure /health endpoint for health checks. HTTPS via Let's Encrypt automatic (Traefik). Redeploys trigger via GET /deploy?uuid={uuid} over SSH."
     },
     {
       "id": "infrastructure-neon-setup",
@@ -1657,6 +1660,75 @@
         "edit-workflows": "#iterative-editing-workflows"
       },
       "digest": "Guidelines for generating project images with Gemini Image MCP — prompt patterns, aspect ratios, design-system-aware prompts, iterative editing, and assets.md format."
+    },
+    {
+      "id": "ai-agents-durable-workflows-hitl",
+      "name": "durable workflows hitl",
+      "path": "ai-agents/durable-workflows-hitl.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "workflow",
+        "durability"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "durable workflow",
+        "checkpoint",
+        "checkpointing",
+        "human in the loop",
+        "hitl",
+        "requestport",
+        "requestinfoevent",
+        "resume workflow",
+        "long running workflow",
+        "approval workflow",
+        "icheckpointstore"
+      ],
+      "anchors": {
+        "when": "#quando-usar-este-standard",
+        "hitl": "#human-in-the-loop-via-requestport",
+        "checkpointing": "#checkpointing--durável-sem-depender-de-azure",
+        "durable-task": "#azure-durable-task-extension--escape-hatch-not-default"
+      },
+      "digest": "HITL via RequestPort — a workflow node that pauses and waits for an external (human) response via RequestInfoEvent. Checkpointing is GA and Azure-free: CheckpointManager.CreateInMemory() for tests, CreateJson(FileSystemJsonCheckpointStore) for local-disk durability, or a custom ICheckpointStore (recommended against the project's own Postgres). Microsoft.Agents.AI.DurableTask (Azure Durable Task Scheduler) is documented as an escape hatch only, not adopted as default."
+    },
+    {
+      "id": "ai-agents-vector-data-extensions",
+      "name": "vector data extensions",
+      "path": "ai-agents/vector-data-extensions.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "rag",
+        "vector-data"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "microsoft extensions vectordata",
+        "vectorstorecollection",
+        "vector store abstraction",
+        "data ingestion",
+        "ingestion pipeline",
+        "semantic kernel connectors exception",
+        "pgvector connector",
+        "vectorstorewriter"
+      ],
+      "anchors": {
+        "naming-trap": "#a-pegadinha-de-nomenclatura-crítico--leia-antes-de-tudo",
+        "maturity": "#maturidade-atual-verificado-2026-07-06",
+        "decision-matrix": "#decision-matrix--custom-pgvector-vs-vectordata",
+        "data-ingestion": "#microsoftextensionsdataingestion-preview--pipeline-pattern-para-adoção-futura"
+      },
+      "digest": "Microsoft.Extensions.VectorData.Abstractions (GA) is the provider-agnostic vector-store abstraction; Microsoft.Extensions.DataIngestion (preview) is the companion ETL pipeline. Concrete connectors (Postgres, Qdrant, SQL Server...) ship under Microsoft.SemanticKernel.Connectors.* package names despite having nothing to do with Semantic Kernel — an explicit exception to ai-agents-setup's SK ban. Default RAG storage stays ai-agents-rag-custom-pgvector; adopt VectorData only for genuine multi-backend portability, since the Postgres connector is still prerelease."
     }
   ],
   "sharedAliases": {

package/framework/standards/ai-agents/durable-workflows-hitl.md

@@ -0,0 +1,191 @@
+# MAF Workflows — Checkpointing & Human-in-the-Loop
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 1 (on-keyword)
+> **Keywords:** durable workflow, checkpoint, checkpointing, human in the loop, hitl, requestport, requestinfoevent, resume workflow, long running workflow, approval workflow, icheckpointstore, filesystemjsoncheckpointstore
+> **Read by Claude in:** plan (when `ai-agents-workflows` identifies a genuine HITL or long-running need) + implement (wiring `RequestPort` / `CheckpointManager`)
+
+**Verified against:** Microsoft.Agents.AI 1.0 GA (`Microsoft.Agents.AI.Workflows` namespace) + Microsoft.Agents.AI.DurableTask (prerelease, Azure-coupled — documented as an escape hatch, not adopted as default). Last-verified: 2026-07-06.
+
+---
+
+## Quando usar este standard
+
+Read `ai-agents-sweet-spot` and `ai-agents-workflows` first. This standard applies only once `ai-agents-workflows` has justified a Workflow **and** the reason is one of:
+
+- Long-running execution with a human-in-the-loop (HITL) approval step.
+- A workflow whose state must survive a process restart (deploy, crash, restart) between steps.
+
+If neither applies, a plain workflow (or no workflow at all — see `ai-agents-sweet-spot`) is enough; do not add checkpointing or `RequestPort` "just in case."
+
+---
+
+## Human-in-the-Loop via `RequestPort`
+
+HITL is modeled with `RequestPort` — a special node in the workflow graph that pauses execution and waits for an external (human) response instead of processing automatically.
+
+```csharp
+using Microsoft.Agents.AI.Workflows;
+
+// Request type the port sends out, response type it expects back.
+RequestPort<ApprovalRequest, bool> approvalPort =
+    RequestPort.Create<ApprovalRequest, bool>("RefundApproval");
+
+var workflow = new WorkflowBuilder(refundAnalyzerAgent)
+    .AddEdge(refundAnalyzerAgent, approvalPort)
+    .AddEdge(approvalPort, refundProcessorExecutor)
+    .WithOutputFrom(refundProcessorExecutor)
+    .Build();
+```
+
+Running the workflow, the caller watches for `RequestInfoEvent` and sends the human's answer back — the framework routes the response to the executor that made the request:
+
+```csharp
+await using StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, input);
+await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+{
+    switch (evt)
+    {
+        case RequestInfoEvent requestEvt:
+            // Surface requestEvt.Request to a human (dashboard, email, Slack, ...).
+            // This is where execution pauses until an external answer arrives.
+            bool approved = await GetHumanDecisionAsync(requestEvt.Request);
+            await run.SendResponseAsync(requestEvt.Request.CreateResponse(approved));
+            break;
+
+        case WorkflowOutputEvent outputEvt:
+            Console.WriteLine($"Workflow completed: {outputEvt.Data}");
+            break;
+    }
+}
+```
+
+**Agent tool-approval uses the same mechanism.** When an agent orchestration (sequential, concurrent, group chat) calls a tool marked as requiring approval, the workflow pauses and emits a `RequestInfoEvent` whose payload is a `ToolApprovalRequestContent` instead of a custom request type — no separate API to learn. See `ai-agents-multi-agent-patterns` for agent orchestration patterns this composes with.
+
+---
+
+## Checkpointing — durável sem depender de Azure
+
+Checkpointing is part of the **base, GA** `Microsoft.Agents.AI.Workflows` namespace — no extra/preview package required. A checkpoint captures the full workflow state at each superstep boundary: executor state, pending messages, and pending `RequestPort` requests (so a pending approval survives a restore).
+
+### Three storage options
+
+| Store | Durability | When to use |
+|-------|-----------|-------------|
+| `CheckpointManager.CreateInMemory()` | In-process only, lost on restart | Tests, demos, short-lived workflows |
+| `CheckpointManager.CreateJson(new FileSystemJsonCheckpointStore(dir))` | Local disk, survives process restart | Single-instance VPS deployments — no Azure, no preview package |
+| Custom `ICheckpointStore` implementation | Whatever backend you implement it against | **Recommended for production** — implement against the project's own Neon Postgres table, matching the ownership model already used by `ai-agents-rag-custom-pgvector` |
+
+```csharp
+using Microsoft.Agents.AI.Workflows;
+
+// Local-disk durability — no Azure dependency:
+var checkpointFolder = Directory.CreateDirectory("./checkpoints");
+CheckpointManager checkpointManager = CheckpointManager.CreateJson(
+    new FileSystemJsonCheckpointStore(checkpointFolder));
+
+StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, input, checkpointManager);
+await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+{
+    if (evt is SuperStepCompletedEvent stepEvt)
+    {
+        CheckpointInfo? checkpoint = stepEvt.CompletionInfo?.Checkpoint;
+        // Persist checkpoint.CheckpointId alongside the business record
+        // (e.g. the refund request row) so it can be resumed after a restart.
+    }
+}
+```
+
+Resuming after a restart — rehydrate into a **new** run instance from the last known checkpoint:
+
+```csharp
+StreamingRun resumedRun = await InProcessExecution.ResumeStreamingAsync(
+    newWorkflowInstance, savedCheckpoint, checkpointManager);
+
+await foreach (WorkflowEvent evt in resumedRun.WatchStreamAsync())
+{
+    // A pending RequestPort request is re-emitted here as a RequestInfoEvent —
+    // the paused approval survives the restart.
+    if (evt is RequestInfoEvent requestEvt) { /* re-surface to the human */ }
+}
+```
+
+### Custom executor state
+
+An executor with instance state beyond the message flow must opt in explicitly:
+
+```csharp
+internal sealed class RefundAnalyzerExecutor() : Executor("RefundAnalyzer")
+{
+    private const string StateKey = "AnalysisHistory";
+    private List<string> _history = [];
+
+    protected override ValueTask OnCheckpointingAsync(IWorkflowContext context, CancellationToken ct = default)
+        => context.QueueStateUpdateAsync(StateKey, _history);
+
+    protected override async ValueTask OnCheckpointRestoredAsync(IWorkflowContext context, CancellationToken ct = default)
+        => _history = await context.ReadStateAsync<List<string>>(StateKey);
+}
+```
+
+### `ICheckpointStore` — Neon/Postgres-backed (recommended production pattern)
+
+Implementing `ICheckpointStore` against the project's own Postgres database keeps checkpoint durability inside the same infrastructure the rest of the project already trusts (see `infrastructure-neon-setup`), instead of introducing a new storage dependency:
+
+```csharp
+public sealed class PostgresCheckpointStore(NpgsqlDataSource dataSource) : ICheckpointStore
+{
+    // Persist/retrieve checkpoint blobs in a workflow_checkpoints table
+    // (workflow_id, checkpoint_id, payload jsonb/bytea, created_at).
+    // Implement per the ICheckpointStore contract — see Microsoft.Agents.AI.Workflows docs.
+}
+```
+
+> **Security:** checkpoint storage is a trust boundary. Never restore a checkpoint from an untrusted or unauthenticated source — a tampered checkpoint can inject arbitrary workflow state.
+
+---
+
+## Azure Durable Task extension — escape hatch, not default
+
+`Microsoft.Agents.AI.DurableTask` (prerelease) adds durability backed by the **Azure Durable Task Scheduler**, including cost-efficient multi-day HITL waits with zero compute cost while paused. Even its "bring-your-own-compute / self-hosted" mode still requires a Durable Task Scheduler backend (`Microsoft.DurableTask.*.AzureManaged` packages) — self-hosted means your own worker process, not an Azure-free backend.
+
+This framework deploys to VPS/Coolify by default and does not adopt Azure as a default dependency (see `ai-agents-setup` §3.4 on Azure OpenAI). For that reason, `Microsoft.Agents.AI.DurableTask` is **not adopted as default** here. The `CheckpointManager` + custom `ICheckpointStore` pattern above covers the same durability need without an Azure dependency. Only reach for the Durable Task extension when a specific client already runs on Azure and needs multi-day/serverless HITL waits — record that decision in `decisions.md`.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Right way |
+|--------------|----------------|-----------|
+| Adding a `Workflow` with `RequestPort` but no `CheckpointManager` | A pending human approval is lost if the process restarts while waiting | Wire a persistent `CheckpointManager` (file-based or custom `ICheckpointStore`) whenever a HITL wait can outlive a single process lifetime |
+| Reaching for `Microsoft.Agents.AI.DurableTask` by default | Adds an Azure Durable Task Scheduler dependency this framework's VPS-first stack doesn't otherwise need | Use base `CheckpointManager` + custom `ICheckpointStore`; reserve the Durable Task extension for projects already committed to Azure |
+| Storing checkpoints in a public or unauthenticated location | Checkpoint storage is a trust boundary — a tampered checkpoint can inject arbitrary state on restore | Restrict read/write access to the checkpoint store the same way you would a secrets store |
+| Skipping `OnCheckpointingAsync`/`OnCheckpointRestoredAsync` on an executor with instance state | State silently resets to defaults after a resume, corrupting workflow logic | Any executor with fields beyond the message flow must implement both methods |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] `ai-agents-workflows`' HITL or long-running criterion is documented in `decisions.md` before this standard is applied.
+- [ ] Every HITL wait point uses `RequestPort` + handles `RequestInfoEvent`.
+- [ ] A `CheckpointManager` is wired whenever the workflow can pause across a process restart — `CreateInMemory()` is acceptable only for tests/demos.
+- [ ] If a custom `ICheckpointStore` was implemented, it persists to infrastructure already owned by the project (e.g., Neon Postgres), not a new ad hoc store.
+- [ ] Executors with instance state implement `OnCheckpointingAsync` and `OnCheckpointRestoredAsync`.
+- [ ] `Microsoft.Agents.AI.DurableTask` is present only if the project already runs on Azure and the choice is recorded in `decisions.md`.
+
+---
+
+## References
+
+- `ai-agents-workflows` — when a Workflow (and therefore this standard) is justified
+- `ai-agents-sweet-spot` — single agent vs workflow decision
+- `ai-agents-multi-agent-patterns` — agent orchestrations that share the tool-approval HITL mechanism
+- `ai-agents-setup` — the VPS-first, non-Azure-default stance this standard follows for durability
+- `infrastructure-neon-setup` — Postgres connection patterns for a custom `ICheckpointStore`
+- Human-in-the-loop (HITL) | Microsoft Learn: https://learn.microsoft.com/en-us/agent-framework/workflows/human-in-the-loop
+- Checkpoints | Microsoft Learn: https://learn.microsoft.com/en-us/agent-framework/workflows/checkpoints
+- Durable Extension | Microsoft Learn: https://learn.microsoft.com/en-us/agent-framework/integrations/durable-extension
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/durable-workflows-hitl.md v1.0 (2026-07-06)*