@polymorphism-tech/morph-spec 8.21.0 → 8.23.0

package/src/commands/state/finish.js

@@ -13,6 +13,11 @@ import {
 } from '../project/worktree.js';
 import { detectDefaultBranch, hasOriginRemote } from '../../lib/git/default-branch.js';
 import { releaseClaim } from '../../../framework/hooks/shared/claim-registry.js';
+import {
+  composeProjectName,
+  resolveComposeFile,
+  tearDownStack,
+} from '../../../framework/hooks/shared/e2e-check.js';
 import { runArchive } from './archive.js';
 
 /** workType → conventional-commit type. `hotfix` IS a fix; anything else is a chore. */
@@ -85,12 +90,20 @@ export async function finishCommand(feature, options = {}) {
   // working on it (B1). Released on EVERY success path — hooking it into emit
   // is the single point that covers merge/PR/--keep alike. Fail-open: a claim
   // that outlives its feature only expires on its own TTL.
+  //
+  // The e2e stack rides along for the same reason: `morph-spec verify` leaves it
+  // UP on purpose (cold-starting a container per task is what makes the loop
+  // unusable), so something has to be the one place that reclaims the
+  // containers and their ports when the feature closes. Best-effort by
+  // contract — a stack that refuses to come down must never fail a finish that
+  // already merged.
   const emit = (obj) => {
     if (obj?.finished === true) {
       try {
         const common = execFileSync('git', ['rev-parse', '--git-common-dir'], { cwd: root, stdio: 'pipe' }).toString().trim();
         if (common) releaseClaim(feature, { gitCommonDir: resolve(root, common) });
       } catch { /* fail-open */ }
+      tearDownE2eStack(feature, root);
     }
     console.log(JSON.stringify(obj));
   };
@@ -392,12 +405,17 @@ async function integratePr({ emit, root, feature, expectedBranch, defaultBranch,
 // ── output helpers ────────────────────────────────────────────────────────
 
 /**
- * Report the use cases the archive promoted into `.morph/specs/usecases/`.
- * Absent when nothing was promoted, so a feature with no use cases keeps the
- * exact output shape it had before this existed.
+ * Report the use cases the archive promoted into `.morph/specs/usecases/`, and
+ * any that were REFUSED for a numbering collision (`ucCollisions` — see
+ * `usecase-promoter.js`'s reservation-backed guard). Both absent when there is
+ * nothing to report, so a feature with no use cases keeps the exact output
+ * shape it had before either existed.
  */
 function promotedNote(arch) {
-  return arch?.promotedUseCases?.length ? { promotedUseCases: arch.promotedUseCases } : {};
+  return {
+    ...(arch?.promotedUseCases?.length ? { promotedUseCases: arch.promotedUseCases } : {}),
+    ...(arch?.refusedUseCases?.length ? { ucCollisions: arch.refusedUseCases } : {}),
+  };
 }
 
 function mergeOutput({ feature, branch, worktreePath, teardown, shedBackup }) {
@@ -502,6 +520,31 @@ function readFeatureJson(cwd, feature) {
   }
 }
 
+/**
+ * Reclaim the feature's verification stack, if the project has one.
+ *
+ * Runs from the ROOT rather than the worktree: by the time a finish emits
+ * success the worktree may already be gone, and the compose file is versioned
+ * so the root's copy is equivalent. Entirely fail-open — no compose, no docker,
+ * or a stubborn container are all non-events here.
+ */
+function tearDownE2eStack(feature, root) {
+  try {
+    const config = JSON.parse(
+      readFileSync(join(root, '.morph', 'config', 'config.json'), 'utf8').replace(/^/, '')
+    );
+    const composeFile = resolveComposeFile(root, config);
+    if (!composeFile) return;
+
+    const projectName = composeProjectName(feature);
+    tearDownStack(root, {
+      composeFile,
+      projectName,
+      env: { COMPOSE_PROJECT_NAME: projectName },
+    });
+  } catch { /* fail-open — teardown must never fail a completed finish */ }
+}
+
 /** Drop a feature from the thin, gitignored root index (never via saveState). */
 function dropFromRootIndex(root, feature) {
   const rootPath = join(root, '.morph', 'state.json');

package/src/commands/state/handoff.js

@@ -6,8 +6,9 @@
  * worktree session, a resumed session after a phase transition). The handoff
  * is the sanctioned way to carry context across: derived, regenerable, and
  * pointer-based (see handoff-generator.js). This command is also called
- * in-process by `worktree setup`, `create --worktree` and `advance` — the CLI
- * surface exists for the LLM/user to refresh the document on demand.
+ * in-process by `worktree setup`, `create --worktree`, `advance` and
+ * `approve` — the CLI surface exists for the LLM/user to refresh the
+ * document on demand.
  */
 
 import chalk from 'chalk';

package/src/commands/state/usecase.js

@@ -0,0 +1,77 @@
+/**
+ * `morph-spec usecase reserve [--count <n>] [--feature <name>] [--json]` —
+ * atomically mint the next N `UC-{nn}` numbers, shared across every worktree
+ * of this repo. See `usecase-registry.js` for why this exists (worktrees only
+ * ever see their own tree, so an independent max+1 scan collides).
+ *
+ * `--feature` is more than an audit label: `usecase-promoter.js`'s collision
+ * guard uses the reservation record to tell a legitimate cross-feature
+ * correction (never reserved — reusing a published number by design) from an
+ * accidental collision (both features reserved the same id). Passing it is
+ * how `morph-plan` gets that protection; omitting it degrades to "reserved,
+ * no owner recorded" — still collision-free, just unable to name the
+ * conflicting feature if one ever surfaces.
+ */
+
+import chalk from 'chalk';
+import { existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { resolveGitCommonDir } from '../../../framework/hooks/shared/git-paths.js';
+import { reserveUseCases } from '../../lib/specs/usecase-registry.js';
+
+/**
+ * Best-effort feature-name inference when `--feature` is omitted: only when
+ * exactly one active feature exists is the guess unambiguous. Anything else
+ * (zero, or more than one) is left null rather than guessed wrong — a wrong
+ * guess would poison the collision guard's provenance record.
+ */
+function inferActiveFeature(cwd) {
+  const featuresDir = join(cwd, '.morph', 'features');
+  try {
+    if (!existsSync(featuresDir)) return null;
+    const entries = readdirSync(featuresDir, { withFileTypes: true }).filter((e) => e.isDirectory());
+    return entries.length === 1 ? entries[0].name : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {{ count?: string, feature?: string, json?: boolean, cwd?: string }} [options]
+ */
+export function usecaseReserveCommand(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const count = Number.parseInt(options.count, 10);
+  const n = Number.isInteger(count) && count > 0 ? count : 1;
+  const feature = options.feature || inferActiveFeature(cwd) || null;
+
+  let gitCommonDir = null;
+  try { gitCommonDir = resolveGitCommonDir(cwd); } catch { gitCommonDir = null; }
+
+  let result;
+  try {
+    result = reserveUseCases(cwd, { feature, count: n, gitCommonDir });
+  } catch (error) {
+    if (options.json) {
+      console.log(JSON.stringify({ reserved: false, error: error.message }));
+      process.exit(1);
+    }
+    console.error(chalk.red(`\n❌ ${error.message}\n`));
+    process.exit(1);
+  }
+
+  const warning = gitCommonDir
+    ? null
+    : 'projeto fora de um repositório git — numeração protegida só localmente; paralelismo entre worktrees NÃO está garantido.';
+
+  if (options.json) {
+    console.log(JSON.stringify({ reserved: true, ...result, feature, warning }));
+    process.exit(0);
+  }
+
+  console.log(chalk.green(`\n✅ Reservado: ${result.numbers.join(' ')}`));
+  if (feature) console.log(chalk.gray(`   feature: ${feature}`));
+  if (warning) console.log(chalk.yellow(`⚠️  ${warning}\n`));
+  else console.log('');
+  process.exit(0);
+}

package/src/commands/validation/validate-feature.js

@@ -80,7 +80,7 @@ const OUTPUT_SECTIONS = {
     ],
   },
   // morph-plan (mandate.md) emits: Stack, Standards obrigatórios,
-  // Patterns proibidos, Checklist de done.
+  // Patterns proibidos, Verificação de runtime, Checklist de done.
   'mandate.md': {
     required: [
       'Stack',
@@ -89,6 +89,12 @@ const OUTPUT_SECTIONS = {
     ],
     recommended: [
       ['Patterns proibidos', 'Padrões proibidos', 'Padroes proibidos', 'Forbidden Patterns', 'Forbidden', 'Proibido'],
+      // Recommended rather than required on purpose: mandate.md freezes after
+      // Gate 2 (protect-spec-files blocks Write AND Edit), so promoting this to
+      // `required` would fail every in-flight feature with no way to fix it.
+      // New mandates get the section from morph-plan §4; the enforcement that
+      // actually matters is verify's e2e node, not this heading check.
+      ['Verificação de runtime', 'Verificacao de runtime', 'Runtime', 'E2E'],
     ],
     optional: [
       ['Riscos', 'Risks'],

package/src/commands/validation/verify.js

@@ -37,6 +37,10 @@ function formatVerifyResult(result) {
       detail = node.reason || '';
     } else if (name === 'validators' && node.score != null) {
       detail = `score ${node.score}/10`;
+    } else if (node.reason) {
+      // A green e2e still carries meaning worth showing: smoke-only vs specs,
+      // warm reuse vs rebuild. Without it, "pass" hides how much was proven.
+      detail = `${node.durationMs}ms — ${node.reason}`;
     } else {
       detail = `${node.durationMs}ms`;
     }
@@ -49,6 +53,12 @@ function formatVerifyResult(result) {
     for (const line of result.feedback) lines.push(`  ${line}`);
   }
 
+  if (result.traceability?.warnings?.length > 0) {
+    lines.push('');
+    lines.push(chalk.yellow('Traceability warnings (advisory — never fails verify):'));
+    for (const w of result.traceability.warnings) lines.push(`  ⚠ ${w}`);
+  }
+
   lines.push('');
   return lines.join('\n');
 }
@@ -149,6 +159,8 @@ export async function verifyCommand(featureName, taskId, options = {}) {
     timeout: options.timeout,
     skipTests: options.skipTests,
     skipBuild: options.skipBuild,
+    skipE2e: options.skipE2e,
+    freshE2e: options.freshE2e,
   });
 
   const scopeKey = taskId ? `taskVerifications.${taskId}` : 'verifications.feature';
@@ -168,6 +180,7 @@ export async function verifyCommand(featureName, taskId, options = {}) {
         build: result.nodes.build.status,
         tests: result.nodes.tests.status,
         validators: result.nodes.validators.status,
+        e2e: result.nodes.e2e.status,
       },
       score: result.nodes.validators.score ?? null,
       attempts: (prevEntry?.attempts ?? 0) + 1,

package/src/lib/e2e/compose-env.js

@@ -0,0 +1,74 @@
+/**
+ * Compose environment for the e2e stack — the port block a feature owns, plus
+ * the credentials its auth setup needs.
+ *
+ * This lives in ONE place because it has two callers that must never disagree:
+ * `morph-spec e2e up` (manual) and the `e2e` node inside `morph-spec verify`
+ * (the one that actually runs in the loop). When only the manual path built the
+ * port block, the isolation was real in the command nobody runs and absent in
+ * the one everybody runs — two worktrees would get distinct container names via
+ * COMPOSE_PROJECT_NAME and then collide on host port 3000 anyway, surfacing as
+ * "port is already allocated" and pausing a gate over an infrastructure clash
+ * rather than a defect.
+ *
+ * It sits in src/lib rather than framework/hooks/shared because it depends on
+ * env-allocator.js: hooks are installed standalone into target projects, where
+ * `src/` does not exist, so the dependency may only point this way.
+ *
+ * @module lib/e2e/compose-env
+ */
+
+import { join } from 'path';
+
+import { loadEnvFile } from '../../../framework/hooks/shared/e2e-check.js';
+import { allocateEnvBlock, resolveFleetConfig } from '../worktree/env-allocator.js';
+
+/**
+ * Build the environment a `docker compose` invocation should carry.
+ *
+ * Port variables mirror `buildEnvFileContent()` in env-allocator.js so a
+ * compose file and a `.morph/worktree.env` describe the same world: `PORT` for
+ * the web tier, `ASPNETCORE_URLS` on base+1 for a .NET backend.
+ *
+ * `PLAYWRIGHT_BASE_URL` is derived here rather than left to the spec config —
+ * the suite has to be told where the app actually landed, otherwise a feature
+ * on port 4020 gets tested against a hardcoded localhost:3000 and fails with
+ * ECONNREFUSED that looks exactly like a broken app.
+ *
+ * Fail-open throughout: with no git dir (or a corrupt registry) the caller gets
+ * default ports, which only matters when two stacks run at once.
+ *
+ * @param {object} params
+ * @param {string} params.cwd - project root
+ * @param {object|null} [params.config] - .morph/config/config.json contents
+ * @param {string} params.featureName
+ * @param {string|null} [params.gitCommonDir]
+ * @returns {Record<string,string>}
+ */
+export function buildComposeEnv({ cwd, config, featureName, gitCommonDir }) {
+  const env = {};
+
+  if (gitCommonDir) {
+    try {
+      const { basePort, blockSize } = resolveFleetConfig(cwd);
+      const block = allocateEnvBlock(featureName, { gitCommonDir, basePort, blockSize });
+
+      env.MORPH_PORT_BASE = String(block.base);
+      env.MORPH_PORT_RANGE = `${block.range[0]}-${block.range[1]}`;
+      env.PORT = String(block.base);
+      env.PLAYWRIGHT_BASE_URL = `http://localhost:${block.base}`;
+
+      if (/\bdotnet\b/i.test(String(config?.project?.stack ?? ''))) {
+        env.ASPNETCORE_URLS = `http://localhost:${block.base + 1}`;
+      }
+    } catch {
+      // No block → default ports. Surfaces later as a port conflict, never here.
+    }
+  }
+
+  // Credentials live in a gitignored env file, never in the committed config.
+  const envFile = config?.e2e?.auth?.envFile;
+  if (envFile) Object.assign(env, loadEnvFile(join(cwd, envFile)));
+
+  return env;
+}

package/src/lib/generators/handoff-generator.js

@@ -9,8 +9,8 @@
  * Deterministic by construction — everything here is derived from feature.json,
  * tasks.json, decisions.md and the worktree env manifest. The document is
  * therefore REGENERABLE (never hand-edited, never merged): `morph-spec handoff`
- * rebuilds it, and setup/create/advance regenerate it at the moments a new
- * session is most likely to pick the feature up.
+ * rebuilds it, and setup/create/advance/approve regenerate it at the moments a
+ * new session is most likely to pick the feature up.
  *
  * Every section is fail-open: a missing tasks.json or a corrupt decisions.md
  * degrades that section, never the document.

package/src/lib/specs/usecase-promoter.js

@@ -12,15 +12,29 @@
  *     as a no-op rather than an error.
  *   - **No-op without the folder.** A feature with no use cases promotes nothing.
  *   - **Idempotent.** Re-promoting the same use case rewrites the same content.
- *   - **Overwrite by ID, not by filename.** `UC-07-old-slug.md` in the archive is
- *     REPLACED by an incoming `UC-07-new-slug.md`. Keying on the filename would
- *     leave two files claiming UC-07 the first time a slug is reworded — and the
- *     `bug` work type exists precisely to correct an existing use case.
+ *   - **Overwrite by ID, not by filename — with a collision backstop.**
+ *     `UC-07-old-slug.md` in the archive is REPLACED by an incoming
+ *     `UC-07-new-slug.md`. Keying on the filename would leave two files
+ *     claiming UC-07 the first time a slug is reworded — and the `bug` work
+ *     type exists precisely to correct an existing use case, from a DIFFERENT
+ *     feature than the one that first published it, sometimes rewording the
+ *     slug in the same pass. That legitimate case is INDISTINGUISHABLE, by
+ *     filename and slug alone, from two worktrees that independently minted
+ *     the SAME number for two UNRELATED use cases (the numbering-collision bug
+ *     this backstop exists for) — a user has already lost a use case this way
+ *     in production. The one signal that tells them apart is `usecase-registry.js`'s
+ *     reservation record: a feature that REPLACES a number it never reserved is
+ *     reusing a published UC by design (the bug/update flow); a feature that
+ *     REPLACES a number it DID reserve, and finds someone ELSE'S feature already
+ *     sitting on that ID, is the collision — refuse that one specific promotion
+ *     rather than silently destroy the other feature's use case.
  */
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, rmSync } from 'fs';
-import { join } from 'path';
+import { basename, join, relative } from 'path';
 import { OUTPUT_SCHEMA } from '../../core/paths/output-schema.js';
+import { resolveGitCommonDir } from '../../../framework/hooks/shared/git-paths.js';
+import { reservationOwner } from './usecase-registry.js';
 
 const UC = OUTPUT_SCHEMA.usecases;
 const UC_FILENAME_RE = new RegExp(UC.filenamePattern);
@@ -35,38 +49,102 @@ export function useCaseId(filename) {
 }
 
 /**
- * Rewrite the frontmatter `status:` to `implemented`.
+ * Set (or replace) a single top-level frontmatter field, preserving every
+ * other line, the original EOL style, and anything after the closing `---`.
  *
- * A file with no frontmatter is copied verbatim: the use case belongs to the
- * author, and inventing a header would be a silent edit of their document.
+ * A file with no frontmatter block is returned UNCHANGED: the use case
+ * belongs to the author, and inventing a header would be a silent edit of
+ * their document.
  *
  * @param {string} content
+ * @param {string} key
+ * @param {string} value
  * @returns {string}
  */
-export function stampImplemented(content) {
+function setFrontmatterField(content, key, value) {
   const m = /^(?---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/.exec(content);
   if (!m || m.index !== 0) return content;
 
   const [full, open, body, close] = m;
   const eol = full.includes('\r\n') ? '\r\n' : '\n';
-  const statusLine = /^status:[ \t]*.*$/m;
-  const next = statusLine.test(body)
-    ? body.replace(statusLine, 'status: implemented')
-    : `${body}${eol}status: implemented`;
+  const fieldLine = new RegExp(`^${key}:[ \\t]*.*$`, 'm');
+  const next = fieldLine.test(body)
+    ? body.replace(fieldLine, `${key}: ${value}`)
+    : `${body}${eol}${key}: ${value}`;
 
   return open + next + close + content.slice(full.length);
 }
 
+/** Read a single top-level frontmatter field. `null` when absent or there is no frontmatter block. */
+function readFrontmatterField(content, key) {
+  const m = /^(?---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/.exec(content);
+  if (!m || m.index !== 0) return null;
+  const line = new RegExp(`^${key}:[ \\t]*(.+?)[ \\t]*$`, 'm').exec(m[2]);
+  return line ? line[1].trim() : null;
+}
+
+/**
+ * Rewrite the frontmatter `status:` to `implemented`.
+ *
+ * A file with no frontmatter is copied verbatim: the use case belongs to the
+ * author, and inventing a header would be a silent edit of their document.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+export function stampImplemented(content) {
+  return setFrontmatterField(content, 'status', 'implemented');
+}
+
+/**
+ * Stamp the promoting feature's name into `sourceFeature:` — the provenance
+ * record the collision guard (below) compares against a reservation to tell a
+ * legitimate cross-feature correction from an accidental numbering collision.
+ *
+ * @param {string} content
+ * @param {string} feature
+ * @returns {string}
+ */
+export function stampSourceFeature(content, feature) {
+  return setFrontmatterField(content, 'sourceFeature', feature);
+}
+
+/**
+ * Build the message for a refused promotion — named clearly enough that the
+ * next session (or human) can actually recover, not just "colisão".
+ *
+ * The recovery instruction has to be honest about WHERE the file sits: by the
+ * time this runs, `runArchive` has already moved the feature folder, and its
+ * own idempotent short-circuit (`existsSync(archivePath)`) means re-running
+ * `archive`/`finish` on this feature promotes NOTHING a second time — so
+ * "renumber and re-run finish" would be a lie. The file is wherever `srcDir`
+ * actually is (the feature's `2-plan/usecases/`, wherever that folder lives
+ * right now — pre- or post-archive, the caller decides), and recovery is
+ * either a fresh reservation + manual copy, or editing the archive in place.
+ *
+ * @returns {string}
+ */
+function collisionMessage({ id, incoming, existing, existingFeature, feature, relIncomingPath }) {
+  return `${id}: colisão de numeração — "${incoming}" (feature "${feature}") não pôde substituir "${existing}" ` +
+    `já promovido no acervo por "${existingFeature}". O arquivo continua em ${relIncomingPath}. ` +
+    'Se for um use case NOVO: renumere-o com `morph-spec usecase reserve` e promova manualmente para ' +
+    '.morph/specs/usecases/ (o finish/archive não reprocessa uma feature já arquivada). ' +
+    `Se for uma CORREÇÃO do mesmo UC publicado: edite .morph/specs/usecases/${existing} diretamente em vez de reservar um número novo.`;
+}
+
 /**
  * Copy every use case of a feature into the project's permanent archive.
  *
  * @param {string} cwd        - project root that owns `.morph/specs/`
  * @param {string} featureDir - the feature folder holding `2-plan/usecases/`
- * @returns {{ promoted: string[], replaced: string[] }} filenames, always arrays
+ * @returns {{ promoted: string[], replaced: string[], refused: Array<{id: string,
+ *   incoming: string, existing: string, existingFeature: string, message: string}> }}
+ *   filenames, always arrays
  */
 export function promoteUseCases(cwd, featureDir) {
-  const empty = { promoted: [], replaced: [] };
+  const empty = { promoted: [], replaced: [], refused: [] };
   const srcDir = join(featureDir, UC.phaseDir, UC.dirname);
+  const feature = basename(featureDir);
 
   let names;
   try {
@@ -80,6 +158,7 @@ export function promoteUseCases(cwd, featureDir) {
   const destDir = join(cwd, '.morph', 'specs', 'usecases');
   const promoted = [];
   const replaced = [];
+  const refused = [];
 
   try {
     mkdirSync(destDir, { recursive: true });
@@ -87,6 +166,11 @@ export function promoteUseCases(cwd, featureDir) {
     return empty;
   }
 
+  // Resolved ONCE per call — pure filesystem, no subprocess (git-paths.js) —
+  // and reused for every collision check below.
+  let gitCommonDir = null;
+  try { gitCommonDir = resolveGitCommonDir(cwd); } catch { gitCommonDir = null; }
+
   // Existing archive entries, indexed by use-case ID — the key the overwrite
   // rule is written against.
   const existingById = new Map();
@@ -99,22 +183,54 @@ export function promoteUseCases(cwd, featureDir) {
 
   for (const name of names) {
     try {
-      const content = stampImplemented(readFileSync(join(srcDir, name), 'utf8'));
       const id = useCaseId(name);
       const stale = id ? existingById.get(id) : null;
 
-      // Same ID under a different filename: drop the old file, or the archive
-      // would end up with two documents claiming the same UC number.
+      // Same ID under a different filename: normally the old file is dropped
+      // (a slug reword, or the `bug` flow correcting a published UC), or the
+      // archive would end up with two documents claiming the same UC number.
+      //
+      // Backstop: refuse instead when BOTH are true —
+      //   (a) THIS feature holds a reservation for `id` in usecase-registry.js
+      //       (it believes it MINTED a new number), and
+      //   (b) the archive entry already there was promoted by a DIFFERENT
+      //       feature (its stamped `sourceFeature` says so).
+      // A feature correcting a published UC never reserved that UC's number —
+      // it reused one already in the acervo — so that legitimate flow never
+      // trips this. Two features that each reserved the SAME number (the
+      // collision this exists for) always do. No reservation record at all
+      // (no git common dir, or a legacy archive entry predating this stamp) is
+      // fail-open: nothing to compare against, so nothing is refused.
       if (stale && stale !== name) {
+        let staleFeature = null;
+        try { staleFeature = readFrontmatterField(readFileSync(join(destDir, stale), 'utf8'), 'sourceFeature'); } catch { /* unreadable — no signal */ }
+        const incomingOwner = id ? reservationOwner(id, { cwd, gitCommonDir }) : null;
+
+        if (staleFeature && staleFeature !== feature && incomingOwner === feature) {
+          refused.push({
+            id,
+            incoming: name,
+            existing: stale,
+            existingFeature: staleFeature,
+            message: collisionMessage({
+              id, incoming: name, existing: stale, existingFeature: staleFeature, feature,
+              relIncomingPath: relative(cwd, join(srcDir, name)).replace(/\\/g, '/'),
+            }),
+          });
+          continue; // leave the existing archive entry untouched
+        }
+
         rmSync(join(destDir, stale), { force: true });
         replaced.push(stale);
       }
 
+      let content = stampImplemented(readFileSync(join(srcDir, name), 'utf8'));
+      content = stampSourceFeature(content, feature);
       writeFileSync(join(destDir, name), content, 'utf8');
       promoted.push(name);
       if (id) existingById.set(id, name);
     } catch { /* one unreadable use case must not sink the rest */ }
   }
 
-  return { promoted, replaced };
+  return { promoted, replaced, refused };
 }