@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

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

@@ -2,11 +2,8 @@ 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` both apply: they write the same
- * `approvalGates` entry, so they must refuse the same inputs.
- *
- * @returns {{ title: string, hints: string[] } | null}
+ * 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;

package/src/commands/state/create.js

@@ -10,29 +10,9 @@ 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 {
@@ -44,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' });
@@ -54,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}`,
@@ -72,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)) {
@@ -112,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);
     }
@@ -133,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 plan 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)) {
@@ -161,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},`));
@@ -182,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}"`));
@@ -217,14 +153,11 @@ export async function createCommand(featureName, options = {}) {
     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}`,
@@ -236,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'));
@@ -257,25 +181,17 @@ 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 });
       }
@@ -296,9 +212,7 @@ export async function createCommand(featureName, options = {}) {
       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) {
@@ -307,8 +221,7 @@ export async function createCommand(featureName, options = {}) {
       if (branchResult) out.branch = branchResult;
       if (planSkeleton) out.planSkeleton = planSkeleton;
       if (gitignoreAdded.length) out.gitignoreAdded = gitignoreAdded;
-      // The move of the PRIMARY checkout is never silent — under --json it goes
-      // to stderr so it survives `... --json > out.json` instead of vanishing.
+      // Under --json the move goes to stderr, so it survives `... --json > out.json`.
       if (branchResult?.movedFrom) {
         console.error(chalk.yellow(branchMoveWarning(branchResult).join('\n')));
       }

package/src/commands/state/delete.js

@@ -6,33 +6,10 @@ import { isValidFeatureName, cwdIsInsideWorktree, teardownWorktree, resolvePrima
 import { resolveFeatureTree } from '../../lib/worktree/feature-truth.js';
 import { tearDownFeatureStack } from '../../lib/e2e/stack-teardown.js';
 
-/**
- * `morph-spec delete <feature>` — remove a feature. Hard by default (folder is
- * gone), soft via `--archive` (moved to .morph/archive with status
- * "abandoned"). The complement of `archive`: archive = completed work you keep;
- * delete = dead scaffolds and abandoned drafts you clear out.
- *
- * The critical guarantee — mirrored from `archive` — is that the deletion also
- * drops the feature from the thin root index (.morph/state.json). Without that,
- * the next `loadState` resurrects the folder from the stale index entry
- * (turning a delete into a zombie). We edit the index directly rather than
- * calling saveState, which would re-materialize .morph/features/{name}.
- *
- * Refuses when any gate is approved (real work, not a dead shell), unless
- * `--force`.
- *
- * SECURITY: `featureName` is an unsanitized CLI argument that flows straight
- * into `rmSync(..., { recursive: true })` — the same class of bug the worktree
- * teardown guards against, but here the danger is path TRAVERSAL rather than a
- * followed symlink. `join(cwd, '.morph', 'features', '../../.claude')`
- * resolves to `cwd/.claude`, so an unvalidated name can point the hard-delete
- * at the shared `.claude/` install (or anything else relative to cwd). Gated
- * by `isValidFeatureName` (same kebab-slug rule `create` stamps at birth) PLUS
- * a resolved-path containment assert — validated by path, not by the
- * convention that a real feature name never contains `..`.
- */
-
-/** Refuse a delete/archive whose resolved target escapes `.morph/features/{scope}/{name}`. */
+// `featureName` flows into a recursive rmSync and `../../.claude` would resolve to the shared
+// install: the name is validated AND the resolved path must stay contained. Dropping the root
+// index entry matters too, or the next loadState resurrects the folder.
+
 function assertContained(scopeDir, name, target) {
   const scopeAbs = resolve(scopeDir) + sep;
   const targetAbs = resolve(target);
@@ -57,7 +34,6 @@ function approvedGates(feature) {
     .map(([name]) => name);
 }
 
-/** Drop the feature from the thin, derivable root index (like archive does). */
 function dropFromIndex(cwd, featureName) {
   const rootPath = join(cwd, '.morph', 'state.json');
   if (!existsSync(rootPath)) return;
@@ -76,11 +52,7 @@ export async function deleteCommand(featureName, options = {}) {
   try {
     const cwd = options.cwd || process.cwd();
 
-    // Gate 0: valid kebab name — refuses BEFORE any path is built from it, so a
-    // traversal attempt (`../../.claude`) never reaches existsSync/rmSync. Same
-    // gate `create` stamps at birth and `finish` re-checks; unlike those two,
-    // delete/archive take a FRESH argument every invocation, so this cannot rely
-    // on "every real feature folder is already a valid slug".
+    // Validated BEFORE any path is built: delete takes a fresh argument on every invocation.
     if (!isValidFeatureName(featureName)) {
       console.error(chalk.red(`\n❌ Invalid feature name: "${featureName}"`));
       console.error(chalk.gray('Use kebab-case: lowercase letters, digits and hyphens (e.g. "user-onboarding")\n'));
@@ -97,14 +69,12 @@ export async function deleteCommand(featureName, options = {}) {
       process.exit(1);
     }
 
-    // Read the authoritative feature.json directly (not loadState — a read that
-    // mutates state has no place inside a delete).
+    // Not loadState: a read that mutates state has no place inside a delete.
     let feature = {};
     if (existsSync(fjPath)) {
       try { feature = JSON.parse(readFileSync(fjPath, 'utf8')); } catch { feature = {}; }
     }
 
-    // Precondition: no approved gate (real work) unless --force.
     const approved = approvedGates(feature);
     if (approved.length && !options.force) {
       console.error(chalk.red(`\n❌ "${featureName}" has approved gate(s): ${approved.join(', ')}.`));
@@ -113,14 +83,8 @@ 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.
+    // A live worktree owns the real state; deleting the root registration would orphan it. A distinct
+    // consent from --force on purpose: --force answers a state risk, this one is a filesystem risk.
     const owner = resolveFeatureTree(featureName, cwd);
     const liveElsewhere = (owner.source === 'registry' || owner.source === 'pointer') && owner.tree;
     if (liveElsewhere) {
@@ -141,14 +105,9 @@ export async function deleteCommand(featureName, options = {}) {
         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`.
+      // PROVE-or-DECLINE: a refusal here must leave everything untouched.
       const root = resolvePrimaryRoot(cwd);
-      // The feature's verification stack (containers, ports, volumes, stamp)
-      // comes down BEFORE its worktree: the compose file and the bind mount
-      // live there, and a deleted feature has nothing to keep a volume for.
-      // Fail-open by contract — a stubborn container never blocks the delete.
+      // The stack comes down BEFORE the worktree, where its compose file and bind mount live. Fail-open.
       try {
         tearDownFeatureStack(featureName, { root, worktreePath: owner.tree, volumes: true });
       } catch { /* fail-open */ }
@@ -166,15 +125,11 @@ export async function deleteCommand(featureName, options = {}) {
         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) {
-      // Soft delete: move to .morph/archive with status "abandoned".
       const archiveDir = join(cwd, '.morph', 'archive');
       const archivePath = join(archiveDir, featureName);
       if (existsSync(archivePath)) {
@@ -209,7 +164,6 @@ export async function deleteCommand(featureName, options = {}) {
       process.exit(0);
     }
 
-    // Hard delete: remove the folder (git-aware), then drop from index.
     let staged = false;
     if (useGit) {
       try {
@@ -218,13 +172,7 @@ export async function deleteCommand(featureName, options = {}) {
       } catch {
         // 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 (2-plan/ 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.
+      // `git rm` only removes tracked files: scaffolded empty phase folders survive it.
       if (existsSync(featuresPath)) rmSync(featuresPath, { recursive: true, force: true });
       try { execSync(`git add -A "${featuresPath}"`, { cwd, stdio: 'pipe' }); staged = true; } catch { /* not fatal */ }
     } else {