@monte3l/groundwork 0.0.0

package/templates/core/bin/lib/verify-steps.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * The single source of truth for what `pnpm verify` runs locally, what the
+ * lefthook `pre-push` lanes run, and what each `.github/workflows/ci.yml`
+ * job runs. Both YAML files name a *group*, never a step id: groups are a
+ * closed, five-member set (see GROUPS below); steps are not. That's what
+ * lets a new step -- core or pack-contributed -- join `pnpm verify` without
+ * ever touching either YAML file, and what keeps this the one list to keep
+ * in sync instead of three that agree by hand.
+ *
+ * Pack-installed steps live in verify-steps.packs.json, a plain JSON array
+ * the bootstrapper CLI appends to when installing a pack -- it has no JS
+ * parser and never gains one. A missing file means no packs are installed.
+ * A present-but-malformed file is a hard failure, never a silent fallback
+ * to core-only: a typo'd `group` would otherwise mean a step that runs in
+ * `pnpm verify` and in no gate at all, which is exactly the drift this file
+ * exists to prevent.
+ *
+ * Each step's `cmd` is the argv array to run (via `node:child_process`
+ * `spawnSync`, stdio inherited so failures are visible directly).
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export const GROUPS = ["format", "lint", "typecheck", "build", "test"];
+
+/**
+ * The gate steps this baseline ships, before any pack's are appended.
+ * @public Exported for the parity test that compares this file with its TypeScript twin in
+ * m3l-groundwork; nothing else in a bootstrapped project imports it.
+ */
+export const CORE_STEPS = [
+  {
+    id: "format",
+    group: "format",
+    name: "Format check",
+    cmd: ["pnpm", "format:check"],
+  },
+  { id: "lint", group: "lint", name: "Lint", cmd: ["pnpm", "lint"] },
+  {
+    id: "harness",
+    group: "lint",
+    name: "Check Claude Code harness",
+    cmd: ["node", "bin/check-harness.mjs"],
+  },
+  {
+    id: "toolchain",
+    group: "lint",
+    name: "Check TypeScript toolchain",
+    cmd: ["node", "bin/check-toolchain.mjs"],
+  },
+  {
+    id: "knip",
+    group: "lint",
+    name: "Check unused code and dependencies",
+    cmd: ["pnpm", "knip"],
+  },
+  {
+    id: "typecheck",
+    group: "typecheck",
+    name: "Typecheck",
+    cmd: ["pnpm", "typecheck"],
+  },
+  { id: "build", group: "build", name: "Build", cmd: ["pnpm", "build"] },
+  {
+    id: "test",
+    group: "test",
+    name: "Test (coverage)",
+    cmd: ["pnpm", "test:coverage"],
+  },
+  {
+    id: "exports",
+    group: "build",
+    name: "Check package exports",
+    cmd: ["node", "bin/check-exports.mjs"],
+  },
+  {
+    id: "node-version",
+    group: "build",
+    name: "Check Node version pin",
+    cmd: ["node", "bin/check-node-version.mjs"],
+  },
+];
+
+/** Reads and validates verify-steps.packs.json. Absence is fine (no packs installed). */
+function readPackSteps() {
+  const path = fileURLToPath(
+    new URL("./verify-steps.packs.json", import.meta.url),
+  );
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return [];
+  }
+
+  const parsed = JSON.parse(raw);
+  if (!Array.isArray(parsed)) {
+    throw new Error("verify-steps.packs.json must be a JSON array of steps");
+  }
+  for (const step of parsed) {
+    for (const field of ["id", "group", "name"]) {
+      if (typeof step?.[field] !== "string") {
+        throw new Error(
+          `verify-steps.packs.json: a step is missing "${field}"`,
+        );
+      }
+    }
+    if (!Array.isArray(step.cmd) || step.cmd.length === 0) {
+      throw new Error(`verify-steps.packs.json: step "${step.id}" has no cmd`);
+    }
+    if (!GROUPS.includes(step.group)) {
+      throw new Error(
+        `verify-steps.packs.json: step "${step.id}" has unknown group "${step.group}" -- known: ${GROUPS.join(", ")}`,
+      );
+    }
+  }
+  return parsed;
+}
+
+export const VERIFY_STEPS = [...CORE_STEPS, ...readPackSteps()];
+
+/** Look up one step by id, or `undefined` if no step has that id. */
+export function findStep(id) {
+  return VERIFY_STEPS.find((step) => step.id === id);
+}
+
+/** All steps belonging to one group, in VERIFY_STEPS order. */
+export function stepsInGroup(group) {
+  return VERIFY_STEPS.filter((step) => step.group === group);
+}

package/templates/core/bin/lib/verify-steps.packs.json

@@ -0,0 +1 @@
+[]

package/templates/core/bin/lint-commit.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/**
+ * Wraps `@commitlint/lint` + `@commitlint/load` directly (no `@commitlint/cli`
+ * dependency needed) against this project's `commitlint.config.js`. Also
+ * validates that no forbidden `Claude-*` trailer survived into the message
+ * (a backstop -- `strip-claude-trailers.mjs` runs first in the `commit-msg`
+ * hook and should have already removed any harness-injected one;
+ * `Co-Authored-By:` is never forbidden).
+ *
+ * Usage: `lint-commit.mjs --edit <path-to-commit-msg-file>` (lefthook's
+ * `commit-msg` hook contract) or `lint-commit.mjs <message>` directly.
+ */
+import process from "node:process";
+import { readFileSync } from "node:fs";
+import load from "@commitlint/load";
+import lint from "@commitlint/lint";
+
+const args = process.argv.slice(2);
+const editIndex = args.indexOf("--edit");
+const message =
+  editIndex === -1 ? args.join(" ") : readFileSync(args[editIndex + 1], "utf8");
+
+const FORBIDDEN_TRAILER = /^Claude-(?!Session:)[A-Za-z-]*:/m;
+
+function validateForbiddenTrailers(text) {
+  return !FORBIDDEN_TRAILER.test(text) && !/^Claude-Session:/m.test(text);
+}
+
+const config = await load({}, { file: "commitlint.config.js" });
+const result = await lint(
+  message,
+  config.rules,
+  config.parserPreset ? { parserOpts: config.parserPreset.parserOpts } : {},
+);
+
+if (!validateForbiddenTrailers(message)) {
+  console.error(
+    "commit message carries a forbidden Claude-* trailer (only Co-Authored-By: is allowed)",
+  );
+  process.exit(1);
+}
+
+if (!result.valid) {
+  for (const problem of result.errors) {
+    console.error(`✗ ${problem.message}`);
+  }
+  process.exit(1);
+}
+
+console.log("✓ commit message is a valid Conventional Commit");

package/templates/core/bin/strip-claude-trailers.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * `commit-msg`: strips any harness-injected `Claude-*` trailer line from the
+ * commit message file in place before `lint-commit.mjs` validates it.
+ * `Co-Authored-By:` is never touched -- it is the one trailer this repo
+ * wants to keep.
+ */
+import process from "node:process";
+import { readFileSync, writeFileSync } from "node:fs";
+
+const path = process.argv[2];
+if (!path) {
+  console.error("strip-claude-trailers: expected a commit-message file path");
+  process.exit(1);
+}
+
+const text = readFileSync(path, "utf8");
+const stripped = text
+  .split("\n")
+  .filter((line) => !/^Claude-[A-Za-z-]*:/.test(line))
+  .join("\n");
+
+if (stripped !== text) {
+  writeFileSync(path, stripped);
+}

package/templates/core/bin/verify.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * `pnpm verify` -- runs every step in VERIFY_STEPS (bin/lib/verify-steps.mjs)
+ * sequentially and reports pass/fail for each. `--step <id>` runs a single
+ * named step; `--group <name>` runs every step in one of the five fixed
+ * groups (format/lint/typecheck/build/test). `.github/workflows/ci.yml` and
+ * `lefthook.yml` each invoke `--group <name>`, never individual step ids, so
+ * a new step -- core or pack-contributed -- is picked up by both without
+ * either file changing.
+ */
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import {
+  VERIFY_STEPS,
+  GROUPS,
+  findStep,
+  stepsInGroup,
+} from "./lib/verify-steps.mjs";
+
+const args = process.argv.slice(2);
+const stepIndex = args.indexOf("--step");
+const requestedId = stepIndex === -1 ? null : args[stepIndex + 1];
+const groupIndex = args.indexOf("--group");
+const requestedGroup = groupIndex === -1 ? null : args[groupIndex + 1];
+
+if (requestedGroup && !GROUPS.includes(requestedGroup)) {
+  console.error(
+    `verify: unknown group "${requestedGroup}" -- known groups: ${GROUPS.join(", ")}`,
+  );
+  process.exit(1);
+}
+
+const steps = requestedId
+  ? [findStep(requestedId)].filter((step) => step !== undefined)
+  : requestedGroup
+    ? stepsInGroup(requestedGroup)
+    : VERIFY_STEPS;
+
+if (requestedId && steps.length === 0) {
+  console.error(
+    `verify: unknown step "${requestedId}" -- known ids: ${VERIFY_STEPS.map((s) => s.id).join(", ")}`,
+  );
+  process.exit(1);
+}
+
+let failed = false;
+for (const step of steps) {
+  console.log(`\n▶ ${step.name} (${step.id})`);
+  const [cmd, ...cmdArgs] = step.cmd;
+  const result = spawnSync(cmd, cmdArgs, { stdio: "inherit" });
+  if (result.status !== 0) {
+    failed = true;
+    console.error(`✗ ${step.name} failed`);
+    if (!requestedId && !requestedGroup) {
+      // Local `pnpm verify` (no --step/--group): keep going so a single
+      // early failure doesn't hide every other failing step in the same run.
+      continue;
+    }
+    break;
+  }
+  console.log(`✓ ${step.name}`);
+}
+
+process.exit(failed ? 1 : 0);

package/templates/core/commitlint.config.js

@@ -0,0 +1,11 @@
+/**
+ * Conventional Commits, enforced on `commit-msg` via lefthook.
+ *
+ * `feat:` -> minor, `fix:` -> patch, `feat!:` / `BREAKING CHANGE:` -> major.
+ * Other types (`docs`, `refactor`, `test`, `chore`, ...) do not release.
+ *
+ * @type {import("@commitlint/types").UserConfig}
+ */
+export default {
+  extends: ["@commitlint/config-conventional"],
+};

package/templates/core/docs/research/harness-refresh.md

@@ -0,0 +1,27 @@
+# Harness refresh tracker
+
+<!-- harness-refresh: last-verified=unset claude-code-version=unset -->
+
+Living record of `harness-guidance` (refresh mode) sweeps — the per-facet,
+per-source state a run diffs against, so each sweep reports what
+**changed** since the last one instead of rediscovering the whole `.claude/`
+surface from scratch. Updated **in place** on every run, never as a new
+dated file.
+
+This tracker has not had its first sweep yet (`last-verified=unset`). Run
+`harness-guidance` in refresh mode — or let `/customize`'s guidance pass
+seed it — to populate the sections below.
+
+## Outstanding drift
+
+_(none recorded yet — first sweep populates this section)_
+
+## Facet state
+
+| Facet                        | Last verified | Notes |
+| ---------------------------- | ------------- | ----- |
+| `models-tiering`             | unset         |       |
+| `cc-features-settings`       | unset         |       |
+| `agent-subagent-design`      | unset         |       |
+| `skills-context-engineering` | unset         |       |
+| `hooks-lifecycle`            | unset         |       |

package/templates/core/docs/research/typescript-refresh.md

@@ -0,0 +1,32 @@
+# TypeScript refresh tracker
+
+<!-- typescript-refresh: last-verified=unset typescript-version=unset -->
+
+Living record of `typescript-guidance` (refresh mode) sweeps — the
+per-facet, per-source state a run diffs against, so each sweep reports what
+**changed** since the last one instead of rediscovering the whole toolchain
+from scratch. Updated **in place** on every run, never as a new dated file.
+
+`typescript-version` in the header records the newest **upstream**
+TypeScript release the last sweep verified against — deliberately distinct
+from `package.json`'s own `typescript` devDependency pin, which this
+tracker exists to check against, not restate. The two numbers disagreeing
+is not a bug in the tracker; it's the finding.
+
+This tracker has not had its first sweep yet (`last-verified=unset`). Run
+`typescript-guidance` in refresh mode — or let `/customize`'s guidance pass
+seed it — to populate the sections below.
+
+## Outstanding drift
+
+_(none recorded yet — first sweep populates this section)_
+
+## Facet state
+
+| Facet                        | Last verified | Notes |
+| ---------------------------- | ------------- | ----- |
+| `compiler-config-flags`      | unset         |       |
+| `modules-esm-node-interop`   | unset         |       |
+| `packaging-declaration-emit` | unset         |       |
+| `lint-typing-rules`          | unset         |       |
+| `testing-language-features`  | unset         |       |

package/templates/core/eslint.config.js

@@ -0,0 +1,105 @@
+// @ts-check
+import js from "@eslint/js";
+import { defineConfig } from "eslint/config";
+import { configs } from "typescript-eslint";
+import { importX } from "eslint-plugin-import-x";
+import { createTypeScriptImportResolver } from "eslint-import-resolver-typescript";
+import tsdoc from "eslint-plugin-tsdoc";
+import globals from "globals";
+
+const CJS_DIRNAME = "__dir" + "name";
+const CJS_FILENAME = "__file" + "name";
+
+export default defineConfig(
+  {
+    ignores: [
+      "**/dist/**",
+      "**/node_modules/**",
+      "**/coverage/**",
+      // .claude/agents|skills|rules contain only docs (prompts, reference
+      // data a skill reads, not code this project executes); hooks are the
+      // only code under .claude/ and stay linted below.
+      ".claude/agents/**",
+      ".claude/skills/**",
+      ".claude/rules/**",
+    ],
+  },
+  js.configs.recommended,
+  ...configs.recommendedTypeChecked,
+  importX.flatConfigs.recommended,
+  importX.flatConfigs.typescript,
+  {
+    files: ["**/*.ts"],
+    linterOptions: {
+      // Stale eslint-disable directives are always a bug: they either never
+      // suppressed anything or the underlying finding was fixed, leaving
+      // noise that misleads reviewers.
+      reportUnusedDisableDirectives: "error",
+    },
+    languageOptions: {
+      parserOptions: {
+        projectService: {
+          allowDefaultProject: ["vitest.config.ts"],
+        },
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    settings: {
+      "import-x/resolver-next": [createTypeScriptImportResolver()],
+    },
+    rules: {
+      // --- ESM correctness: the #1 documented gotcha ---------------------
+      "import-x/extensions": [
+        "error",
+        "ignorePackages",
+        { js: "always", ts: "never" },
+      ],
+
+      // --- Strictness: no `any` in the public API -------------------------
+      "@typescript-eslint/no-explicit-any": "error",
+      "@typescript-eslint/no-non-null-assertion": "error",
+      "@typescript-eslint/no-floating-promises": "error",
+      "@typescript-eslint/switch-exhaustiveness-check": "error",
+      "@typescript-eslint/consistent-type-imports": "error",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
+      ],
+
+      // --- Style / design --------------------------------------------------
+      "prefer-const": "error",
+      "no-var": "error",
+      eqeqeq: ["error", "always", { null: "ignore" }],
+
+      // --- ESM only: ban CommonJS constructs -------------------------------
+      "no-restricted-globals": [
+        "error",
+        { name: CJS_DIRNAME, message: "CommonJS only; this package is ESM." },
+        { name: CJS_FILENAME, message: "CommonJS only; this package is ESM." },
+        { name: "require", message: "CommonJS only; this package is ESM." },
+      ],
+      "import-x/no-commonjs": "error",
+    },
+  },
+  {
+    files: ["src/**/*.ts"],
+    plugins: { tsdoc },
+    rules: {
+      "tsdoc/syntax": "warn",
+      "import-x/no-default-export": "error",
+    },
+  },
+  {
+    files: ["**/*.mjs", "**/*.js"],
+    ...configs.disableTypeChecked,
+  },
+  {
+    files: ["bin/**/*.mjs", ".claude/hooks/**/*.mjs"],
+    languageOptions: {
+      globals: { ...globals.node },
+    },
+    rules: {
+      "import-x/no-unresolved": "off",
+    },
+  },
+);

package/templates/core/knip.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://unpkg.com/knip@6/schema.json",
+  "entry": ["src/index.ts", "bin/*.mjs", ".claude/hooks/*.mjs"],
+  "project": ["src/**/*.ts", "bin/**/*.mjs", ".claude/hooks/**/*.mjs"],
+  "ignoreDependencies": ["@commitlint/config-conventional", "@commitlint/types"]
+}

package/templates/core/lefthook.yml

@@ -0,0 +1,39 @@
+# Git hooks, managed by Lefthook.
+# Install/refresh with `pnpm exec lefthook install` (wired into `prepare`).
+# yaml-language-server: $schema=https://json.schemastore.org/lefthook.json
+
+# Fail closed when no lefthook binary resolves at all. Without this, a
+# generated shim whose final else-branch only echoes "Can't find lefthook in
+# PATH" falls through with exit 0, silently skipping every gate below.
+assert_lefthook_installed: true
+
+pre-commit:
+  parallel: true
+  commands:
+    lint:
+      glob: "**/*.ts"
+      run: pnpm exec eslint --fix {staged_files}
+      stage_fixed: true
+    format:
+      glob: "**/*.{ts,json,md,yml,yaml}"
+      run: pnpm exec prettier --write {staged_files}
+      stage_fixed: true
+
+commit-msg:
+  commands:
+    commitlint:
+      run: node bin/strip-claude-trailers.mjs {1} && node bin/lint-commit.mjs --edit {1}
+
+pre-push:
+  parallel: true
+  commands:
+    format:
+      run: node bin/verify.mjs --group format
+    lint:
+      run: node bin/verify.mjs --group lint
+    typecheck:
+      run: node bin/verify.mjs --group typecheck
+    build:
+      run: node bin/verify.mjs --group build
+    test:
+      run: node bin/verify.mjs --group test

package/templates/core/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Bootstrapped by m3l-groundwork.",
+  "packageManager": "pnpm@12.4.0",
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "typecheck": "tsc -b --force",
+    "lint": "eslint .",
+    "format": "prettier --write . --cache --cache-strategy content",
+    "format:check": "prettier --check . --cache --cache-strategy content",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "knip": "knip",
+    "check:exports": "node bin/check-exports.mjs",
+    "check:node-version": "node bin/check-node-version.mjs",
+    "verify": "node bin/verify.mjs",
+    "prepare": "lefthook install"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@commitlint/config-conventional": "^21.2.2",
+    "@commitlint/lint": "^21.2.2",
+    "@commitlint/load": "^21.2.2",
+    "@commitlint/types": "^21.2.0",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.13.3",
+    "@vitest/coverage-v8": "^4.1.11",
+    "eslint": "^10.9.1",
+    "eslint-import-resolver-typescript": "^4.4.5",
+    "eslint-plugin-import-x": "^4.17.1",
+    "eslint-plugin-tsdoc": "^0.5.2",
+    "globals": "^17.12.0",
+    "knip": "^6.34.0",
+    "lefthook": "^2.1.12",
+    "prettier": "^3.9.6",
+    "publint": "^0.3.24",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.69.0",
+    "vitest": "^4.1.11"
+  }
+}

package/templates/core/pnpm-workspace.yaml

@@ -0,0 +1,13 @@
+# A single-package project still needs this file: pnpm 10+ moved
+# install-script approval here (the `pnpm` field in package.json is no
+# longer read).
+allowBuilds:
+  # lefthook's postinstall fetches its platform binary; needed for the git
+  # hooks to actually work.
+  lefthook: true
+  # unrs-resolver is a native binary transitive dep of
+  # eslint-import-resolver-typescript; it works without its optional native
+  # acceleration, so this is explicitly false (not omitted) so pnpm skips
+  # the build with a notice instead of erroring when no compiler toolchain
+  # is available.
+  unrs-resolver: false

package/templates/core/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Placeholder entry point — replace with your project's real public API.
+ *
+ * @example
+ * ```ts
+ * import { placeholder } from "./index.js";
+ * placeholder(); // "hello from this project"
+ * ```
+ */
+export function placeholder(): string {
+  return "hello from this project";
+}

package/templates/core/tests/index.test.ts

@@ -0,0 +1,8 @@
+import { describe, expect, it } from "vitest";
+import { placeholder } from "../src/index.js";
+
+describe("placeholder", () => {
+  it("returns a non-empty greeting", () => {
+    expect(placeholder()).toContain("hello");
+  });
+});

package/templates/core/tsconfig.base.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "es2023",
+    "lib": ["es2023"],
+    "types": ["node"],
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "exactOptionalPropertyTypes": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
+    "allowUnreachableCode": false,
+    // isolatedDeclarations stays out of the base config deliberately: the
+    // build project sets it individually (see tsconfig.build.json), but the
+    // tooling project (tsconfig.json) sets declaration: false and includes
+    // tests/, which isolatedDeclarations does not tolerate.
+    //
+    // noUnusedLocals / noUnusedParameters are deliberately NOT set:
+    // @typescript-eslint/no-unused-vars already covers both at error level
+    // (eslint.config.js) with an `^_`-prefix escape hatch this codebase
+    // relies on; tsc's flags honor no such pattern for locals.
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "composite": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}

package/templates/core/tsconfig.build.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "isolatedDeclarations": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "tsBuildInfoFile": "./dist/.tsbuildinfo"
+  },
+  "include": ["src/**/*.ts"]
+}

package/templates/core/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "composite": false,
+    "declaration": false,
+    "declarationMap": false,
+    "noEmit": true,
+    "rootDir": "."
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"]
+}