@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/src/commands/state/archive.js

@@ -2,12 +2,9 @@ import chalk from 'chalk';
 import { existsSync, renameSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { join, resolve, sep } from 'path';
 import { execFileSync } from 'child_process';
-import { promoteUseCases, SPECS_USECASES_PATHSPEC } from '../../lib/specs/usecase-promoter.js';
-import { applySpecRevocations } from '../../lib/specs/acervo-lifecycle.js';
-import { ADR_INDEX_PATHSPEC } from '../../lib/specs/adr-index.js';
+import { ADR_INDEX_PATHSPEC, updateAdrIndex } from '../../lib/specs/adr-index.js';
 import { isValidFeatureName } from '../project/worktree.js';
 
-/** Refuse a move whose resolved target escapes `scopeDir`. */
 function assertContained(scopeDir, name, target) {
   const scopeAbs = resolve(scopeDir) + sep;
   const targetAbs = resolve(target);
@@ -16,21 +13,7 @@ function assertContained(scopeDir, name, target) {
   }
 }
 
-/**
- * `morph-spec archive <feature>` — atomic, git-aware archive of a completed
- * feature. Stamps the feature completed, moves `.morph/features/{name}/` →
- * `.morph/archive/{name}/`, COMMITS the move (scoped to the feature's pathspec),
- * and cleans the thin root index.
- *
- * Two callers:
- *   - `archiveCommand` (standalone `morph-spec archive` / `/morph-archive`) —
- *     archive-without-integrate, for legacy features and cleanup.
- *   - `finishCommand` — runs `runArchive` INSIDE the `morph/{feature}` branch so
- *     the committed archived state travels with the merge/PR in one integration.
- *
- * Taxonomy: archived = `status: "completed"` + `archivedAt` (per the project
- * decision — no separate "archived" status value).
- */
+// Archived = `status: "completed"` + `archivedAt`; there is no separate "archived" status.
 
 function isGitRepo(cwd) {
   try {
@@ -41,7 +24,6 @@ function isGitRepo(cwd) {
   }
 }
 
-/** Tolerant read of the review gate — mirrors the finish path's shape handling. */
 function readReviewApproved(fjPath) {
   try {
     const fj = JSON.parse(readFileSync(fjPath, 'utf8'));
@@ -53,33 +35,14 @@ function readReviewApproved(fjPath) {
 }
 
 /**
- * Core archive — NO process.exit. Returns a result the caller reports.
- *
- * Reads/writes everything relative to `cwd` (never a hard-coded process.cwd()),
- * so `finishCommand` can archive inside a worktree's own tree.
- *
- * Idempotent: if `.morph/archive/{feature}` already exists, returns
- * `{ ok: true, alreadyArchived: true }` WITHOUT failing — essential so a re-run
- * of `finish` (which archives inside the branch) does not blow up.
- *
- * @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[],
- *   refusedUseCases?: Array<{id: string, incoming: string, existing: string, existingFeature: string, message: string}>,
- *   keptSuperseded?: Array<{id: string, file: string, supersededBy: string|null, scope?: string}>,
- *   supersededUseCases?: Array<{id: string, file: string, supersededBy: string, scope?: string}>,
- *   revocationProblems?: Array<{id: string|null, reason: string, message: string}>,
- *   adrIndex?: {added: string[], revoked: string[], narrowed: string[]}|null }}
+ * Never calls process.exit, and resolves everything from `cwd` so `finish` can archive inside a
+ * worktree. Idempotent: an existing archive returns `{ ok: true, alreadyArchived: true }`.
  */
 export function runArchive(feature, opts = {}) {
   const cwd = opts.cwd || process.cwd();
 
-  // Gate 0: valid kebab name — refuses BEFORE any path is built from it. Same
-  // gate `finish` already applies upstream (defense-in-depth here); the
-  // standalone `archiveCommand` has no other gate at all, so without this an
-  // unvalidated `feature` reaches `renameSync` and can MOVE a directory outside
-  // .morph/features/ (`../../.claude` resolves to `cwd/.claude`).
+  // Validated BEFORE any path is built: `../../.claude` would let renameSync move a directory
+  // outside .morph/features/.
   if (!isValidFeatureName(feature)) {
     return { ok: false, error: 'invalid-feature-name' };
   }
@@ -93,16 +56,7 @@ export function runArchive(feature, opts = {}) {
   const featPathspec = join('.morph', 'features', feature);
   const archivePathspec = join('.morph', 'archive', feature);
 
-  // Idempotent short-circuit: already archived here. Checked FIRST so a re-run
-  // after a partial finish reports "already done", never "not found".
-  //
-  // Consequence, deliberate: this short-circuits BEFORE the use-case promotion
-  // below, so a promotion that degraded fail-open is NOT retried by re-running
-  // `finish`. That is the price of "closing a feature never fails" — an archived
-  // feature stays archived, and the only signal is an absent `promotedUseCases`
-  // in the output. Recovering means copying the UCs into `.morph/specs/usecases/`
-  // by hand; making this retry would mean re-entering the archive path for an
-  // already-closed feature, which is a worse trade.
+  // Checked FIRST so a re-run after a partial finish reports "already done", never "not found".
   if (existsSync(archivePath)) {
     return { ok: true, alreadyArchived: true, archived: false, archivePath };
   }
@@ -111,8 +65,6 @@ export function runArchive(feature, opts = {}) {
     return { ok: false, error: 'feature-folder-not-found' };
   }
 
-  // Precondition: Gate 3 (review) approved — archiving is for completed work.
-  // Read from the feature's own folder (pre-move), tolerant of legacy shapes.
   const fjPathBefore = join(featuresPath, 'feature.json');
   if (!opts.force && !readReviewApproved(fjPathBefore)) {
     return { ok: false, error: 'review-not-approved' };
@@ -120,9 +72,7 @@ export function runArchive(feature, opts = {}) {
 
   const useGit = opts.git !== false && isGitRepo(cwd);
 
-  // 1) Move the folder. Prefer `git mv` (keeps history + stages in one step);
-  //    fall back to a filesystem rename (+ git add) when the folder isn't
-  //    tracked yet or git mv fails.
+  // `git mv` keeps history and stages in one step; an untracked folder falls back to rename.
   mkdirSync(archiveDir, { recursive: true });
   let staged = false;
   if (useGit) {
@@ -140,8 +90,6 @@ export function runArchive(feature, opts = {}) {
     renameSync(featuresPath, archivePath);
   }
 
-  // 2) Stamp the authoritative feature.json (now at the archive path) as
-  //    completed + archived, and re-stage it so the commit carries the stamp.
   const fjPathAfter = join(archivePath, 'feature.json');
   if (existsSync(fjPathAfter)) {
     try {
@@ -156,63 +104,23 @@ export function runArchive(feature, opts = {}) {
     } catch { /* non-fatal — the move is what matters */ }
   }
 
-  // 3) Promote the feature's use cases into the project's permanent archive
-  //    (.morph/specs/usecases/). Read from the ALREADY-MOVED folder so there is
-  //    a single source path, and land inside the SAME scoped commit below — the
-  //    archive travels with the integration, exactly like the archived state
-  //    (MORPH.md §2.2). Fail-open: any failure degrades to "promoted nothing",
-  //    never to a refused close.
-  let promotedUseCases = [];
-  let refusedUseCases = [];
-  let keptSuperseded = [];
-  try {
-    const { promoted, refused, keptSuperseded: kept } = promoteUseCases(cwd, archivePath);
-    promotedUseCases = promoted;
-    refusedUseCases = refused;
-    keptSuperseded = kept;
-    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
-      // tracks. The replaced-by-ID deletions are tracked, so that same commit
-      // would carry them even without this line (verified by mutating it away) —
-      // `-A` is belt-and-braces, but dropping the `git add` entirely would
-      // silently promote nothing on a first delivery.
-      try { execFileSync('git', ['add', '-A', '--', SPECS_USECASES_PATHSPEC], { cwd, stdio: 'pipe' }); } catch { /* non-fatal */ }
-    }
-  } catch { /* promotion must never block archiving */ }
-
-  // 3b) Apply what the feature's spec.md declared it revokes: acervo use cases
-  //     turn `superseded`, and the ADR index gains/loses files. After the
-  //     promotion, so a substitute promoted just now is already in place (and
-  //     one it refused is known not to be); same commit, same fail-open contract.
-  let lifecycle = { superseded: [], adrIndex: null, problems: [] };
+  // Fail-open: the ADR index must never block archiving.
+  let adrIndex = { changed: false, added: [], revoked: [], narrowed: [], problems: [] };
   try {
-    lifecycle = applySpecRevocations(cwd, archivePath, { refused: refusedUseCases });
-  } catch { /* revocation must never block archiving */ }
-  const acervoChanged = promotedUseCases.length > 0 || lifecycle.superseded.length > 0;
-  const adrIndexChanged = lifecycle.adrIndex?.changed === true;
-  if (useGit && staged) {
-    if (lifecycle.superseded.length) {
-      try { execFileSync('git', ['add', '-A', '--', SPECS_USECASES_PATHSPEC], { cwd, stdio: 'pipe' }); } catch { /* non-fatal */ }
-    }
-    if (adrIndexChanged) {
-      try { execFileSync('git', ['add', '-A', '--', ADR_INDEX_PATHSPEC], { cwd, stdio: 'pipe' }); } catch { /* non-fatal */ }
-    }
+    adrIndex = updateAdrIndex(cwd, archivePath);
+  } catch { /* fail-open */ }
+  if (useGit && staged && adrIndex.changed) {
+    try { execFileSync('git', ['add', '-A', '--', ADR_INDEX_PATHSPEC], { cwd, stdio: 'pipe' }); } catch { /* non-fatal */ }
   }
 
-  // 4) Commit the move — SCOPED to this feature's pathspec, NEVER `commit -a`
-  //    (same anti-sweep discipline as `finish`'s worktree teardown). This is what
-  //    lets the archived state travel with the branch on `finish` (archive-before-merge).
-  //    The acervo pathspecs join only when something under them changed: git
-  //    refuses a pathspec that matches nothing, and that refusal would leave the
-  //    tree dirty and break the checkout/merge that follows.
+  // Scoped to this feature's pathspec, never `commit -a`. The ADR index joins only when it
+  // changed: git refuses a pathspec that matches nothing, leaving the tree dirty for the merge.
   let committed = false;
   if (useGit && staged) {
     const pathspecs = [
       featPathspec,
       archivePathspec,
-      ...(acervoChanged ? [SPECS_USECASES_PATHSPEC] : []),
-      ...(adrIndexChanged ? [ADR_INDEX_PATHSPEC] : []),
+      ...(adrIndex.changed ? [ADR_INDEX_PATHSPEC] : []),
     ];
     try {
       execFileSync('git', ['commit', '-m', `morph-spec archive: ${feature}`, '--', ...pathspecs], { cwd, stdio: 'pipe' });
@@ -220,9 +128,7 @@ export function runArchive(feature, opts = {}) {
     } catch { /* nothing to commit / no identity — not fatal, the move + stage stand */ }
   }
 
-  // 5) Drop the feature from the thin root index. Edit the index file directly
-  //    rather than calling saveState — saveState would re-create
-  //    .morph/features/{name}/feature.json and undo the archive.
+  // Not saveState: it would re-create .morph/features/{name}/feature.json and undo the archive.
   const rootPath = join(cwd, '.morph', 'state.json');
   if (existsSync(rootPath)) {
     try {
@@ -236,21 +142,14 @@ export function runArchive(feature, opts = {}) {
     } catch { /* index is derivable — non-fatal */ }
   }
 
-  const adr = lifecycle.adrIndex;
   return {
-    ok: true, archived: true, committed, staged, archivePath, promotedUseCases, refusedUseCases,
-    keptSuperseded,
-    supersededUseCases: lifecycle.superseded,
-    revocationProblems: lifecycle.problems,
-    adrIndex: adrIndexChanged ? { added: adr.added, revoked: adr.revoked, narrowed: adr.narrowed } : null,
+    ok: true, archived: true, committed, staged, archivePath,
+    revocationProblems: adrIndex.problems,
+    adrIndex: adrIndex.changed ? { added: adrIndex.added, revoked: adrIndex.revoked, narrowed: adrIndex.narrowed } : null,
   };
 }
 
-/**
- * Standalone `morph-spec archive <feature>` — thin wrapper over `runArchive`
- * that maps its result to the CLI's messages and exit codes. Preserves the
- * historical behaviour: an already-archived feature is reported as a refusal.
- */
+// Unlike `runArchive`, an already-archived feature is reported as a refusal here.
 export async function archiveCommand(featureName, options = {}) {
   try {
     const result = runArchive(featureName, {
@@ -281,27 +180,12 @@ export async function archiveCommand(featureName, options = {}) {
 
     console.log(chalk.green(`\n📦 Archived "${featureName}" → .morph/archive/${featureName}/`));
     console.log(chalk.gray(`   status: completed, archivedAt stamped in feature.json.`));
-    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}`));
-      }
-    }
-    for (const k of result.keptSuperseded ?? []) {
-      console.log(chalk.yellow(`   ${k.id} continua superseded (superseded_by: ${k.supersededBy ?? '?'}) — a cópia promovida não trazia o status, e o acervo o manteve.`));
-    }
-    for (const s of result.supersededUseCases ?? []) {
-      console.log(chalk.gray(`   ${s.id} → status: superseded (superseded_by: ${s.supersededBy}${s.scope ? `; ainda vale em: ${s.scope}` : ''}).`));
-    }
     if (result.adrIndex) {
       const { added, revoked, narrowed } = result.adrIndex;
       console.log(chalk.gray(`   ADR index (.morph/specs/adrs/): +${added.length} −${revoked.length} ~${narrowed.length}.`));
     }
     if (result.revocationProblems?.length) {
-      console.log(chalk.yellow(`\n⚠️  ${result.revocationProblems.length} revogação(ões) do spec.md NÃO aplicada(s):`));
+      console.log(chalk.yellow(`\n⚠️  ${result.revocationProblems.length} revogação(ões) do plan.md NÃO aplicada(s):`));
       for (const p of result.revocationProblems) {
         console.log(chalk.yellow(`   ${p.message}`));
       }

package/src/commands/state/auto-approval.js

@@ -0,0 +1,65 @@
+import { planAutoApprovalBlock } from './gate-check.js';
+import { uiuxAutoApprovalBlock } from '../../lib/specs/screen-checklist.js';
+
+/**
+ * Why an "auto" signature may not stamp `gate`, or null when it may. The one rule
+ * `approve` and `advance` share: they write the same `approvalGates` entry.
+ */
+export function autoApprovalRefusal({ cwd, featureName, feature, gate, approvedBy }) {
+  if (approvedBy !== 'auto' || !gate) return null;
+
+  if (gate === 'review' && feature.workType === 'hotfix') {
+    return {
+      title: 'Hotfix exige aprovação humana no Gate 3 — trust:auto não se aplica.',
+      hints: ['Aprove com --approver <nome>, num terminal interativo, ou pela resposta humana "aprovado" (state-sync) via AskUserQuestion.'],
+    };
+  }
+
+  const decision = feature.gateDecisions?.[gate];
+  if (decision?.pause === true) {
+    return {
+      title: `O Gate "${gate}" registrou pause:true — auto-aprovação não se aplica.`,
+      hints: [
+        `Sinal: ${decision.reason || 'risco detectado'}`,
+        'A decisão gravada exigia pausa humana. Aprove com --approver <nome>, num',
+        'terminal interativo, ou pela resposta humana via AskUserQuestion (state-sync).',
+        'Se o sinal de risco já não vale, regrave a decisão:',
+        `morph-spec gate-decision ${featureName} ${gate} --pause false --reason "<motivo>"`,
+      ],
+    };
+  }
+
+  if (gate === 'plan') {
+    const block = planAutoApprovalBlock(cwd, featureName);
+    if (block) {
+      return {
+        title: `O gate "plan" não pode ser auto-aprovado — ${block}.`,
+        hints: ['Com plan-check verde, rode de novo; ou aprove com --approver <nome>. O --force não dispensa o checks.json.'],
+      };
+    }
+  }
+
+  if (gate === 'uiux') {
+    const block = uiuxAutoApprovalBlock(cwd, featureName, feature);
+    if (block) {
+      return {
+        title: `O Gate "uiux" não pode ser auto-aprovado — ${block}.`,
+        hints: [
+          'Complete o checklist (ver a skill morph-uiux) e rode de novo, aprove com',
+          '--approver <nome>, ou, se a pausa já foi decidida, grave a decisão:',
+          `morph-spec gate-decision ${featureName} uiux --pause false --reason "<motivo>"`,
+          'O --force não dispensa o checklist.',
+        ],
+      };
+    }
+  }
+
+  return null;
+}
+
+export function printRefusal(chalk, refusal) {
+  console.error(chalk.red(`\n❌ ${refusal.title}`));
+  refusal.hints.forEach((line, i) => {
+    console.error(chalk.gray(`   ${line}${i === refusal.hints.length - 1 ? '\n' : ''}`));
+  });
+}

package/src/commands/state/create.js

@@ -7,30 +7,12 @@ import { WORK_TYPES, DEFAULT_WORK_TYPE, POLICY_APPROVER_PREFIX, isValidWorkType,
 import { detectWorkType } from '../../lib/work-type-detector.js';
 import { runWorktreeSetup, materializeState, isGitRepo, branchExists, buildBranchName } from '../project/worktree.js';
 import { detectDefaultBranch } from '../../lib/git/default-branch.js';
+import { writePlanSkeleton } from '../../lib/plan/plan-template.js';
+import { seedDotnetBuildIgnores } from '../../lib/stack/dotnet-build-ignores.js';
 
-/**
- * Common flow (no `--worktree`): still isolate the feature on its own branch
- * `morph/{feature}`, branched from the DEFAULT branch (never HEAD — so it never
- * inherits another feature branch's commits) and checked out in place, so
- * `morph-spec finish` can later merge/PR it back. Symmetric with the worktree
- * flow, which gets its branch from `runWorktreeSetup`.
- *
- * That checkout moves the dev's PRIMARY working tree, and `stdio: 'pipe'`
- * swallows even git's own message — so the move is reported by the caller
- * (`branchMoveWarning`), never silent. `checkout: false` (`--no-checkout`)
- * still CREATES the branch — `finish --pr|--merge` depends on it existing in
- * both flows — and only skips moving the tree.
- *
- * Fail-open: outside a git repo, with no resolvable default, or on any git
- * error, the feature is simply left on the current branch — never a failed birth.
- *
- * @param {string} featureName
- * @param {{ checkout?: boolean }} [opts] - `checkout: false` keeps the tree put
- * @returns {{ branched: boolean, checkedOut: boolean, branch?: string, from?: string,
- *             movedFrom?: string, stayedOn?: string, reason?: string }}
- *   `movedFrom` is present ONLY when the working tree actually moved (it names
- *   the branch left behind); `stayedOn` only when the move was declined.
- */
+// Branches from the DEFAULT branch, never HEAD, so it never inherits another feature's commits.
+// `checkout: false` still CREATES the branch, which `finish` depends on. Fail-open: any git error
+// leaves the feature on the current branch, never a failed birth.
 function branchCommonFlow(featureName, { checkout = true } = {}) {
   const cwd = process.cwd();
   try {
@@ -42,7 +24,6 @@ function branchCommonFlow(featureName, { checkout = true } = {}) {
       execFileSync('git', ['branch', branch, defaultBranch], { cwd, stdio: 'pipe' });
     }
     const current = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd, stdio: 'pipe' }).toString().trim();
-    // Already there: nothing moved, so nothing to warn about.
     if (current === branch) return { branched: true, checkedOut: true, branch, from: defaultBranch };
     if (!checkout) return { branched: true, checkedOut: false, branch, from: defaultBranch, stayedOn: current };
     execFileSync('git', ['checkout', branch], { cwd, stdio: 'pipe' });
@@ -52,14 +33,7 @@ function branchCommonFlow(featureName, { checkout = true } = {}) {
   }
 }
 
-/**
- * The alert for a checkout that MOVED. Built once and rendered on both
- * surfaces — stdout (human) and stderr (under `--json`, so it survives a
- * stdout redirect) — so the two can never drift apart.
- *
- * @param {{ branch: string, movedFrom: string }} branchResult
- * @returns {string[]} lines, unstyled and unindented
- */
+// One builder for stdout and (under --json) stderr, so the two surfaces never drift.
 function branchMoveWarning({ branch, movedFrom }) {
   return [
     `⚠️  Working tree MOVED: ${movedFrom} → ${branch}`,
@@ -70,21 +44,12 @@ function branchMoveWarning({ branch, movedFrom }) {
   ];
 }
 
-/** Feature names are kebab-case: lowercase alphanumerics and hyphens. */
 const FEATURE_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
 
 const VALID_STATUSES = ['draft', 'in_progress', 'completed'];
 const VALID_DETECT_SOURCES = ['deterministic', 'llm', 'user'];
 
-/**
- * Resolve the work type for a NEW feature from `--type`/`--request`, or fall
- * back to the default. Never touches the filesystem/state — pure control
- * flow so it can `process.exit` before any side effect happens.
- *
- * @param {{ type?: string, request?: string, detectSource?: string }} options
- * @param {string} now - ISO timestamp, stamped into workTypeDetection.decidedAt
- * @returns {{ workType: string, workTypeDetection?: object }}
- */
+// Pure control flow, so it can `process.exit` before any side effect happens.
 function resolveWorkType(options, now) {
   if (options.type !== undefined) {
     if (!isValidWorkType(options.type)) {
@@ -110,10 +75,8 @@ function resolveWorkType(options, now) {
   if (options.request !== undefined) {
     const d = detectWorkType({ text: options.request });
     if (d.confidence !== 'high') {
-      // Router contract: determinism first, ambiguity escalates to the
-      // LLM/HCOP caller (which re-runs `create --type <chosen>`). The
-      // feature must NOT be created on this path — always JSON, regardless
-      // of --json, since this is the machine-consumable half of the contract.
+      // Ambiguity escalates to the caller, which re-runs `create --type`: nothing is created here, and
+      // the output is always JSON since this is the machine-consumable half of the contract.
       console.log(JSON.stringify({ needsDecision: true, candidates: d.candidates, matched: d.matched }));
       process.exit(2);
     }
@@ -131,20 +94,8 @@ function resolveWorkType(options, now) {
   return { workType: DEFAULT_WORK_TYPE };
 }
 
-/**
- * `morph-spec create <feature>` — explicit feature birth: classifies the
- * work type (`--type`/`--request`), creates `.morph/features/{feature}/`
- * scaffolded per the type's dimensioned pipeline, stamps policy-approved
- * gates (`approvedBy: "policy:{type}"`) for the gates that type skips, and
- * (with `--worktree`) births the feature already inside its own git
- * worktree on branch `morph/{feature}`.
- *
- * Replaces the implicit birth via the state-sync hook on the first Write —
- * the skills call this at proposal start so the authoritative state exists
- * with the full canonical shape before any artifact lands. Idempotent: an
- * existing feature is reported and left untouched — no re-stamping, no
- * re-scaffolding, no worktree setup.
- */
+// Idempotent: an existing feature is reported and left untouched (no re-stamping, no
+// re-scaffolding, no worktree setup).
 export async function createCommand(featureName, options = {}) {
   try {
     if (!FEATURE_NAME_RE.test(featureName)) {
@@ -159,15 +110,8 @@ export async function createCommand(featureName, options = {}) {
       process.exit(1);
     }
 
-    // `--no-checkout` pede que o checkout PRINCIPAL não se mova; `--worktree`
-    // nunca o move — a feature nasce numa árvore separada, e o caminho de
-    // worktree sequer chama `branchCommonFlow`, que é o único leitor do flag.
-    // Aceitar a combinação em silêncio é dizer que o CLI honrou um pedido que
-    // ele ignorou — o mesmo anti-padrão que esta série de fixes tirou do
-    // `finish --pr --push`. Recusa ALTA, e AQUI: junto das outras validações
-    // de forma, ANTES de `createFeature` — a primeira mutação do `create`.
-    // Uma recusa depois dela deixaria a feature nascida por um comando que
-    // falhou, pior que o no-op que ela substitui.
+    // `--worktree` nunca move o checkout principal: aceitar `--no-checkout` junto em silêncio é fingir
+    // que o pedido foi honrado. Recusa AQUI, antes de `createFeature`, a primeira mutação do `create`.
     if (options.worktree && options.checkout === false) {
       console.error(chalk.red(`\n❌ no-checkout-with-worktree: --no-checkout não se combina com --worktree`));
       console.error(chalk.gray(`   O --worktree já não move o checkout desta árvore: a feature nasce em worktrees/${featureName},`));
@@ -180,16 +124,10 @@ export async function createCommand(featureName, options = {}) {
     const now = new Date().toISOString();
     const { workType, workTypeDetection } = resolveWorkType(options, now);
 
-    // Identity at birth: every feature is stamped name (slug by default) +
-    // description, so it is never an anonymous {status,updatedAt} shell.
-    // `--request` (which the router already consumes) doubles as the
-    // description seed. A NEW feature with no description source is refused —
-    // the description is the one identity field a human must supply. An
-    // idempotent re-run on an EXISTING feature never demands it.
+    // A NEW feature with no description source is refused: it is the one identity field a human
+    // must supply. An idempotent re-run never demands it.
     const description = options.description ?? options.request ?? null;
-    // Existence check via the filesystem, NOT getFeature/loadState — loadState
-    // throws when no state exists yet (a feature can be the first morph action
-    // in a fresh project), which would break birth-from-nothing.
+    // Filesystem, not loadState: loadState throws when no state exists yet (birth from nothing).
     const alreadyExists = existsSync(join(process.cwd(), '.morph', 'features', featureName, 'feature.json'));
     if (!alreadyExists && (description === null || String(description).trim() === '')) {
       console.error(chalk.red(`\n❌ A feature needs a description at birth: "${featureName}"`));
@@ -211,16 +149,15 @@ export async function createCommand(featureName, options = {}) {
 
     let worktreeResult = null;
     let branchResult = null;
+    let planSkeleton = null;
+    let gitignoreAdded = [];
 
     if (created) {
-      // Scaffold the phase folders this work type starts with.
       for (const folder of wt.scaffold) {
         mkdirSync(join(featureDir, folder), { recursive: true });
       }
 
-      // Stamp the gates this type skips by policy — NEVER "auto" (the
-      // gate-guard hook only special-cases approvedBy === "auto"; policy:{type}
-      // keeps the audit trail honest while staying silent to the guard).
+      // NEVER "auto": the gate-guard hook special-cases it; `policy:{type}` keeps the audit honest.
       for (const gate of wt.skippedGates) {
         await setApprovalGate(featureName, gate, true, {
           approvedBy: `${POLICY_APPROVER_PREFIX}${workType}`,
@@ -232,19 +169,10 @@ export async function createCommand(featureName, options = {}) {
         worktreeResult = await runWorktreeSetup(featureName, {});
         if (worktreeResult?.created && worktreeResult.path) {
           try {
-            // feature.json in the root is NOT committed yet (create just
-            // wrote it), so the branch `runWorktreeSetup` forked off the
-            // DEFAULT branch cannot have it — copy the freshly-scaffolded
-            // folder into the worktree and re-materialize its local state.json.
+            // The root feature.json is not committed yet, so the worktree branch cannot have it: copy it in.
             cpSync(featureDir, join(worktreeResult.path, '.morph', 'features', featureName), { recursive: true });
-            // The `.worktree` registration is ROOT-OWNED metadata (runWorktreeSetup
-            // stamped it onto the root's feature.json, which cpSync just copied in).
-            // Strip it from the worktree's branch-local copy so the branch commits a
-            // clean feature.json — otherwise it merges back into the root at
-            // `morph-spec finish` and the post-merge cleanup leaves the root dirty.
-            // verify.decidePersistence reads the registration from the ROOT's copy,
-            // never this branch-local one (see verify.js), so stripping is safe and
-            // restores the invariant that comment relies on.
+            // `.worktree` is ROOT-OWNED: left in the branch copy it merges back at `finish` and leaves the
+            // root dirty. verify reads the registration from the root copy only.
             try {
               const wtFeatureJson = join(worktreeResult.path, '.morph', 'features', featureName, 'feature.json');
               const fj = JSON.parse(readFileSync(wtFeatureJson, 'utf8'));
@@ -253,41 +181,47 @@ export async function createCommand(featureName, options = {}) {
                 writeFileSync(wtFeatureJson, JSON.stringify(fj, null, 2), 'utf8');
               }
             } catch { /* fail-open — root copy still carries the registration for verify */ }
-            // Re-materialize now that the feature.json exists in the worktree, and
-            // report THIS result — runWorktreeSetup's earlier materialize ran before
-            // the copy (no features yet), so its `materialized:false` was stale.
+            // Re-materialize after the copy: the setup's earlier materialize ran with no features yet.
             const remat = await materializeState(worktreeResult.path);
             worktreeResult.materialized = remat.materialized;
-            // Same reason the setup path generates one: the new instance's first
-            // read. Regenerated here because setup ran before the copy above.
             try {
               const { writeHandoff } = await import('../../lib/generators/handoff-generator.js');
-              // 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.
+              // `worktree` was stripped from this copy above, so pass 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 */ }
         }
       } else {
-        // Common flow: still isolate the feature on its own branch so `finish`
-        // can merge/PR it back. Fail-open (see branchCommonFlow).
         // Commander's `--no-checkout` sets options.checkout === false.
         branchResult = branchCommonFlow(featureName, { checkout: options.checkout !== false });
       }
+
+      // protect-spec-files freezes an existing file once its approval is stamped,
+      // so a type born pre-approved must create it itself. With a worktree it goes
+      // only there: an extra file in the root copy makes `finish` refuse a dirty root.
+      if (wt.scaffold.includes('2-plan') && !wt.skippedGates.includes('plan')) {
+        const home = worktreeResult?.created && worktreeResult.path ? worktreeResult.path : process.cwd();
+        try {
+          planSkeleton = writePlanSkeleton(featureName, home);
+        } catch (err) {
+          planSkeleton = { written: false, error: err.message };
+        }
+      }
+
+      const home = worktreeResult?.created && worktreeResult.path ? worktreeResult.path : process.cwd();
+      gitignoreAdded = seedDotnetBuildIgnores(home, { featureName, configRoot: process.cwd() });
     }
 
-    // `feature` is a snapshot from BEFORE the gate-stamping/worktree steps —
-    // setApprovalGate/runWorktreeSetup each do their own loadState()/saveState()
-    // round-trip on disk, so re-read the authoritative copy for reporting.
+    // `feature` predates the gate-stamping and worktree steps, which each round-trip state on disk.
     const finalFeature = created ? (getFeature(featureName) || feature) : feature;
 
     if (options.json) {
       const out = { feature: featureName, created, ...finalFeature };
       if (worktreeResult) out.worktree = worktreeResult;
       if (branchResult) out.branch = branchResult;
-      // The move of the PRIMARY checkout is never silent — under --json it goes
-      // to stderr so it survives `... --json > out.json` instead of vanishing.
+      if (planSkeleton) out.planSkeleton = planSkeleton;
+      if (gitignoreAdded.length) out.gitignoreAdded = gitignoreAdded;
+      // Under --json the move goes to stderr, so it survives `... --json > out.json`.
       if (branchResult?.movedFrom) {
         console.error(chalk.yellow(branchMoveWarning(branchResult).join('\n')));
       }
@@ -300,6 +234,12 @@ export async function createCommand(featureName, options = {}) {
       console.log(chalk.gray(`   .morph/features/${featureName}/feature.json (canonical shape)`));
       console.log(chalk.gray(`   status: ${finalFeature.status} | createdAt: ${finalFeature.createdAt}`));
       console.log(chalk.gray(`   scaffolded: ${wt.scaffold.join(', ')}`));
+      if (gitignoreAdded.length) {
+        console.log(chalk.gray(`   .gitignore: ${gitignoreAdded.join(' ')} adicionados (projeto .NET)`));
+      }
+      if (planSkeleton?.written) {
+        console.log(chalk.gray(`   2-plan/plan.md: esqueleto escrito (gramática: morph-spec plan-check --help)`));
+      }
       if (wt.skippedGates.length) {
         console.log(chalk.yellow(`   gates skipped by policy:${finalFeature.workType}: ${wt.skippedGates.join(', ')}`));
       }