@polymorphism-tech/morph-spec 8.22.0 → 8.24.1

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

@@ -4,7 +4,7 @@ description: Localiza um standard específico via busca server-side (morph-spec
 version: core
 when-to-invoke: quando precisar consultar um standard específico durante a implementação
 user-invokable: true
-cliVersion: "8.22.0"
+cliVersion: "8.24.1"
 ---
 
 # morph-standards

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.22.0"
+cliVersion: "8.24.1"
 ---
 
 # 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/package.json

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

package/src/commands/project/worktree.js

@@ -31,10 +31,13 @@
  */
 
 import { execSync, execFileSync } from 'child_process';
-import { existsSync, mkdirSync, symlinkSync, readFileSync, writeFileSync, appendFileSync, lstatSync, unlinkSync, rmdirSync, readdirSync, cpSync } from 'fs';
-import { join, resolve, dirname, relative } from 'path';
+import { existsSync, mkdirSync, symlinkSync, readFileSync, writeFileSync, appendFileSync, lstatSync, unlinkSync, rmdirSync, cpSync } from 'fs';
+import { join, resolve, dirname } from 'path';
 import chalk from 'chalk';
 import { detectDefaultBranch } from '../../lib/git/default-branch.js';
+// The reparse scan lives in hooks/shared because the PreToolUse guardrail needs
+// the SAME answer this file does, and hooks can never import from `src/`.
+import { findReparsePoints } from '../../../framework/hooks/shared/reparse-scan.js';
 
 /**
  * The directory new worktrees are created under, relative to the primary root.
@@ -740,64 +743,6 @@ export function unlinkWorktreeInfraLinks(worktreePath, mainCwd) {
   return removed;
 }
 
-/**
- * Every reparse point anywhere under `worktreePath`, as relative paths.
- *
- * CRITICAL — this is the gate that keeps `morph-spec finish` (worktree teardown)
- * from destroying the project, and it must be exhaustive. BOTH `git worktree remove` and its
- * `--force` fallback FOLLOW reparse points out of the worktree and delete the
- * PRIMARY ROOT's real files. The plain removal is not the safe one: it refuses
- * only when it sees modified/untracked *tracked-scope* content, so a GITIGNORED
- * junction (`node_modules`, `.claude`) leaves `git status` empty, the removal
- * proceeds, exits 0 — and the target is gone.
- *
- * So the check cannot live in the `catch` of the plain removal (unreachable on
- * exactly the destructive path), and it cannot be a fixed list of the links
- * `setup` creates: a nested link inside a real `node_modules` (npm link, npm
- * workspaces) is invisible to any top-level inventory. We scan the whole tree
- * and NEVER recurse INTO a reparse point — descending one would walk the target
- * we are trying to protect (and could not terminate on a cycle).
- *
- * An empty result is NOT the same as a safe one: a directory we could not read
- * or an entry we could not lstat might BE (or contain) a reparse point. Those
- * answer `unprovable: true`, and the caller must treat that exactly like a found
- * link — decline. "I saw nothing" and "I proved there is nothing" are different
- * claims, and only the second one may authorize a removal.
- *
- * @param {string} dir
- * @param {string} [base] - root of the scan, for relative reporting
- * @param {{points: string[], unprovable: string[]}} [acc]
- * @returns {{points: string[], unprovable: string[]}} both empty = provably clean
- */
-function findReparsePoints(dir, base = dir, acc = { points: [], unprovable: [] }) {
-  let entries;
-  try {
-    entries = readdirSync(dir, { withFileTypes: true });
-  } catch {
-    // Unreadable (ACL, lock, EMFILE): we cannot prove what is in here.
-    acc.unprovable.push((relative(base, dir) || '.').replace(/\\/g, '/'));
-    return acc;
-  }
-  for (const entry of entries) {
-    const p = join(dir, entry.name);
-    let st;
-    try {
-      st = lstatSync(p);
-    } catch {
-      acc.unprovable.push(relative(base, p).replace(/\\/g, '/'));
-      continue;
-    }
-    if (st.isSymbolicLink()) {
-      // Forward slashes: every other path this command reports is normalized,
-      // and these end up in JSON the caller may compare or display.
-      acc.points.push(relative(base, p).replace(/\\/g, '/'));
-      continue; // do NOT descend — that is the target, not the worktree
-    }
-    if (st.isDirectory() && entry.name !== '.git') findReparsePoints(p, base, acc);
-  }
-  return acc;
-}
-
 /**
  * Gitignored paths a morph worktree owns and that are safe to remove — but ONLY
  * once backed up (see backupWorktreeIgnored). `.morph/state.json` is provably
@@ -1085,6 +1030,60 @@ async function clearRootWorktreeRegistration(root, feature) {
   } catch { /* fail-open — a dirty root is a nuisance, not a reason to fail */ }
 }
 
+/**
+ * Why `git worktree remove` failed, from its stderr.
+ *
+ * The distinction that matters is `in-use` — on Windows a process whose cwd is
+ * inside the worktree (another Claude Code instance, VS Code, a dev server, a
+ * stray terminal) pins the directory and the removal cannot proceed. That is a
+ * human-actionable cause with a specific fix ("close it"), and printing it is
+ * the difference between a message the user can act on and one that just says
+ * "failed" — which is what made a raw `git worktree remove --force` look like
+ * the only way forward.
+ *
+ * @param {string} stderr
+ * @returns {{ kind: 'in-use'|'unknown', detail: string }}
+ */
+function classifyRemovalError(stderr) {
+  const text = String(stderr || '').trim();
+  const inUse = /permission denied|EPERM|EBUSY|being used by another process|resource busy|access is denied|is locked/i.test(text);
+  // First stderr line only: the rest is git's usual advice block, and this lands
+  // in a JSON field a human reads.
+  const detail = text.split(/\r?\n/).find((l) => l.trim()) || '';
+  return { kind: inUse ? 'in-use' : 'unknown', detail: detail.slice(0, 200) };
+}
+
+/**
+ * Run the removal, with one retry round after a short pause.
+ *
+ * The retry exists for the transient Windows handle (antivirus/indexer touching
+ * a file mid-removal) — the same class the repo already retries in
+ * `atomicWriteJson`. It deliberately does NOT help the `in-use` case: a held
+ * directory stays held, and that one needs the human, not another attempt.
+ *
+ * `--force` is safe HERE and only here: the caller proved `blockers.length ===
+ * 0` before calling, so there is nothing left for it to traverse out of.
+ *
+ * @param {string} worktreePath
+ * @param {string} root
+ * @returns {Promise<{ removed: boolean, failure: {kind: string, detail: string}|null }>}
+ */
+async function attemptWorktreeRemoval(worktreePath, root) {
+  let lastStderr = '';
+  for (let round = 0; round < 2; round++) {
+    for (const args of [['worktree', 'remove', worktreePath], ['worktree', 'remove', '--force', worktreePath]]) {
+      try {
+        execFileSync('git', args, { cwd: root, stdio: 'pipe' });
+        return { removed: true, failure: null };
+      } catch (err) {
+        lastStderr = err?.stderr ? String(err.stderr) : (err?.message || '');
+      }
+    }
+    if (round === 0) await new Promise((r) => setTimeout(r, 200));
+  }
+  return { removed: false, failure: classifyRemovalError(lastStderr) };
+}
+
 /**
  * Remove a feature's worktree after its branch is integrated — PROVE-or-DECLINE.
  * The single most dangerous step in the lifecycle, so it declines whenever it
@@ -1095,15 +1094,22 @@ async function clearRootWorktreeRegistration(root, feature) {
  *   2. it deletes GITIGNORED files outright — a user's `.env` is not disposable,
  *      and the clean-check cannot see them.
  *
+ * A non-removal comes in two flavours the caller must not conflate — see the
+ * rollback comment below. `refused` (we proved it unsafe) restores the infra
+ * junctions; a FAILURE (git errored) deliberately leaves them down, reported in
+ * `infraLeftUnlinked`.
+ *
  * `deleteBranch` decouples `git branch -d` from removal: true for `--merge` (the
  * branch is integrated), false for `--pr` (the open PR still needs the branch).
  *
  * @param {string} worktreePath
  * @param {{ root: string, feature: string, branch: string, options?: object, deleteBranch?: boolean }} ctx
  * @returns {Promise<{ worktreeRemoved: boolean, ignoredBackup: string|null, discarded: string[],
- *   blockers: string[], ignoredBlocking: string[], shieldable: string[], declineReason: string|null }>}
+ *   blockers: string[], ignoredBlocking: string[], shieldable: string[], declineReason: string|null,
+ *   relinked: boolean, refused: boolean, infraLeftUnlinked: string[],
+ *   removalFailure: {kind: string, detail: string}|null }>}
  */
-export async function teardownWorktree(worktreePath, { root, feature, branch, options = {}, deleteBranch = true }) {
+export async function teardownWorktree(worktreePath, { root, feature, branch, options = {}, deleteBranch = true, addressByTarget = false }) {
   // Drop the infra junctions FIRST, without following them — this is what makes
   // a removal survivable (see unlinkWorktreeInfraLinks). Runs unconditionally.
   //
@@ -1130,18 +1136,11 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
   const canRemove = clearedToRemove && (!ignored.shieldable.length || ignoredBackup !== null);
 
   let worktreeRemoved = false;
+  let removalFailure = null;
   if (canRemove) {
-    try {
-      execFileSync('git', ['worktree', 'remove', worktreePath], { cwd: root, stdio: 'pipe' });
-      worktreeRemoved = true;
-    } catch {
-      // Nothing is left to traverse (proven above), so --force can only act
-      // inside the worktree.
-      try {
-        execFileSync('git', ['worktree', 'remove', '--force', worktreePath], { cwd: root, stdio: 'pipe' });
-        worktreeRemoved = true;
-      } catch { /* fail-open — cleanup is best-effort once integration landed */ }
-    }
+    const attempt = await attemptWorktreeRemoval(worktreePath, root);
+    worktreeRemoved = attempt.removed;
+    removalFailure = attempt.failure; // null once removed
   }
 
   if (worktreeRemoved) {
@@ -1161,30 +1160,58 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
     await clearRootWorktreeRegistration(root, feature);
   }
 
-  // Rollback (A4): the removal was refused or failed, so the worktree is still
-  // there — but without the junctions this function dropped up front, which is
-  // strictly worse than never having tried (the observed complaint: "um estado
-  // pior que não ter tentado"). Put them back so the worktree stays usable and
-  // the user can just re-run finish from the primary root. Fail-open: a failed
-  // re-link reports `relinked: false` and the caller falls back to telling the
-  // user to run `morph-spec worktree link --all`.
+  // Rollback (A4) — ONLY on a REFUSAL, never on a FAILURE. The two look alike
+  // (worktree still there, junctions dropped) and must be treated as opposites:
+  //
+  //   REFUSED (`!canRemove`): we proved removal unsafe, so the user keeps
+  //     working in this worktree. Leaving the junctions down is "um estado pior
+  //     que não ter tentado" — put them back.
+  //   FAILED (`canRemove` but git errored): removal WAS the user's intent and
+  //     the only obstacle is a lock. Re-linking here would restore the exact
+  //     hazard that destroyed installations — the retry (ours, theirs, or a raw
+  //     `git worktree remove --force` pasted from an old transcript) would then
+  //     follow the junctions out. Leaving them down makes EVERY subsequent
+  //     attempt safe, because there is nothing left to traverse.
+  //
+  // Fail-open on the refusal path: a failed re-link reports `relinked: false`
+  // and the caller falls back to telling the user to run `worktree link --all`.
+  const refused = !canRemove;
   let relinked = false;
-  if (!worktreeRemoved && unlinked.length && existsSync(worktreePath)) {
+  if (refused && unlinked.length && existsSync(worktreePath)) {
     try {
       setupInfraLinks(worktreePath, root);
       relinked = true;
     } catch { relinked = false; }
   }
-
+  // What the caller must tell the user about on the FAILURE path: the worktree
+  // survived without its shared infra, on purpose.
+  const infraLeftUnlinked = (!worktreeRemoved && !refused) ? unlinked : [];
+
+  // Every branch names `morph-spec worktree remove` and NEVER `git worktree
+  // remove`. The raw command follows the junctions this function manages, and a
+  // decline is exactly the moment a frustrated reader copies whatever command
+  // the tool just printed — that copy is what emptied a primary root's
+  // `.claude/` and `.morph/framework/`. `worktree remove` re-runs this same
+  // PROVE-or-DECLINE path and accepts the same `--discard-ignored` consent, so
+  // there is no decline left where the raw command would be the right answer.
+  // A worktree with no feature identity (the ones `isolation: "worktree"`
+  // creates) can only be re-addressed by path — naming a feature that does not
+  // resolve would hand the reader a command that FAILS, and a failing safe
+  // command is exactly how people end up back at the raw one.
+  const removeCmd = (addressByTarget || !isValidFeatureName(feature))
+    ? `morph-spec worktree remove --target "${worktreePath}"`
+    : `morph-spec worktree remove ${feature}`;
   const declineReason = worktreeRemoved
     ? null
     : ignored.blocking.length
-      ? `worktree NÃO removido: contém arquivo(s) gitignored que existem só ali e o \`git worktree remove\` apagaria (${ignored.blocking.slice(0, 5).join(', ')}${ignored.blocking.length > 5 ? `, +${ignored.blocking.length - 5}` : ''}). Salve o que importa e rode \`git worktree remove --force "${worktreePath}"\`${deleteBranch ? ` + \`git branch -d ${branch}\`` : ''}, ou re-execute o finish com \`--discard-ignored\` para descartá-los deliberadamente`
+      ? `worktree NÃO removido: contém arquivo(s) gitignored que existem só ali e a remoção apagaria (${ignored.blocking.slice(0, 5).join(', ')}${ignored.blocking.length > 5 ? `, +${ignored.blocking.length - 5}` : ''}). Salve o que importa e rode \`${removeCmd}\`, ou \`${removeCmd} --discard-ignored\` para descartá-los deliberadamente`
       : blockers.length
-        ? `worktree NÃO removido: ainda contém link(s)/caminho(s) não verificáveis (${blockers.join(', ')}) que o \`git worktree remove\` seguiria para fora, apagando o alvo na raiz. Remova-os e rode \`git worktree remove "${worktreePath}"\`${deleteBranch ? ` + \`git branch -d ${branch}\`` : ''}`
+        ? `worktree NÃO removido: ainda contém link(s)/caminho(s) não verificáveis (${blockers.join(', ')}) que a remoção seguiria para fora, apagando o alvo na raiz. Remova-os e rode \`${removeCmd}\``
         : ignored.shieldable.length && ignoredBackup === null
-          ? `worktree NÃO removido: o backup do gitignored do worktree falhou, e sem ele a remoção seria destrutiva. Rode \`git worktree remove --force "${worktreePath}"\` manualmente se não precisar desse conteúdo`
-          : `o \`git worktree remove\` falhou. Rode \`git worktree remove "${worktreePath}"\` manualmente`;
+          ? `worktree NÃO removido: o backup do gitignored do worktree falhou, e sem ele a remoção seria destrutiva. Libere espaço/permissão em \`.git/morph-spec/\` e rode \`${removeCmd}\`, ou \`${removeCmd} --discard-ignored\` se não precisar desse conteúdo`
+          : removalFailure?.kind === 'in-use'
+            ? `worktree NÃO removido: o diretório está EM USO por outro processo (instância do Claude Code, VS Code, dev server ou terminal com cwd em "${worktreePath}"). A infra compartilhada ficou DESMONTADA de propósito — feche o que está usando o diretório e rode \`${removeCmd}\`. Se preferir continuar trabalhando nele, restaure a infra com \`morph-spec worktree link --all\``
+            : `worktree NÃO removido: a remoção falhou${removalFailure?.detail ? ` (${removalFailure.detail})` : ''}. A infra compartilhada ficou DESMONTADA de propósito — rode \`${removeCmd}\` para tentar de novo, ou \`morph-spec worktree link --all\` para voltar a trabalhar nele`;
 
   return {
     worktreeRemoved,
@@ -1195,7 +1222,144 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
     shieldable: ignored.shieldable,
     declineReason,
     relinked,
+    refused,
+    infraLeftUnlinked,
+    removalFailure,
+  };
+}
+
+/**
+ * Is `cwd` the worktree we are about to remove, or inside it?
+ *
+ * Hoisted out of `finish` so BOTH callers share one answer. Windows holds a
+ * lock on a process's working directory, so a removal issued from inside the
+ * target fails — and in `finish`'s case it fails AFTER the archive is committed
+ * and the branch merged, leaving an orphan directory and a de-registered
+ * worktree. Refusing up front costs one `cd`.
+ *
+ * @param {string} cwd
+ * @param {string} worktreePath
+ * @returns {boolean}
+ */
+export function cwdIsInsideWorktree(cwd, worktreePath) {
+  const cwdNorm = resolve(cwd).replace(/\\/g, '/');
+  const wtNorm = resolve(worktreePath).replace(/\\/g, '/');
+  return cwdNorm === wtNorm || cwdNorm.startsWith(`${wtNorm}/`);
+}
+
+// ── remove ───────────────────────────────────────────────────────────────
+
+/**
+ * Command handler for `morph-spec worktree remove <feature>` /
+ * `morph-spec worktree remove --target <path>`.
+ *
+ * WHY THIS EXISTS: `teardownWorktree` — the only removal that drops the infra
+ * junctions before letting git near the directory — used to be reachable ONLY
+ * through `morph-spec finish`. So every message that had to tell a user how to
+ * remove a worktree pointed at raw `git worktree remove`, which follows those
+ * junctions out and empties the primary root's `.claude/` and
+ * `.morph/framework/`. This command is the safe answer those messages now give.
+ *
+ * Two ways to address the target, because there are two kinds of worktree:
+ *   <feature>       — a morph worktree, resolved through `findWorktreeForFeature`
+ *   --target <path> — any registered worktree, including the ones the Agent
+ *                     tool's `isolation: "worktree"` creates, which have no
+ *                     feature registration for the lookup to find.
+ *
+ * It removes ONLY. No archive, no merge, and the branch survives by default —
+ * closing a feature is still `morph-spec finish`.
+ *
+ * @param {string|undefined} featureArg
+ * @param {{ target?: string, discardIgnored?: boolean, deleteBranch?: boolean, cwd?: string }} [options]
+ */
+export async function worktreeRemoveCommand(featureArg, options = {}) {
+  const cwdArg = options.cwd || process.cwd();
+  const emit = (obj, code) => { console.log(JSON.stringify(obj)); process.exit(code); };
+
+  if (!isGitRepo(cwdArg)) emit({ removed: false, error: 'not-a-git-repo' }, 1);
+  const root = resolvePrimaryRoot(cwdArg);
+
+  let worktreePath = null;
+  let feature = featureArg || null;
+  let branch = null;
+  // Can a re-run be addressed as `remove <feature>`? Only when the feature name
+  // is what resolved the worktree in the first place.
+  let featureAddressable = !options.target;
+
+  if (options.target) {
+    worktreePath = resolve(options.target).replace(/\\/g, '/');
+    // The target MUST be a registered worktree. Without this the command would
+    // hand an arbitrary path to `git worktree remove` — and `--target ../..`
+    // is the same path-traversal class already fixed in delete/archive.
+    const entry = parseWorktreeList(root).find((e) => e.path === worktreePath);
+    if (!entry) {
+      emit({ removed: false, error: 'not-a-registered-worktree', target: worktreePath, root,
+        hint: 'o path precisa ser um worktree registrado neste repo — confira `morph-spec worktree list`' }, 1);
+    }
+    if (worktreePath === root) {
+      emit({ removed: false, error: 'refuses-primary-root', path: worktreePath,
+        hint: 'a raiz primária nunca é removível por este comando' }, 1);
+    }
+    branch = entry.branch ? entry.branch.replace(/^refs\/heads\//, '') : null;
+    // Best-effort feature identity — used for the backup/env-release bookkeeping
+    // inside the teardown. A `morph/{f}` branch means `remove <feature>` would
+    // resolve too, so re-run advice may name it; anything else stays --target.
+    if (!feature && branch?.startsWith('morph/')) {
+      feature = branch.slice('morph/'.length);
+      featureAddressable = isValidFeatureName(feature);
+    }
+  } else {
+    if (!isValidFeatureName(feature)) {
+      emit({ removed: false, error: 'invalid-feature-name', feature: feature ?? null,
+        hint: 'informe <feature> (kebab-case) ou use --target <path>' }, 1);
+    }
+    const found = findWorktreeForFeature(feature, root);
+    if (!found || found.path.replace(/\\/g, '/') === root) {
+      emit({ removed: false, error: 'no-worktree-for-feature', feature, root,
+        hint: `nenhum worktree separado para "${feature}" — confira \`morph-spec worktree list\`` }, 1);
+    }
+    worktreePath = found.path;
+    branch = found.branch;
+  }
+
+  // Same guard finish applies, for the same Windows reason — and this command
+  // is MORE likely to hit it: the natural moment to run it is right after
+  // working inside the worktree.
+  if (cwdIsInsideWorktree(cwdArg, worktreePath)) {
+    emit({ removed: false, error: 'cwd-inside-worktree', path: worktreePath, root,
+      hint: `saia do worktree antes de removê-lo — o processo trava o próprio diretório de trabalho. Rode de novo a partir de "${root}"` }, 1);
+  }
+
+  const teardown = await teardownWorktree(worktreePath, {
+    root,
+    feature: feature || 'worktree',
+    branch,
+    options: { discardIgnored: options.discardIgnored === true },
+    // Removing a worktree is not closing a feature: the branch is the work, and
+    // deleting it here would discard unintegrated commits. Opt-in only.
+    deleteBranch: options.deleteBranch === true,
+    // Re-run advice must address the worktree the way it was addressable here:
+    // a `--target` worktree has no feature name that would resolve.
+    addressByTarget: !featureAddressable,
+  });
+
+  const out = {
+    removed: teardown.worktreeRemoved,
+    path: worktreePath,
+    ...(branch ? { branch } : {}),
+    ...(feature ? { feature } : {}),
   };
+  if (teardown.worktreeRemoved) {
+    if (teardown.discarded.length) out.discardedIgnored = teardown.discarded;
+    if (teardown.ignoredBackup) out.ignoredBackup = teardown.ignoredBackup;
+  } else {
+    out.refused = teardown.refused;
+    if (teardown.blockers.length) out.reparsePoints = teardown.blockers;
+    if (teardown.ignoredBlocking.length) out.ignoredFiles = teardown.ignoredBlocking;
+    if (teardown.infraLeftUnlinked.length) out.infraLeftUnlinked = teardown.infraLeftUnlinked;
+    out.hint = teardown.declineReason;
+  }
+  emit(out, teardown.worktreeRemoved ? 0 : 1);
 }
 
 // ── list ─────────────────────────────────────────────────────────────────

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.'));