From b2a4d6d95c59df1df266287c1895c8a5c146d9de Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 6 Sep 2026 14:50:18 +0000
Subject: [PATCH 1/3] feat(create-objectstack): ship a CI workflow in the blank
 template
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The scaffolder already created `.github/` at runtime for one file
(copilot-instructions.md) while the template's own gates — `validate` and
`typecheck` — shipped as npm scripts nothing ever ran, so every scaffolded
project started with zero CI and the "metadata mistakes fail silently at
runtime, the gates are where they surface" claim rested on a human
remembering to type the command.

Adds `.github/workflows/ci.yml` to the blank template: one job, one file,
checkout -> pnpm/action-setup -> setup-node (Node 22, pnpm cache) ->
`pnpm install --frozen-lockfile` -> `pnpm validate` -> `pnpm typecheck`.

No `pnpm lint` step: the blank template declares no `lint` script and
neither scaffolder writes one, so that step would fail on the first push of
every scaffolded project. The new test derives the allowed step set from the
template's package.json so the two cannot drift.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PbJ5Cy9KDAzeQHo8bsMadG
---
 packages/create-objectstack/package.json      |   3 +-
 .../src/template-ci-workflow.test.ts          | 211 ++++++++++++++++++
 .../src/template-consistency.test.ts          |  11 +
 .../templates/blank/.github/workflows/ci.yml  |  60 +++++
 pnpm-lock.yaml                                |   3 +
 5 files changed, 287 insertions(+), 1 deletion(-)
 create mode 100644 packages/create-objectstack/src/template-ci-workflow.test.ts
 create mode 100644 packages/create-objectstack/src/templates/blank/.github/workflows/ci.yml

diff --git a/packages/create-objectstack/package.json b/packages/create-objectstack/package.json
index bb6cdb946e..fc54248249 100644
--- a/packages/create-objectstack/package.json
+++ b/packages/create-objectstack/package.json
@@ -34,7 +34,8 @@
     "@types/node": "^26.2.0",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.10",
+    "yaml": "^2.9.0"
   },
   "repository": {
     "type": "git",
diff --git a/packages/create-objectstack/src/template-ci-workflow.test.ts b/packages/create-objectstack/src/template-ci-workflow.test.ts
new file mode 100644
index 0000000000..14319353c1
--- /dev/null
+++ b/packages/create-objectstack/src/template-ci-workflow.test.ts
@@ -0,0 +1,211 @@
+// Copyright (c) 2026 ObjectStack contributors. Apache-2.0 license.
+//
+// The bundled template's own CI workflow (#16330).
+//
+// The scaffolder already creates a `.github/` directory at runtime — for one
+// file, `copilot-instructions.md` — while the template's gates (`validate`,
+// `typecheck`) shipped as npm scripts nothing ever ran. A scaffolded project
+// therefore started with zero CI, and the product claim that metadata mistakes
+// surface at authoring time rested entirely on a human remembering to type the
+// command. `.github/workflows/ci.yml` is the fix; this file is what keeps it
+// honest.
+//
+// Three properties, each of which failed silently before it was pinned:
+//
+//   1. The file is real YAML. A workflow GitHub cannot parse is not reported as
+//      a broken workflow to the user who just scaffolded — it is reported as no
+//      CI at all, which is indistinguishable from the defect being fixed here.
+//   2. Every `pnpm <script>` step names a script the template's own
+//      package.json declares. The original ask listed `pnpm lint`; the template
+//      declares no `lint` script and neither scaffolder writes one, so that step
+//      would have failed on the first push of every scaffolded project. A step
+//      list and a script list drifting apart is the whole failure shape.
+//   3. `.github/` survives the copy. It is the first dot-DIRECTORY the template
+//      has ever carried, and dotfiles have been a packaging problem here before
+//      (`_gitignore`; see TEMPLATE_FILE_ALIASES). The tarball half of that
+//      question is answered by the packing ratchet in
+//      `template-consistency.test.ts`, which packs for real; this file covers
+//      the scaffold-copy half.
+//
+// On the YAML dependency: the sibling `scaffold-e2e-boot-probe.test.ts`
+// deliberately hand-parses a workflow instead of importing a parser, because it
+// needs a `run:` block's bytes verbatim and a parser would normalise a
+// malformed file away. Here the parse IS the assertion, so that reasoning
+// inverts — and `yaml` is a devDependency, which never reaches the published
+// tarball (`files` ships `dist` alone).
+
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+import { copyDir } from './template-copy.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const pkgRoot = path.resolve(HERE, '..');
+const blankDir = path.join(pkgRoot, 'src', 'templates', 'blank');
+
+/** Where the workflow lives in the template, and where it must land in a scaffold. */
+const WORKFLOW_REL = '.github/workflows/ci.yml';
+const workflowPath = path.join(blankDir, ...WORKFLOW_REL.split('/'));
+
+interface WorkflowStep {
+  name?: string;
+  uses?: string;
+  run?: string;
+  with?: Record<string, unknown>;
+}
+
+const readWorkflow = (): Record<string, any> =>
+  parseYaml(fs.readFileSync(workflowPath, 'utf8')) as Record<string, any>;
+
+/**
+ * The `on:` block.
+ *
+ * Read through a fallback because `on` is a YAML **1.1** boolean literal: a
+ * parser on that schema returns the trigger block under the key `true`, not
+ * `"on"`. This package parses with `yaml`, which defaults to the 1.2 core
+ * schema and keeps the string — the fallback is here so a schema change
+ * downgrades to a still-correct read instead of an assertion about `undefined`.
+ */
+const triggersOf = (doc: Record<string, any>): unknown =>
+  doc.on ?? doc[true as unknown as string];
+
+const stepsOf = (doc: Record<string, any>): WorkflowStep[] =>
+  Object.values(doc.jobs as Record<string, { steps?: WorkflowStep[] }>).flatMap(
+    (job) => job.steps ?? [],
+  );
+
+describe('bundled template CI workflow', () => {
+  it('ships a workflow at .github/workflows/ci.yml', () => {
+    expect(
+      fs.existsSync(workflowPath),
+      `the blank template must carry ${WORKFLOW_REL} — without it every scaffolded ` +
+        'project starts with no CI and its validate/typecheck scripts are advisory',
+    ).toBe(true);
+  });
+
+  it('parses as YAML and declares at least one job with steps', () => {
+    const doc = readWorkflow();
+    expect(typeof doc, 'the workflow did not parse to a mapping').toBe('object');
+    expect(doc.name).toBeTruthy();
+
+    const jobs = doc.jobs as Record<string, { steps?: unknown[] }>;
+    expect(Object.keys(jobs).length, 'the workflow declares no jobs').toBeGreaterThan(0);
+    for (const [id, job] of Object.entries(jobs)) {
+      expect(Array.isArray(job.steps), `job "${id}" declares no steps`).toBe(true);
+      expect(job.steps!.length, `job "${id}" has an empty step list`).toBeGreaterThan(0);
+    }
+  });
+
+  it('runs on push and on pull_request', () => {
+    const triggers = triggersOf(readWorkflow());
+    const names = Array.isArray(triggers)
+      ? triggers.map(String)
+      : Object.keys(triggers as Record<string, unknown>);
+    expect(names).toContain('push');
+    expect(names).toContain('pull_request');
+  });
+
+  // The load-bearing one. A workflow step naming a script the project does not
+  // declare fails with `Command "<script>" not found` on the first push — a
+  // scaffold whose CI is red out of the box teaches the user to ignore CI,
+  // which is worse than shipping none. Derived from the template's real
+  // package.json rather than restated, so adding a step for a script that does
+  // not exist (or deleting a script a step runs) reds here.
+  it('runs only package.json scripts the template actually declares', () => {
+    const templatePkg = JSON.parse(
+      fs.readFileSync(path.join(blankDir, 'package.json'), 'utf8'),
+    ) as { scripts: Record<string, string> };
+
+    const invoked: string[] = [];
+    for (const step of stepsOf(readWorkflow())) {
+      if (!step.run) continue;
+      for (const line of step.run.split('\n')) {
+        // `pnpm <word>` where <word> is not a pnpm builtin is a script run.
+        const m = /^\s*pnpm(?:\s+run)?\s+([a-z][a-z0-9:_-]*)/i.exec(line);
+        if (!m) continue;
+        const word = m[1];
+        if (word === 'install' || word === 'exec' || word === 'dlx') continue;
+        invoked.push(word);
+      }
+    }
+
+    expect(invoked.length, 'the workflow runs no project script at all').toBeGreaterThan(0);
+    for (const script of invoked) {
+      expect(
+        Object.keys(templatePkg.scripts),
+        `${WORKFLOW_REL} runs \`pnpm ${script}\`, but the blank template's package.json ` +
+          'declares no such script — the step would fail on the first push of every ' +
+          'scaffolded project. Add the script to the template (and to the other ' +
+          'scaffolder, packages/cli/src/commands/init.ts) or drop the step.',
+      ).toContain(script);
+    }
+
+    // The two gates this workflow exists to run.
+    expect(invoked).toContain('validate');
+    expect(invoked).toContain('typecheck');
+  });
+
+  // Derived from the Dockerfile's build stage rather than restated: the
+  // template states its Node floor there (its `engines` block carries only a
+  // pnpm floor), so these are the same declaration and must not drift.
+  it('pins the same Node major the template Dockerfile builds on', () => {
+    const dockerfile = fs.readFileSync(path.join(blankDir, 'Dockerfile'), 'utf8');
+    const fromNode = /^FROM\s+node:(\d+)[-\s]/m.exec(dockerfile);
+    expect(fromNode, 'the template Dockerfile no longer builds on a node: base image').toBeTruthy();
+
+    const setupNode = stepsOf(readWorkflow()).find((s) => s.uses?.startsWith('actions/setup-node@'));
+    expect(setupNode, 'the workflow has no actions/setup-node step').toBeTruthy();
+    expect(
+      String(setupNode!.with!['node-version']),
+      "the workflow's Node pin and the Dockerfile's build image are one declaration",
+    ).toBe(fromNode![1]);
+  });
+
+  // pnpm must be on PATH before setup-node runs, because `cache: pnpm` makes
+  // setup-node shell out to pnpm to locate the store. Getting the order wrong
+  // does not degrade — it kills the job in the setup step.
+  it('acquires pnpm before the setup-node step that caches through it', () => {
+    const steps = stepsOf(readWorkflow());
+    const pnpmAt = steps.findIndex((s) => s.uses?.startsWith('pnpm/action-setup@'));
+    const nodeAt = steps.findIndex((s) => s.uses?.startsWith('actions/setup-node@'));
+    expect(pnpmAt, 'the workflow never acquires pnpm').toBeGreaterThanOrEqual(0);
+    expect(nodeAt).toBeGreaterThanOrEqual(0);
+    if (String(steps[nodeAt].with?.cache ?? '') === 'pnpm') {
+      expect(
+        pnpmAt,
+        'setup-node with `cache: pnpm` shells out to pnpm; acquiring pnpm after it ' +
+          'fails the job with "Unable to locate executable file: pnpm"',
+      ).toBeLessThan(nodeAt);
+    }
+  });
+
+  it('pins every action to a version tag', () => {
+    for (const step of stepsOf(readWorkflow())) {
+      if (!step.uses) continue;
+      expect(step.uses, `unpinned action reference: ${step.uses}`).toMatch(/@v\d+/);
+    }
+  });
+
+  // The dot-DIRECTORY half of the packaging question. `.github/` is the first
+  // one this template has carried; `copyDir` is what materialises a scaffold,
+  // so this is the real copy, not a re-implementation of it. The tarball half
+  // — whether `npm pack` strips the directory — is answered by the packing
+  // ratchet in template-consistency.test.ts, which packs for real.
+  it('lands in a scaffold under its real dot-directory name', () => {
+    const out = fs.mkdtempSync(path.join(os.tmpdir(), 'create-objectstack-ci-'));
+    try {
+      const collected: string[] = [];
+      copyDir(blankDir, out, collected);
+
+      const landed = path.join(out, ...WORKFLOW_REL.split('/'));
+      expect(fs.existsSync(landed), `${WORKFLOW_REL} did not survive the scaffold copy`).toBe(true);
+      expect(collected).toContain(WORKFLOW_REL);
+      expect(fs.readFileSync(landed, 'utf8')).toBe(fs.readFileSync(workflowPath, 'utf8'));
+    } finally {
+      fs.rmSync(out, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/packages/create-objectstack/src/template-consistency.test.ts b/packages/create-objectstack/src/template-consistency.test.ts
index ee44ed17ab..c6fcd68e3e 100644
--- a/packages/create-objectstack/src/template-consistency.test.ts
+++ b/packages/create-objectstack/src/template-consistency.test.ts
@@ -365,6 +365,17 @@ describe('templates survive npm packing', () => {
     expect(rules).toContain('.env');
   });
 
+  // The first dot-DIRECTORY the template has ever carried (#16330). The set
+  // comparison above already covers it, but it names nothing: a strip of
+  // `.github` would read there as "some file went missing". Naming the path
+  // literally, the way the .dockerignore case below does, is what makes the
+  // answer to "do nested dot-directories survive `npm pack`?" readable.
+  it('carries the .github workflow directory through the tarball and the scaffold', () => {
+    expect(packed).toContain('blank/.github/workflows/ci.yml');
+    expect(scaffolded).toContain('.github/workflows/ci.yml');
+    expect(TEMPLATE_FILE_ALIASES.has('.github')).toBe(false);
+  });
+
   it('leaves a literal template dotfile that packs fine alone', () => {
     // .dockerignore is NOT stripped — verified against the published 15.1.1
     // tarball, which ships it while .gitignore is absent. It stays literal, so
diff --git a/packages/create-objectstack/src/templates/blank/.github/workflows/ci.yml b/packages/create-objectstack/src/templates/blank/.github/workflows/ci.yml
new file mode 100644
index 0000000000..93bb7e416d
--- /dev/null
+++ b/packages/create-objectstack/src/templates/blank/.github/workflows/ci.yml
@@ -0,0 +1,60 @@
+# Continuous integration for this ObjectStack app.
+#
+# ObjectStack metadata fails SILENTLY at runtime, not at edit time: a mistyped
+# permission grant or a bare field name in an action predicate raises nothing,
+# it just behaves wrongly for whoever hits it first. `objectstack validate` is
+# where that class surfaces — and running it is something a human, or an AI
+# agent authoring metadata in this project, has to remember. This workflow is
+# what makes it unskippable. AGENTS.md carries the authoring conventions it
+# enforces.
+#
+# One job, one file: a starting point, not a CI framework. Grow it with the
+# project — add a step when you add a script, a second job when you deploy.
+
+name: CI
+
+on: [push, pull_request]
+
+# Read-only. Nothing here writes to the repository or publishes anything.
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: Validate
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+
+      # pnpm BEFORE setup-node, deliberately. `cache: pnpm` below makes
+      # setup-node shell out to pnpm to locate the store, so pnpm has to be on
+      # PATH by then. Reversed, this does not degrade — the job dies in the
+      # setup step with "Unable to locate executable file: pnpm".
+      #
+      # `version` is explicit because this project declares no `packageManager`
+      # field — pinning one would make the project pnpm-only, and a
+      # corepack-driven npm or yarn then refuses to run in it — so
+      # pnpm/action-setup has nothing to resolve from. Keep this in step with
+      # the `engines.pnpm` floor in package.json.
+      - uses: pnpm/action-setup@v6
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: pnpm
+
+      # `--frozen-lockfile` installs exactly what the lockfile records and fails
+      # when the two disagree, so `pnpm-lock.yaml` has to be committed.
+      # Scaffolding wrote it for you unless you passed `--skip-install`; in that
+      # case run `pnpm install` once and commit the result.
+      - run: pnpm install --frozen-lockfile
+
+      # The gate this file exists for: schema, CEL predicates and widget
+      # bindings. The same checks `pnpm build` runs, without producing an
+      # artifact.
+      - run: pnpm validate
+
+      - run: pnpm typecheck
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 65614ce890..a07f9e9762 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -900,6 +900,9 @@ importers:
       vitest:
         specifier: ^4.1.10
         version: 4.1.10(@opentelemetry/api@1.9.1)(@types/node@26.2.0)(@vitest/coverage-v8@4.1.10)(happy-dom@20.10.2)(jsdom@30.0.1(@noble/hashes@2.3.0))(msw@2.14.6(@types/node@26.2.0)(typescript@6.0.3))(vite@8.0.16(@types/node@26.2.0)(esbuild@0.28.2)(jiti@2.7.0)(tsx@4.23.12)(yaml@2.9.0))
+      yaml:
+        specifier: ^2.9.0
+        version: 2.9.0
 
   packages/drivers/driver-memory:
     dependencies:

From 900c487c23cfe6bab5cbf14c55340f5fdbb20e73 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 6 Sep 2026 14:59:18 +0000
Subject: [PATCH 2/3] fix(docs-audit): scope the dot-directory prune premise to
 the files the walk collects
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`walkSourceFiles` prunes every dot-directory under `packages/**` as build
residue, and `--self-test` re-measures the premise that makes that safe rather
than quoting it. The premise was stated over ALL tracked files, but the walk
collects `.ts` and nothing else, so it was strictly stronger than the property
the prune rests on.

The blank project template now commits `.github/workflows/ci.yml` — a template
asset this audit has never had a reason to read — which reds the pin while the
prune's actual safety is untouched. A false positive about a real premise is
the shape most likely to get a good pin deleted, so the measurement is scoped to
the extension the walk collects and stays armed for the first tracked `.ts`
under a dot-directory, which is the case the comment describes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PbJ5Cy9KDAzeQHo8bsMadG
---
 .../scaffold-blank-template-ci-workflow.md    | 18 +++++++++
 scripts/docs-audit/affected-docs.mjs          | 40 ++++++++++++-------
 2 files changed, 44 insertions(+), 14 deletions(-)
 create mode 100644 .changeset/scaffold-blank-template-ci-workflow.md

diff --git a/.changeset/scaffold-blank-template-ci-workflow.md b/.changeset/scaffold-blank-template-ci-workflow.md
new file mode 100644
index 0000000000..ed3f8fe411
--- /dev/null
+++ b/.changeset/scaffold-blank-template-ci-workflow.md
@@ -0,0 +1,18 @@
+---
+"create-objectstack": minor
+---
+
+Scaffolded projects now ship a CI workflow. The blank template carries
+`.github/workflows/ci.yml` — one job, on `push` and `pull_request`: checkout,
+pnpm, Node 22, `pnpm install --frozen-lockfile`, then `pnpm validate` and
+`pnpm typecheck`.
+
+The scaffolder already created `.github/` at runtime for a single file
+(`copilot-instructions.md`) while the template's gates shipped as npm scripts
+nothing ever ran, so a fresh project started with no CI at all — and ObjectStack
+metadata mistakes fail silently at runtime, which makes `objectstack validate`
+the only place they surface early. That gate is now unskippable for a human and
+for an AI agent authoring metadata in the project, instead of advisory.
+
+Existing projects are unaffected; copy the file from a fresh scaffold to adopt
+it.
diff --git a/scripts/docs-audit/affected-docs.mjs b/scripts/docs-audit/affected-docs.mjs
index b54025f9b3..95f03bc320 100644
--- a/scripts/docs-audit/affected-docs.mjs
+++ b/scripts/docs-audit/affected-docs.mjs
@@ -2115,12 +2115,16 @@ function walkSourceFiles(root, readDir = readdirSync) {
       //
       // Naming the two (three) directories would fix today and leave the next emitted
       // tree to be discovered the same way, so the rule is the class. It is safe because
-      // it is MEASURED, not assumed: on `6b8c67778`,
-      //   git ls-files 'packages/**' | grep -cE '(^|/)\.[^/]+/'   →   0
-      // no TRACKED file under `packages/**` lives in a dot-directory at all, so this
-      // prunes residue and nothing else. That premise is not left to age quietly — the
-      // live pin in `--self-test` re-measures it on every run and reds the day a tracked
-      // source file appears under one.
+      // it is MEASURED, not assumed:
+      //   git ls-files 'packages/**' | grep -E '(^|/)\.[^/]+/' | grep -c '\.ts$'   →   0
+      // no TRACKED file this walk would COLLECT lives in a dot-directory, so this prunes
+      // residue and nothing else. The measurement is scoped to `.ts` because that is the
+      // only extension the walk collects: `packages/create-objectstack` commits a
+      // `.github/workflows/ci.yml` inside its bundled project template — a template asset
+      // this walk has never had a reason to read — and a premise stated over ALL tracked
+      // files reds on that while the prune's actual safety is untouched. That premise is
+      // not left to age quietly — the live pin in `--self-test` re-measures it on every
+      // run and reds the day a tracked SOURCE file appears under one.
       //
       // Applied to DIRECTORIES only: a dotfile that is somehow a `.ts` source is still
       // the file arms' business, not this one's.
@@ -5708,16 +5712,24 @@ function selfTest() {
     // (4) THE PREMISE OF THE DOT-DIRECTORY PRUNE (#15446 / #15457), RE-MEASURED rather
     // than quoted. `walkSourceFiles` prunes every dot-directory under `packages/**` as
     // build residue; that is a safe rule only while no TRACKED source lives in one —
-    // zero of them do, measured on `6b8c67778`. Written as a comment the measurement
-    // would age in silence and the walk would start dropping real source with nothing
-    // saying so. Asserted here it reds on the first tracked file under a dot-directory,
-    // and the remedy is then a choice made deliberately: move the file, or go back to
-    // pruning the residue trees by name.
+    // zero of them do. Written as a comment the measurement would age in silence and the
+    // walk would start dropping real source with nothing saying so. Asserted here it reds
+    // on the first tracked SOURCE file under a dot-directory, and the remedy is then a
+    // choice made deliberately: move the file, or go back to pruning the residue trees by
+    // name.
+    //
+    // Scoped to `.ts`, the only extension the walk collects, and NOT a weakening: the
+    // property the prune rests on is "nothing this walk would have collected is hidden by
+    // it", and a non-`.ts` file was never collectable. Stated over all tracked files the
+    // pin reds on a template asset — `packages/create-objectstack` commits
+    // `src/templates/blank/.github/workflows/ci.yml`, a file a scaffolded project needs
+    // and this audit has no interest in — which is a false positive about a real premise,
+    // the shape most likely to get a good pin deleted.
     const trackedDotDirFiles = sh('git ls-files packages')
       .split('\n')
-      .filter((f) => /(^|\/)\.[^/]+\//.test(f));
-    check('walkSourceFiles', 'no TRACKED file under packages/** lives in a dot-directory — the premise the prune rests on',
-      'git ls-files packages, filtered to dot-directories', 0, trackedDotDirFiles.length);
+      .filter((f) => /(^|\/)\.[^/]+\//.test(f) && f.endsWith('.ts'));
+    check('walkSourceFiles', 'no TRACKED .ts source under packages/** lives in a dot-directory — the premise the prune rests on',
+      'git ls-files packages, filtered to .ts under dot-directories', 0, trackedDotDirFiles.length);
   }
 
   // ── The floor: every declared battery RAN, and ran its cases (#13489) ───

From 4f566942fed6f5e55fcba3caf0281d999b8ec7ab Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 6 Sep 2026 15:46:34 +0000
Subject: [PATCH 3/3] feat(create-objectstack): the blank template declares
 `lint`, and CI runs it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The workflow shipped `validate` and `typecheck` only, because the template
declared no `lint` script and a step naming one would have failed on the first
push of every scaffolded project. Adding the script is inside this package, so
the omission rested on an untested option rather than on a measurement.

Measured instead: scaffolded a project for real from the repo-built scaffolder,
installed its dependencies from the registry (@objectstack/cli 17.3.0), wired
`"lint": "objectstack lint"` and ran it — exit 0, "All checks passed". So the
script and the step both land.

`lint` is not a second spelling of `validate`. `validate.ts` and `lint.ts` share
the authoring-rule engine, but `checkHookBodyLowering` is imported by `lint.ts`
alone — so without this step a scaffolded project has no way to reach the
hook-body lowering rule, one of the two defects this card was filed about.

The derived-step test now requires `lint` alongside `validate` and `typecheck`,
and still derives the ALLOWED set from the template's own package.json, so the
step list and the script list cannot drift apart in either direction.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PbJ5Cy9KDAzeQHo8bsMadG
---
 .../scaffold-blank-template-ci-workflow.md    | 14 +++++++++----
 .../src/template-ci-workflow.test.ts          | 20 ++++++++++++++-----
 .../templates/blank/.github/workflows/ci.yml  |  7 +++++++
 .../src/templates/blank/README.md             |  2 ++
 .../src/templates/blank/package.json          |  1 +
 5 files changed, 35 insertions(+), 9 deletions(-)

diff --git a/.changeset/scaffold-blank-template-ci-workflow.md b/.changeset/scaffold-blank-template-ci-workflow.md
index ed3f8fe411..6dd09b327f 100644
--- a/.changeset/scaffold-blank-template-ci-workflow.md
+++ b/.changeset/scaffold-blank-template-ci-workflow.md
@@ -2,10 +2,16 @@
 "create-objectstack": minor
 ---
 
-Scaffolded projects now ship a CI workflow. The blank template carries
-`.github/workflows/ci.yml` — one job, on `push` and `pull_request`: checkout,
-pnpm, Node 22, `pnpm install --frozen-lockfile`, then `pnpm validate` and
-`pnpm typecheck`.
+Scaffolded projects now ship a CI workflow, and a `lint` script for it to run.
+The blank template carries `.github/workflows/ci.yml` — one job, on `push` and
+`pull_request`: checkout, pnpm, Node 22, `pnpm install --frozen-lockfile`, then
+`pnpm validate`, `pnpm lint` and `pnpm typecheck`.
+
+`lint` is new to the template (`objectstack lint`). It is not a second spelling
+of `validate`: the two share the authoring-rule engine but only `lint` runs the
+hook-body lowering check, which catches handlers that have silently stopped
+lowering to metadata-only bodies — a change of deployment shape produced by a
+refactor that looks like tidying.
 
 The scaffolder already created `.github/` at runtime for a single file
 (`copilot-instructions.md`) while the template's gates shipped as npm scripts
diff --git a/packages/create-objectstack/src/template-ci-workflow.test.ts b/packages/create-objectstack/src/template-ci-workflow.test.ts
index 14319353c1..ca72e93a2c 100644
--- a/packages/create-objectstack/src/template-ci-workflow.test.ts
+++ b/packages/create-objectstack/src/template-ci-workflow.test.ts
@@ -16,10 +16,13 @@
 //      a broken workflow to the user who just scaffolded — it is reported as no
 //      CI at all, which is indistinguishable from the defect being fixed here.
 //   2. Every `pnpm <script>` step names a script the template's own
-//      package.json declares. The original ask listed `pnpm lint`; the template
-//      declares no `lint` script and neither scaffolder writes one, so that step
-//      would have failed on the first push of every scaffolded project. A step
-//      list and a script list drifting apart is the whole failure shape.
+//      package.json declares. This is not hypothetical: the template shipped no
+//      `lint` script while the card asked for a `pnpm lint` step, and that step
+//      would have failed on the first push of every scaffolded project with
+//      `Command "lint" not found`. The template now declares `lint` — measured
+//      green against a real scaffold before the step was added — and this pin
+//      is what keeps the step list and the script list from drifting apart
+//      again, in either direction.
 //   3. `.github/` survives the copy. It is the first dot-DIRECTORY the template
 //      has ever carried, and dotfiles have been a packaging problem here before
 //      (`_gitignore`; see TEMPLATE_FILE_ALIASES). The tarball half of that
@@ -143,8 +146,15 @@ describe('bundled template CI workflow', () => {
       ).toContain(script);
     }
 
-    // The two gates this workflow exists to run.
+    // The three gates this workflow exists to run. `lint` is here on a
+    // MEASUREMENT, not on the card's wording: scaffolded for real from the
+    // repo-built scaffolder, `npm install` against the registry, then
+    // `npm run lint` -> exit 0, "All checks passed". It is not a second
+    // spelling of `validate` either — `validate.ts` and `lint.ts` share the
+    // authoring-rule engine but only `lint.ts` imports `checkHookBodyLowering`,
+    // so dropping this step drops that rule from every scaffolded project.
     expect(invoked).toContain('validate');
+    expect(invoked).toContain('lint');
     expect(invoked).toContain('typecheck');
   });
 
diff --git a/packages/create-objectstack/src/templates/blank/.github/workflows/ci.yml b/packages/create-objectstack/src/templates/blank/.github/workflows/ci.yml
index 93bb7e416d..18a128d199 100644
--- a/packages/create-objectstack/src/templates/blank/.github/workflows/ci.yml
+++ b/packages/create-objectstack/src/templates/blank/.github/workflows/ci.yml
@@ -57,4 +57,11 @@ jobs:
       # artifact.
       - run: pnpm validate
 
+      # Not a second spelling of `validate`. The two share the authoring-rule
+      # engine but not the rule set — the hook-body lowering check, which
+      # catches handlers that silently stop lowering to metadata-only bodies
+      # (a change of deployment shape, from a refactor that looks like
+      # tidying), runs here and nowhere else.
+      - run: pnpm lint
+
       - run: pnpm typecheck
diff --git a/packages/create-objectstack/src/templates/blank/README.md b/packages/create-objectstack/src/templates/blank/README.md
index ab302ca65b..d8486405be 100644
--- a/packages/create-objectstack/src/templates/blank/README.md
+++ b/packages/create-objectstack/src/templates/blank/README.md
@@ -100,6 +100,8 @@ After editing any metadata, run:
 
 ```bash
 pnpm validate     # schema + CEL predicates + widget bindings (no artifact)
+pnpm lint         # authoring rules validate does not run — e.g. a handler that
+                  # stopped lowering to a metadata-only body
 pnpm typecheck    # TypeScript types against @objectstack/spec
 ```
 
diff --git a/packages/create-objectstack/src/templates/blank/package.json b/packages/create-objectstack/src/templates/blank/package.json
index d2707381b9..125997e869 100644
--- a/packages/create-objectstack/src/templates/blank/package.json
+++ b/packages/create-objectstack/src/templates/blank/package.json
@@ -11,6 +11,7 @@
     "start": "objectstack start",
     "build": "objectstack build",
     "validate": "objectstack validate",
+    "lint": "objectstack lint",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {