@opengsd/gsd-core 1.9.0 → 1.10.0

package/scripts/lint-allow-test-rule-refs.allowlist.json

@@ -1,5 +1,5 @@
 [
-  "tests/agent-classification-parity.test.cjs :: runtime-contract-is-the-product — docs/AGENTS.md section layout + docs/INVENTORY.md table ARE the classification surface being validated",
+  "tests/agent-classification-parity.test.cjs :: source-text-is-the-product",
   "tests/agent-frontmatter.test.cjs :: source-text-is-the-product",
   "tests/agent-required-reading-consistency.test.cjs :: source-text-is-the-product",
   "tests/agent-size-budget.test.cjs :: source-text-is-the-product",
@@ -15,23 +15,20 @@
   "tests/autonomous-interactive.test.cjs :: source-text-is-the-product",
   "tests/autonomous-to-flag.test.cjs :: source-text-is-the-product",
   "tests/chain-flag-plan-phase.test.cjs :: source-text-is-the-product",
-  "tests/changeset-cli.test.cjs :: reads a product workflow .md file (not CJS source) to verify",
+  "tests/changeset-cli.test.cjs :: source-text-is-the-product",
   "tests/check-update-config-dir.test.cjs :: structural-regression-guard",
-  "tests/ci-test-scope.test.cjs :: CLI usage banner presence is a user-facing contract.",
-  "tests/ci-test-scope.test.cjs :: CLI usage failure text is user-facing contract for this parser guard.",
   "tests/claude-md.test.cjs :: source-text-is-the-product",
   "tests/claude-skills-migration.test.cjs :: source-text-is-the-product",
   "tests/cleanup-branch-pruning.test.cjs :: source-text-is-the-product",
   "tests/cline-install.test.cjs :: source-text-is-the-product",
   "tests/cline-support.test.cjs :: source-text-is-the-product",
-  "tests/clock-seam.test.cjs :: line 159 reads the STATE.md temp file written by readModifyWriteStateMd — this is a runtime output file assertion, not a source-grep; the API returns void so a file read-back is the only way to verify the transform was applied",
   "tests/code-review-agent-skills.test.cjs :: source-text-is-the-product",
   "tests/code-review-command.test.cjs :: source-text-is-the-product",
   "tests/code-review-pipeline-regression.test.cjs :: source-text-is-the-product",
   "tests/code-review.test.cjs :: source-text-is-the-product",
   "tests/codebuddy-install.test.cjs :: source-text-is-the-product",
   "tests/codex-config.test.cjs :: source-text-is-the-product",
-  "tests/command-contract.test.cjs :: source-text-is-the-product — commands/gsd/*.md files ARE the",
+  "tests/command-contract.test.cjs :: source-text-is-the-product",
   "tests/commands.test.cjs :: source-text-is-the-product",
   "tests/concurrency-safety.test.cjs :: source-text-is-the-product",
   "tests/config-field-docs.test.cjs :: docs-parity",
@@ -47,18 +44,15 @@
   "tests/discuss-phase-power.test.cjs :: source-text-is-the-product",
   "tests/docs-parity-live-registry.test.cjs :: source-text-is-the-product",
   "tests/drift-detection.test.cjs :: source-text-is-the-product",
-  "tests/edge-probe-docs-fixtures.test.cjs :: runtime-contract-is-the-product — the rendered reference/SPEC/ADR vocab surfaces are the runtime contract; this pins their bijection to the code (docs-parity)",
-  "tests/edge-probe-planner-contract.test.cjs :: runtime-contract-is-the-product — plan-phase.md's planner prompt is the deployed runtime contract under assertion",
-  "tests/edge-probe-spec-phase-contract.test.cjs :: runtime-contract-is-the-product — spec-phase.md Step 5.5 is the deployed workflow runtime contract under assertion",
+  "tests/edge-probe-docs-fixtures.test.cjs :: source-text-is-the-product",
+  "tests/edge-probe-planner-contract.test.cjs :: source-text-is-the-product",
+  "tests/edge-probe-spec-phase-contract.test.cjs :: source-text-is-the-product",
   "tests/edit-phase.test.cjs :: source-text-is-the-product",
   "tests/eslint-rules.test.cjs :: <source-grep reason> must still error",
   "tests/eslint-rules.test.cjs :: pending migration",
   "tests/eslint-rules.test.cjs :: source-text-is-the-product",
   "tests/execute-phase-active-flags.test.cjs :: source-text-is-the-product",
   "tests/execute-phase-step-5-5-deviation-doc.test.cjs :: source-text-is-the-product",
-  "tests/execute-phase-wave.test.cjs :: behavioral — calls gsd-tools and asserts structured output",
-  "tests/execute-phase-wave.test.cjs :: behavioral — exercises config-set validation, not source text",
-  "tests/execute-phase-wave.test.cjs :: behavioral — exercises gsd-tools wave-defaulting logic",
   "tests/execute-phase-wave.test.cjs :: source-text-is-the-product",
   "tests/execute-phase-worktree-artifacts.test.cjs :: source-text-is-the-product",
   "tests/explore-command.test.cjs :: source-text-is-the-product",
@@ -66,9 +60,8 @@
   "tests/forensics.test.cjs :: source-text-is-the-product",
   "tests/frontmatter-cli.test.cjs :: source-text-is-the-product",
   "tests/gates-taxonomy.test.cjs :: source-text-is-the-product",
-  "tests/git-base-branch.test.cjs :: runtime-contract-is-the-product",
-  "tests/git-base-branch.test.cjs :: runtime-contract-is-the-product — the workflow .md content IS",
-  "tests/gsd-check-update-worker-platform-gate.test.cjs :: structural assertion on spawn-options shape; the behavior",
+  "tests/git-base-branch.test.cjs :: source-text-is-the-product",
+  "tests/gsd-check-update-worker-platform-gate.test.cjs :: structural-regression-guard",
   "tests/gsd-researcher-app-aware.test.cjs :: source-text-is-the-product",
   "tests/gsd-researcher-flow-diagram.test.cjs :: source-text-is-the-product",
   "tests/gsd-settings-advanced.test.cjs :: source-text-is-the-product",
@@ -80,21 +73,18 @@
   "tests/install-minimal-hooks.test.cjs :: source-text-is-the-product",
   "tests/install-nested-layout.test.cjs :: source-text-is-the-product",
   "tests/install-runtime-artifacts.test.cjs :: source-text-is-the-product",
-  "tests/install.test.cjs :: runtime-contract-is-the-product",
   "tests/install.test.cjs :: source-text-is-the-product",
-  "tests/intel.test.cjs :: source-text-is-the-product — agents/gsd-intel-updater.md IS the",
-  "tests/intel.test.cjs :: source-text-is-the-product — readFileSync assertions target API-SURFACE.md, which is the generated product of intelApiSurface; asserting on its text content is the only way to verify correct generation.",
-  "tests/inventory-headings-countfree.test.cjs :: runtime-contract-is-the-product — INVENTORY.md heading format is the shipped doc surface being locked",
+  "tests/intel.test.cjs :: source-text-is-the-product",
+  "tests/inventory-headings-countfree.test.cjs :: source-text-is-the-product",
   "tests/ios-scaffold-safety.test.cjs :: source-text-is-the-product",
   "tests/issue-2639-codex-toml-neutralization.test.cjs :: source-text-is-the-product",
   "tests/issue-429-comment-text-gate.test.cjs :: source-text-is-the-product",
-  "tests/issue-498-update-backup-runtime-dir.test.cjs :: structural assertion on the deployed update.md backup bash;",
-  "tests/issue-57-runtime-install-no-drift.test.cjs :: delegation-presence guard. Catches wholesale removal of the registry",
-  "tests/issue-57-runtime-install-no-drift.test.cjs :: structural guard over bin/install.js source. Behavioral assertions",
+  "tests/issue-498-update-backup-runtime-dir.test.cjs :: source-text-is-the-product",
+  "tests/issue-57-runtime-install-no-drift.test.cjs :: structural-regression-guard",
   "tests/issue-607-installer-dry-run.install.test.cjs :: integration-test-input",
   "tests/issue-607-legacy-cleanup.test.cjs :: integration-test-input",
   "tests/issue-787-cline-hooks-agents.test.cjs :: source-text-is-the-product",
-  "tests/issue-815-update-next-channel.test.cjs :: reads product workflow/command markdown to verify the --next RC channel contract — not a source-grep test",
+  "tests/issue-815-update-next-channel.test.cjs :: source-text-is-the-product",
   "tests/locking-bugs-1909-1916-1925-1927.test.cjs :: architectural-invariant",
   "tests/mcp-tool-inheritance.test.cjs :: source-text-is-the-product",
   "tests/milestone-summary.test.cjs :: source-text-is-the-product",
@@ -111,7 +101,6 @@
   "tests/path-replacement.test.cjs :: source-text-is-the-product",
   "tests/phase-dependency-levels.test.cjs :: source-text-is-the-product",
   "tests/phase.test.cjs :: source-text-is-the-product",
-  "tests/phase.test.cjs :: state-md-is-the-runtime-contract — regression tests for",
   "tests/phase6-capability-docs.test.cjs :: source-text-is-the-product",
   "tests/phase6-capstone-conformance.test.cjs :: source-text-is-the-product",
   "tests/phase6-planning-capabilities.test.cjs :: source-text-is-the-product",
@@ -127,7 +116,6 @@
   "tests/product-name-purity.test.cjs :: source-text-is-the-product",
   "tests/profile-output.test.cjs :: source-text-is-the-product",
   "tests/progress-forensic.test.cjs :: source-text-is-the-product",
-  "tests/prompt-budget-cli.test.cjs :: prompt-content-is-the-product",
   "tests/prompt-thinning.test.cjs :: source-text-is-the-product",
   "tests/quick-session-management.test.cjs :: source-text-is-the-product",
   "tests/qwen-skills-migration.test.cjs :: source-text-is-the-product",
@@ -137,12 +125,11 @@
   "tests/release-coverage-scope.test.cjs :: source-text-is-the-product",
   "tests/release-tarball-smoke-workflow.test.cjs :: source-text-is-the-product",
   "tests/release-tarball-smoke.install.test.cjs :: integration-test-input",
-  "tests/research-agent-profiles.test.cjs :: <runtime-contract-is-the-product> research agent .md content is the governed surface",
+  "tests/research-agent-profiles.test.cjs :: source-text-is-the-product",
   "tests/review-default-reviewers-workflow.test.cjs :: source-text-is-the-product",
   "tests/roadmap.test.cjs :: source-text-is-the-product",
-  "tests/run-tests-harness.test.cjs :: run-tests.cjs is a CLI test harness whose only IR is its",
-  "tests/runtime-launcher-parity.test.cjs :: structural parity/drift guard — asserts literal presence/absence of the canonical gsd_run launcher and the retired $GSD_SDK / `/gsd-tools` tokens across workflow markdown; there is no typed IR for \"this source file does not contain substring X\".",
-  "tests/runtime-name-policy.test.cjs :: runtime-contract-is-the-product — FALLBACK_ALIASES source text IS the",
+  "tests/runtime-launcher-parity.test.cjs :: structural-regression-guard",
+  "tests/runtime-name-policy.test.cjs :: source-text-is-the-product",
   "tests/scan-command.test.cjs :: source-text-is-the-product",
   "tests/secret-scan-lint.security.test.cjs :: source-text-is-the-product",
   "tests/secure-phase.test.cjs :: source-text-is-the-product",
@@ -153,7 +140,6 @@
   "tests/settings-jsonc.test.cjs :: structural-regression-guard",
   "tests/skill-frontmatter-contract.test.cjs :: source-text-is-the-product",
   "tests/spawn-liveness-banner.test.cjs :: source-text-is-the-product",
-  "tests/state-acquirestatelock-non-eexist.test.cjs :: architectural-invariant",
   "tests/state.test.cjs :: source-text-is-the-product",
   "tests/subagent-timeout.test.cjs :: source-text-is-the-product",
   "tests/template.test.cjs :: source-text-is-the-product",
@@ -167,7 +153,7 @@
   "tests/workflow-compat.test.cjs :: source-text-is-the-product",
   "tests/workflow-guard-registration.test.cjs :: structural-regression-guard",
   "tests/workflow-maintainer-skip.test.cjs :: source-text-is-the-product",
-  "tests/workflow-shell-pinning.test.cjs :: file-scope prefilter, not a test assertion — we need to",
+  "tests/workflow-shell-pinning.test.cjs :: source-text-is-the-product",
   "tests/workflow-size-budget.test.cjs :: source-text-is-the-product",
   "tests/workspace.test.cjs :: source-text-is-the-product",
   "tests/worktree-cleanup.test.cjs :: source-text-is-the-product",

package/scripts/lint-compiled-artifact-sync.cjs

@@ -43,7 +43,12 @@ const REASON = Object.freeze({
 });
 
 function git(args) {
-  return execFileSync('git', args, { cwd: REPO_ROOT, encoding: 'utf8' });
+  // -c safe.directory=REPO_ROOT: containerized CI checkouts are frequently
+  // owned by a different uid than the one running the test process, and git
+  // refuses to operate at all on such a repo ("detected dubious ownership")
+  // unless explicitly trusted. Scoped per-invocation (not written to any
+  // config file) so this never widens trust beyond this one call.
+  return execFileSync('git', ['-c', `safe.directory=${REPO_ROOT}`, ...args], { cwd: REPO_ROOT, encoding: 'utf8' });
 }
 
 /**

package/scripts/lint-docs-command-form.cjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+/**
+ * lint-docs-command-form.cjs
+ *
+ * Enforces the human-facing command form in docs/ (#2903).
+ *
+ * `/gsd:<cmd>` (and bare `gsd:<cmd>`) is a SOURCE-AUTHORING token: install-time
+ * converters (`transformContentToHyphen`, `convertSlashCommandsTo<Runtime>SkillMentions`)
+ * rewrite it to `/gsd-<cmd>` per-runtime. It is correct in `commands/gsd/**`,
+ * `gsd-core/workflows/**`, and `agents/**` — but docs are never passed through a
+ * converter, so a doc telling a reader to type `/gsd:<cmd>` names a command no
+ * runtime registers. The real user-facing form is `/gsd-<cmd>`.
+ *
+ * This guard fails any `docs/**\/*.md` file that still contains `/gsd:<cmd>` or
+ * bare `gsd:<cmd>` where `<cmd>` is a real command name (drawn from the
+ * `commands/gsd/*.md` roster). It explicitly permits `/gsd-core:<cmd>` (the
+ * Claude Code plugin namespace) and any `gsd:<token>` whose `<token>` is not a
+ * real command (e.g. the `gsd:section` / `gsd:loop-host` workflow-fragment
+ * marker syntax documented in docs/reference/workflow-fragments.md, or
+ * `gsd:command-name` used as a placeholder while explaining the Gemini CLI
+ * colon-form convention).
+ *
+ * Exclusions (never checked):
+ *   - docs/adr/**                  (historical record)
+ *   - docs/RELEASE-NOTES-LEGACY.md (maintainer question still open)
+ *   - commands/gsd/**, gsd-core/workflows/**, agents/** — never touched by this
+ *     guard at all; the colon form is correct there.
+ *
+ * Exemption — `name:` frontmatter key citations: source command files
+ * (`commands/gsd/*.md`) carry the colon form in their `name:` YAML frontmatter
+ * key (e.g. `name: gsd:next`). A doc that quotes that key verbatim — e.g.
+ * `` `name: gsd:next` `` or `name: gsd:next` — is citing the real source file,
+ * not telling a reader what to type. Rewriting that citation to `gsd-next`
+ * would make the doc lie about the source it's quoting, so a `gsd:<cmd>` token
+ * immediately preceded by `name:` (optionally with a backtick/whitespace in
+ * between) is permitted. This is narrow: it does not exempt `gsd:<cmd>`
+ * anywhere else on the line or file, including the reader-facing `/gsd-<cmd>`
+ * form that may appear later in the same sentence.
+ *
+ * Detection is case-insensitive (`/GSD:next`, `Gsd:Next`, etc. are all
+ * flagged) since the install-time converters and runtimes treat command names
+ * case-insensitively in practice, and a doc typo in casing is still a lie
+ * about the real command form.
+ *
+ * Exit 0 if no violations; exit 1 if any are found (with stderr diagnostics).
+ */
+
+'use strict';
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const SELF_PATH = path.resolve(__filename);
+// GSD_LINT_DOCS_COMMAND_FORM_REPO_ROOT is used by tests to redirect the guard to
+// a temporary fixture git repo without touching the real working tree.
+const REPO_ROOT = process.env.GSD_LINT_DOCS_COMMAND_FORM_REPO_ROOT
+  ? path.resolve(process.env.GSD_LINT_DOCS_COMMAND_FORM_REPO_ROOT)
+  : path.resolve(__dirname, '..');
+
+const DOCS_PREFIX = 'docs/';
+const ADR_PREFIX = 'docs/adr/';
+const RELEASE_NOTES_LEGACY = 'docs/RELEASE-NOTES-LEGACY.md';
+const COMMANDS_DIR = path.join(REPO_ROOT, 'commands/gsd');
+
+// Matches `/gsd:<cmd>` and bare `gsd:<cmd>` (not part of `/gsd-core:<cmd>`,
+// which does not contain the substring `gsd:` — the hyphen breaks it).
+// Case-insensitive so `/GSD:next` / `Gsd:Next` are also caught.
+const COMMAND_FORM_RE = /(^|[^A-Za-z0-9_-])(\/)?gsd:([A-Za-z0-9_-]+)/gi;
+
+// A `gsd:<cmd>` token is exempt when it is a citation of a source file's
+// YAML `name:` frontmatter key — i.e. the text immediately before the match
+// (ending exactly where the match begins) is `name:` followed by optional
+// whitespace and/or a backtick. Only applies to the bare (non-`/`) form,
+// since the real frontmatter key never carries a leading slash.
+const NAME_KEY_CITATION_RE = /name:\s*`?\s*$/i;
+
+function loadRoster() {
+  let entries;
+  try {
+    entries = fs.readdirSync(COMMANDS_DIR);
+  } catch (err) {
+    throw new ExitError(1, 'ERROR lint-docs-command-form: could not read commands/gsd: ' + err.message);
+  }
+  return new Set(
+    entries.filter((f) => f.endsWith('.md')).map((f) => f.replace(/\.md$/, '')),
+  );
+}
+
+function isCheckedDocsFile(relPath) {
+  if (!relPath.startsWith(DOCS_PREFIX)) return false;
+  if (relPath.startsWith(ADR_PREFIX)) return false;
+  if (relPath === RELEASE_NOTES_LEGACY) return false;
+  return relPath.endsWith('.md');
+}
+
+/**
+ * Pure scan — no fs, no git. Returns violations for a single file's content.
+ *
+ * @param {string} relPath  file path (used only in violation records)
+ * @param {string} content  file contents
+ * @param {Set<string>} roster  valid command names
+ * @returns {Array<{file:string, line:number, col:number, text:string}>}
+ */
+function scanContent(relPath, content, roster) {
+  const violations = [];
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    COMMAND_FORM_RE.lastIndex = 0;
+    let match;
+    while ((match = COMMAND_FORM_RE.exec(line)) !== null) {
+      const [, pre, slash, cmd] = match;
+      if (!roster.has(cmd.toLowerCase())) continue;
+      if (!slash) {
+        const preContext = line.slice(0, match.index + pre.length);
+        if (NAME_KEY_CITATION_RE.test(preContext)) continue;
+      }
+      const matchedToken = (slash || '') + 'gsd:' + cmd;
+      violations.push({
+        file: relPath,
+        line: i + 1,
+        col: match.index + pre.length + 1,
+        text: matchedToken,
+      });
+    }
+  }
+  return violations;
+}
+
+function main() {
+  const roster = loadRoster();
+
+  let trackedFiles;
+  try {
+    trackedFiles = execFileSync('git', ['ls-files'], { cwd: REPO_ROOT, encoding: 'utf8' })
+      .split('\n')
+      .map((f) => f.trim())
+      .filter(Boolean);
+  } catch (err) {
+    throw new ExitError(1, 'ERROR lint-docs-command-form: git ls-files failed: ' + err.message);
+  }
+
+  const docsFiles = trackedFiles.filter(isCheckedDocsFile);
+  const violations = [];
+
+  for (const relPath of docsFiles) {
+    const fullPath = path.join(REPO_ROOT, relPath);
+    if (path.resolve(fullPath) === SELF_PATH) continue;
+
+    let content;
+    try {
+      content = fs.readFileSync(fullPath, 'utf8');
+    } catch {
+      // Unreadable/deleted files — skip silently.
+      continue;
+    }
+
+    violations.push(...scanContent(relPath, content, roster));
+  }
+
+  if (violations.length === 0) {
+    process.stdout.write(
+      'ok lint-docs-command-form: ' + docsFiles.length + ' file(s) checked, 0 violations\n',
+    );
+    return 0;
+  }
+
+  process.stderr.write('\nERROR lint-docs-command-form: ' + violations.length + ' violation(s) found\n\n');
+  for (const v of violations) {
+    process.stderr.write('  ' + v.file + ':' + v.line + ':' + v.col + ' — ' + JSON.stringify(v.text) + '\n');
+  }
+  process.stderr.write('\n');
+  process.stderr.write(
+    'Fix: docs are never passed through the install-time slash-form converters, so the\n',
+  );
+  process.stderr.write(
+    '      colon form names a command no runtime registers. Rewrite to the hyphen form\n',
+  );
+  process.stderr.write(
+    '      (`/gsd-<cmd>`), or `/gsd-core:<cmd>` if this is genuinely the Claude Code\n',
+  );
+  process.stderr.write('      plugin namespace.\n\n');
+  return 1;
+}
+
+if (require.main === module) runMain(main);
+
+module.exports = {
+  scanContent,
+  isCheckedDocsFile,
+  loadRoster,
+  COMMAND_FORM_RE,
+};

package/scripts/lint-docs-required.cjs

@@ -16,6 +16,10 @@
 const { parseFragment, FRAGMENT_ERROR } = require('./changeset/parse.cjs');
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 
+// #2988: the repo's integration/default branch — the base every PR targets.
+// Used as the local fallback when GITHUB_BASE_REF is unset (CI sets it).
+const DEFAULT_BASE = 'next';
+
 const LINT_REASON = Object.freeze({
   OK_NO_TRIGGERING_FRAGMENTS: 'ok_no_triggering_fragments',
   OK_DOCS_UPDATED: 'ok_docs_updated',
@@ -149,7 +153,10 @@ function main() {
     } catch { /* fall through */ }
   }
 
-  const base = process.env.GITHUB_BASE_REF || 'main';
+  // #2988: local fallback must match the repo's integration branch (`next`),
+  // not the release branch (`main`). CI sets GITHUB_BASE_REF explicitly; the
+  // fallback only fires locally, where `next` is the base every PR targets.
+  const base = process.env.GITHUB_BASE_REF || DEFAULT_BASE;
   let changedFiles = [];
   try {
     // execFileSync with argv — no shell, so a malicious GITHUB_BASE_REF
@@ -216,6 +223,7 @@ module.exports = {
   OPT_OUT_LABEL,
   TRIGGERING_TYPES,
   FRAGMENT_ERROR,
+  DEFAULT_BASE,
   isFragmentPath,
   isDocsFile,
   isExemptFragment,