@polymorphism-tech/morph-spec 8.24.2 → 8.24.3

package/README.md

@@ -3,7 +3,7 @@
 > Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.
 
 **Package:** `@polymorphism-tech/morph-spec`
-**Version:** 8.24.2  
+**Version:** 8.24.3  
 **Requires:** Node.js 22+, Claude Code
 
 ---
@@ -368,4 +368,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v8.24.2 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v8.24.3 by [Polymorphism Tech](https://polymorphism.tech)*

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "8.24.2",
+  "version": "8.24.3",
   "displayName": "MORPH-SPEC Framework",
   "description": "Spec-driven development with 38 agents and 8-phase workflow for .NET/Blazor/Next.js/Azure",
   "publisher": "polymorphism-tech",

package/docs/CHEATSHEET.md

@@ -185,4 +185,4 @@ Never edited directly — go through CLI commands or `morph-spec update` instead
 
 ---
 
-*morph-spec v8.24.2 by Polymorphism Tech*
+*morph-spec v8.24.3 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -249,4 +249,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.24.2 by Polymorphism Tech*
+*morph-spec v8.24.3 by Polymorphism Tech*

package/framework/skills/core/create-umbraco-lp/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a criação de uma landing page nova ponta-a-ponta a partir do
 version: core
 when-to-invoke: ao iniciar um novo projeto de LP com o template Umbraco genérico
 user-invokable: true
-cliVersion: "8.24.2"
+cliVersion: "8.24.3"
 stacks:
   - umbraco
 ---

package/framework/skills/core/migrate-lp-to-umbraco/SKILL.md

@@ -4,7 +4,7 @@ description: Migra uma landing page existente (React/Vite, Next.js estático ou
 version: core
 when-to-invoke: ao receber instrução "use /migrate-lp-to-umbraco {projeto}" do usuário, ou quando o usuário descrever necessidade de migrar uma LP para Umbraco
 user-invokable: true
-cliVersion: "8.24.2"
+cliVersion: "8.24.3"
 stacks:
   - umbraco
 ---

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

@@ -4,7 +4,7 @@ description: Orquestra a execução autônoma de tasks de uma feature morph-spec
 version: core
 when-to-invoke: após Gate 2 aprovado, ao receber instrução "use /morph-apply" ou "implementar feature"
 user-invokable: true
-cliVersion: "8.24.2"
+cliVersion: "8.24.3"
 ---
 
 # morph-apply

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: "8.24.2"
+cliVersion: "8.24.3"
 ---
 
 # morph-brainstorming

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: "8.24.2"
+cliVersion: "8.24.3"
 ---
 
 # morph-eval

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

@@ -4,7 +4,7 @@ description: ADW cirúrgico de hotfix — resolve uma queda/bug crítico de prod
 version: core
 when-to-invoke: ao receber "/morph-hotfix {feature}", quando a morph-proposal classifica o pedido como workType hotfix (Passo 0), ou o usuário diz "produção caiu / hotfix / urgente"
 user-invokable: true
-cliVersion: "8.24.2"
+cliVersion: "8.24.3"
 ---
 
 # morph-hotfix

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: "8.24.2"
+cliVersion: "8.24.3"
 ---
 
 # morph-implement

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

@@ -4,7 +4,7 @@ description: Guia a produção dos artefatos de planejamento de uma feature (use
 version: core
 when-to-invoke: ao iniciar a fase plan de uma feature, após o Gate 1 (proposal aprovado)
 user-invokable: true
-cliVersion: "8.24.2"
+cliVersion: "8.24.3"
 ---
 
 # morph-plan

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: "8.24.2"
+cliVersion: "8.24.3"
 ---
 
 # morph-proposal

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: "8.24.2"
+cliVersion: "8.24.3"
 ---
 
 # morph-review

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: "8.24.2"
+cliVersion: "8.24.3"
 ---
 
 # morph-stack-scan

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.24.2"
+cliVersion: "8.24.3"
 ---
 
 # 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.24.2"
+cliVersion: "8.24.3"
 ---
 
 # morph-uiux

package/package.json

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

package/src/commands/project/worktree.js

@@ -968,11 +968,23 @@ export function shedRootFeatureScope(root, feature) {
  * from blocking every other feature's finish). `ok:false` means the status call
  * itself failed; an empty `dirt` means clean enough to merge into.
  *
+ * `exemptOwnScope` additionally forgives everything under
+ * `.morph/features/{feature}/` — the EXACT pathspec `shedRootFeatureScope`
+ * backs up and discards. It exists so `finish` can ask "is the root clean
+ * enough to merge into?" BEFORE archiving anything, where the shed has not run
+ * yet and the feature's own scaffold is still on disk. Without it that early
+ * question answers "dirty" for a root that the shed would have cleaned, and a
+ * finish that works today would start being refused.
+ *
+ * Callers must keep the post-shed check: this one is an early refusal so the
+ * archive never happens, not the authoritative gate.
+ *
  * @param {string} root
  * @param {string} feature - the feature THIS finish acts on (its own scope is the shed's job)
+ * @param {{ exemptOwnScope?: boolean }} [opts]
  * @returns {{ ok: boolean, dirt: string[] }}
  */
-export function primaryRootUnexplainedDirt(root, feature) {
+export function primaryRootUnexplainedDirt(root, feature, opts = {}) {
   let rootStatusRaw;
   try {
     // `--untracked-files=all`, not the default: the default collapses an
@@ -982,9 +994,11 @@ export function primaryRootUnexplainedDirt(root, feature) {
   } catch {
     return { ok: false, dirt: [] };
   }
+  const ownScope = `.morph/features/${feature}/`;
   const dirt = rootStatusRaw.split('\0').filter((record) => {
     if (!record || record.length < 4) return false;
     const p = record.slice(3).replace(/\\/g, '/');
+    if (opts.exemptOwnScope && p.startsWith(ownScope)) return false;
     return !isLiveSiblingWorktreeRegistration(p, root, feature);
   });
   return { ok: true, dirt };

package/src/commands/state/finish.js

@@ -180,6 +180,14 @@ export async function finishCommand(feature, options = {}) {
     // merge). A feature with NO morph/{f} branch was born before this flow —
     // route it explicitly to archive-without-integrate, never a generic refusal.
     if (!branchExists(expectedBranch, root)) {
+      // No branch AND no feature on disk is not a legacy feature — it is a
+      // feature that is not here at all (wrong name, wrong tree, or already
+      // archived). Routing that to `archive legacy` would tell the user to
+      // archive something that does not exist.
+      if (!existsSync(join(root, '.morph', 'features', feature))) {
+        emit({ finished: false, error: 'feature-not-found', feature, ...featureElsewhereHint(root, root, feature) });
+        process.exit(1);
+      }
       emit({
         finished: false,
         error: 'no-feature-branch',
@@ -203,6 +211,22 @@ export async function finishCommand(feature, options = {}) {
     featureCwd = root;
   }
 
+  // Validation 0c: the feature must still BE there. Without this, a missing
+  // feature.json makes the optional chaining below fall through to
+  // `review-not-approved`, which collapses three different situations into one
+  // wrong diagnosis: gate genuinely unapproved, feature already archived, and
+  // feature living on a branch we are not on. The second one is what a user
+  // hits when retrying an interrupted finish, and being told "Gate 3 not
+  // approved" about an approved gate sends them looking in the wrong place.
+  //
+  // Keyed on the DIRECTORY, not on the parse: readFeatureJson also returns null
+  // for malformed JSON, and a legacy feature with a folder but no (or broken)
+  // feature.json is a real thing that `--force` is expected to push through.
+  if (!existsSync(join(featureCwd, '.morph', 'features', feature))) {
+    emit({ finished: false, error: 'feature-not-found', feature, ...featureElsewhereHint(featureCwd, root, feature) });
+    process.exit(1);
+  }
+
   // Validation 1: Gate 3 (review) approved on the feature's own feature.json.
   const fj = readFeatureJson(featureCwd, feature);
   if (!options.force && !(fj?.approvalGates?.review?.approved === true || fj?.approvals?.review?.approved === true)) {
@@ -239,6 +263,37 @@ export async function finishCommand(feature, options = {}) {
     process.exit(1);
   }
 
+  // ── MERGE precondition, BEFORE the archive ────────────────────────────────
+  // `--merge` lands its merge commit in the PRIMARY ROOT, so the root has to be
+  // clean. That check used to live inside integrateMerge — i.e. AFTER
+  // runArchive had already moved the feature to .morph/archive/, promoted its
+  // use cases and COMMITTED. A root dirtied by unrelated work therefore got a
+  // refusal on a half-finished feature, and the retry then failed for a
+  // different reason entirely (the feature was no longer in features/).
+  //
+  // `exemptOwnScope` because shedRootFeatureScope has not run yet: this
+  // feature's own root-side scaffold is still on disk and is not a reason to
+  // refuse — the shed backs it up and discards it moments later.
+  //
+  // `--pr` is exempt by design: integratePr pushes from the root but never
+  // checks out or merges there, so root dirt cannot corrupt it.
+  if (mode === 'merge' && isWorktreeFlow) {
+    const rootPre = primaryRootUnexplainedDirt(root, feature, { exemptOwnScope: true });
+    if (!rootPre.ok) {
+      emit({ finished: false, error: 'primary-root-status-failed', feature });
+      process.exit(1);
+    }
+    if (rootPre.dirt.length) {
+      emit({
+        finished: false,
+        error: 'primary-root-dirty',
+        hint: 'a raiz primária tem trabalho não commitado — o merge acontece nela; commite ou faça stash antes do finish',
+        feature,
+      });
+      process.exit(1);
+    }
+  }
+
   // ── PR preconditions run BEFORE the archive, so a refused --pr has NO side
   //    effect (nothing archived, nothing committed). ─────────────────────────
   if (mode === 'pr') {
@@ -284,6 +339,11 @@ async function integrateMerge({ emit, root, feature, expectedBranch, defaultBran
     const { shedBackup } = shedRootFeatureScope(root, feature);
     const backupNote = shedBackup ? { shedBackup } : {};
 
+    // Final gate before the merge commit lands. The pre-archive check above
+    // already refused an unrelated-dirt root WITHOUT side effects, so reaching
+    // a refusal HERE means the shed itself dirtied the root — a bug signal, not
+    // user error. Kept because this is the last moment before we mutate the
+    // default branch, and it is nearly free.
     const rootClean = primaryRootUnexplainedDirt(root, feature);
     if (!rootClean.ok) {
       emit({ finished: false, error: 'primary-root-status-failed', feature, ...backupNote });
@@ -521,6 +581,52 @@ function gitErr(err) {
   return (((err.stdout && err.stdout.toString()) || '') + ((err.stderr && err.stderr.toString()) || '')).slice(0, 2000) || (err.message || '').slice(0, 500);
 }
 
+/**
+ * Where a feature that is NOT in `features/` actually went, as extra fields on
+ * the `feature-not-found` payload.
+ *
+ * Exists because "not found" is the least useful thing we can say about a
+ * feature the user just worked on. The two real cases:
+ *
+ *  - ARCHIVED: an earlier finish archived it and then failed to integrate.
+ *    What is missing is the merge, not the whole finish — say so, because the
+ *    user's instinct is to re-run `finish` and get refused again.
+ *  - ON ITS BRANCH: the feature was created on `morph/{f}` and the command is
+ *    running from the default branch, where `.morph/features/{f}` does not
+ *    exist yet. Naming the branch turns a dead end into one checkout.
+ *
+ * Fail-open in every direction: a hint that cannot be computed is simply absent.
+ *
+ * @param {string} featureCwd - the tree we looked in
+ * @param {string} root - the primary root
+ * @param {string} feature
+ * @returns {{ archived?: string, hint?: string, onBranch?: string }}
+ */
+function featureElsewhereHint(featureCwd, root, feature) {
+  try {
+    const archived = join(featureCwd, '.morph', 'archive', feature);
+    if (existsSync(archived)) {
+      return {
+        archived: archived.replace(/\\/g, '/'),
+        hint: `'${feature}' já foi arquivada por um finish anterior — o que faltou foi a integração. Verifique se o merge/PR já aconteceu antes de refazer o trabalho à mão.`,
+      };
+    }
+  } catch { /* fail-open */ }
+
+  try {
+    const branch = `morph/${feature}`;
+    const listed = execFileSync('git', ['branch', '--list', branch], { cwd: root, stdio: 'pipe' }).toString().trim();
+    if (listed) {
+      return {
+        onBranch: branch,
+        hint: `'${feature}' não está nesta árvore, mas a branch ${branch} existe — rode o finish de lá (\`git checkout ${branch}\`) ou do worktree da feature.`,
+      };
+    }
+  } catch { /* fail-open — sem git, sem hint */ }
+
+  return { hint: `'${feature}' não existe em .morph/features/ nesta árvore. Confira o nome com \`morph-spec list --all\`.` };
+}
+
 function readFeatureJson(cwd, feature) {
   try {
     return JSON.parse(readFileSync(join(cwd, '.morph', 'features', feature, 'feature.json'), 'utf8'));