@opengsd/gsd-core 1.15.0 → 1.17.0

package/scripts/lint-planning-document-positive-control.cjs

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * PlanningDoc positive-control lint (ADR-4910 §7, "Every parser ships a
+ * positive control per accepted grammar", epic #4906 Phase 6 / #5007).
+ *
+ * `NodeKind` (`src/planning-document.cts`, compiled to
+ * `gsd-core/bin/lib/planning-document.cjs`) is the single-source union naming
+ * every grammar `parsePlanningDoc` accepts: `frontmatter` / `section` /
+ * `boldField` / `table` / `checklist`. This lint asserts one positive-control
+ * fixture per declared grammar, under `tests/fixtures/planning-document/`,
+ * each of which must round-trip through the real `parsePlanningDoc` and
+ * actually produce a node of that kind — not merely "the parser didn't
+ * throw". Per CONTRIBUTING.md's fixture-provenance rule (#2371), every
+ * fixture here is authored independently, never copied from
+ * `src/planning-document.cts`'s own docstring examples or from
+ * `tests/planning-document.test.cjs`'s existing fixtures.
+ *
+ * The `accepted` set (`NodeKind`) is a TypeScript-only type, erased by
+ * compilation — it carries no runtime value in the built `.cjs` seam. So this
+ * lint reads it directly out of `src/planning-document.cts`'s own source
+ * text (the `export type NodeKind = ...;` declaration), the same way
+ * `scripts/lint-phase-id-drift.cjs` reads source text for its own literal
+ * checks — NOT by importing a type, which is impossible from a `.cjs`
+ * script. This is what makes the guarantee live: a NEW grammar kind added to
+ * `NodeKind` with no registry entry fails this lint immediately, before any
+ * fixture is even written, closing the "parser without one fails the build"
+ * requirement in ADR-4910 §7.
+ *
+ * Modeled on `scripts/lint-table-schema-drift.cjs`'s registry/exit-code/
+ * error-message structure — a hardcoded `{grammar -> fixture file}` map,
+ * exit 0 clean / exit 1 with a per-entry reason on drift, wired into
+ * `lint:ci` — but the ASSERTION is stricter than that script's verbatim-
+ * substring check: proof the grammar is genuinely *accepted* (the fixture
+ * parses without error and yields a node of that kind), per ADR-4910 §7's
+ * own text, not just "a string appears somewhere".
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const PLANNING_DOCUMENT_SRC = path.join('src', 'planning-document.cts');
+const PLANNING_DOCUMENT_LIB = path.join('gsd-core', 'bin', 'lib', 'planning-document.cjs');
+const FIXTURE_DIR = path.join('tests', 'fixtures', 'planning-document');
+
+// grammar kind (must match a `NodeKind` union member verbatim) -> the ONE
+// canonical positive-control fixture file (relative to FIXTURE_DIR) that
+// proves that grammar is accepted (ADR-4910 §7).
+const POSITIVE_CONTROL_REGISTRY = {
+  frontmatter: 'frontmatter.md',
+  section: 'section.md',
+  boldField: 'boldfield.md',
+  table: 'table.md',
+  checklist: 'checklist.md',
+};
+
+// Any real entry from `PLANNING_ARTIFACTS` satisfies `parsePlanningDoc`'s
+// artifact-kind gate equally — the specific name does not affect which
+// grammars a fixture's BODY is recognised as containing.
+const FIXTURE_ARTIFACT_NAME = 'ROADMAP.md';
+
+// Test-only env var name. `resolveRegistry` below JSON-parses this (when set)
+// and shallow-merges it over `POSITIVE_CONTROL_REGISTRY`, so a test can spawn
+// THIS SAME, otherwise-unmodified, script file as a real child process
+// against a deliberately broken registry entry (a missing entry, or one
+// pointed at a nonexistent fixture) — proving the lint genuinely fails the
+// build, per ADR-4910 §7's "a parser without one fails the build" guarantee
+// — without ever touching the real registry or fixture files.
+//
+// This env var alone is NEVER sufficient to activate the override — a bare
+// `process.env` lookup would mean a stray, accidentally-inherited copy of
+// this variable (a leftover shell `export`, a misconfigured CI environment,
+// a compromised dependency's postinstall script) could silently swap the
+// registry in a REAL `npm run lint:ci` / `npm run lint:planning-document-
+// positive-control` invocation, with nothing in the code enforcing otherwise
+// (flagged by both the security review and the code-review Standards axis
+// on #5007 Phase 6: the old comment asserted "no real invocation ever sets
+// this" as a convention, not a fact the code made true).
+//
+// What now makes it true, by construction: `scanRepo` only reads this env
+// var via `resolveRegistry` when its caller ALSO passes `allowOverride ===
+// true`, which `main()` only does when the `--test-registry-override` CLI
+// flag is present in argv (see `parseArgs`). The test file spawns this
+// script as a real child process (`tests/helpers/process-seam.cjs`'s
+// `runNode`, over `spawnSync`) — a process boundary that can only carry data
+// in via `env`/`argv`, so the override cannot be passed as an in-process
+// function parameter here the way it can be for the pure functions below.
+// Requiring BOTH the env var and the CLI flag closes the gap: neither
+// `lint:ci` nor `lint:planning-document-positive-control` (see package.json)
+// ever passes `--test-registry-override` in their fixed argv, and unlike an
+// env var, a CLI flag is never accidentally "leaked" into a fixed npm-script
+// invocation. See tests/lint-planning-document-positive-control.test.cjs.
+const TEST_REGISTRY_OVERRIDE_ENV_VAR = 'LINT_PLANNING_DOCUMENT_POSITIVE_CONTROL_TEST_REGISTRY_OVERRIDE';
+
+/** CLI flag gate for the test-only override (see `TEST_REGISTRY_OVERRIDE_ENV_VAR`
+ * above). Must be passed explicitly in argv — never inferred from env — for
+ * `resolveRegistry`'s env-var override to be honored at all. */
+const TEST_REGISTRY_OVERRIDE_CLI_FLAG = '--test-registry-override';
+
+/** Resolve the registry to scan against: the real hardcoded registry, unless
+ * BOTH `allowOverride` is `true` (only ever set by the
+ * `--test-registry-override` CLI flag, see `TEST_REGISTRY_OVERRIDE_CLI_FLAG`)
+ * AND the test-only override env var is set and parses as JSON, in which
+ * case its keys are shallow-merged on top (see
+ * `TEST_REGISTRY_OVERRIDE_ENV_VAR`). Without `allowOverride === true`, the
+ * env var is never even read. */
+function resolveRegistry(env, allowOverride) {
+  if (!allowOverride) return POSITIVE_CONTROL_REGISTRY;
+  const override = env[TEST_REGISTRY_OVERRIDE_ENV_VAR];
+  if (!override) return POSITIVE_CONTROL_REGISTRY;
+  try {
+    const parsed = JSON.parse(override);
+    return { ...POSITIVE_CONTROL_REGISTRY, ...parsed };
+  } catch {
+    return POSITIVE_CONTROL_REGISTRY;
+  }
+}
+
+/**
+ * Extract the live `NodeKind` union members from `planning-document.cts`'s
+ * own source text — the "accepted grammars" set (ADR-4910 §4a) — read
+ * directly from source (never from the compiled seam, which erases the TS
+ * type) so a newly added grammar kind is detected even before any registry
+ * entry or fixture exists for it.
+ *
+ * Pure: takes a `readFile(relPath) -> string|null` accessor so tests can
+ * inject a scratch source file without touching the real repo tree.
+ */
+function readLiveGrammarKinds(readFile) {
+  const text = readFile(PLANNING_DOCUMENT_SRC);
+  if (text == null) {
+    return { ok: false, reason: `cannot read ${PLANNING_DOCUMENT_SRC}` };
+  }
+  const m = /export type NodeKind\s*=\s*([^;]+);/.exec(text);
+  if (!m) {
+    return {
+      ok: false,
+      reason: `could not find 'export type NodeKind = ...;' in ${PLANNING_DOCUMENT_SRC} — has the type been renamed or removed?`,
+    };
+  }
+  const kinds = [...m[1].matchAll(/'([^']+)'/g)].map((mm) => mm[1]);
+  if (kinds.length === 0) {
+    return {
+      ok: false,
+      reason: `the 'NodeKind' union in ${PLANNING_DOCUMENT_SRC} matched but contained no string-literal members`,
+    };
+  }
+  return { ok: true, value: kinds };
+}
+
+/**
+ * Pure: given the live grammar-kind list, the hardcoded registry, a
+ * `readFixture(fileName) -> string|null` accessor, the real `parsePlanningDoc`
+ * function, and the artifact name to parse fixtures as, find every gap.
+ * Returns `[{ kind, fixture?, reason }]`; empty when clean.
+ *
+ * Checks, per live grammar kind:
+ *  1. a registry entry exists at all (the §7 "parser without one fails the
+ *     build" guarantee — this fires even with an EMPTY registry);
+ *  2. the registered fixture file exists and is readable;
+ *  3. the fixture parses successfully via the real parser;
+ *  4. the parsed document actually contains a node of that kind (proof the
+ *     grammar was recognised, not just "didn't throw").
+ * Also flags a registry entry naming a grammar the parser no longer
+ * declares (a stale entry), so the registry cannot silently drift wider
+ * than the parser either.
+ */
+function findPositiveControlGaps(liveKinds, registry, readFixture, parsePlanningDocFn, artifactName) {
+  const violations = [];
+
+  for (const kind of liveKinds) {
+    const fixtureName = registry[kind];
+    if (!fixtureName) {
+      violations.push({
+        kind,
+        reason:
+          `parser declares grammar '${kind}' (NodeKind) but POSITIVE_CONTROL_REGISTRY has no entry for it — ` +
+          'add one and a matching fixture under tests/fixtures/planning-document/',
+      });
+      continue;
+    }
+
+    const content = readFixture(fixtureName);
+    if (content == null) {
+      violations.push({
+        kind,
+        fixture: fixtureName,
+        reason: `fixture file not found or unreadable: ${path.join(FIXTURE_DIR, fixtureName)}`,
+      });
+      continue;
+    }
+
+    const result = parsePlanningDocFn(content, artifactName);
+    if (!result.ok) {
+      violations.push({
+        kind,
+        fixture: fixtureName,
+        reason: `fixture failed to parse via parsePlanningDoc: ${result.reason}`,
+      });
+      continue;
+    }
+
+    const hasKind = result.value.nodes.some((n) => n.kind === kind);
+    if (!hasKind) {
+      violations.push({
+        kind,
+        fixture: fixtureName,
+        reason: `fixture parsed successfully but produced no '${kind}' node — it does not actually exercise this grammar`,
+      });
+    }
+  }
+
+  for (const kind of Object.keys(registry)) {
+    if (!liveKinds.includes(kind)) {
+      violations.push({
+        kind,
+        fixture: registry[kind],
+        reason: `registry entry names grammar '${kind}', which is not in the parser's live NodeKind union — stale entry, remove it`,
+      });
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Load the built seam and the real source/fixture tree rooted at `root`, and
+ * run `findPositiveControlGaps` against them. Returns the same shape as
+ * `findPositiveControlGaps`. If the seam hasn't been built yet, or the
+ * `NodeKind` union can't be located, reports a single actionable violation
+ * rather than throwing.
+ *
+ * `allowOverride` (default `false`) must be explicitly `true` for the
+ * test-only env-var registry override to be honored at all — see
+ * `resolveRegistry` and `TEST_REGISTRY_OVERRIDE_ENV_VAR`'s header comment.
+ */
+function scanRepo(root, env, allowOverride = false) {
+  const readFile = (relPath) => {
+    try {
+      return fs.readFileSync(path.join(root, relPath), 'utf8');
+    } catch {
+      return null;
+    }
+  };
+  const readFixture = (fileName) => readFile(path.join(FIXTURE_DIR, fileName));
+
+  const live = readLiveGrammarKinds(readFile);
+  if (!live.ok) {
+    return [{ kind: null, reason: live.reason }];
+  }
+
+  const libPath = path.join(root, PLANNING_DOCUMENT_LIB);
+  let seam;
+  try {
+    seam = require(libPath);
+  } catch (e) {
+    return [
+      {
+        kind: null,
+        reason: `cannot load the planning-document seam at ${path.relative(root, libPath)} — run 'npm run build:lib' first (${e.message})`,
+      },
+    ];
+  }
+
+  const registry = resolveRegistry(env || process.env, allowOverride);
+  return findPositiveControlGaps(live.value, registry, readFixture, seam.parsePlanningDoc, FIXTURE_ARTIFACT_NAME);
+}
+
+/** Parse a bare `--root <path>` CLI override (defaults to the real repo root)
+ * and the `--test-registry-override` flag that gates `resolveRegistry`'s
+ * env-var override (see `TEST_REGISTRY_OVERRIDE_CLI_FLAG`'s header comment).
+ * No real invocation (`npm run lint:ci`, `npm run lint:planning-document-
+ * positive-control`) ever passes this flag. */
+function parseArgs(argv) {
+  let root = path.join(__dirname, '..');
+  let allowTestRegistryOverride = false;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--root' && argv[i + 1]) {
+      root = path.resolve(argv[i + 1]);
+      i += 1;
+    } else if (argv[i] === TEST_REGISTRY_OVERRIDE_CLI_FLAG) {
+      allowTestRegistryOverride = true;
+    }
+  }
+  return { root, allowTestRegistryOverride };
+}
+
+function main() {
+  const { root, allowTestRegistryOverride } = parseArgs(process.argv.slice(2));
+  const violations = scanRepo(root, process.env, allowTestRegistryOverride);
+  if (violations.length === 0) {
+    process.stdout.write(
+      'ok planning-document-positive-control: every declared PlanningDoc grammar has a passing positive-control fixture\n',
+    );
+    return;
+  }
+  process.stderr.write(
+    'planning-document-positive-control: PlanningDoc grammar(s) missing or failing a positive-control fixture (ADR-4910 §7).\n',
+  );
+  process.stderr.write(
+    'Add/fix a fixture under tests/fixtures/planning-document/ and register it in POSITIVE_CONTROL_REGISTRY in\n' +
+      'scripts/lint-planning-document-positive-control.cjs — each fixture must round-trip through parsePlanningDoc\n' +
+      'and yield a node of the declared kind.\n',
+  );
+  for (const v of violations) {
+    const id = v.kind ?? '?';
+    const loc = v.fixture ? ` (${path.join(FIXTURE_DIR, v.fixture)})` : '';
+    process.stderr.write(`  ${id}${loc}: ${v.reason}\n`);
+  }
+  process.exitCode = 1;
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  findPositiveControlGaps,
+  readLiveGrammarKinds,
+  resolveRegistry,
+  scanRepo,
+  parseArgs,
+  POSITIVE_CONTROL_REGISTRY,
+  FIXTURE_ARTIFACT_NAME,
+  PLANNING_DOCUMENT_SRC,
+  PLANNING_DOCUMENT_LIB,
+  FIXTURE_DIR,
+  TEST_REGISTRY_OVERRIDE_ENV_VAR,
+  TEST_REGISTRY_OVERRIDE_CLI_FLAG,
+};

package/scripts/lint-response-language-coverage.cjs

@@ -78,7 +78,10 @@ const EXACT_INLINE_DIRECTIVE_WORKFLOWS = new Set([
   'discuss-phase/modes/text.md',
   'discuss-phase/templates/context.md',
   'discuss-phase/templates/discussion-log.md',
+  'execute-phase/steps/code-review-disposition.md',
   'execute-phase/steps/codebase-drift-gate.md',
+  'execute-phase/steps/gap-closure-artifacts.md',
+  'execute-phase/steps/regression-gate.md',
   'execute-phase/steps/regression-gate-run.md',
   'execute-phase/steps/worktree-recovery-policy.md',
   'help/modes/brief.md',

package/scripts/lint-skill-deps.cjs

@@ -29,6 +29,8 @@ const { runMain } = require('./lib/cli-exit.cjs');
 
 const PROFILES_MODULE = path.join(__dirname, '..', 'gsd-core', 'bin', 'lib', 'install-profiles.cjs');
 const { PROFILES, loadSkillsManifest, resolveProfile } = require(PROFILES_MODULE);
+// The one frontmatter fence owner, from the same build:lib output as install-profiles.
+const { locateFrontmatterFence } = require('../gsd-core/bin/lib/frontmatter-fence.cjs');
 
 // ---------------------------------------------------------------------------
 // Argument parsing
@@ -58,9 +60,11 @@ function extractBodyReferences(body) {
 }
 
 function extractBody(content) {
-  const fmEnd = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/m);
-  if (!fmEnd) return content;
-  return content.slice(fmEnd[0].length);
+  // The block is the one the one fence owner finds (found while implementing #5105);
+  // the body starts past the closing fence line and its line ending.
+  const fence = locateFrontmatterFence(content);
+  if (!fence || !fence.closed) return content;
+  return content.slice(fence.closingFenceEnd).replace(/^\r?\n/, '');
 }
 
 // ---------------------------------------------------------------------------

package/scripts/lint-test-file-count.allowlist.json

@@ -142,6 +142,7 @@
       "files": [
         "verify-archive-dirs-live-path.test.cjs",
         "verify-health.test.cjs",
+        "verify-lifecycle-writes-e2e.test.cjs",
         "verify-mvp-uat.test.cjs",
         "verify-npm-publish.test.cjs",
         "verify-test-quality.test.cjs",
@@ -150,7 +151,7 @@
         "verify.test.cjs"
       ],
       "issue": "#3813 — the live-path #1883 suite drives buildPlanningSnapshot in-process with an fs fault; the verify module suites are CLI-driving and cannot host an fs monkeypatch",
-      "justification": "verify-command-grounding added by #2401/#3678; allowlist follow-up landed with #3606 (base was red on this lane). #4546 adds verify-work-deferred-promotion (deferred-follow-up promotion writer contract + parity)."
+      "justification": "verify-command-grounding added by #2401/#3678; allowlist follow-up landed with #3606 (base was red on this lane). #4546 adds verify-work-deferred-promotion (deferred-follow-up promotion writer contract + parity). #5105 adds verify-lifecycle-writes-e2e.test.cjs (Phase 3 of #5056: end-to-end fixture proving the fixed post-fingerprint verbs leave an unchanged re-run fresh, plus its own pre-fix CONTROL — a distinct end-to-end concern from the existing per-verb unit suites)."
     },
     "install": {
       "files": [
@@ -293,6 +294,15 @@
       ],
       "issue": "4657",
       "justification": "The ui-consideration-probe cluster gains its workflow-prose contract file (tests/ui-consideration-probe-ui-phase-contract.test.cjs, #4657), mirroring the edge probe's split (edge-probe.test.cjs / edge-probe-docs-fixtures.test.cjs / edge-probe-spec-phase-contract.test.cjs). The contract file reads shipped gsd-core/workflows/ui-phase.md under the source-text-is-the-product exception, which the unit file deliberately does not carry (it asserts typed returns only)."
+    },
+    "verification": {
+      "files": [
+        "verification-append-audit.test.cjs",
+        "verification-overrides.test.cjs",
+        "verification-status.test.cjs"
+      ],
+      "issue": "5105",
+      "justification": "#5105 (Phase 3 of #5056) adds verification-append-audit.test.cjs for the new `verification.append-audit` verb (deny-by-default audit-block append/no-op, #4887) — a distinct concern from verification-status.test.cjs's status/fingerprint suite and verification-overrides.test.cjs's override handling."
     }
   }
 }

package/scripts/lint-test-file-count.cjs

@@ -141,6 +141,38 @@ function buildTestMap(prodPrefixes, allTestFiles) {
   return map;
 }
 
+// #5074: a `<stem>.platform.test.cjs` alongside `<stem>.test.cjs` (or
+// `.test.ts`) in the SAME directory is the other half of that primary file —
+// the platform-sensitive slice extracted so the Windows CI selector runs
+// only the small sibling — not an additional test file. Exclude it from the
+// per-module count and from the allowlist identity comparison. A
+// `.platform.test.cjs` with no base file in the same directory counts
+// normally, so the rule cannot be used to smuggle in new standalone files.
+// An empty stem (bare `platform.test.cjs`) is never treated as a sibling.
+const PLATFORM_SIBLING_RE = /^(.+)\.platform\.test\.(cjs|ts)$/;
+
+function isSplitSibling(fileBasename, siblingBasenamesInDir) {
+  const m = fileBasename.match(PLATFORM_SIBLING_RE);
+  if (!m) return false;
+  const stem = m[1];
+  if (!stem) return false;
+  return siblingBasenamesInDir.includes(`${stem}.test.cjs`) ||
+         siblingBasenamesInDir.includes(`${stem}.test.ts`);
+}
+
+function excludeSplitSiblings(testFiles) {
+  const basenamesByDir = new Map();
+  for (const f of testFiles) {
+    const dir = path.dirname(f);
+    if (!basenamesByDir.has(dir)) basenamesByDir.set(dir, []);
+    basenamesByDir.get(dir).push(path.basename(f));
+  }
+  return testFiles.filter(f => {
+    const dir = path.dirname(f);
+    return !isSplitSibling(path.basename(f), basenamesByDir.get(dir));
+  });
+}
+
 function loadAllowlist() {
   try { return JSON.parse(fs.readFileSync(ALLOWLIST_PATH, 'utf-8')).modules || {}; }
   catch (_) { return {}; }
@@ -160,6 +192,7 @@ function loadAllowlist() {
  * Returns { verdict, prefix, count, knownFiles, novel, stale, files }
  */
 function evaluateLint({ prefix, testFiles, allowlist }) {
+  testFiles = excludeSplitSiblings(testFiles);
   const count = testFiles.length;
   const entry = allowlist[prefix];
   const currentNames = testFiles.map(f => path.basename(f));
@@ -258,7 +291,7 @@ function run() {
 }
 
 module.exports = {
-  Verdict, evaluateLint, testEffectivePrefix, prodPrefix,
+  Verdict, evaluateLint, testEffectivePrefix, prodPrefix, isSplitSibling,
   _collectProdPrefixes: collectProdPrefixes,
   _collectAllTestFiles: collectAllTestFiles,
   _buildTestMap: buildTestMap,

package/scripts/lint-vendored-deps.cjs

@@ -57,6 +57,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+const { buildVendorBundle } = require('./lib/vendor-bundle.cjs');
 
 const ROOT = path.join(__dirname, '..');
 
@@ -89,16 +90,29 @@ function resolvePath(p) {
  *                                       or null when there is no bin-side type twin
  * @property {string|null} srcTwin      path under src/vendor/ to the source-side type twin tsc
  *                                       resolves for a relative import from src/**, or null
- * @property {'upstream-verbatim'|'hand-authored'} twinKind
+ * @property {boolean} [bundle]        Reproducibly bundle upstream and its locked dependencies.
+ * @property {'upstream-verbatim'|'upstream-reference'|'hand-authored'} twinKind
  *                                       'upstream-verbatim': srcTwin/vendoredDts are byte-compared
  *                                       against upstream and each other.
  *                                       'hand-authored': no upstream counterpart exists, so the
  *                                       twin is excluded from the byte-compare (checks 2 and 3
  *                                       above are skipped for this row).
+ *                                       'upstream-reference': srcTwin must be exactly
+ *                                       `export * from '<name>';` (bundled rows).
  */
 
 /** @type {VendoredPackage[]} */
 const VENDORED = [
+  ...['tap-parser', 'saxes'].map((name) => ({
+    name,
+    upstreamCjs: name === 'tap-parser' ? 'node_modules/tap-parser/dist/commonjs/index.js' : 'node_modules/saxes/saxes.js',
+    vendoredCjs: `gsd-core/bin/lib/vendor/${name}.cjs`,
+    upstreamDts: null,
+    vendoredDts: null,
+    srcTwin: `src/vendor/${name}.d.cts`,
+    twinKind: 'upstream-reference',
+    bundle: true,
+  })),
   {
     name: 're2js',
     upstreamCjs: 'node_modules/re2js/build/index.cjs',
@@ -127,6 +141,7 @@ const VENDORED = [
  * @returns {string}
  */
 function buildRefreshCommand(row) {
+  if (row.bundle) return 'npm run lint:vendored-deps -- --fix';
   const parts = [`cp ${row.upstreamCjs} ${row.vendoredCjs}`];
   if (row.twinKind === 'upstream-verbatim' && row.upstreamDts) {
     if (row.vendoredDts) parts.push(`cp ${row.upstreamDts} ${row.vendoredDts}`);
@@ -135,7 +150,8 @@ function buildRefreshCommand(row) {
   return parts.join(' && ');
 }
 
-const REFRESH_COMMAND = VENDORED.map(buildRefreshCommand).join(' && ');
+// Bundled rows share one refresh command; list it once.
+const REFRESH_COMMAND = [...new Set(VENDORED.map(buildRefreshCommand))].join(' && ');
 
 /**
  * Compare two files byte-for-byte. Returns null when equal, or a short
@@ -263,8 +279,17 @@ function readPinState(row, pkgRoot = ROOT) {
 function checkRow(row, pkgRoot = ROOT) {
   const findings = [];
 
-  const cjsDrift = compareFiles(row.vendoredCjs, row.upstreamCjs);
-  if (cjsDrift) findings.push(cjsDrift);
+  if (row.bundle) {
+    const built = buildVendorBundle(pkgRoot, row.upstreamCjs);
+    for (const [file, expected] of [[row.vendoredCjs, built.code], [`${row.vendoredCjs}.LICENSE.txt`, built.notices]]) {
+      if (!fs.existsSync(resolvePath(file)) || !fs.readFileSync(resolvePath(file)).equals(expected)) {
+        findings.push(`${file} != reproducible upstream bundle (including license notices)`);
+      }
+    }
+  } else {
+    const cjsDrift = compareFiles(row.vendoredCjs, row.upstreamCjs);
+    if (cjsDrift) findings.push(cjsDrift);
+  }
 
   if (row.twinKind === 'upstream-verbatim') {
     if (row.upstreamDts && row.vendoredDts) {
@@ -277,6 +302,11 @@ function checkRow(row, pkgRoot = ROOT) {
     }
   } else if (row.twinKind === 'hand-authored') {
     findings.push(...checkHandAuthoredTwin(row));
+  } else if (row.twinKind === 'upstream-reference') {
+    const expected = `export * from '${row.name}';\n`;
+    if (!row.srcTwin || !fs.existsSync(resolvePath(row.srcTwin)) || fs.readFileSync(resolvePath(row.srcTwin), 'utf8') !== expected) {
+      findings.push(`${row.name}: type twin must forward the upstream declarations verbatim`);
+    }
   }
 
   const { pinnedSpec, installedVersion } = readPinState(row, pkgRoot);
@@ -318,7 +348,13 @@ function checkRow(row, pkgRoot = ROOT) {
  * @returns {string[]} findings remaining after the fix (empty when fully resolved)
  */
 function fixRow(row, pkgRoot = ROOT) {
-  fs.copyFileSync(resolvePath(row.upstreamCjs), resolvePath(row.vendoredCjs));
+  if (row.bundle) {
+    const built = buildVendorBundle(pkgRoot, row.upstreamCjs);
+    fs.writeFileSync(resolvePath(row.vendoredCjs), built.code);
+    fs.writeFileSync(resolvePath(`${row.vendoredCjs}.LICENSE.txt`), built.notices);
+  } else {
+    fs.copyFileSync(resolvePath(row.upstreamCjs), resolvePath(row.vendoredCjs));
+  }
 
   if (row.twinKind === 'upstream-verbatim' && row.upstreamDts) {
     if (row.vendoredDts) fs.copyFileSync(resolvePath(row.upstreamDts), resolvePath(row.vendoredDts));

package/scripts/lint-workflow-shellcheck-baseline.json

@@ -354,11 +354,6 @@
     "code": "2012",
     "message": "Use find instead of ls to better handle non-alphanumeric filenames."
   },
-  {
-    "file": "gsd-core/workflows/execute-phase.md",
-    "code": "2012",
-    "message": "Use find instead of ls to better handle non-alphanumeric filenames."
-  },
   {
     "file": "gsd-core/workflows/execute-phase.md",
     "code": "2016",
@@ -384,11 +379,6 @@
     "code": "2086",
     "message": "Double quote to prevent globbing and word splitting."
   },
-  {
-    "file": "gsd-core/workflows/execute-phase.md",
-    "code": "2086",
-    "message": "Double quote to prevent globbing and word splitting."
-  },
   {
     "file": "gsd-core/workflows/execute-phase/detail/elaboration.md",
     "code": "2086",
@@ -414,6 +404,16 @@
     "code": "2086",
     "message": "Double quote to prevent globbing and word splitting."
   },
+  {
+    "file": "gsd-core/workflows/execute-phase/steps/verify-phase-goal.md",
+    "code": "2012",
+    "message": "Use find instead of ls to better handle non-alphanumeric filenames."
+  },
+  {
+    "file": "gsd-core/workflows/execute-phase/steps/verify-phase-goal.md",
+    "code": "2086",
+    "message": "Double quote to prevent globbing and word splitting."
+  },
   {
     "file": "gsd-core/workflows/execute-phase/steps/wave-post-gate-hooks.md",
     "code": "2086",