@polymorphism-tech/morph-spec 8.21.0 → 8.23.0

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

@@ -4,7 +4,7 @@ description: Conduz a fase opcional de UI/UX — design system, mockups, compone
 version: core
 when-to-invoke: ao tomar o ramo uiux (morph-spec advance --design), depois do Gate 1 e antes do morph-plan
 user-invokable: true
-cliVersion: "8.21.0"
+cliVersion: "8.23.0"
 ---
 
 # morph-uiux

package/framework/standards/STANDARDS.json

@@ -1779,6 +1779,34 @@
         "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."
+    },
+    {
+      "id": "backend-dotnet-testing",
+      "name": "testing",
+      "path": "backend/dotnet/testing.md",
+      "category": "backend",
+      "subcategory": "dotnet",
+      "tags": [
+        "backend",
+        "dotnet"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "xunit",
+        "TimeProvider",
+        "FakeTimeProvider",
+        "fake clock",
+        "integration test",
+        "ProblemDetails",
+        "error body assertion"
+      ],
+      "anchors": {
+        "clock": "#rule-1--inject-timeprovider-fake-it-with-faketimeprovider-in-tests",
+        "errorbody": "#rule-2--error-path-tests-assert-the-response-body-not-just-the-status-code"
+      },
+      "digest": "Inject TimeProvider (never DateTime.UtcNow / DateOnly.FromDateTime(DateTime.UtcNow) directly in a handler or validator) and fake it with FakeTimeProvider (Microsoft.Extensions.TimeProvider.Testing) in integration tests — deterministic, no midnight-UTC flake, boundary dates (today vs. yesterday) become facts about the fake clock instead of when the suite happens to run. xUnit + WebApplicationFactory error-path tests (400/404/409) must assert the ProblemDetails response BODY (title/detail/violated field or error code), never just the HTTP status code — a status-only assertion lets the wrong validation rule or the wrong error branch pass silently as long as the status matches."
     }
   ],
   "sharedAliases": {

package/framework/standards/backend/dotnet/fluent-validation-vsa.md

@@ -23,7 +23,10 @@ One validator per request DTO. Lives in the same feature folder as the handler:
 // Features/BookFeature/CreateBook/CreateBookValidator.cs
 public class CreateBookValidator : AbstractValidator<CreateBookRequest>
 {
-    public CreateBookValidator()
+    // TimeProvider injected, never DateTime.UtcNow read directly — see
+    // backend-dotnet-testing (Rule 1): a validator that reads the real clock
+    // cannot be tested deterministically with FakeTimeProvider.
+    public CreateBookValidator(TimeProvider timeProvider)
     {
         RuleFor(c => c.Title)
             .NotEmpty().WithMessage("Title is required")
@@ -41,7 +44,7 @@ public class CreateBookValidator : AbstractValidator<CreateBookRequest>
 
         RuleFor(c => c.PublishedYear)
             .GreaterThan(1000).WithMessage("Published year must be a valid year")
-            .LessThanOrEqualTo(DateTime.UtcNow.Year)
+            .LessThanOrEqualTo(timeProvider.GetUtcNow().Year)
             .WithMessage("Published year cannot be in the future");
     }
 }

package/framework/standards/backend/dotnet/testing.md

@@ -0,0 +1,127 @@
+# .NET Integration Testing — VSA
+
+> **Scope:** dotnet-vsa
+> **Layer:** 0 (always load)
+> **Keywords:** testing, xunit, integration test, TimeProvider, FakeTimeProvider, WebApplicationFactory, ProblemDetails, error body assertion
+> **Load When:** writing or reviewing tests for a dotnet VSA project
+
+**Verified against:** .NET 10 + xUnit 2 + `Microsoft.Extensions.TimeProvider.Testing`. Last-verified: 2026-08-12.
+
+---
+
+## Overview
+
+Integration tests exercise the real ASP.NET Core pipeline (`WebApplicationFactory`) against
+an in-memory/test database — the pattern used across `backend-dotnet-vsa-handler-patterns`'
+handler examples. Two failure modes recur in generated test suites and each has a dedicated
+rule below: tests that read the real system clock instead of an injected, fakeable one; and
+error-path tests that assert only the HTTP status code, leaving the actual failure contract
+(the response body) unverified.
+
+---
+
+## Rule 1 — Inject `TimeProvider`, fake it with `FakeTimeProvider` in tests
+
+Any logic that compares against "now" (a past-date validation, an expiry check, a due-date
+default) MUST read the clock through an injected `TimeProvider` — never `DateTime.UtcNow` or
+`DateOnly.FromDateTime(DateTime.UtcNow)` directly in a handler or validator. A validator that
+reads the real clock makes "today" a moving target: a test asserting "today is valid, yesterday
+is rejected" flakes for real around UTC midnight, and is untestable for the "exactly at the
+boundary" case at all.
+
+```csharp
+// Features/VisitFeature/CloseVisit/CloseVisitValidator.cs
+public sealed class CloseVisitValidator : AbstractValidator<CloseVisitRequest>
+{
+    public CloseVisitValidator(TimeProvider timeProvider)
+    {
+        RuleFor(c => c.FollowUpDate)
+            .Must(date => date!.Value >= Today(timeProvider))
+            .WithErrorCode(VisitErrors.FollowUpDateInPast.Code)
+            .WithMessage(VisitErrors.FollowUpDateInPast.Description)
+            .When(c => c.FollowUpDate.HasValue);
+    }
+
+    private static DateOnly Today(TimeProvider timeProvider) =>
+        DateOnly.FromDateTime(timeProvider.GetUtcNow().UtcDateTime);
+}
+```
+
+Register the real clock once in `Program.cs`:
+
+```csharp
+builder.Services.AddSingleton(TimeProvider.System);
+```
+
+In tests, swap it for `Microsoft.Extensions.TimeProvider.Testing`'s `FakeTimeProvider` —
+deterministic, no dependency on when the suite happens to run:
+
+```csharp
+// tests/.../Infrastructure/VetClinicApiFactory.cs
+public sealed class VetClinicApiFactory : WebApplicationFactory<Program>
+{
+    public FakeTimeProvider TimeProvider { get; } = new(new DateTimeOffset(2026, 6, 15, 0, 0, 0, TimeSpan.Zero));
+
+    protected override void ConfigureWebHost(IWebHostBuilder builder) =>
+        builder.ConfigureServices(services =>
+        {
+            services.RemoveAll<TimeProvider>();
+            services.AddSingleton<TimeProvider>(TimeProvider);
+        });
+}
+```
+
+```csharp
+// The boundary case ("today is accepted, yesterday is not") becomes a fact about
+// the fake clock, not about when CI happens to run.
+DateOnly today = DateOnly.FromDateTime(factory.TimeProvider.GetUtcNow().UtcDateTime);
+DateOnly yesterday = today.AddDays(-1);
+```
+
+---
+
+## Rule 2 — Error-path tests assert the response BODY, not just the status code
+
+A test that only checks `response.StatusCode` proves the endpoint returns *a* 400/404/409 — it
+proves nothing about *why*, and lets the wrong validation rule or the wrong error code pass
+silently as long as the status happens to match. Every error-path test MUST also assert the
+`ProblemDetails` body: at minimum `title` (or `type`) and the specific field/reason that
+triggered the failure.
+
+```csharp
+// Wrong — proves only that SOMETHING was rejected, not what:
+HttpResponseMessage response = await client.PostAsJsonAsync($"visits/{id}/close", body);
+Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode);
+```
+
+```csharp
+// Right — the body is the actual contract a client integrates against:
+HttpResponseMessage response = await client.PostAsJsonAsync($"visits/{id}/close", body);
+Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode);
+
+ProblemDetails? problem = await response.Content.ReadFromJsonAsync<ProblemDetails>();
+Assert.NotNull(problem);
+Assert.Contains("FollowUpDate", problem!.Extensions["errors"]!.ToString());
+Assert.Equal(VisitErrors.FollowUpDateInPast.Code, GetErrorCode(problem));
+```
+
+The same discipline applies to 404 (`NotFound` — assert the entity/id named in the problem
+detail) and 409 (`Conflict` — assert the conflict reason, e.g. `"Visit.AlreadyClosed"`, not just
+that a conflict happened). A status-only assertion is a regression magnet: swapping
+`VisitErrors.NotFound` for `VisitErrors.AlreadyClosed` in the wrong branch still returns 404/409
+respectively and the test suite stays green.
+
+---
+
+## Anti-Patterns
+
+| Do NOT | Do Instead |
+|--------|------------|
+| Read `DateTime.UtcNow` / `DateOnly.FromDateTime(DateTime.UtcNow)` directly in a handler or validator | Inject `TimeProvider`, read `timeProvider.GetUtcNow()` |
+| Leave a test's "past date" derived from the real system clock (`DateTime.UtcNow.AddDays(-1)`) | Swap `TimeProvider` for `FakeTimeProvider` in the test factory and derive dates from it |
+| Assert only `response.StatusCode` on an error path | Also deserialize and assert the `ProblemDetails` body (title/detail/violated field or error code) |
+| Treat a passing status-only test as proof the error message/code is correct | Assert the specific error code/field — a wrong branch can still return the right status |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/templates/infrastructure/docker/docker-compose.template.yml

@@ -1,7 +1,19 @@
 # Docker Compose for Local Development
 # Next.js + Neon Stack
-
-version: '3.8'
+#
+# Ports come from variables with sane defaults so `morph-spec e2e up` can hand
+# each feature worktree its own port block (see env-allocator.js). Hardcode
+# "3000:3000" here and two features running side by side collide on the host,
+# no matter what the harness injects — the container names would be distinct
+# and the ports would not.
+#
+# Healthchecks are what make `up --wait` meaningful: without them Compose
+# reports "started" the moment the process launches, and the e2e node would
+# navigate an application that is not serving yet.
+#
+# The harness also exports PLAYWRIGHT_BASE_URL for the same allocated port, so
+# `playwright.config.ts` must read it instead of hardcoding a URL:
+#   baseURL: process.env.PLAYWRIGHT_BASE_URL ?? `http://localhost:${process.env.PORT ?? 3000}`
 
 services:
   # Next.js Application
@@ -11,7 +23,7 @@ services:
       dockerfile: Dockerfile.dev
     container_name: {{kebabCase FEATURE_NAME}}-app
     ports:
-      - "3000:3000"
+      - "${PORT:-3000}:3000"
     environment:
       - NODE_ENV=development
       - DATABASE_URL=${DATABASE_URL}
@@ -20,7 +32,14 @@ services:
       - /app/node_modules
       - /app/.next
     depends_on:
-      - postgres
+      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
+      start_period: 20s
     networks:
       - app-network
 
@@ -30,7 +49,7 @@ services:
     container_name: {{kebabCase FEATURE_NAME}}-postgres
     restart: unless-stopped
     ports:
-      - "5432:5432"
+      - "${POSTGRES_PORT:-5432}:5432"
     environment:
       POSTGRES_USER: postgres
       POSTGRES_PASSWORD: postgres
@@ -38,6 +57,11 @@ services:
     volumes:
       - postgres-data:/var/lib/postgresql/data
       - ./migrations:/docker-entrypoint-initdb.d
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d {{snakeCase FEATURE_NAME}}"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
     networks:
       - app-network
 

package/package.json

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

package/src/commands/e2e/e2e.js

@@ -0,0 +1,318 @@
+/**
+ * `morph-spec e2e up|status|down` — lifecycle of the verification stack.
+ *
+ * The stack is deliberately NOT torn down between verifies: cold-starting a
+ * .NET container per task is the difference between a loop people run and one
+ * they disable. `up` brings it (or reuses it), `status` says whether what is
+ * running still matches the working tree, and `down` releases it — which
+ * `morph-spec finish` also does as part of teardown.
+ *
+ * All the real logic lives in framework/hooks/shared/e2e-check.js, shared with
+ * the `verify` e2e node so the two can never drift.
+ *
+ * @module commands/e2e
+ */
+
+import chalk from 'chalk';
+import { execFileSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join, resolve } from 'path';
+
+import {
+  bringUpStack,
+  composeProjectName,
+  computeSourceStamp,
+  defaultExec,
+  getStackStatus,
+  isDockerAvailable,
+  prepareAuth,
+  readStamp,
+  resolveComposeFile,
+  resolveSpecCommand,
+  tearDownStack,
+} from '../../../framework/hooks/shared/e2e-check.js';
+import { buildComposeEnv } from '../../lib/e2e/compose-env.js';
+
+/** Exit code for a usage error, matching `verify`'s convention. */
+const EXIT_USAGE = 2;
+
+// ============================================================================
+// Shared context
+// ============================================================================
+
+/**
+ * Everything the three subcommands need, resolved once.
+ * Returns null (after printing) when the project has no compose file — that is
+ * a usage error here, unlike in the verify node where it is a graded skip.
+ */
+function resolveContext(featureName, { json = false } = {}) {
+  const cwd = process.cwd();
+  const config = readConfig(cwd);
+  const composeFile = resolveComposeFile(cwd, config);
+
+  if (!composeFile) {
+    const message =
+      'No compose file found (compose.yaml, docker-compose.yml, …). ' +
+      'Set project.e2e.composeFile in .morph/config/config.json if it lives elsewhere.';
+    if (json) console.log(JSON.stringify({ error: message }, null, 2));
+    else console.error(chalk.red(`\n❌ ${message}\n`));
+    return null;
+  }
+
+  const projectName = composeProjectName(featureName);
+  const gitCommonDir = resolveGitCommonDir(cwd);
+
+  return {
+    cwd,
+    config,
+    composeFile,
+    projectName,
+    gitCommonDir,
+    env: buildEnv({ cwd, config, featureName, projectName, gitCommonDir }),
+  };
+}
+
+/**
+ * Compose environment: the port block this feature owns, plus any credentials
+ * from the gitignored auth env file.
+ *
+ * The port block comes from `buildComposeEnv` rather than being assembled here
+ * so this command and the `e2e` node inside `verify` agree by construction —
+ * isolation that exists only in the command nobody runs is no isolation at all.
+ * `COMPOSE_PROJECT_NAME` isolates container NAMES but not host ports; a compose
+ * that hardcodes ports instead of reading `${PORT:-3000}` cannot be isolated at
+ * all, which is surfaced as a warning rather than silently accepted.
+ */
+function buildEnv({ cwd, config, featureName, projectName, gitCommonDir }) {
+  return {
+    COMPOSE_PROJECT_NAME: projectName,
+    ...buildComposeEnv({ cwd, config, featureName, gitCommonDir }),
+  };
+}
+
+/**
+ * Warn once when the compose file publishes fixed host ports: with a hardcoded
+ * `"3000:3000"` the fleet port block cannot take effect, so two features
+ * running simultaneously will collide no matter what we inject.
+ */
+function warnOnFixedPorts(cwd, composeFile) {
+  try {
+    const raw = readFileSync(join(cwd, composeFile), 'utf8');
+    const publishesFixed = /^\s*-\s*["']?\d+:\d+["']?\s*$/m.test(raw);
+    if (publishesFixed) {
+      console.log(
+        chalk.yellow(
+          '⚠️  Compose publishes fixed host ports. Parallel worktrees will collide — ' +
+            'use ${PORT:-3000}:3000 so the fleet port block applies.'
+        )
+      );
+    }
+  } catch {
+    // Unreadable compose is the caller's problem, not this warning's.
+  }
+}
+
+// ============================================================================
+// up
+// ============================================================================
+
+/**
+ * `morph-spec e2e up <feature> [--fresh]`
+ *
+ * Exit codes: 0 = stack healthy · 1 = failed to come up (or auth broke) ·
+ * 2 = usage (no compose file / no docker).
+ */
+export async function e2eUpCommand(featureName, options = {}) {
+  const ctx = resolveContext(featureName, options);
+  if (!ctx) process.exit(EXIT_USAGE);
+
+  if (!isDockerAvailable(ctx.cwd)) {
+    console.error(chalk.red('\n❌ Docker is not available in this environment.\n'));
+    process.exit(EXIT_USAGE);
+  }
+
+  if (!options.json) warnOnFixedPorts(ctx.cwd, ctx.composeFile);
+
+  const result = bringUpStack(ctx.cwd, {
+    composeFile: ctx.composeFile,
+    projectName: ctx.projectName,
+    gitCommonDir: ctx.gitCommonDir,
+    env: ctx.env,
+    forceFresh: Boolean(options.fresh),
+  });
+
+  const auth =
+    result.status === 'pass'
+      ? prepareAuth(ctx.cwd, { config: ctx.config, env: ctx.env })
+      : { status: 'skip', reason: null };
+
+  const failed = result.status === 'fail' || auth.status === 'fail';
+  const payload = {
+    feature: featureName,
+    project: ctx.projectName,
+    composeFile: ctx.composeFile,
+    status: failed ? 'fail' : 'pass',
+    reused: result.reused,
+    reason: result.reason,
+    auth: { status: auth.status, reason: auth.reason },
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else if (failed) {
+    console.error(chalk.red(`\n✗ ${result.reason || auth.reason}\n`));
+    if (result.output) console.error(result.output);
+  } else {
+    const how = result.reused ? chalk.gray(`(${result.reason})`) : chalk.gray('(built)');
+    console.log(chalk.green(`\n✓ Stack up — ${ctx.projectName} ${how}`));
+    if (auth.reason) console.log(chalk.gray(`  auth: ${auth.reason}`));
+    console.log('');
+  }
+
+  process.exit(failed ? 1 : 0);
+}
+
+// ============================================================================
+// status
+// ============================================================================
+
+/**
+ * Where the app actually landed.
+ *
+ * The reviewer hands this to the evaluator instead of letting it guess
+ * `localhost:3000` — each feature owns a port block, so the default port is the
+ * one address most likely to be wrong. Mirrors what `playwright.config.ts` is
+ * asked to do, deliberately: one rule, two readers.
+ *
+ * @param {Record<string,string>} env
+ * @returns {string}
+ */
+export function resolveBaseUrl(env = {}) {
+  return env.PLAYWRIGHT_BASE_URL ?? `http://localhost:${env.PORT ?? 3000}`;
+}
+
+/**
+ * `morph-spec e2e status <feature> [--json]`
+ *
+ * Answers the question that matters before trusting a green run: is what is
+ * running still built from the code on disk? Exit 0 when up AND fresh, 1
+ * otherwise — so it can gate a script.
+ */
+export async function e2eStatusCommand(featureName, options = {}) {
+  const ctx = resolveContext(featureName, options);
+  if (!ctx) process.exit(EXIT_USAGE);
+
+  const status = getStackStatus(ctx.cwd, {
+    composeFile: ctx.composeFile,
+    projectName: ctx.projectName,
+    env: ctx.env,
+  });
+
+  const stamp = computeSourceStamp(ctx.cwd);
+  const previous = ctx.gitCommonDir ? readStamp(ctx.gitCommonDir, ctx.projectName) : null;
+  const fresh = Boolean(stamp && previous?.stamp === stamp);
+
+  const spec = resolveSpecCommand(ctx.cwd, ctx.config, ctx.config?.project?.frontendPath);
+
+  const payload = {
+    feature: featureName,
+    project: ctx.projectName,
+    composeFile: ctx.composeFile,
+    up: status.up,
+    healthy: status.healthy,
+    fresh,
+    baseUrl: resolveBaseUrl(ctx.env),
+    builtAt: previous?.builtAt ?? null,
+    specs: spec ? `${spec.command} ${spec.args.join(' ')}` : null,
+    services: status.services.map((s) => ({
+      name: s.Service ?? s.Name ?? null,
+      state: s.State ?? null,
+      health: s.Health || null,
+    })),
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log('');
+    console.log(chalk.bold(`E2E stack — ${ctx.projectName}`));
+    console.log(chalk.gray(`compose: ${ctx.composeFile}`));
+    console.log(chalk.gray(`url:     ${payload.baseUrl}`));
+    console.log('');
+    console.log(`  up       ${status.up ? chalk.green('yes') : chalk.gray('no')}`);
+    console.log(`  healthy  ${status.healthy ? chalk.green('yes') : chalk.gray('no')}`);
+    console.log(
+      `  fresh    ${fresh ? chalk.green('yes') : chalk.yellow('no — source changed since build')}`
+    );
+    console.log(`  specs    ${spec ? payload.specs : chalk.gray('none (smoke only)')}`);
+    for (const s of payload.services) {
+      console.log(chalk.gray(`    · ${s.name}: ${s.state}${s.health ? ` / ${s.health}` : ''}`));
+    }
+    console.log('');
+  }
+
+  process.exit(status.up && status.healthy && fresh ? 0 : 1);
+}
+
+// ============================================================================
+// down
+// ============================================================================
+
+/**
+ * `morph-spec e2e down <feature> [--volumes]`
+ *
+ * Teardown is best-effort by design — a stack that will not come down must
+ * never block `finish`.
+ */
+export async function e2eDownCommand(featureName, options = {}) {
+  const ctx = resolveContext(featureName, options);
+  if (!ctx) process.exit(EXIT_USAGE);
+
+  const result = tearDownStack(ctx.cwd, {
+    composeFile: ctx.composeFile,
+    projectName: ctx.projectName,
+    env: ctx.env,
+    volumes: Boolean(options.volumes),
+  });
+
+  if (options.json) {
+    console.log(JSON.stringify({ feature: featureName, project: ctx.projectName, status: result.status }, null, 2));
+  } else if (result.status === 'pass') {
+    console.log(chalk.green(`\n✓ Stack down — ${ctx.projectName}\n`));
+  } else {
+    console.log(chalk.yellow(`\n⚠️  Teardown reported a problem (not fatal):\n${result.output}\n`));
+  }
+
+  process.exit(0);
+}
+
+// ============================================================================
+// Shared helpers
+// ============================================================================
+
+function readConfig(cwd) {
+  try {
+    const path = join(cwd, '.morph', 'config', 'config.json');
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, 'utf8').replace(/^/, ''));
+  } catch {
+    return null;
+  }
+}
+
+/** Same resolution (and same fail-open) as verify-runner's. */
+function resolveGitCommonDir(cwd) {
+  try {
+    const common = execFileSync('git', ['rev-parse', '--git-common-dir'], {
+      cwd,
+      stdio: 'pipe',
+      encoding: 'utf-8',
+      windowsHide: true,
+    }).trim();
+    return common ? resolve(cwd, common) : null;
+  } catch {
+    return null;
+  }
+}
+
+export { defaultExec };

package/src/commands/state/approve.js

@@ -325,6 +325,17 @@ export async function approveCommand(featureName, gateName, options = {}) {
       ...(selfAssessed ? { selfAssessed: true } : {}),
     });
 
+    // Fleet handoff (mirrors advance.js): approving a gate is exactly when a
+    // feature hands over between sessions too — `approve` is the real path
+    // Gate 2 took in the field (`approve <f> plan --mode auto`), not just
+    // `advance`, so a handoff.md left stale after approve was the common
+    // case, not the edge case. Same helper, same fail-open contract: a
+    // regeneration failure must never fail the approval itself.
+    try {
+      const { writeHandoff } = await import('../../lib/generators/handoff-generator.js');
+      writeHandoff(featureName, process.cwd());
+    } catch { /* fail-open */ }
+
     if (selfAssessed) {
       console.log(chalk.yellow('\n⚠️  Gate 3 aprovado SEM avaliador independente (--self-assessed).'));
       console.log(chalk.gray('   Registrado em feature.json → approvalGates.review.selfAssessed.'));

package/src/commands/state/archive.js

@@ -63,7 +63,8 @@ function readReviewApproved(fjPath) {
  * @param {string} feature
  * @param {{ cwd?: string, force?: boolean, git?: boolean }} [opts]
  * @returns {{ ok: boolean, error?: string, archived?: boolean, alreadyArchived?: boolean,
- *   committed?: boolean, staged?: boolean, archivePath?: string, promotedUseCases?: string[] }}
+ *   committed?: boolean, staged?: boolean, archivePath?: string, promotedUseCases?: string[],
+ *   refusedUseCases?: Array<{id: string, incoming: string, existing: string, existingFeature: string, message: string}> }}
  */
 export function runArchive(feature, opts = {}) {
   const cwd = opts.cwd || process.cwd();
@@ -156,9 +157,11 @@ export function runArchive(feature, opts = {}) {
   //    (MORPH.md §2.2). Fail-open: any failure degrades to "promoted nothing",
   //    never to a refused close.
   let promotedUseCases = [];
+  let refusedUseCases = [];
   try {
-    const { promoted } = promoteUseCases(cwd, archivePath);
+    const { promoted, refused } = promoteUseCases(cwd, archivePath);
     promotedUseCases = promoted;
+    refusedUseCases = refused;
     if (promoted.length && useGit && staged) {
       // This staging exists for the NEW files: promoted use cases are untracked,
       // and the scoped `commit -- <pathspec>` below only knows paths git already
@@ -203,7 +206,7 @@ export function runArchive(feature, opts = {}) {
     } catch { /* index is derivable — non-fatal */ }
   }
 
-  return { ok: true, archived: true, committed, staged, archivePath, promotedUseCases };
+  return { ok: true, archived: true, committed, staged, archivePath, promotedUseCases, refusedUseCases };
 }
 
 /**
@@ -244,6 +247,12 @@ export async function archiveCommand(featureName, options = {}) {
     if (result.promotedUseCases?.length) {
       console.log(chalk.gray(`   ${result.promotedUseCases.length} use case(s) promoted → .morph/specs/usecases/ (status: implemented).`));
     }
+    if (result.refusedUseCases?.length) {
+      console.log(chalk.yellow(`\n⚠️  ${result.refusedUseCases.length} use case(s) NOT promoted — numbering collision:`));
+      for (const r of result.refusedUseCases) {
+        console.log(chalk.yellow(`   ${r.message}`));
+      }
+    }
     if (result.committed) console.log(chalk.gray(`   Move committed on the current branch.\n`));
     else if (result.staged) console.log(chalk.gray(`   Move staged in git; commit it when ready.\n`));
     else console.log('');