@produck/agent-toolkit 0.9.2 → 0.10.0

package/bin/agent-toolkit.mjs

@@ -42,6 +42,10 @@ import {
   printSyncPublishHelp,
   runSyncPublish,
 } from './command/sync-publish/index.mjs';
+import {
+  printSyncTypescriptHelp,
+  runSyncTypescript,
+} from './command/sync-typescript/index.mjs';
 import { hasFlag, parseCommonArgs } from './command/shared/args.mjs';
 import {
   printValidateCommitMsgHelp,
@@ -101,6 +105,10 @@ const COMMANDS = {
     printHelp: printSyncPublishHelp,
     run: runSyncPublish,
   },
+  'sync-typescript': {
+    printHelp: printSyncTypescriptHelp,
+    run: runSyncTypescript,
+  },
 };
 
 const DEFAULT_COMMAND = 'enforce-node-baseline';

package/bin/build-publish-assets.mjs

@@ -49,6 +49,7 @@ const OUTPUT_LERNA_PATH = path.resolve(
   PACKAGE_ROOT,
   'publish-assets/lerna.json',
 );
+const ROOT_PACKAGE_JSON_PATH = path.resolve(REPO_ROOT, 'package.json');
 const LEGACY_OUTPUT_PATH = path.resolve(
   PACKAGE_ROOT,
   'publish-assets/instructions/org.instructions.md',
@@ -80,6 +81,10 @@ function validateSourceFile(fileName, text) {
   }
 }
 
+function resolveSemverExact(text) {
+  return text.replace(/^[\^~>=<]+\s*/, '').trim();
+}
+
 function readAndValidateToolingBaseline() {
   if (!fs.existsSync(SOURCE_TOOLING_BASELINE_PATH)) {
     throw new Error(
@@ -98,25 +103,40 @@ function readAndValidateToolingBaseline() {
     );
   }
 
-  const c8Version = baseline?.tools?.c8?.version;
-  const lernaVersion = baseline?.tools?.lerna?.version;
-  const coverageScriptTemplate = baseline?.coverage?.scriptTemplate;
-
   if (typeof baseline.schemaVersion !== 'number') {
     throw new Error(
       `Invalid tooling baseline schemaVersion in: ${SOURCE_TOOLING_BASELINE_PATH}`,
     );
   }
 
+  // Auto-resolve tool versions: only override version when set to "auto"
+  const rootPkg = JSON.parse(fs.readFileSync(ROOT_PACKAGE_JSON_PATH, 'utf8'));
+  const devDeps = rootPkg.devDependencies || {};
+
+  for (const [toolName, entry] of Object.entries(baseline.tools)) {
+    if (entry.version === 'auto') {
+      const depVersion = devDeps[toolName];
+      if (typeof depVersion === 'string' && depVersion.trim()) {
+        entry.version = resolveSemverExact(depVersion);
+      }
+    }
+  }
+
+  const c8Version = baseline?.tools?.c8?.version;
+  const lernaVersion = baseline?.tools?.lerna?.version;
+  const coverageScriptTemplate = baseline?.coverage?.scriptTemplate;
+
   if (typeof c8Version !== 'string' || c8Version.trim() === '') {
     throw new Error(
-      `Invalid tools.c8.version in: ${SOURCE_TOOLING_BASELINE_PATH}`,
+      `Invalid tools.c8.version in: ${SOURCE_TOOLING_BASELINE_PATH} ` +
+        '(c8 must be listed in root package.json devDependencies)',
     );
   }
 
   if (typeof lernaVersion !== 'string' || lernaVersion.trim() === '') {
     throw new Error(
-      `Invalid tools.lerna.version in: ${SOURCE_TOOLING_BASELINE_PATH}`,
+      `Invalid tools.lerna.version in: ${SOURCE_TOOLING_BASELINE_PATH} ` +
+        '(lerna must be listed in root package.json devDependencies)',
     );
   }
 
@@ -129,6 +149,7 @@ function readAndValidateToolingBaseline() {
     );
   }
 
+  // Dynamically inject @produck/eslint-rules version from its own package.json
   const eslintRulesPkgPath = path.resolve(
     PACKAGE_ROOT,
     '../eslint-rules/package.json',
@@ -146,6 +167,7 @@ function readAndValidateToolingBaseline() {
       };
     }
   }
+
   return `${JSON.stringify(baseline, null, 2)}\n`;
 }
 

package/bin/command/main/help.txt

@@ -7,6 +7,7 @@ agent-toolkit commands:
   sync-editorconfig
   sync-git
   sync-format
+  sync-typescript
   sync-install
   sync-lint
   sync-publish

package/bin/command/sync-coverage/index.mjs

@@ -51,6 +51,35 @@ function parseJsonFile(filePath, label) {
   }
 }
 
+function resolveSemverExact(text) {
+  return text.replace(/^[\^~>=<]+\s*/, '').trim();
+}
+
+function resolveToolVersionFromDevDeps(baseline, toolName) {
+  // If baseline has a concrete version (not "auto"), use it directly.
+  // This is the case when reading the published publish-assets baseline.
+  const baselineVersion = String(
+    baseline?.tools?.[toolName]?.version || '',
+  ).trim();
+  if (baselineVersion && baselineVersion !== 'auto') {
+    return baselineVersion;
+  }
+
+  // Fall back to resolving from local root package.json devDependencies.
+  // This covers source baseline with version="auto" during local dev.
+  const repoRoot = path.resolve(PACKAGE_ROOT, '../..');
+  const pkgJsonPath = path.resolve(repoRoot, 'package.json');
+  if (fs.existsSync(pkgJsonPath)) {
+    const pkg = parseJsonFile(pkgJsonPath, 'root package.json');
+    const dep = pkg?.devDependencies?.[toolName];
+    if (typeof dep === 'string' && dep.trim()) {
+      return resolveSemverExact(dep);
+    }
+  }
+
+  return '';
+}
+
 function loadToolingBaseline() {
   const toolingBaselinePath = TOOLING_BASELINE_CANDIDATE_PATHS.find(
     (candidatePath) => {
@@ -76,7 +105,7 @@ function loadToolingBaseline() {
     process.exit(2);
   }
 
-  const c8Version = baseline?.tools?.c8?.version;
+  const c8Version = resolveToolVersionFromDevDeps(baseline, 'c8');
   if (typeof c8Version !== 'string' || c8Version.trim() === '') {
     console.error(
       `Tooling baseline tools.c8.version must be a non-empty string: ${toolingBaselinePath}`,

package/bin/command/sync-coverage/required-c8-config.json

@@ -1,15 +1,20 @@
 {
+  "branches": 99.5,
   "check-coverage": true,
   "exclude": [
     "**/node_modules/**",
     "**/coverage/**",
     "**/dist/**",
     "**/build/**",
-    "**/out/**"
+    "**/out/**",
+    "**/test/**"
   ],
-  "reporter": ["lcov", "html", "text-summary"],
-  "branches": 99.5,
   "functions": 99.5,
-  "statements": 99.5,
-  "lines": 99.5
+  "lines": 99.5,
+  "reporter": [
+    "lcov",
+    "html",
+    "text-summary"
+  ],
+  "statements": 99.5
 }

package/bin/command/sync-format/index.mjs

@@ -99,6 +99,35 @@ function parseJsonFile(filePath, label) {
   }
 }
 
+function resolveSemverExact(text) {
+  return text.replace(/^[\^~>=<]+\s*/, '').trim();
+}
+
+function resolveToolVersionFromDevDeps(baseline, toolName) {
+  // If baseline has a concrete version (not "auto"), use it directly.
+  // This is the case when reading the published publish-assets baseline.
+  const baselineVersion = String(
+    baseline?.tools?.[toolName]?.version || '',
+  ).trim();
+  if (baselineVersion && baselineVersion !== 'auto') {
+    return baselineVersion;
+  }
+
+  // Fall back to resolving from local root package.json devDependencies.
+  // This covers source baseline with version="auto" during local dev.
+  const repoRoot = path.resolve(PACKAGE_ROOT, '../..');
+  const pkgJsonPath = path.resolve(repoRoot, 'package.json');
+  if (fs.existsSync(pkgJsonPath)) {
+    const pkg = parseJsonFile(pkgJsonPath, 'root package.json');
+    const dep = pkg?.devDependencies?.[toolName];
+    if (typeof dep === 'string' && dep.trim()) {
+      return resolveSemverExact(dep);
+    }
+  }
+
+  return '';
+}
+
 function loadToolingBaseline() {
   const toolingBaselinePath = TOOLING_BASELINE_CANDIDATE_PATHS.find(
     (candidatePath) => {
@@ -117,9 +146,7 @@ function loadToolingBaseline() {
   }
 
   const baseline = parseJsonFile(toolingBaselinePath, 'Tooling baseline file');
-  const prettierVersion = String(
-    baseline?.tools?.prettier?.version || '',
-  ).trim();
+  const prettierVersion = resolveToolVersionFromDevDeps(baseline, 'prettier');
 
   if (!prettierVersion) {
     console.error(

package/bin/command/sync-git/index.mjs

@@ -116,6 +116,35 @@ function getRequiredToolkitDevDependency() {
   return version;
 }
 
+function resolveSemverExact(text) {
+  return text.replace(/^[\^~>=<]+\s*/, '').trim();
+}
+
+function resolveToolVersionFromDevDeps(baseline, toolName) {
+  // If baseline has a concrete version (not "auto"), use it directly.
+  // This is the case when reading the published publish-assets baseline.
+  const baselineVersion = String(
+    baseline?.tools?.[toolName]?.version || '',
+  ).trim();
+  if (baselineVersion && baselineVersion !== 'auto') {
+    return baselineVersion;
+  }
+
+  // Fall back to resolving from local root package.json devDependencies.
+  // This covers source baseline with version="auto" during local dev.
+  const repoRoot = path.resolve(PACKAGE_ROOT, '../..');
+  const pkgJsonPath = path.resolve(repoRoot, 'package.json');
+  if (fs.existsSync(pkgJsonPath)) {
+    const pkg = parseJsonFile(pkgJsonPath, 'root package.json');
+    const dep = pkg?.devDependencies?.[toolName];
+    if (typeof dep === 'string' && dep.trim()) {
+      return resolveSemverExact(dep);
+    }
+  }
+
+  return '';
+}
+
 function loadToolingBaseline() {
   const toolingBaselinePath = TOOLING_BASELINE_CANDIDATE_PATHS.find(
     (candidatePath) => {
@@ -134,8 +163,8 @@ function loadToolingBaseline() {
   }
 
   const baseline = parseJsonFile(toolingBaselinePath, 'Tooling baseline file');
-  const huskyVersion = String(baseline?.tools?.husky?.version || '').trim();
-  const lernaVersion = String(baseline?.tools?.lerna?.version || '').trim();
+  const huskyVersion = resolveToolVersionFromDevDeps(baseline, 'husky');
+  const lernaVersion = resolveToolVersionFromDevDeps(baseline, 'lerna');
 
   if (!huskyVersion || !lernaVersion) {
     console.error(

package/bin/command/sync-lint/index.mjs

@@ -128,16 +128,38 @@ function getRequiredEslintDevDependencies() {
     eslintRulesVersion = v;
   }
 
+  function resolveSemverExact(text) {
+    return text.replace(/^[\^~>=<]+\s*/, '').trim();
+  }
+
+  function resolveToolVersionFromDevDeps(name) {
+    // If baseline has a concrete version (not "auto"), use it directly.
+    // This is the case when reading the published publish-assets baseline.
+    const entry = baseline?.tools?.[name];
+    const v = typeof entry?.version === 'string' ? entry.version.trim() : '';
+    if (v && v !== 'auto') {
+      return v;
+    }
+
+    // Fall back to resolving from local root package.json devDependencies.
+    // This covers source baseline with version="auto" during local dev.
+    const repoRoot = path.resolve(PACKAGE_ROOT, '../..');
+    const pkgJsonPath = path.resolve(repoRoot, 'package.json');
+    if (fs.existsSync(pkgJsonPath)) {
+      const pkg = parseJsonFile(pkgJsonPath, 'root package.json');
+      const dep = pkg?.devDependencies?.[name];
+      if (typeof dep === 'string' && dep.trim()) {
+        return resolveSemverExact(dep);
+      }
+    }
+
+    return '';
+  }
+
   const deps = { [ESLINT_RULES_PACKAGE_NAME]: eslintRulesVersion };
 
   for (const name of ESLINT_TOOLING_PACKAGE_NAMES) {
-    const entry = baseline?.tools?.[name];
-    const v =
-      typeof entry?.version === 'string'
-        ? entry.version.trim()
-        : /* c8 ignore next */
-        '';
-    /* c8 ignore next 6 */
+    const v = resolveToolVersionFromDevDeps(name);
     if (!v) {
       console.error(
         `Tooling baseline tools["${name}"].version must be a non-empty string: ${toolingBaselinePath}`,

package/bin/command/sync-typescript/help.txt

@@ -0,0 +1,14 @@
+Usage:
+  agent-toolkit sync-typescript --package-root <pkg> [--cwd <dir>]
+    [--check] [--dry-run] [--json <file>]
+
+Behavior:
+  - Creates a tsconfig.json for a sub-package that extends the root
+    tsconfig.json with the correct relative path
+  - If tsconfig.json already exists, skips without modifying
+
+Rules:
+  - --package-root is required
+  - --check validates without writing and exits non-zero if file is missing
+  - --dry-run prints planned changes without writing
+  - --check takes precedence over --dry-run

package/bin/command/sync-typescript/index.mjs

@@ -0,0 +1,154 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { getSingle, hasFlag } from '../shared/args.mjs';
+import { printTextResource } from '../shared/text-resource.mjs';
+
+const COMMAND_DIR = path.dirname(fileURLToPath(import.meta.url));
+const HELP_FILE = path.resolve(COMMAND_DIR, 'help.txt');
+const TSCONFIG_FILE = 'tsconfig.json';
+
+const PACKAGE_TSCONFIG_TEMPLATE = {
+  compilerOptions: {
+    lib: ['ESNext'],
+    types: ['node'],
+    strictNullChecks: true,
+    allowJs: true,
+    noEmit: true,
+    module: 'NodeNext',
+  },
+};
+
+export function printSyncTypescriptHelp() {
+  printTextResource(HELP_FILE);
+}
+
+function readJsonIfExists(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function computeExtendsPath(packageRoot, repoRoot) {
+  const relative = path.relative(packageRoot, repoRoot);
+  const normalized = relative.replace(/\\/g, '/');
+  if (!normalized || normalized === '.') {
+    return './tsconfig.json';
+  }
+  return normalized.startsWith('..')
+    ? `${normalized}/tsconfig.json`
+    : `./${normalized}/tsconfig.json`;
+}
+
+export function runSyncTypescript(options) {
+  const cwd = path.resolve(getSingle(options, '--cwd', process.cwd()));
+  const check = hasFlag(options, '--check');
+  const dryRun = hasFlag(options, '--dry-run') && !check;
+  const jsonFile = getSingle(options, '--json', '');
+  const packageRoot = getSingle(options, '--package-root', '');
+  const mode = check ? 'check' : dryRun ? 'dry-run' : 'sync';
+
+  if (!packageRoot) {
+    console.error('--package-root is required');
+    process.exit(2);
+  }
+
+  if (!fs.existsSync(cwd)) {
+    console.error(`CWD does not exist: ${cwd}`);
+    process.exit(2);
+  }
+
+  const pkgDir = path.resolve(cwd, packageRoot);
+  if (!fs.existsSync(pkgDir)) {
+    console.error(`Package root does not exist: ${pkgDir}`);
+    process.exit(2);
+  }
+
+  const tsconfigPath = path.resolve(pkgDir, TSCONFIG_FILE);
+  const current = readJsonIfExists(tsconfigPath);
+  const fileExists = current !== null;
+
+  // If tsconfig.json already exists, skip without checking content
+  if (fileExists) {
+    const report = {
+      cwd,
+      mode,
+      ok: true,
+      tsconfigPath,
+      required: {
+        file: path.join(packageRoot, TSCONFIG_FILE),
+      },
+      status: {
+        fileExistsBefore: true,
+        mismatchesBefore: [],
+        fileExistsAfter: true,
+        mismatchesAfter: [],
+        updated: false,
+        skipped: true,
+      },
+    };
+
+    if (jsonFile) {
+      const outPath = path.resolve(cwd, jsonFile);
+      fs.mkdirSync(path.dirname(outPath), { recursive: true });
+      fs.writeFileSync(outPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+    }
+
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+
+  const expectedExtends = computeExtendsPath(pkgDir, cwd);
+  const expectedPkgConfig = {
+    extends: expectedExtends,
+    ...PACKAGE_TSCONFIG_TEMPLATE,
+  };
+
+  const plannedContent = `${JSON.stringify(expectedPkgConfig, null, 2)}\n`;
+
+  if (mode === 'sync') {
+    fs.writeFileSync(tsconfigPath, plannedContent, 'utf8');
+  }
+
+  const mismatches = [
+    {
+      file: path.join(packageRoot, TSCONFIG_FILE),
+      expected: JSON.stringify(expectedPkgConfig, null, 2),
+      actual: 'missing',
+    },
+  ];
+
+  const report = {
+    cwd,
+    mode,
+    ok: mode !== 'check',
+    tsconfigPath,
+    required: {
+      file: path.join(packageRoot, TSCONFIG_FILE),
+    },
+    status: {
+      fileExistsBefore: false,
+      mismatchesBefore: mismatches,
+      fileExistsAfter: mode === 'sync',
+      mismatchesAfter: mode === 'sync' ? [] : mismatches,
+      updated: mode === 'sync',
+    },
+  };
+
+  if (jsonFile) {
+    const outPath = path.resolve(cwd, jsonFile);
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+  }
+
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) {
+    process.exit(2);
+  }
+}

package/package.json

@@ -1,36 +1,36 @@
 {
-  "name": "@produck/agent-toolkit",
-  "version": "0.9.2",
-  "description": "Central CLI toolkit for organization AI execution workflows",
-  "type": "module",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/produck/.github.git",
-    "directory": "packages/agent-toolkit"
-  },
   "bin": {
     "agent-toolkit": "bin/agent-toolkit.mjs"
   },
-  "scripts": {
-    "prepack": "node ./bin/build-publish-assets.mjs",
-    "test": "node test/index.mjs",
-    "produck:coverage": "c8 --reporter=lcov --reporter=html --reporter=text-summary npm test",
-    "produck:lint": "eslint --fix . --max-warnings=0"
+  "description": "Central CLI toolkit for organization AI execution workflows",
+  "devDependencies": {
+    "@produck/eslint-rules": "^0.4.1",
+    "c8": "11.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
   },
   "files": [
     "bin",
     "publish-assets"
   ],
+  "license": "MIT",
+  "name": "@produck/agent-toolkit",
   "publishConfig": {
     "access": "public"
   },
-  "engines": {
-    "node": ">=18.0.0"
+  "repository": {
+    "directory": "packages/agent-toolkit",
+    "type": "git",
+    "url": "git+https://github.com/produck/.github.git"
   },
-  "license": "MIT",
-  "devDependencies": {
-    "@produck/eslint-rules": "^0.4.0",
-    "c8": "11.0.0"
+  "scripts": {
+    "prepack": "node ./bin/build-publish-assets.mjs",
+    "produck:coverage": "c8 --reporter=lcov --reporter=html --reporter=text-summary npm test",
+    "produck:lint": "eslint --fix . --max-warnings=0",
+    "test": "node test/index.mjs"
   },
-  "gitHead": "aa9500630476fb423720f0b0056096e0e87e4c21"
+  "type": "module",
+  "version": "0.10.0",
+  "gitHead": "d0d432838dddbbc90f340b525bdd41153f8e6502"
 }

package/publish-assets/instructions/produck/00-produck-base.instructions.md

@@ -32,12 +32,12 @@ repositories:
   - `.github/copilot-instructions.md` — repository-specific exceptions and
     stricter local constraints.
 
-Editing rule (upstream only):
+Editing rule:
 
 - Update downstream baseline rules directly in
   `.github/distribution/produck/*.instructions.md`.
-- Add organization-only governance under
-  `.github/instructions/produck/` only when it must not be distributed.
+- For internal-only governance (this repo only, not distributed), add files
+  under `.github/instructions/produck/`.
 
 ## Default expectations
 

package/publish-assets/instructions/produck/10-produck-node.instructions.md

@@ -53,16 +53,8 @@ Notes:
   - Use central remediation command to deploy root lint script/config and
     eslint integration baseline:
     `npm exec -- agent-toolkit sync-lint --cwd .`.
-  - `c8` execution baseline for deployed coverage scripts is fixed to the
-    version specified in `tooling-version-baseline.json`.
   - Downstream repositories must not use unversioned `npx c8` or `c8@latest`
     in shared scripts/CI.
-  - Root local governance must pin `devDependencies.c8`,
-    `devDependencies.husky`, `devDependencies.lerna`, and
-    `devDependencies.@produck/agent-toolkit` via
-    `agent-toolkit sync-git`.
-  - Root local governance must pin `devDependencies.@produck/eslint-rules`
-    via `agent-toolkit sync-lint`.
 
 - Testing strategy and framework are repository-defined.
 - `verify` scripts are optional repository-local health checks and are not
@@ -78,43 +70,14 @@ Notes:
 - Commit prechecks still require passing repository style gates (for example
   `produck:format` and `produck:lint`).
 
-Central toolkit command role model:
-
-- `agent-toolkit sync-instructions` is guidance-first distribution for
-  organization baseline instructions.
-- `sync-instructions` is not a hard gate; use it to reduce instruction drift,
-  but do not assume it can fully prevent AI hallucination or iterative drift.
-- `agent-toolkit preflight` is the hard guard for organization engineering
-  baseline and is mandatory for required baseline checks.
-- `agent-toolkit sync-install` is the hard guard for root install script
-  governance and is mandatory in monorepo mode.
-- `agent-toolkit sync-coverage` is the hard guard for monorepo coverage
-  governance and is mandatory in monorepo mode.
-- `agent-toolkit sync-git` is the hard guard for local anti-drift hook
-  governance and is mandatory in monorepo mode.
-- `agent-toolkit sync-format` is the hard guard for root format
-  script/config governance and is mandatory in monorepo mode.
-- `agent-toolkit sync-lint` is the hard guard for root lint
-  script/config and eslint integration governance and is mandatory in monorepo
-  mode.
-- `agent-toolkit sync-publish` is the hard guard for root publish script
-  governance when `lerna.json` is present.
-- For simplified downstream execution of mandatory flow (1 -> 2 -> ... -> 9),
-  use:
-  `npm exec -- agent-toolkit`.
-- Equivalent explicit form:
+Enforcement:
+
+- For one-step execution of all mandatory checks, use:
   `npm exec -- agent-toolkit enforce-node-baseline --cwd .`.
-- `agent-toolkit validate-commit-msg` is a hard guard for AI-agent-authored
-  `git commit` and `git commit --amend` operations.
-- For human engineers, commit-message validation is recommended rather than
-  mandatory unless repository-specific hooks/CI enforce it.
-- Do not require retroactive rewrite/amend of historical commits solely to
-  satisfy commit-message validator rules.
-- `agent-toolkit run-capture` and `agent-toolkit summarize-log` are AI-agent
-  execution guardrails.
-- These guardrails pair with node-first execution policy: prefer Node.js
-  interpreter workflows for parsing/filtering over brittle OS-shell pipelines.
-- For human engineers, `run-capture` and `summarize-log` are optional helpers.
+- `agent-toolkit validate-commit-msg` is required for AI-agent-authored
+  `git commit` and `git commit --amend`.
+- For human engineers, commit-message validation is recommended.
+- Do not require retroactive rewrite/amend of historical commits.
 
 Test authoring baseline:
 
@@ -143,67 +106,164 @@ Team conventions for `.gitignore`:
 
 ## Monorepo mode
 
-Repository layout:
+### Repository layout
 
 - Root-level `docs/` is required.
 - Each package/app should contain its own `src/` and `test/`.
 
-Script placement:
+### Root `package.json` governance
+
+The root `package.json` exists only for development orchestration. It is
+never consumed as a downstream dependency, so runtime-oriented fields are
+prohibited.
+
+#### Required fields
+
+- `name` — A fixed name stabilizes the `name` field in `package-lock.json`.
+- `private`: `true` — Prevents accidental npm publish.
+- `workspaces` — Explicit path list only; see constraints below.
+- `scripts` — See [Required scripts](#required-scripts) section below.
+- `devDependencies` — The development materials manifest. Root
+  `devDependencies` is the single source of truth for organization-level and
+  repository-level tooling.
+
+#### Optional fields
+
+- `version` — Root is not published; version is meaningless.
+- `description` — Root is not published; description has no practical use.
+- `engines` — Not required. Leave this to Node.js version managers if
+  needed.
+
+#### Prohibited fields
+
+The following fields must never appear in root `package.json`:
+
+- `type`
+- `main`
+- `exports`
+- `types`
+- `files`
+- `publishConfig`
+- `dependencies`
+
+#### `workspaces` field constraints
+
+- Do not use wildcard/glob patterns (for example `packages/*`, `**`, `?`,
+  `{}` or `[]`).
+- List each workspace package path explicitly.
+
+### Required scripts
+
+Root `package.json` must define:
+
+| Script key              | Required value                                                                                    |
+| ----------------------- | ------------------------------------------------------------------------------------------------- |
+| `produck:install`       | `npm -v && npm install`                                                                           |
+| `prepare`               | `husky`                                                                                           |
+| `test`                  | Repository-defined (may use `--workspaces --if-present`)                                          |
+| `produck:coverage`      | Organization-defined via `agent-toolkit sync-coverage`                                            |
+| `produck:lint`          | Organization-defined via `agent-toolkit sync-lint`                                                |
+| `produck:format`        | Organization-defined via `agent-toolkit sync-format`                                              |
+| `produck:commit:check`  | `npm run produck:format && npm run produck:lint`                                                  |
+| `produck:baseline`      | `npm exec --package=@produck/agent-toolkit@latest -- agent-toolkit enforce-node-baseline --cwd .` |
+| `produck:publish`       | Required when `lerna.json` is present; governed by `agent-toolkit sync-publish`                   |
+| `produck:publish:check` | Required when `lerna.json` is present; governed by `agent-toolkit sync-publish`                   |
+
+Notes:
 
-- Root `package.json` must provide `produck:install`, `test`, `produck:coverage`,
-  and `produck:lint` orchestration scripts.
-- Root `package.json` must reserve `produck:commit:check` for organization
-  anti-drift gate with required value:
-  `npm run produck:format && npm run produck:lint`.
-- Root `package.json` must reserve `prepare` for husky setup with required
-  value: `husky`.
-- Root `package.json` must reserve `produck:format` and `produck:lint` for
-  organization-controlled format/lint gates.
-- Root `package.json` must reserve `produck:publish` for organization-controlled
-  publish gate when `lerna.json` is present (governed by
-  `agent-toolkit sync-publish`).
 - `publish` may be defined at root or package level based on release workflow.
-- Workspace subpackage `produck:coverage` scripts must be synchronized by
-  `agent-toolkit sync-coverage`.
-- Root local hook governance must be synchronized by
-  `agent-toolkit sync-git`.
-- Root local shared script governance must initialize
-  `scripts.produck:install` with required value `npm -v && npm install`
-  via `agent-toolkit sync-install`.
-- Root local format governance must be synchronized by
-  `agent-toolkit sync-format`.
-- Root local lint governance must be synchronized by
-  `agent-toolkit sync-lint`.
-- Root local shared script/dependency governance must pin root
-  `devDependencies.c8`,
-  `devDependencies.husky`, `devDependencies.lerna`,
-  `devDependencies.@produck/agent-toolkit` via
-  `agent-toolkit sync-git`.
-- Root local shared script/dependency governance must initialize
-  `scripts.produck:coverage` with workspace-level execution behavior:
-  attempt `test` on all workspace packages using `--workspaces --if-present`.
-- Root local shared script/dependency governance must initialize `.c8rc.json`
-  via `agent-toolkit sync-coverage`.
-- Root local format governance must initialize `.prettierrc` and
-  `scripts.produck:format` via `agent-toolkit sync-format`.
-- Root local lint governance must initialize `eslint.config.mjs`,
-  `scripts.produck:lint`, and `devDependencies.@produck/eslint-rules`
-  (including append-mode integration for existing eslint config) via
-  `agent-toolkit sync-lint`.
-- Root `package.json` must define a `produck:baseline` script for organization
-  baseline enforcement:
+- Remediation commands (run from root):
+  - `npm exec -- agent-toolkit sync-install --cwd .` — deploy root install script
+  - `npm exec -- agent-toolkit sync-coverage --cwd .` — deploy coverage scripts
+  - `npm exec -- agent-toolkit sync-git --cwd .` — deploy git hooks and deps
+  - `npm exec -- agent-toolkit sync-format --cwd .` — deploy format config
+  - `npm exec -- agent-toolkit sync-lint --cwd .` — deploy lint config
+
+### Workspace `package.json` governance
+
+#### Property restrictions
+
+Workspace-level `package.json` must NOT contain:
+
+- `private` — Package publication state is managed by the root workspace;
+  individual workspace packages should not declare it.
+- `workspaces` — Only the root `package.json` defines workspace paths.
+  Nested declarations violate the centralization principle.
+- Root orchestration scripts — These are the root `package.json`'s
+  responsibility and must not be duplicated in workspace packages:
+  `produck:install`, `produck:baseline`, `produck:commit:check`, `prepare`,
+  `produck:format`, `produck:publish`, `produck:publish:check`
+
+#### Recommended structure
+
+Workspace packages should keep their `package.json` lean, containing only:
+
+- Package metadata: `name`, `version`, `type`, `main`, `exports`, etc.
+- Dependencies: `dependencies`, `devDependencies`
+- Package-level scripts: `test`, `produck:coverage`
+
+#### Publish metadata governance
+
+Workspace packages that are published to npm must correctly declare the
+following fields. These control the package's npm registry page appearance and
+link back to the git hosting platform.
+
+**Required fields:**
+
+- `description` — Short summary shown on npm search results and package page.
+  Must be meaningful and accurate.
+- `license` — SPDX license identifier (for example `"MIT"`). Displayed on npm
+  package page.
+
+**Repository linkage fields** (affect npm "repository", "bugs", "homepage"
+links):
+
+- `repository` — Must use the expanded object form with `directory` to
+  identify the subpackage location within the monorepo:
   ```json
-  "produck:baseline": "npm exec --package=@produck/agent-toolkit@latest -- agent-toolkit enforce-node-baseline --cwd ."
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/produck/<repo>.git",
+    "directory": "packages/<name>"
+  }
   ```
+  The `url` value must match the repository's canonical git remote. The
+  `directory` value must be the package's workspace-relative path from the
+  monorepo root.
+- `bugs` — Must link to the GitHub issues page:
+  ```json
+  "bugs": {
+    "url": "https://github.com/produck/<repo>/issues"
+  }
+  ```
+- `homepage` — Must point to the package's README on the default branch, using
+  the `directory` form to navigate to the subpackage:
+  ```json
+  "homepage": "https://github.com/produck/<repo>/tree/main/packages/<name>#readme"
+  ```
+
+**Recommended fields:**
+
+- `keywords` — Array of strings that describe the package. Improves npm search
+  discoverability. Omit if the package has no meaningful keywords.
+
+**Rationale:**
+
+- Without `repository.directory`, npm links the repository field to the
+  monorepo root, which is not helpful for subpackage visitors.
+- Without `bugs`, npm omits the "Report issues" link on the package page.
+- Without `description`, npm shows "(not yet filled)" on the package page.
+- Invalid or missing `license` causes npm warnings during publish.
 
-Release tooling policy (required):
+### Release tooling policy
 
 - Monorepo release workflow must use `lerna`.
 - `lerna` execution version is governed at organization level, not per
   repository.
 - Source of truth for `lerna` version baseline:
   `.github/distribution/produck/tooling-version-baseline.json`.
-- Required execution baseline: version specified in `tooling-version-baseline.json`.
+- Required execution baseline: version specified in the
+  `tooling-version-baseline.json`.
 - Required invocation:
   `npm exec -- lerna <subcommand>`.
 - Downstream repositories must not use unversioned `npx lerna` or
@@ -212,34 +272,7 @@ Release tooling policy (required):
 - Keep an emergency organization-level rollback path when baseline version is
   updated.
 
-Root workspace `package.json` minimal baseline (required):
-
-- `private`: `true`
-- `workspaces` (explicit package path list only)
-- `scripts` with at least: `produck:install`, `test`, `produck:coverage`,
-  `produck:lint`
-- `publish` script is optional at root when release is managed per package or
-  by external workflow.
-
-`workspaces` field constraints (required):
-
-- Do not use wildcard/glob patterns (for example `packages/*`, `**`, `?`,
-  `{}` or `[]`).
-- List each workspace package path explicitly.
-
-Avoid unused root runtime/publish fields by default:
-
-- `type`
-- `main`
-- `exports`
-- `types`
-- `files`
-- `publishConfig`
-
-Add the fields above only when the monorepo root itself is an executable
-runtime package or is intentionally published.
-
-Ignore strategy:
+### Ignore strategy
 
 - Keep ignore rules centralized at repository root whenever possible.
 - Add package-level `.gitignore` only when a package has unique generated

package/publish-assets/instructions/produck/12-produck-test.instructions.md

@@ -52,6 +52,35 @@ import './feature-b.test.mjs';
 - Avoid global side effects that persist across test cases.
 - Clean up resources (temp files, open handles) at the end of each test case.
 
+## API usage conventions
+
+- Callback functions for `describe` and `it` MUST use arrow functions. Do not
+  use `function` keyword or method shorthand syntax.
+
+  Correct:
+
+  ```js
+  describe('my feature', () => {
+    it('should work', () => {
+      // assertions
+    });
+  });
+  ```
+
+  Wrong:
+
+  ```js
+  describe('my feature', function () {
+    it('should work', function () {
+      // assertions
+    });
+  });
+  ```
+
+- Deep nesting of `describe` blocks can make test output harder to read. When
+  nesting becomes excessive, split the test file and use `await import()` to
+  reorganize — this keeps the actual test code at shallow nesting levels.
+
 ## Naming conventions
 
 - Test files use the `.test.mjs` suffix.
@@ -59,6 +88,69 @@ import './feature-b.test.mjs';
   the module name or command name).
 - `it` labels should describe the expected behavior in plain language.
 
+### Suite name conventions
+
+The `describe` suite name encodes the member type under test using a prefix
+convention:
+
+| Prefix | Meaning                                              | Example                   |
+| ------ | ---------------------------------------------------- | ------------------------- |
+| `::`   | Class static public member or namespace static       | `describe('::parse()')`   |
+| `.`    | Class instance member                                | `describe('.validate()')` |
+| `()`   | Marks the target as a function (composable)          | `describe('::create()')`  |
+| `>`    | Return-value testing, nested inside a function suite | `describe('>result')`     |
+| `#`    | Event emitter — test event dispatch behavior         | `describe('#error')`      |
+
+Prefixes and `()` compose freely. For example:
+
+| Suite name    | Meaning                       |
+| ------------- | ----------------------------- |
+| `::parse()`   | Static function `parse`       |
+| `::VERSION`   | Static property `VERSION`     |
+| `.validate()` | Instance method `validate`    |
+| `.name`       | Instance property `name`      |
+| `validate()`  | Standalone function (unbound) |
+
+Examples:
+
+```js
+describe('::parse()', () => {
+  it('should parse valid input', () => {
+    /* ... */
+  });
+});
+
+describe('::VERSION', () => {
+  it('should be a semver string', () => {
+    /* ... */
+  });
+});
+
+describe('.validate()', () => {
+  it('should reject invalid data', () => {
+    /* ... */
+  });
+
+  describe('>result', () => {
+    it('should be a boolean', () => {
+      /* ... */
+    });
+  });
+});
+
+describe('.name', () => {
+  it('should be non-empty', () => {
+    /* ... */
+  });
+});
+
+describe('#error', () => {
+  it('should emit on failure', () => {
+    /* ... */
+  });
+});
+```
+
 ## Local debug workflow (recommended)
 
 When debugging a failing test case:

package/publish-assets/instructions/produck/15-produck-workspace.instructions.md

@@ -34,17 +34,14 @@ The Produck monorepo provides unified configuration across all packages for cons
 - If a repository overrides inherited rules, include only the deltas and
   document the rationale.
 
-**Usage in packages:**
+**Usage:**
 
-```javascript
-// packages/my-package/eslint.config.mjs
-import rootConfig from '../../eslint.config.mjs';
-
-export default [
-  ...rootConfig,
-  // Package-specific overrides here
-];
-```
+- Root `eslint.config.mjs` applies to all packages automatically via ESLint
+  flat config resolution — sub-packages are NOT required to create their own
+  `eslint.config.mjs`.
+- Sub-packages may create a package-level `eslint.config.mjs` on demand for
+  workspace-specific overrides, but this is opt-in and not proactively
+  deployed.
 
 ### 2. TypeScript Configuration (`tsconfig.json`, conditional)
 
@@ -59,24 +56,34 @@ export default [
 - If any package uses TypeScript source files or needs centralized strict/type
   options, create root `tsconfig.json` and let TypeScript packages extend it.
 
-**Recommended key settings when present:**
+**Governance (enforced by `agent-toolkit sync-typescript`):**
+
+Run `agent-toolkit sync-typescript --package-root packages/<name> --cwd .`
+to ensure a sub-package has a `tsconfig.json` that extends the root with the
+correct relative path and uses standard compiler options. If the file already
+exists, it is skipped without modification.
+
+**Enforced settings:**
 
 - Target: ES2022
 - Strict mode: enabled
-- Module resolution: node
+- Module resolution: bundler
 - Source maps: enabled
 - Declaration files: generated
 
-**Usage in TypeScript packages:**
+**Usage in TypeScript packages (auto-generated by `--package-root`):**
 
 ```json
 {
   "extends": "../../tsconfig.json",
   "compilerOptions": {
-    "outDir": "./dist"
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "test"]
+    "lib": ["ESNext"],
+    "types": ["node"],
+    "strictNullChecks": true,
+    "allowJs": true,
+    "noEmit": true,
+    "module": "NodeNext"
+  }
 }
 ```
 
@@ -161,32 +168,22 @@ npm run produck:coverage
 
 1. Create `packages/my-package/` directory
 2. Create `packages/my-package/package.json` with workspace configuration
-3. Inherit root configs:
-   - ESLint: extend `../../eslint.config.mjs`
+3. Config inheritance:
+   - ESLint: root `eslint.config.mjs` applies automatically — package-level
+     `eslint.config.mjs` is opt-in and not proactively deployed.
    - TypeScript (when root `tsconfig.json` exists): extend
      `../../tsconfig.json`
    - Prettier: uses root `.prettierrc` automatically
 
 ### Package-Level Overrides
 
-Each package can extend/override shared config:
-
-**ESLint example:**
+Each package's specific needs should be handled within the root shared config
+whenever possible. Per-package ESLint config files are opt-in and not
+proactively deployed; sub-packages may create one on demand.
 
-```javascript
-import rootConfig from '../../eslint.config.mjs';
-import onlyWarn from 'eslint-plugin-only-warn';
-
-export default [
-  ...rootConfig,
-  {
-    plugins: { 'only-warn': onlyWarn },
-    rules: {
-      'custom-rule': 'warn', // package-specific override
-    },
-  },
-];
-```
+For TypeScript configuration, packages may extend root `tsconfig.json` (see
+[TypeScript Configuration](#2-typescript-configuration-tsconfigjson-conditional)
+above).
 
 ## .editorconfig
 

package/publish-assets/instructions/produck/20-produck-commit.instructions.md

@@ -191,6 +191,18 @@ Commit precheck gate (AI-agent required, human recommended):
 
 If validation fails, fix the message and rerun until it passes.
 
+## Workspace Draft Files
+
+AI agents **must not** create or organize commit message draft files (such as
+`.git/COMMIT_EDITMSG` snapshots, staged-message backups, or raw draft text
+files) anywhere in the working tree.
+
+**Exception**: draft files are allowed if the filename matches the
+`*.ign*` glob pattern (for example `commit-msg.ign` or
+`message.draft.ignore`). This ensures the file is covered by the
+organization-level `.gitignore` rules and will never be accidentally
+committed.
+
 ## Notes
 
 - Keep the summary concise and specific.

package/publish-assets/instructions/produck/tooling-version-baseline.json

@@ -1,79 +1,84 @@
 {
+  "coverage": {
+    "scriptTemplate": "c8 --reporter=lcov --reporter=html --reporter=text-summary npm test"
+  },
+  "enforce": {
+    "sharedScriptsDisallow": [
+      "npx c8",
+      "c8@latest",
+      "npx lerna",
+      "lerna@latest",
+      "npx prettier",
+      "prettier@latest"
+    ]
+  },
   "schemaVersion": 1,
-  "updatedAt": "2026-05-12",
   "tools": {
-    "c8": {
-      "version": "11.0.0",
+    "@eslint/config-helpers": {
+      "allowLatest": false,
       "policy": "pinned",
-      "allowLatest": false
+      "version": "0.6.0"
     },
-    "husky": {
-      "version": "9.1.7",
+    "@eslint/js": {
+      "allowLatest": false,
       "policy": "pinned",
-      "allowLatest": false
+      "version": "10.0.1"
     },
-    "lerna": {
-      "version": "9.0.7",
+    "@eslint/json": {
+      "allowLatest": false,
       "policy": "pinned",
-      "allowLatest": false
+      "version": "1.2.0"
     },
-    "prettier": {
-      "version": "3.8.3",
+    "@eslint/markdown": {
+      "allowLatest": false,
       "policy": "pinned",
-      "allowLatest": false
+      "version": "8.0.2"
     },
-    "eslint": {
-      "version": "10.4.0",
+    "@types/node": {
+      "allowLatest": false,
       "policy": "pinned",
-      "allowLatest": false
+      "version": "22.19.19"
     },
-    "@eslint/js": {
-      "version": "10.0.1",
+    "c8": {
+      "allowLatest": false,
       "policy": "pinned",
-      "allowLatest": false
+      "version": "11.0.0"
     },
-    "@eslint/json": {
-      "version": "1.2.0",
+    "eslint": {
+      "allowLatest": false,
       "policy": "pinned",
-      "allowLatest": false
+      "version": "10.4.0"
     },
-    "@eslint/markdown": {
-      "version": "8.0.1",
+    "globals": {
+      "allowLatest": false,
       "policy": "pinned",
-      "allowLatest": false
+      "version": "17.6.0"
     },
-    "@eslint/config-helpers": {
-      "version": "0.6.0",
+    "husky": {
+      "allowLatest": false,
       "policy": "pinned",
-      "allowLatest": false
+      "version": "9.1.7"
     },
-    "typescript-eslint": {
-      "version": "8.59.4",
+    "lerna": {
+      "allowLatest": false,
       "policy": "pinned",
-      "allowLatest": false
+      "version": "9.0.7"
     },
-    "globals": {
-      "version": "17.6.0",
+    "prettier": {
+      "allowLatest": false,
       "policy": "pinned",
-      "allowLatest": false
+      "version": "3.8.3"
+    },
+    "typescript-eslint": {
+      "allowLatest": false,
+      "policy": "pinned",
+      "version": "8.60.0"
     },
     "@produck/eslint-rules": {
-      "version": "0.4.0",
+      "version": "0.4.1",
       "policy": "pinned",
       "allowLatest": false
     }
   },
-  "coverage": {
-    "scriptTemplate": "c8 --reporter=lcov --reporter=html --reporter=text-summary npm test"
-  },
-  "enforce": {
-    "sharedScriptsDisallow": [
-      "npx c8",
-      "c8@latest",
-      "npx lerna",
-      "lerna@latest",
-      "npx prettier",
-      "prettier@latest"
-    ]
-  }
+  "updatedAt": "2026-05-12"
 }

package/publish-assets/lerna.json

@@ -1,12 +1,12 @@
 {
   "$schema": "./node_modules/lerna/schemas/lerna-schema.json",
   "command": {
-    "version": {
-      "commitHooks": false
-    },
     "publish": {
       "ignoreScripts": false,
       "message": "[PUBLISH]"
+    },
+    "version": {
+      "commitHooks": false
     }
   },
   "useNx": false,

package/publish-assets/prettierrc

@@ -7,5 +7,13 @@
   "bracketSpacing": true,
   "arrowParens": "always",
   "printWidth": 80,
-  "endOfLine": "lf"
+  "endOfLine": "lf",
+  "overrides": [
+    {
+      "files": "*.json",
+      "options": {
+        "printWidth": 1
+      }
+    }
+  ]
 }