@polymorphism-tech/morph-spec 8.27.0 → 8.29.0

package/framework/standards/frontend/seo/meta-schema-audit.md

@@ -0,0 +1,134 @@
+# SEO, Schema and Launch Audit
+
+> **Scope:** frontend-seo
+> **Layer:** 3
+> **Keywords:** seo, meta tags, open graph, schema.org, json-ld, rich results, lighthouse, accessibility, go-live audit
+> **Load When:** any public-facing page is being built or is about to go live
+
+**Verified against:** Schema.org vocabulary + Lighthouse via Chrome DevTools MCP, shipped to production. Last-verified: 2026-08-21.
+
+---
+
+A page that cannot be found and does not share well is half delivered. This layer is cheap (almost all of it lives in `<head>`) and pays for itself. Covers the essential meta set, Open Graph, JSON-LD by business type, the accessibility items that also affect ranking, and the audit to run before going live.
+
+---
+
+## Section 1: Essential Meta
+
+```html
+<title>{Brand} · {short value proposition in {city}}</title>
+<meta name="description" content="{1-2 sentences: what it does, where, and a differentiator or proof}" />
+<link rel="canonical" href="https://{domain}/" />
+<meta name="theme-color" content="{brand background color}" />
+<link rel="icon" type="image/png" href="/img/{favicon}.png" />
+
+<!-- font preconnect: measurable performance win -->
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+```
+
+- **`title`**: brand plus proposition plus place, when it is a local business. Do not stuff keywords.
+- **`description`**: what it sells, to whom, where, plus a proof hook (rating, years, differentiator).
+- **`canonical`**: always present, to avoid duplicate-URL dilution.
+- **`lang`**: set the real locale on `<html>` (for example `lang="pt-BR"`).
+
+---
+
+## Section 2: Open Graph and Twitter Cards
+
+Without these, a link pasted into WhatsApp, Instagram or LinkedIn renders as a bare, ugly card. With them, it renders as an image card.
+
+```html
+<meta property="og:type" content="website" />
+<meta property="og:locale" content="pt_BR" />
+<meta property="og:site_name" content="{Brand}" />
+<meta property="og:title" content="{share title, can be more emotional than the SEO title}" />
+<meta property="og:description" content="{one sentence}" />
+<meta property="og:url" content="https://{domain}/" />
+<meta property="og:image" content="https://{domain}/img/{share-image}.jpg" />
+<meta name="twitter:card" content="summary_large_image" />
+```
+
+`og:image` should be 1200x630 and must use an absolute URL. Use the strongest image on the page.
+
+---
+
+## Section 3: Schema.org (JSON-LD) by Business Type
+
+Structured data is what earns rich results (stars, address, opening hours). Pick `@type` from the business:
+
+| Business | `@type` |
+|---|---|
+| Retail, fashion, tailoring | `ClothingStore` or `Store` |
+| Local service (clinic, studio, workshop) | `LocalBusiness` or a specific subtype |
+| Property developer, real estate | `RealEstateAgent`, or `Residence` / `Apartment` |
+| Restaurant, food | `Restaurant` |
+| SaaS, software | `SoftwareApplication` or `Organization` |
+| Independent professional | `ProfessionalService` |
+
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "ClothingStore",
+  "name": "{Brand}",
+  "image": "https://{domain}/img/{hero}.jpg",
+  "description": "{description}",
+  "address": {
+    "@type": "PostalAddress",
+    "streetAddress": "{street, number}", "addressLocality": "{city}",
+    "addressRegion": "{state}", "postalCode": "{zip}", "addressCountry": "BR"
+  },
+  "telephone": "+55-XX-XXXXX-XXXX",
+  "url": "https://{domain}/",
+  "aggregateRating": { "@type": "AggregateRating", "ratingValue": "4.9", "reviewCount": "74" },
+  "openingHours": "Mo-Fr 09:00-18:00"
+}
+</script>
+```
+
+**Include only true fields.** `aggregateRating` goes in only with a real number from a real source (for example the client's Google rating and review count). Never invent a rating. With no real data, omit the block entirely. Fabricated structured data is both a trust problem and a manual-action risk.
+
+---
+
+## Section 4: Accessibility (Also An SEO Signal)
+
+- `lang` set correctly on `<html>`.
+- Descriptive `alt` on every content image, including video posters.
+- Sufficient contrast for text over media. Check against the brightest frames, not the average. See `frontend/design-system/premium-finish.md`.
+- Logical focus order, visible `:focus-visible`.
+- Overlays carry `role`, `aria-modal`, and close on Escape.
+- `prefers-reduced-motion` honored: scroll-driven effects do not mount.
+- Coherent heading hierarchy: exactly one `<h1>`, then `<h2>` / `<h3>`.
+
+---
+
+## Section 5: Pre-Launch Audit
+
+"Premium" is confirmed by measurement, not by vibe. Run this before the go-live gate and fix what hurts:
+
+| Check | How | Pass condition |
+|---|---|---|
+| Lighthouse | Chrome DevTools MCP `lighthouse_audit` | Performance, SEO, Best Practices, Accessibility reviewed and explained |
+| Console | Desktop and mobile viewport | Zero errors |
+| Share card | Paste the URL into an OG validator or a test chat | Image card renders with the right title |
+| Technical SEO | `seo-analyzer` pass over meta, headings, links | No missing or duplicated essentials |
+| Cross-device | Desktop, tablet, mobile; Safari or iOS included | Layout holds, motion fallbacks fire |
+
+**On Performance specifically:** a heavy frame sequence (see `frontend/scroll-driven/frame-scrub.md`) will cost Performance points. That is an accepted, deliberate trade. What must be confirmed is that the cost sits in the scrub and not in unoptimized images, dead JS, or missing compression. State the trade explicitly rather than letting a low score pass unexamined.
+
+Record the audited viewports and the Lighthouse result alongside the go-live decision.
+
+---
+
+## Checklist
+
+- [ ] Title, description, canonical, theme-color, favicon in place
+- [ ] `lang` correct on `<html>`
+- [ ] Font preconnects present
+- [ ] Full Open Graph set with an absolute 1200x630 `og:image`
+- [ ] JSON-LD present, `@type` matched to the business, every field true
+- [ ] `aggregateRating` backed by real data, or omitted
+- [ ] Alt text, focus order, heading hierarchy, reduced-motion verified
+- [ ] Lighthouse run; any Performance cost traced to a deliberate trade
+- [ ] Console clean, share card verified, cross-device pass recorded

package/package.json

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

package/src/commands/project/doctor.js

@@ -564,10 +564,15 @@ export async function doctorWorktreesCommand(targetPath, options = {}) {
   const { auditWorktrees, pruneWorktrees } = await import('../../lib/worktree/worktree-audit.js');
 
   if (options.prune) {
-    const before = auditWorktrees(targetPath).filter((i) => i.type === 'registered-missing').length;
-    const result = pruneWorktrees(targetPath);
-    if (result.pruned) logger.success(`git worktree prune: ${before} registro(s) órfão(s) removido(s).`);
+    const beforeIssues = auditWorktrees(targetPath);
+    const beforeMissing = beforeIssues.filter((i) => i.type === 'registered-missing').length;
+    const beforeDangling = beforeIssues.filter((i) => i.type === 'dangling-registration').length;
+    const result = await pruneWorktrees(targetPath);
+    if (result.pruned) logger.success(`git worktree prune: ${beforeMissing} registro(s) órfão(s) removido(s).`);
     else logger.warn(`prune falhou: ${result.error}`);
+    if (result.clearedRegistrations.length) {
+      logger.success(`registro de worktree limpo em ${result.clearedRegistrations.length}/${beforeDangling} feature(s): ${result.clearedRegistrations.map((r) => r.feature).join(', ')}`);
+    }
   }
 
   const issues = auditWorktrees(targetPath);
@@ -589,7 +594,7 @@ export async function doctorWorktreesCommand(targetPath, options = {}) {
     console.log(`     ${i.detail}`);
     console.log(`     → ${i.fix}`);
   }
-  if (issues.some((i) => i.type === 'registered-missing') && !options.prune) {
+  if (issues.some((i) => i.type === 'registered-missing' || i.type === 'dangling-registration') && !options.prune) {
     logger.dim('\n  Rode `morph-spec doctor --worktrees --prune` para limpar os registros órfãos.');
   }
   return false;

package/src/commands/project/worktree.js

@@ -443,7 +443,13 @@ export async function runWorktreeSetup(feature, options = {}) {
         const normalizedExisting = existingPath.replace(/\\/g, '/');
         const normalizedNew = worktreePath.replace(/\\/g, '/');
         if (normalizedExisting !== normalizedNew && existsSync(existingPath)) {
-          return { ok: false, exitCode: 3, created: false, error: 'worktree-exists-elsewhere', existingPath, feature };
+          return {
+            ok: false, exitCode: 3, created: false, error: 'worktree-exists-elsewhere', existingPath, feature,
+            hint: `A different live worktree is already registered for "${feature}". `
+              + `If it's stale (removed by hand, or by \`git worktree prune\` directly, outside \`morph-spec finish\`/\`worktree remove\`), `
+              + `run \`morph-spec doctor --worktrees --prune\` to clear the registration, or `
+              + `\`morph-spec worktree remove --target "${existingPath}"\` if the directory is still there but unwanted.`,
+          };
         }
       }
     }
@@ -519,7 +525,10 @@ export async function runWorktreeSetup(feature, options = {}) {
     try {
       if (existsSync(join(worktreePath, '.morph', 'features', feature, 'feature.json'))) {
         const { writeHandoff } = await import('../../lib/generators/handoff-generator.js');
-        writeHandoff(feature, worktreePath);
+        // `worktree` is ROOT-OWNED bookkeeping, absent from this branch-local
+        // copy by contract — pass it explicitly so the doc built FROM INSIDE
+        // the worktree still says "Local: worktree", not "raiz primária".
+        writeHandoff(feature, worktreePath, { worktree: { path: worktreePath, branch } });
       }
     } catch { /* fail-open */ }
 
@@ -1018,7 +1027,7 @@ export function primaryRootUnexplainedDirt(root, feature, opts = {}) {
  * @param {string} root
  * @param {string} feature
  */
-async function clearRootWorktreeRegistration(root, feature) {
+export async function clearRootWorktreeRegistration(root, feature) {
   const featPathspec = `.morph/features/${feature}`;
   try {
     const rootFjPath = join(root, '.morph', 'features', feature, 'feature.json');
@@ -1044,6 +1053,39 @@ async function clearRootWorktreeRegistration(root, feature) {
   } catch { /* fail-open — a dirty root is a nuisance, not a reason to fail */ }
 }
 
+/**
+ * Clear a feature's `worktree` registration ONLY when it's dangling — the
+ * path it names no longer exists on disk (the directory was removed outside
+ * `morph-spec finish`/`worktree remove`: by hand, by `git worktree prune`, or
+ * by any tool that doesn't know about this pointer).
+ *
+ * Deliberately narrower than `clearRootWorktreeRegistration`: a registration
+ * naming a worktree that's still ALIVE is not a bug to repair — it's the
+ * anti-dupe guard's only signal (`runWorktreeSetup` Guard 3) and `verify`'s
+ * only signal for which cwd may persist (`decidePersistence`). Clearing a
+ * live registration would trade a true pointer for a false negative on both.
+ *
+ * Reuses `clearRootWorktreeRegistration` for the actual mutation (same
+ * atomic-write + scoped-commit contract) once the dangling predicate holds.
+ *
+ * @param {string} root
+ * @param {string} feature
+ * @returns {Promise<{ cleared: boolean }>}
+ */
+export async function clearDanglingWorktreeRegistration(root, feature) {
+  try {
+    const rootFjPath = join(root, '.morph', 'features', feature, 'feature.json');
+    if (!existsSync(rootFjPath)) return { cleared: false };
+    const fj = JSON.parse(readFileSync(rootFjPath, 'utf8'));
+    const path = fj?.worktree?.path;
+    if (!path || existsSync(path)) return { cleared: false };
+    await clearRootWorktreeRegistration(root, feature);
+    return { cleared: true };
+  } catch {
+    return { cleared: false }; // fail-open — malformed feature.json must never throw
+  }
+}
+
 /**
  * Why `git worktree remove` failed, from its stderr.
  *

package/src/commands/state/advance.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'url';
 import { getFeature, setApprovalGate, derivePhase } from '../../core/state/state-manager.js';
 import { unmetPrereqs } from '../../core/state/gate-order.js';
 import { OUTPUT_SCHEMA } from '../../core/paths/output-schema.js';
+import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
 
 const FRAMEWORK_DIR = fileURLToPath(new URL('../../../framework/', import.meta.url));
 
@@ -111,6 +112,17 @@ export async function advanceCommand(featureName, options = {}) {
       process.exit(1);
     }
 
+    // Owner-tree guard: a live worktree elsewhere owns this feature's state —
+    // never stamp a gate onto the root's birth-instant skeleton (branch-drift
+    // created by this command, not merely left behind by one).
+    const owner = assertOwnerTree(featureName, process.cwd());
+    if (owner.blocked) {
+      for (const { tone, text } of ownerTreeRefusalLines(featureName, owner.tree, owner.branch, `morph-spec advance ${featureName}`)) {
+        console.error(chalk[tone](text));
+      }
+      process.exit(1);
+    }
+
     const featurePath = join(process.cwd(), '.morph', 'features', featureName);
     const phase = derivePhase(featurePath);
 

package/src/commands/state/approve.js

@@ -6,6 +6,7 @@ import { join } from 'path';
 import { getFeature, setApprovalGate, getApprovalGate, getApprovalHistory, derivePhase } from '../../core/state/state-manager.js';
 import { unmetPrereqs } from '../../core/state/gate-order.js';
 import { evaluatorReportState, COMPOSITE_SCORE_TOKEN } from '../../lib/evaluator-report.js';
+import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
 
 /**
  * The literal token `review-report.md` carries to declare which tree it
@@ -86,6 +87,14 @@ export async function unapproveCommand(featureName, gateName, options = {}) {
       process.exit(1);
     }
 
+    const owner = assertOwnerTree(featureName, process.cwd());
+    if (owner.blocked) {
+      for (const { tone, text } of ownerTreeRefusalLines(featureName, owner.tree, owner.branch, `morph-spec unapprove ${featureName} ${gateName}`)) {
+        console.error(chalk[tone](text));
+      }
+      process.exit(1);
+    }
+
     const currentStatus = getApprovalGate(featureName, gateName);
     if (!currentStatus?.approved) {
       console.log(chalk.yellow(`\n⚠️  Gate "${gateName}" is not currently approved — nothing to revoke\n`));
@@ -155,6 +164,17 @@ export async function approveCommand(featureName, gateName, options = {}) {
       process.exit(1);
     }
 
+    // Owner-tree guard: a live worktree elsewhere owns this feature's state —
+    // never stamp a gate onto the root's birth-instant skeleton (branch-drift
+    // created by this command, not merely left behind by one).
+    const owner = assertOwnerTree(featureName, process.cwd());
+    if (owner.blocked) {
+      for (const { tone, text } of ownerTreeRefusalLines(featureName, owner.tree, owner.branch, `morph-spec approve ${featureName} ${gateName}`)) {
+        console.error(chalk[tone](text));
+      }
+      process.exit(1);
+    }
+
     // Check if already approved
     const currentStatus = getApprovalGate(featureName, gateName);
     if (currentStatus?.approved) {

package/src/commands/state/create.js

@@ -215,7 +215,10 @@ export async function createCommand(featureName, options = {}) {
             // read. Regenerated here because setup ran before the copy above.
             try {
               const { writeHandoff } = await import('../../lib/generators/handoff-generator.js');
-              writeHandoff(featureName, worktreeResult.path);
+              // Same reason as runWorktreeSetup's own call: `worktree` was just
+              // stripped from this branch-local copy a few lines up, so the doc
+              // must be told explicitly where it actually lives.
+              writeHandoff(featureName, worktreeResult.path, { worktree: { path: worktreeResult.path, branch: worktreeResult.branch } });
             } catch { /* fail-open */ }
           } catch { /* fail-open — the feature already exists in root */ }
         }

package/src/commands/state/delete.js

@@ -2,7 +2,8 @@ import chalk from 'chalk';
 import { existsSync, rmSync, renameSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { join, resolve, sep } from 'path';
 import { execSync } from 'child_process';
-import { isValidFeatureName } from '../project/worktree.js';
+import { isValidFeatureName, cwdIsInsideWorktree, teardownWorktree, resolvePrimaryRoot } from '../project/worktree.js';
+import { resolveFeatureTree } from '../../lib/worktree/feature-truth.js';
 
 /**
  * `morph-spec delete <feature>` — remove a feature. Hard by default (folder is
@@ -111,6 +112,57 @@ export async function deleteCommand(featureName, options = {}) {
       process.exit(1);
     }
 
+    // A live worktree elsewhere owns this feature's REAL state — deleting the
+    // root's registration here would orphan the worktree + branch silently
+    // (no `no-feature` audit hit either: featureCommittedOnBranch stays true).
+    // Distinct consent from --force on purpose: --force answers "approved gate
+    // present, delete anyway" (a STATE risk); a live worktree is a FILESYSTEM
+    // risk (orphan directory, junctions into the primary root) — the same
+    // reasoning that keeps `worktree remove`'s PROVE-or-DECLINE separate from
+    // gate policy.
+    const owner = resolveFeatureTree(featureName, cwd);
+    const liveElsewhere = (owner.source === 'registry' || owner.source === 'pointer') && owner.tree;
+    if (liveElsewhere) {
+      if (!options.withWorktree) {
+        const payload = { error: 'feature-has-worktree', feature: featureName, worktree: { path: owner.tree, branch: owner.branch } };
+        if (options.json) { console.log(JSON.stringify(payload)); process.exit(1); }
+        console.error(chalk.red(`\n❌ "${featureName}" tem um worktree vivo em ${owner.tree}.`));
+        console.error(chalk.gray('   Feche com `morph-spec finish <feature> --pr|--merge` se o trabalho vale,'));
+        console.error(chalk.gray(`   ou \`morph-spec worktree remove ${featureName}\` e rode o delete de novo,`));
+        console.error(chalk.gray(`   ou \`morph-spec delete ${featureName} --with-worktree\` para fazer os dois num passo.\n`));
+        process.exit(1);
+      }
+
+      if (cwdIsInsideWorktree(cwd, owner.tree)) {
+        const payload = { error: 'cwd-inside-worktree', feature: featureName, path: owner.tree };
+        if (options.json) { console.log(JSON.stringify(payload)); process.exit(1); }
+        console.error(chalk.red(`\n❌ Rode fora do worktree antes de removê-lo: ${owner.tree}\n`));
+        process.exit(1);
+      }
+
+      // PROVE-or-DECLINE first — only delete the feature's own copy if the
+      // worktree actually came down. A refusal here must leave EVERYTHING
+      // untouched, same contract as `worktree remove`.
+      const root = resolvePrimaryRoot(cwd);
+      const teardown = await teardownWorktree(owner.tree, {
+        root,
+        feature: featureName,
+        branch: owner.branch,
+        options: { discardIgnored: options.discardIgnored === true },
+        deleteBranch: options.deleteBranch === true, // kept by default — it is the work
+      });
+      if (!teardown.worktreeRemoved) {
+        const payload = { error: 'worktree-removal-failed', feature: featureName, declineReason: teardown.declineReason };
+        if (options.json) { console.log(JSON.stringify(payload)); process.exit(1); }
+        console.error(chalk.red(`\n❌ Não foi possível remover o worktree — nada foi apagado.`));
+        console.error(chalk.gray(`   ${teardown.declineReason || 'motivo desconhecido'}\n`));
+        process.exit(1);
+      }
+      // Fall through: the feature's own .morph/features/{featureName} copy in
+      // `cwd` (the primary root, by construction of `liveElsewhere`) is deleted
+      // by the normal flow below, exactly as if there had never been a worktree.
+    }
+
     const useGit = isGitRepo(cwd) && options.git !== false;
 
     if (options.archive) {
@@ -156,10 +208,17 @@ export async function deleteCommand(featureName, options = {}) {
         execSync(`git rm -r -f --quiet "${featuresPath}"`, { cwd, stdio: 'pipe' });
         staged = true;
       } catch {
-        // Untracked (never committed) — just remove it from disk.
-        rmSync(featuresPath, { recursive: true, force: true });
-        try { execSync(`git add -A "${featuresPath}"`, { cwd, stdio: 'pipe' }); staged = true; } catch { /* not fatal */ }
+        // Untracked (never committed) — nothing for git rm to act on.
       }
+      // `git rm` only ever removes TRACKED files — a scaffolded phase folder
+      // with no artifact in it (0-proposal/ with nothing written yet) has no
+      // tracked blob and survives as an empty directory on disk. This bit
+      // real after --with-worktree: teardownWorktree's own registration-clear
+      // commits the root's feature.json on its way through, so `git rm`
+      // SUCCEEDS on that one file while the sibling empty folders it never
+      // tracked are left behind. Unconditional sweep closes both paths at once.
+      if (existsSync(featuresPath)) rmSync(featuresPath, { recursive: true, force: true });
+      try { execSync(`git add -A "${featuresPath}"`, { cwd, stdio: 'pipe' }); staged = true; } catch { /* not fatal */ }
     } else {
       rmSync(featuresPath, { recursive: true, force: true });
     }

package/src/commands/state/finish.js

@@ -483,7 +483,15 @@ async function integrateMerge({ emit, root, feature, expectedBranch, defaultBran
 
     if (options.keep) {
       dropFromRootIndex(root, feature);
-      emit({ finished: true, mode: 'merge', feature, merged: expectedBranch, kept: true, worktreeRemoved: false, ...backupNote, ...ucNote });
+      // Worktree preserved on purpose: the root's `worktree` registration stays
+      // VALID (it still names a live directory), so nothing to clean up here —
+      // only report where it lives and how to close it later.
+      emit({
+        finished: true, mode: 'merge', feature, merged: expectedBranch, kept: true, worktreeRemoved: false,
+        worktree: { path: worktreePath, branch: expectedBranch },
+        hint: `worktree preservado em ${worktreePath} — feche depois com \`morph-spec worktree remove ${feature}\`.`,
+        ...backupNote, ...ucNote,
+      });
       process.exit(0);
     }
 
@@ -574,7 +582,17 @@ async function integratePr({ emit, root, feature, expectedBranch, defaultBranch,
     ...(shedBackup ? { shedBackup } : {}),
     ...(teardown
       ? { worktreeRemoved: teardown.worktreeRemoved, ...teardownExtras(teardown, worktreePath, expectedBranch, false) }
-      : { worktreeRemoved: false }),
+      : {
+        worktreeRemoved: false,
+        // isWorktreeFlow && options.keep is the only way `teardown` stays null
+        // with a worktree still alive — the common flow has none to report.
+        ...(isWorktreeFlow && options.keep
+          ? {
+            worktree: { path: worktreePath, branch: expectedBranch },
+            hint: `worktree preservado em ${worktreePath} — feche depois com \`morph-spec worktree remove ${feature}\`.`,
+          }
+          : {}),
+      }),
   };
   emit(out);
   process.exit(0);

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

@@ -6,6 +6,7 @@ import { shouldPauseGate, getRiskSignals } from '../../lib/risk-detector.js';
 import { evaluatorCompositeScore } from '../../lib/evaluator-report.js';
 import { persistGateDecision, VALID_GATES, readTrustFromConfig } from './gate-decision.js';
 import { detectDefaultBranch, getHeadSha, getDiffStat } from '../../lib/git/default-branch.js';
+import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
 
 /**
  * `--signals` on `gate-check` is NOT a general override like `gate-decision`'s
@@ -154,6 +155,18 @@ export async function gateCheckCommand(featureName, gateName, options = {}) {
       process.exit(1);
     }
 
+    // Owner-tree guard: gate-check reads workType/tasks/scores/git off cwd
+    // AND writes the resulting decision through persistGateDecision — both
+    // halves are wrong from a tree that isn't this feature's own, so refuse
+    // rather than compute a decision from stale reads and then fail to save it.
+    const owner = assertOwnerTree(featureName, process.cwd());
+    if (owner.blocked) {
+      for (const { tone, text } of ownerTreeRefusalLines(featureName, owner.tree, owner.branch, `morph-spec gate-check ${featureName} ${gateName}`)) {
+        console.error(chalk[tone](text));
+      }
+      process.exit(1);
+    }
+
     let overrides = {};
     if (options.signals !== undefined) {
       let parsed;

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

@@ -2,6 +2,7 @@ import chalk from 'chalk';
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { getFeature, updateFeature } from '../../core/state/state-manager.js';
+import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
 
 export const VALID_GATES = ['proposal', 'uiux', 'plan', 'review'];
 
@@ -96,6 +97,14 @@ export async function gateDecisionCommand(featureName, gateName, options = {}) {
       process.exit(1);
     }
 
+    const owner = assertOwnerTree(featureName, process.cwd());
+    if (owner.blocked) {
+      for (const { tone, text } of ownerTreeRefusalLines(featureName, owner.tree, owner.branch, `morph-spec gate-decision ${featureName} ${gateName} --pause ${pause}`)) {
+        console.error(chalk[tone](text));
+      }
+      process.exit(1);
+    }
+
     let signals = {};
     if (options.signals !== undefined) {
       try {

package/src/commands/state/handoff.js

@@ -9,18 +9,32 @@
  * in-process by `worktree setup`, `create --worktree`, `advance` and
  * `approve` — the CLI surface exists for the LLM/user to refresh the
  * document on demand.
+ *
+ * WORKTREE-AWARE: `create --worktree` writes a COMPLETE feature.json into the
+ * primary root and the branch-committed copy (`morph/{f}`) becomes the truth
+ * from then on. Building the handoff from `process.cwd()` unconditionally
+ * used to mean: run this from the root while the worktree is alive, and you
+ * either got "Feature not found" (root's copy was already sheded) or a
+ * document silently built from the stale birth skeleton, written INTO the
+ * root (a second, always-defasada copy of a document that's supposed to be
+ * regenerated, not duplicated). This resolves the owning tree first
+ * (`resolveFeatureTree`) and writes THERE, unless `--here` forces the cwd.
  */
 
 import chalk from 'chalk';
 import { buildHandoff, writeHandoff } from '../../lib/generators/handoff-generator.js';
+import { resolveFeatureTree } from '../../lib/worktree/feature-truth.js';
 
 /**
  * @param {string} featureName
- * @param {{ json?: boolean }} [options]
+ * @param {{ json?: boolean, here?: boolean }} [options]
  */
 export function handoffCommand(featureName, options = {}) {
-  const result = buildHandoff(featureName, process.cwd());
-  if (!result) {
+  const cwd = process.cwd();
+
+  const owner = options.here ? { source: 'cwd', tree: cwd, branch: null, worktree: null } : resolveFeatureTree(featureName, cwd);
+
+  if (owner.source === 'none') {
     if (options.json) {
       console.log(JSON.stringify({ error: 'feature-not-found', feature: featureName }));
     } else {
@@ -29,10 +43,35 @@ export function handoffCommand(featureName, options = {}) {
     process.exit(1);
   }
 
-  const path = writeHandoff(featureName, process.cwd());
+  if (owner.source === 'branch-only') {
+    // The truth exists, committed on morph/{feature}, but is not materialized
+    // into ANY tree right now. A handoff points at files on disk — pointing
+    // at files that exist nowhere is worse than recusing outright.
+    const hint = `morph-spec worktree setup ${featureName}  (ou: git checkout ${owner.branch})`;
+    if (options.json) {
+      console.log(JSON.stringify({ error: 'feature-not-in-tree', feature: featureName, branch: owner.branch, hint }));
+    } else {
+      console.error(chalk.red(`\n❌ "${featureName}" está commitada em \`${owner.branch}\`, mas não está materializada em árvore nenhuma.`));
+      console.error(chalk.gray(`   ${hint}\n`));
+    }
+    process.exit(1);
+  }
+
+  const tree = owner.tree;
+  const result = buildHandoff(featureName, tree, { worktree: owner.worktree });
+  if (!result) {
+    if (options.json) {
+      console.log(JSON.stringify({ error: 'feature-not-found', feature: featureName, tree }));
+    } else {
+      console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
+    }
+    process.exit(1);
+  }
+
+  const path = writeHandoff(featureName, tree, { worktree: owner.worktree });
   if (!path) {
     if (options.json) {
-      console.log(JSON.stringify({ error: 'write-failed', feature: featureName }));
+      console.log(JSON.stringify({ error: 'write-failed', feature: featureName, tree }));
     } else {
       console.error(chalk.red(`\n❌ Could not write handoff.md for ${featureName}\n`));
     }
@@ -40,11 +79,14 @@ export function handoffCommand(featureName, options = {}) {
   }
 
   if (options.json) {
-    console.log(JSON.stringify({ path, feature: featureName, ...result.meta }));
+    console.log(JSON.stringify({ path, feature: featureName, tree, source: owner.source, ...result.meta }));
     return;
   }
 
   console.log(chalk.green(`\n✅ Handoff gerado: ${path}`));
+  if (tree !== cwd) {
+    console.log(chalk.yellow(`   resolvido para ${tree} — a cópia da raiz é esqueleto de nascimento, não a verdade.`));
+  }
   console.log(chalk.gray(`   fase ${result.meta.phase} · tasks ${result.meta.tasksDone}/${result.meta.tasksTotal} · ${result.meta.generatedAt}`));
   console.log(chalk.gray('   A próxima sessão lê este documento antes de continuar (ponteiros, não cópias).\n'));
 }