@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

package/src/commands/scaffold/scaffold.js

@@ -1,11 +1,3 @@
-/**
- * Scaffold Command - Generate feature files from templates.
- *
- * Sub-commands:
- * - scaffold dotnet <feature> <slice-name> — VSA feature slice (.NET)
- * - scaffold nextjs <feature> — Feature page + components (Next.js)
- */
-
 import chalk from 'chalk';
 import { relative } from 'path';
 import { logger } from '../../utils/logger.js';
@@ -17,11 +9,6 @@ import {
 
 const KEBAB_REGEX = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 
-/**
- * Validate that a name is valid kebab-case.
- * @param {string} name
- * @param {string} label
- */
 function validateKebabCase(name, label) {
   if (!KEBAB_REGEX.test(name)) {
     logger.error(`Invalid ${label}: "${name}"`);
@@ -30,11 +17,6 @@ function validateKebabCase(name, label) {
   }
 }
 
-/**
- * Log the result of a scaffold operation.
- * @param {Array<{path: string, skipped: boolean}>} files
- * @param {string} outputDir
- */
 function logResult(files, outputDir) {
   let created = 0;
   let skipped = 0;
@@ -56,16 +38,12 @@ function logResult(files, outputDir) {
   logger.info(parts.join(', '));
 }
 
-/**
- * Scaffold .NET VSA feature slice.
- */
 export async function scaffoldDotnetCommand(feature, sliceName, options) {
   validateKebabCase(feature, 'feature name');
   validateKebabCase(sliceName, 'slice name');
 
   const outputDir = options.outputDir || process.cwd();
 
-  // Detect or use provided namespace
   const namespace = options.namespace || detectNamespace(outputDir);
   if (!namespace) {
     logger.error('Could not detect namespace');
@@ -100,9 +78,6 @@ export async function scaffoldDotnetCommand(feature, sliceName, options) {
   }
 }
 
-/**
- * Scaffold Next.js feature page with components and hooks.
- */
 export async function scaffoldNextjsCommand(feature, options) {
   validateKebabCase(feature, 'feature name');
 

package/src/commands/state/advance.js

@@ -14,44 +14,17 @@ import { seedDotnetBuildIgnores } from '../../lib/stack/dotnet-build-ignores.js'
 
 const FRAMEWORK_DIR = fileURLToPath(new URL('../../../framework/', import.meta.url));
 
-/**
- * `morph-spec advance <feature>` — approve the current phase's gate AND scaffold
- * the next phase's folder in one step. This is the sanctioned, one-command way
- * to move a feature forward: it removes the need to hand-edit state.json (gate)
- * AND the need to `mkdir` the next phase folder by hand. Once the gate is
- * approved, the enforce-phase-writes hook permits writing the next phase's first
- * canonical artifact (which then advances the derived phase).
- */
-
-// The gate approved when *completing* a given phase. `implement` has no gate
-// (it ends when all slices are done), so advancing from implement just
-// scaffolds the review folder.
+// `implement` has no gate: advancing from it only scaffolds the review folder.
 const PHASE_GATE = { plan: 'plan', uiux: 'uiux', review: 'review' };
 
-// The next phase folder to scaffold when advancing FROM a given phase. The
-// default forward path skips the optional design phase (plan → implement); pass
-// --design to take the uiux branch (plan → 1-design).
 const NEXT_PHASE_DIR = {
   plan: '3-implement',
   uiux: '3-implement',
   implement: '4-review',
 };
 
-/**
- * The canonical artifacts the phase being CLOSED owes, per
- * `framework/phases.json → phases[phase].requiredOutputs`, resolved to real
- * filenames through OUTPUT_SCHEMA.
- *
- * Data-driven on purpose: adding an artifact to a phase must not need a code
- * change here, and the list must never drift from the phase definition.
- * Fail-open — an unreadable phases.json/OUTPUT_SCHEMA yields an empty list, so
- * a broken install degrades to today's behaviour instead of blocking every
- * advance.
- *
- * @param {string} phase
- * @param {string} featurePath
- * @returns {string[]} relative paths of the MISSING required artifacts
- */
+// Data-driven from phases.json so the list never drifts from the phase definition. Fail-open:
+// an unreadable phases.json yields an empty list instead of blocking every advance.
 function missingPhaseArtifacts(phase, featurePath) {
   try {
     const phasesPath = join(FRAMEWORK_DIR, 'phases.json');
@@ -59,8 +32,7 @@ function missingPhaseArtifacts(phase, featurePath) {
     const required = phases[phase]?.requiredOutputs || [];
     const missing = [];
     for (const outputType of required) {
-      // requiredOutputs already carries OUTPUT_SCHEMA's camelCase keys — an
-      // unknown key is skipped rather than guessed at.
+      // An unknown key is skipped rather than guessed at.
       const entry = OUTPUT_SCHEMA[outputType];
       if (!entry?.filename || !entry?.phaseDir) continue;
       const rel = `${entry.phaseDir}/${entry.filename}`;
@@ -79,20 +51,8 @@ function unfinishedSliceReports(featurePath) {
   return progress.slices.filter((s) => s.status !== 'feito').map((s) => `3-implement/reports/${s.id}.md`);
 }
 
-/**
- * When a required artifact is absent HERE, check whether it exists in the
- * worktree that owns this feature. `feature.json` travels committed on
- * `morph/{feature}`, so a feature developed in a worktree has its artifacts
- * there and only a scaffold in the primary root — running `advance` from the
- * root then demanded a file that already exists, one directory over.
- *
- * Message-only: this never reads state for a decision and never writes across
- * trees. It replaces a misleading error with an accurate one.
- *
- * Fail-open — no git, no worktree, or any error yields null (today's message).
- *
- * @returns {Promise<{path: string, branch: string|null, present: string[]}|null>}
- */
+// Message-only and fail-open: names the worktree that holds the artifacts instead of demanding
+// a file that exists one directory over. Never writes across trees.
 async function artifactsLiveInWorktree(featureName, missing) {
   try {
     const { findWorktreeForFeature } = await import('../project/worktree.js');
@@ -107,7 +67,6 @@ async function artifactsLiveInWorktree(featureName, missing) {
   }
 }
 
-/** Resolve who approved, honestly (mirrors approve.js — no fake human signatures). */
 function resolveApprovedBy(options) {
   if (options.approver) return options.approver;
   if (options.mode === 'auto') return 'auto';
@@ -133,9 +92,7 @@ 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).
+    // A live worktree elsewhere owns the state: never stamp a gate onto the root skeleton.
     const owner = assertOwnerTree(featureName, process.cwd());
     if (owner.blocked) {
       for (const { tone, text } of ownerTreeRefusalLines(featureName, owner.tree, owner.branch, `morph-spec advance ${featureName}`)) {
@@ -169,17 +126,10 @@ export async function advanceCommand(featureName, options = {}) {
       return;
     }
 
-    // Phase-exit artifact check: a phase transition must not step over what the
-    // phase it is CLOSING owes. `implement` has no gate, so this is the only
-    // thing that keeps a feature with unfinished slice reports out of review.
-    //
-    // `--force` bypasses (same deliberate-recovery role it already plays for
-    // gate order) but still names what was skipped — a silent bypass would be
-    // the defect again.
+    // `implement` has no gate, so this is what keeps unfinished slice reports out of review.
+    // `--force` bypasses it but still names what was skipped.
     const missingArtifacts = missingPhaseArtifacts(phase, featurePath);
     if (missingArtifacts.length && !options.force) {
-      // Divergence, not absence: name the tree that actually holds the work
-      // instead of asking for a file that exists in it.
       const elsewhere = await artifactsLiveInWorktree(featureName, missingArtifacts);
       if (elsewhere) {
         console.error(chalk.red(`\n❌ A fase "${phase}" de "${featureName}" não pode ser encerrada A PARTIR DESTA ÁRVORE.`));
@@ -199,16 +149,10 @@ export async function advanceCommand(featureName, options = {}) {
       process.exit(1);
     }
 
-    // 1) Approve the gate that completes the current phase.
     const gate = PHASE_GATE[phase];
     const approvedBy = resolveApprovedBy(options);
 
-    // Gate monotonicity (mirrors approve.js): advance is a gate write-path too,
-    // so it must not stamp gate N while a predecessor is pending. In the
-    // sanctioned flow advance is always in-order, but an anomalous filesystem
-    // state — e.g. 1-design/design-system.md present without the plan gate —
-    // would otherwise let advance deepen the violation by stamping uiux.
-    // Escape via --force for deliberate recovery.
+    // Gate monotonicity: never stamp gate N while a predecessor is pending (`--force` to recover).
     if (gate) {
       const unmet = unmetPrereqs(gate, feature.approvalGates);
       if (unmet.length && !options.force) {
@@ -218,19 +162,8 @@ export async function advanceCommand(featureName, options = {}) {
       }
     }
 
-    // Gate idempotency (F15): `setApprovalGate` REPLACES the gate object whole
-    // (state-manager.js), so re-writing an already-approved gate does not
-    // refresh it — it destroys `approvedBy`, `timestamp`, `notes` and
-    // `selfAssessed` in one assignment. And `resolveApprovedBy` above answers
-    // "auto" in every headless context, so `approve f plan --approver
-    // lucas` followed by `advance f` used to rewrite a human's signature as
-    // "auto" — the one stamp the charter forbids on a human-approved gate.
-    // The state-sync hook already carries exactly this guard; `advance`, the
-    // other gate write-path, simply never got it.
-    //
-    // It skips ONLY the write. The scaffold and the handoff below still run,
-    // so re-running `advance` after a failed scaffold keeps working — the
-    // reason this is a guard and not an abort.
+    // `setApprovalGate` replaces the gate whole: rewriting an approved gate would turn a human
+    // signature into "auto". Skips ONLY the write, so the scaffold and handoff below still run.
     const priorGate = gate ? feature.approvalGates?.[gate] : null;
     const alreadyApproved = priorGate?.approved === true;
 
@@ -250,7 +183,6 @@ export async function advanceCommand(featureName, options = {}) {
       });
     }
 
-    // 2) Scaffold the next phase folder so the agent can write its first artifact.
     let nextDir = NEXT_PHASE_DIR[phase];
     if (phase === 'plan' && options.design) nextDir = '1-design';
     if (nextDir) {
@@ -260,9 +192,7 @@ export async function advanceCommand(featureName, options = {}) {
     if (nextDir === '1-design') reportDesignSeed(seedDesignArtifacts(featureName, process.cwd()));
     if (phase === 'plan') reportDotnetIgnores(seedDotnetBuildIgnores(process.cwd(), { featureName }));
 
-    // Fleet handoff: a phase transition is exactly when a session hands the
-    // feature over (to a new instance, or to itself after /compact) — refresh
-    // the derived handoff.md so the next reader starts from the new phase.
+    // A phase transition is when a session hands the feature over: refresh handoff.md.
     try {
       const { writeHandoff } = await import('../../lib/generators/handoff-generator.js');
       writeHandoff(featureName, process.cwd());
@@ -276,8 +206,7 @@ export async function advanceCommand(featureName, options = {}) {
       const by = options.force ? '--force' : `aprovado por ${approvedBy}`;
       console.log(chalk.yellow(`   ⚠️  ${by}: avançou com o ${checklistBlock}.`));
     }
-    // Report what actually happened: claiming "approved (auto)" when nothing
-    // was written is how the destroyed signature stayed invisible.
+    // Never claim "approved (auto)" when nothing was written.
     if (gate && alreadyApproved) {
       console.log(chalk.gray(`   Gate "${gate}" was already approved (${priorGate.approvedBy || 'unknown'}) — approval preserved, nothing re-written.`));
     } else if (gate) {

package/src/commands/state/approve.js

@@ -19,14 +19,8 @@ export { REVIEWED_SHA_TOKEN };
 
 const SIGNED_OFF = { required: [], reports: {}, checks: { status: 'ok', total: 0, missing: [], notProven: [] } };
 
-/**
- * Do the review reports still describe the current tree? Every report present
- * is compared; the worst answer wins.
- *
- * @param {ReturnType<typeof reviewReports>} reports
- * @returns {{ status: 'ok'|'stale'|'unstamped'|'skip', file?: string, reviewed?: string, head?: string, ahead?: number }}
- *   `skip`: no verifier report or no git repo. Never a false refusal.
- */
+// The worst answer across every report present wins. `skip` (no verifier report, no git) never
+// refuses falsely.
 function reviewStaleness(reports) {
   if (reports.verifier.status === 'missing') return { status: 'skip' };
   const cwd = process.cwd();
@@ -64,9 +58,6 @@ function reviewStaleness(reports) {
   return unstamped ?? { status: 'ok', head };
 }
 
-/**
- * Unapprove action function - Revoke a previously approved gate
- */
 export async function unapproveCommand(featureName, gateName, options = {}) {
   try {
     if (!VALID_GATES.includes(gateName)) {
@@ -95,8 +86,7 @@ export async function unapproveCommand(featureName, gateName, options = {}) {
       return;
     }
 
-    // Same honesty rule as approveCommand: don't pretend a human revoked
-    // the gate when there's no interactive shell behind the invocation.
+    // Don't pretend a human revoked the gate without an interactive shell behind the call.
     let revokedBy;
     if (options.revoker) {
       revokedBy = options.revoker;
@@ -123,44 +113,25 @@ export async function unapproveCommand(featureName, gateName, options = {}) {
   }
 }
 
-/**
- * Approval Commands - Manage approval gates for MORPH workflow
- *
- * Commands:
- * - approve: Mark a gate as approved
- * - unapprove: Revoke a gate approval
- * - approval-status: Show approval status for all gates
- */
-
 const program = new Command();
 
-/**
- * Valid approval gate names
- */
 const VALID_GATES = ['plan', 'uiux', 'review'];
 
-/**
- * Approve action function - Mark a gate as approved
- */
 export async function approveCommand(featureName, gateName, options = {}) {
   try {
-    // Validate gate name
     if (!VALID_GATES.includes(gateName)) {
       console.error(chalk.red(`\n❌ Invalid gate: ${gateName}`));
       console.log(chalk.gray(`Valid gates: ${VALID_GATES.join(', ')}\n`));
       process.exit(1);
     }
 
-    // Get feature state
     const feature = getFeature(featureName);
     if (!feature) {
       console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
       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).
+    // A live worktree elsewhere owns the state: never stamp a gate onto the root skeleton.
     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}`)) {
@@ -169,27 +140,18 @@ export async function approveCommand(featureName, gateName, options = {}) {
       process.exit(1);
     }
 
-    // Check if already approved
     const currentStatus = getApprovalGate(featureName, gateName);
     if (currentStatus?.approved) {
       console.log(chalk.yellow(`\n⚠️  Gate "${gateName}" is already approved`));
       console.log(chalk.gray(`Approved at: ${currentStatus.timestamp}`));
       console.log(chalk.gray(`Approved by: ${currentStatus.approvedBy || 'Unknown'}`));
-      // This early-out is a no-op that still exits 0 — deliberate, and
-      // `--force` does NOT cover it (that flag only covers gate ORDER). A
-      // caller who meant to re-approve therefore reads success and is left
-      // with nowhere to go. The way out already exists as `unapprove`; the
-      // message just never named it. Naming it is the whole fix (no new flag).
+      // `--force` does not cover this no-op (it only covers gate ORDER), so name the way out.
       console.log(chalk.gray(`To approve it again, revoke it first: morph-spec unapprove ${featureName} ${gateName}\n`));
       if (gateName === 'plan') reportDotnetIgnores(seedDotnetBuildIgnores(process.cwd(), { featureName }));
       return;
     }
 
-    // Gate monotonicity: a gate may only be approved once its predecessors are
-    // approved (plan → review; uiux requires plan). Prevents the shape of a
-    // review approved with the plan still pending. Policy-stamped
-    // gates count as approved, so chore/hotfix satisfy prereqs naturally.
-    // Escape via --force for deliberate recovery.
+    // Gate monotonicity: predecessors first; policy stamps count (`--force` to recover).
     const unmet = unmetPrereqs(gateName, feature.approvalGates);
     if (unmet.length && !options.force) {
       console.error(chalk.red(`\n❌ Cannot approve "${gateName}" — prerequisite gate(s) not approved: ${unmet.join(', ')}.`));
@@ -197,22 +159,8 @@ export async function approveCommand(featureName, gateName, options = {}) {
       process.exit(1);
     }
 
-    // Resolve who approved BEFORE the hotfix backstop — the backstop gates on
-    // the resolved signature, not the raw --mode string (see below).
-    //
-    // approvedBy resolution (most explicit wins):
-    //   1. --approver flag (CLI caller signalled who approved)
-    //   2. --mode auto  → "auto" (intentionally non-human signature)
-    //   3. interactive shell (TTY on stdin) → $USER / $USERNAME (a real
-    //      human is at the terminal; their name is the honest answer)
-    //   4. non-interactive (no TTY) → "auto"
-    //
-    // The TTY check exists because morph-spec is increasingly invoked
-    // from headless contexts (claude -p subprocesses, CI, the
-    // morph-e2e-tester). Stamping the host's $USERNAME on a gate that
-    // no human actually approved is misleading — it lies to the audit
-    // trail. "auto" reads as what it is: a deterministic policy gate,
-    // not a human signing off.
+    // Resolved BEFORE the hotfix backstop, which gates on the signature. Without a TTY the answer
+    // is "auto": stamping $USERNAME on a gate no human approved lies to the audit trail.
     let approvedBy;
     if (options.approver) {
       approvedBy = options.approver;
@@ -230,16 +178,8 @@ export async function approveCommand(featureName, gateName, options = {}) {
       process.exit(1);
     }
 
-    // Gate 3 staleness backstop (D1): a review reviews a TREE, and the tree
-    // moves. Observed: a review report written at b30ac6e, then T3 landed and
-    // inverted the default of a business rule; the report stayed in the repo
-    // claiming 976/976 tests (they were 982) and never mentioning T3. Nothing
-    // detected that the review artifact had fallen behind the code it reviews.
-    //
-    // The report stamps the SHA it reviewed; approval compares it with HEAD.
-    // A stamp that is BEHIND HEAD refuses. A MISSING stamp only warns — reports
-    // written before this existed must not brick a legacy feature — but the
-    // warning names the exact token to add, so it teaches instead of nagging.
+    // A review reviews a TREE: a `Reviewed-SHA` behind HEAD refuses. A missing stamp only warns,
+    // naming the token to add, so a legacy report does not brick the feature.
     const reports = gateName === 'review' ? reviewReports(process.cwd(), featureName) : null;
     if (gateName === 'review') {
       const stale = reviewStaleness(reports);
@@ -290,9 +230,8 @@ export async function approveCommand(featureName, gateName, options = {}) {
           selfAssessed = true;
         }
 
-        // Sem gate-check prévio não há `gateDecisions.review` para o backstop acima morder; em
-        // campo, ships passaram assim com verify vermelho ou ausente. A auto-aprovação recalcula
-        // a decisão pela MESMA régua do gate-check. --self-assessed já dispensou os relatórios.
+        // Sem gate-check prévio não há `gateDecisions.review` para o backstop morder: a auto-aprovação
+        // recalcula a decisão pela MESMA régua do gate-check. --self-assessed já dispensou os relatórios.
         if (approvedBy === 'auto') {
           const signals = collectSignals(featureName, feature, process.cwd(), 'review');
           if (selfAssessed) signals.reviewReports = SIGNED_OFF;
@@ -321,12 +260,7 @@ export async function approveCommand(featureName, gateName, options = {}) {
       ...(selfAssessed ? { selfAssessed: true } : {}),
     });
 
-    // Fleet handoff (mirrors advance.js): approving a gate is exactly when a
-    // feature hands over between sessions too — `approve` is the real path
-    // the plan gate took in the field (`approve <f> plan --mode auto`), not just
-    // `advance`, so a handoff.md left stale after approve was the common
-    // case, not the edge case. Same helper, same fail-open contract: a
-    // regeneration failure must never fail the approval itself.
+    // Approving is a session handoff too; a regeneration failure must never fail the approval.
     try {
       const { writeHandoff } = await import('../../lib/generators/handoff-generator.js');
       writeHandoff(featureName, process.cwd());
@@ -347,28 +281,20 @@ export async function approveCommand(featureName, gateName, options = {}) {
   }
 }
 
-/**
- * Approve command - Mark a gate as approved
- */
 program
   .command('approve <feature> <gate>')
   .description('Approve a phase gate to allow workflow progression')
   .action(approveCommand);
 
-/**
- * Approval status action function - Show all gates and their status
- */
 export async function approvalStatusCommand(featureName, options = {}) {
   try {
-    // Get feature state
     const feature = getFeature(featureName);
     if (!feature) {
       console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
       process.exit(1);
     }
 
-    // v5 removed the stored feature.phase — derive it from the filesystem +
-    // approved gates (same as `morph-spec status`), never print "unknown".
+    // Phase derived from the filesystem + approved gates, never "unknown".
     const featurePath = join(process.cwd(), '.morph', 'features', featureName);
     const phase = feature.phase || derivePhase(featurePath);
 
@@ -377,7 +303,6 @@ export async function approvalStatusCommand(featureName, options = {}) {
     const uiuxGate = getApprovalGate(featureName, 'uiux');
     const uiuxTaken = uiuxGate?.approved === true || existsSync(join(featurePath, '1-design'));
 
-    // JSON output
     if (options.json) {
       const status = {
         feature: featureName,
@@ -398,11 +323,9 @@ export async function approvalStatusCommand(featureName, options = {}) {
     console.log(chalk.bold(`\n📋 Approval Status for: ${featureName}`));
     console.log('━'.repeat(60));
 
-    // Show current phase
     console.log(chalk.cyan(`\nCurrent Phase: ${phase}`));
     console.log(chalk.gray(`Feature Status: ${feature.status || 'unknown'}\n`));
 
-    // Show each gate
     console.log(chalk.bold('Approval Gates:'));
 
     for (const gateName of VALID_GATES) {
@@ -444,7 +367,6 @@ export async function approvalStatusCommand(featureName, options = {}) {
       }
     }
 
-    // Show approval history if available
     const history = getApprovalHistory(featureName);
     if (history && history.length > 0) {
       console.log(chalk.bold('\nApproval History:'));
@@ -462,16 +384,12 @@ export async function approvalStatusCommand(featureName, options = {}) {
   }
 }
 
-/**
- * Approval status command - Show all gates and their status
- */
 program
   .command('approval-status <feature>')
   .alias('status')
   .description('Show approval status for all gates')
   .action(approvalStatusCommand);
 
-// Only parse if run directly (not imported as module)
 if (import.meta.url === `file://${process.argv[1]}`) {
   if (process.argv.length > 2) {
     program.parse(process.argv);

package/src/commands/state/archive.js

@@ -5,7 +5,6 @@ import { execFileSync } from 'child_process';
 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);
@@ -14,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 {
@@ -39,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'));
@@ -51,30 +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,
- *   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' };
   }
@@ -88,9 +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"; an ADR
-  // index update that degraded fail-open is therefore not retried.
+  // 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 };
   }
@@ -99,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' };
@@ -108,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) {
@@ -128,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 {
@@ -144,9 +104,7 @@ export function runArchive(feature, opts = {}) {
     } catch { /* non-fatal — the move is what matters */ }
   }
 
-  // 3) The closing plan's project-wide ADRs enter the index and the ones it
-  //    revokes leave it, in the same scoped commit below. Fail-open: the index
-  //    must never block archiving.
+  // Fail-open: the ADR index must never block archiving.
   let adrIndex = { changed: false, added: [], revoked: [], narrowed: [], problems: [] };
   try {
     adrIndex = updateAdrIndex(cwd, archivePath);
@@ -155,12 +113,8 @@ export function runArchive(feature, opts = {}) {
     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 ADR index joins only when it 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 = [
@@ -174,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 {
@@ -197,11 +149,7 @@ export function runArchive(feature, opts = {}) {
   };
 }
 
-/**
- * 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, {