@produck/agent-toolkit 0.10.0 → 0.11.1

package/README.md

@@ -26,7 +26,7 @@ What it does (in order):
 6. Deploys root `.c8rc.json` and root `c8` devDependency
    **Note:** The `produck:coverage` script in subpackages is for local and AI development use only. It is NOT enforced by organization CI or `.c8rc.json`. Only the root workspace (monorepo root) is subject to org-level coverage enforcement and `.c8rc.json`.
 7. Deploys root `.gitattributes`
-8. Deploys the pinned `produck:coverage` script and `c8` devDependency to each workspace package, and enforces `scripts.test` (generates a default `test` script when missing).
+8. Deploys the pinned `produck:coverage` script to each workspace package and enforces `scripts.test` (generates a default `test` script when missing). Workspace packages rely on root-level c8 devDependency (hoisted by npm workspaces).
 9. Deploys `.husky/pre-commit` and `.husky/commit-msg`
 
 After running, add the persistent enforcement entry to the repository
@@ -90,11 +90,14 @@ failure:
    (`produck:baseline`, `produck:commit:check`) plus shared pinned root
    devDependencies (`husky`, `lerna`, `@produck/agent-toolkit`)
 8. `sync-coverage` — deploy root `scripts.produck:coverage`, `.c8rc.json`, and
-   root `c8` devDependency, then deploy pinned `produck:coverage` script and
-   `c8` devDependency into each workspace package, and ensure each workspace
-   package has `scripts.test` (auto-generate a default value when missing)
-9. `sync-publish` — create default `lerna.json` when missing and deploy root
-   `scripts.produck:publish:check` plus `scripts.produck:publish`
+   root `c8` devDependency (root-only; does not touch workspace packages)
+9. `sync-workspace` — deploy pinned `produck:coverage` script to each
+   workspace package and enforce `scripts.test` (auto-generate a default value
+   when missing). Workspace packages rely on root-level c8 devDependency
+   (hoisted by npm workspaces) and must not duplicate c8 in their own
+   `devDependencies`
+10. `sync-publish` — create default `lerna.json` when missing and deploy root
+    `scripts.produck:publish:check` plus `scripts.produck:publish`
 
 Add to downstream repository root `package.json` for one-command enforcement:
 

package/bin/agent-toolkit.mjs

@@ -46,6 +46,10 @@ import {
   printSyncTypescriptHelp,
   runSyncTypescript,
 } from './command/sync-typescript/index.mjs';
+import {
+  printSyncWorkspaceHelp,
+  runSyncWorkspace,
+} from './command/sync-workspace/index.mjs';
 import { hasFlag, parseCommonArgs } from './command/shared/args.mjs';
 import {
   printValidateCommitMsgHelp,
@@ -109,6 +113,10 @@ const COMMANDS = {
     printHelp: printSyncTypescriptHelp,
     run: runSyncTypescript,
   },
+  'sync-workspace': {
+    printHelp: printSyncWorkspaceHelp,
+    run: runSyncWorkspace,
+  },
 };
 
 const DEFAULT_COMMAND = 'enforce-node-baseline';

package/bin/command/enforce-node-baseline/help.txt

@@ -12,13 +12,14 @@ Behavior:
     5) sync-lint
     6) sync-install
     7) sync-git
-    8) sync-coverage
-    9) sync-publish
+    8) sync-coverage (root-level only)
+    9) sync-workspace (workspace packages, scripts only)
+   10) sync-publish
   - Stops at first failed step and exits non-zero
   - Prints one combined JSON report for all executed steps
 
 Rules:
-  - --check runs non-mutating validation mode for step 2, step 3, step 4, step 5, step 6, step 7, step 8, and step 9
-  - --dry-run runs non-mutating preview mode for step 2, step 3, step 4, step 5, step 6, step 7, step 8, and step 9
+  - --check runs non-mutating validation mode for step 2 through step 10
+  - --dry-run runs non-mutating preview mode for step 2 through step 10
   - --check takes precedence over --dry-run
-  - --workspace filters coverage sync targets in step 8
+  - --workspace filters workspace package targets in step 9

package/bin/command/enforce-node-baseline/index.mjs

@@ -168,6 +168,16 @@ export function runEnforceNodeBaseline(options) {
     syncEslintConfigArgs.push('--dry-run');
   }
 
+  const syncWorkspaceArgs = ['sync-workspace', '--cwd', cwd];
+  for (const workspacePath of workspaces) {
+    syncWorkspaceArgs.push('--workspace', workspacePath);
+  }
+  if (check) {
+    syncWorkspaceArgs.push('--check');
+  } else if (dryRun) {
+    syncWorkspaceArgs.push('--dry-run');
+  }
+
   const plan = [
     { name: 'preflight', args: preflightArgs },
     { name: 'sync-instructions', args: syncInstructionsArgs },
@@ -177,6 +187,7 @@ export function runEnforceNodeBaseline(options) {
     { name: 'sync-install', args: syncInstallArgs },
     { name: 'sync-git', args: syncGitArgs },
     { name: 'sync-coverage', args: syncCoverageArgs },
+    { name: 'sync-workspace', args: syncWorkspaceArgs },
     { name: 'sync-publish', args: syncPublishArgs },
   ];
 

package/bin/command/main/help.txt

@@ -5,14 +5,15 @@ agent-toolkit commands:
   summarize-log
   sync-coverage
   sync-editorconfig
-  sync-git
   sync-format
-  sync-typescript
+  sync-git
   sync-install
+  sync-instructions
   sync-lint
   sync-publish
+  sync-typescript
+  sync-workspace
   validate-commit-msg
-  sync-instructions
 
 Default:
   agent-toolkit

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

@@ -1,30 +1,15 @@
 Usage:
   agent-toolkit sync-coverage [--cwd <dir>]
-    [--workspace <path>] ... [--check] [--dry-run] [--json <file>]
+    [--check] [--dry-run] [--json <file>]
 
 Behavior:
-  - Adds or updates root scripts.produck:coverage, root .c8rc.json, and root devDependencies.c8.
-  - Adds or updates scripts.produck:coverage and devDependencies.c8 in each workspace package.json.
-  - Enforces scripts.test in each workspace package.json.
-  - If scripts.test is missing, generates:
-    node -e "console.log('No tests configured')"
-  - The produck:coverage script in subpackages is for local and AI development use only.
-  - Subpackage produck:coverage is NOT enforced by organization CI or .c8rc.json.
-  - Only the root workspace (monorepo root) is subject to org-level coverage enforcement and .c8rc.json.
+  - Adds or updates root scripts.produck:coverage, root .c8rc.json,
+    and root devDependencies.c8.
+  - Only the root workspace (monorepo root) is subject to org-level
+    coverage enforcement and .c8rc.json.
   - Organization-reserved script key is scripts.produck:coverage
-  - Target script is rendered from organization tooling baseline file
-    (lookup order):
-    1) .github/distribution/produck/tooling-version-baseline.json
-    2) publish-assets/instructions/produck/tooling-version-baseline.json
-  - Baseline template:
-    c8 --reporter=lcov --reporter=html --reporter=text-summary npm test
+  - c8 version is resolved from organization tooling baseline file
 
 Rules:
-  - When --workspace is omitted, root package.json workspaces are used
-  - Root workspaces must be explicit paths (no glob tokens)
-  - Workspace package.json files must include scripts.test
-  - Workspace package.json files must pin devDependencies.c8 to baseline version
-  - Subpackage produck:coverage is not a CI or org gate; it is for local/dev use only
-  - Only the root workspace is enforced by org CI and .c8rc.json
   - --check validates without writing and exits non-zero on mismatch
   - --dry-run prints planned changes without writing

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

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { getMulti, getSingle, hasFlag } from '../shared/args.mjs';
+import { getSingle, hasFlag } from '../shared/args.mjs';
 import { printTextResource } from '../shared/text-resource.mjs';
 
 const COMMAND_DIR = path.dirname(fileURLToPath(import.meta.url));
@@ -19,7 +19,6 @@ const TOOLING_BASELINE_CANDIDATE_PATHS = [
     'publish-assets/instructions/produck/tooling-version-baseline.json',
   ),
 ];
-const GLOB_TOKEN_PATTERN = /[*?{}[\]]/;
 const REQUIRED_ROOT_COVERAGE_SCRIPT_KEY = 'produck:coverage';
 const REQUIRED_ROOT_COVERAGE_SCRIPT_VALUE = [
   'c8',
@@ -28,10 +27,6 @@ const REQUIRED_ROOT_COVERAGE_SCRIPT_VALUE = [
   '--workspaces',
   '--if-present',
 ].join(' ');
-const REQUIRED_COVERAGE_SCRIPT_KEY = 'produck:coverage';
-const REQUIRED_TEST_SCRIPT_KEY = 'test';
-const DEFAULT_TEST_SCRIPT_VALUE =
-  'node -e "console.log(\'No tests configured\')"';
 const REQUIRED_C8_CONFIG_FILE = '.c8rc.json';
 const REQUIRED_C8_CONFIG_TEMPLATE_FILE = path.resolve(
   COMMAND_DIR,
@@ -127,12 +122,6 @@ function loadToolingBaseline() {
   };
 }
 
-function buildRequiredCoverageScript(baseline) {
-  const c8Version = String(baseline.tools.c8.version);
-  const coverageTemplate = String(baseline.coverage.scriptTemplate);
-  return coverageTemplate.replace(/\{c8\.version\}/g, c8Version);
-}
-
 function buildRequiredC8DevDependency(baseline) {
   return String(baseline.tools.c8.version);
 }
@@ -160,37 +149,6 @@ function loadRequiredC8ConfigContent() {
   return `${JSON.stringify(template, null, 2)}\n`;
 }
 
-function resolveWorkspacePaths(cwd, options) {
-  const manual = getMulti(options, '--workspace');
-  if (manual.length > 0) {
-    return manual;
-  }
-
-  const rootPackageJsonPath = path.resolve(cwd, 'package.json');
-  const rootPackageJson = parseJsonFile(
-    rootPackageJsonPath,
-    'Root package.json',
-  );
-  if (!Array.isArray(rootPackageJson.workspaces)) {
-    return [];
-  }
-
-  const workspaces = rootPackageJson.workspaces.map((entry) => String(entry));
-  if (workspaces.length === 0) {
-    return [];
-  }
-
-  const hasGlob = workspaces.some((entry) => GLOB_TOKEN_PATTERN.test(entry));
-  if (hasGlob) {
-    console.error(
-      'Root package.json `workspaces` must use explicit paths without glob tokens',
-    );
-    process.exit(2);
-  }
-
-  return workspaces;
-}
-
 function syncRootCoverage(
   cwd,
   mode,
@@ -274,130 +232,6 @@ function syncRootCoverage(
   };
 }
 
-function reconcileCoverageScript(
-  cwd,
-  workspacePath,
-  mode,
-  requiredCoverageScript,
-  requiredC8Version,
-) {
-  const packageDir = path.resolve(cwd, workspacePath);
-  const packageJsonPath = path.resolve(packageDir, 'package.json');
-
-  const result = {
-    workspacePath,
-    packageDir,
-    packageJsonPath,
-    exists: false,
-    validJson: false,
-    previousCoverage: null,
-    coverageScript: null,
-    previousTestScript: null,
-    testScript: null,
-    previousC8DevDependency: null,
-    c8DevDependency: null,
-    matchesRequiredCoverageBefore: false,
-    matchesRequiredCoverageAfter: false,
-    hasRequiredTestScriptBefore: false,
-    hasRequiredTestScriptAfter: false,
-    matchesRequiredC8DevDependencyBefore: false,
-    matchesRequiredC8DevDependencyAfter: false,
-    updated: false,
-    error: '',
-  };
-
-  if (!fs.existsSync(packageJsonPath)) {
-    result.error = `Workspace package.json does not exist: ${workspacePath}`;
-    return result;
-  }
-  result.exists = true;
-
-  let pkg;
-  try {
-    pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
-    result.validJson = true;
-  } catch {
-    result.error = `Workspace package.json is not valid JSON: ${workspacePath}`;
-    return result;
-  }
-
-  const scripts =
-    pkg.scripts &&
-    typeof pkg.scripts === 'object' &&
-    !Array.isArray(pkg.scripts)
-      ? { ...pkg.scripts }
-      : {};
-  const devDependencies =
-    pkg.devDependencies &&
-    typeof pkg.devDependencies === 'object' &&
-    !Array.isArray(pkg.devDependencies)
-      ? { ...pkg.devDependencies }
-      : {};
-
-  const previousCoverage =
-    typeof scripts[REQUIRED_COVERAGE_SCRIPT_KEY] === 'string'
-      ? scripts[REQUIRED_COVERAGE_SCRIPT_KEY]
-      : null;
-  const previousTestScript =
-    typeof scripts[REQUIRED_TEST_SCRIPT_KEY] === 'string' &&
-    scripts[REQUIRED_TEST_SCRIPT_KEY].trim() !== ''
-      ? scripts[REQUIRED_TEST_SCRIPT_KEY]
-      : null;
-  const previousC8DevDependency =
-    typeof devDependencies.c8 === 'string' ? devDependencies.c8 : null;
-  result.previousCoverage = previousCoverage;
-  result.previousTestScript = previousTestScript;
-  result.previousC8DevDependency = previousC8DevDependency;
-  result.matchesRequiredCoverageBefore =
-    previousCoverage === requiredCoverageScript;
-  result.hasRequiredTestScriptBefore = previousTestScript !== null;
-  result.matchesRequiredC8DevDependencyBefore =
-    previousC8DevDependency === requiredC8Version;
-
-  if (
-    (!result.matchesRequiredCoverageBefore ||
-      !result.hasRequiredTestScriptBefore ||
-      !result.matchesRequiredC8DevDependencyBefore) &&
-    mode === 'sync'
-  ) {
-    scripts[REQUIRED_COVERAGE_SCRIPT_KEY] = requiredCoverageScript;
-    if (!result.hasRequiredTestScriptBefore) {
-      scripts[REQUIRED_TEST_SCRIPT_KEY] = DEFAULT_TEST_SCRIPT_VALUE;
-    }
-    devDependencies.c8 = requiredC8Version;
-    pkg.scripts = scripts;
-    pkg.devDependencies = devDependencies;
-    fs.writeFileSync(
-      packageJsonPath,
-      `${JSON.stringify(pkg, null, 2)}\n`,
-      'utf8',
-    );
-    result.updated = true;
-  }
-
-  result.coverageScript =
-    mode === 'sync' && !result.matchesRequiredCoverageBefore
-      ? requiredCoverageScript
-      : previousCoverage;
-  result.testScript =
-    mode === 'sync' && !result.hasRequiredTestScriptBefore
-      ? DEFAULT_TEST_SCRIPT_VALUE
-      : previousTestScript;
-  result.c8DevDependency =
-    mode === 'sync' && !result.matchesRequiredC8DevDependencyBefore
-      ? requiredC8Version
-      : previousC8DevDependency;
-
-  result.matchesRequiredCoverageAfter =
-    result.updated || result.matchesRequiredCoverageBefore;
-  result.hasRequiredTestScriptAfter =
-    (mode === 'sync' && !result.hasRequiredTestScriptBefore) ||
-    result.hasRequiredTestScriptBefore;
-  result.matchesRequiredC8DevDependencyAfter =
-    result.updated || result.matchesRequiredC8DevDependencyBefore;
-  return result;
-}
-
 export function runSyncCoverage(options) {
   const cwd = path.resolve(getSingle(options, '--cwd', process.cwd()));
   const check = hasFlag(options, '--check');
@@ -405,7 +239,6 @@ export function runSyncCoverage(options) {
   const jsonFile = getSingle(options, '--json', '');
   const { baseline: toolingBaseline, toolingBaselinePath } =
     loadToolingBaseline();
-  const requiredCoverageScript = buildRequiredCoverageScript(toolingBaseline);
   const requiredC8Version = buildRequiredC8DevDependency(toolingBaseline);
   const requiredC8ConfigContent = loadRequiredC8ConfigContent();
 
@@ -421,7 +254,6 @@ export function runSyncCoverage(options) {
     requiredC8Version,
     requiredC8ConfigContent,
   );
-  const workspacePaths = resolveWorkspacePaths(cwd, options);
 
   const report = {
     cwd,
@@ -431,12 +263,8 @@ export function runSyncCoverage(options) {
       schemaVersion: toolingBaseline.schemaVersion,
       c8Version: toolingBaseline.tools.c8.version,
     },
-    requiredCoverageScript,
-    requiredTestScript: DEFAULT_TEST_SCRIPT_VALUE,
     requiredC8DevDependency: requiredC8Version,
     root,
-    workspaces: workspacePaths,
-    results: [],
     ok: true,
   };
 
@@ -449,32 +277,6 @@ export function runSyncCoverage(options) {
     report.ok = false;
   }
 
-  for (const workspacePath of workspacePaths) {
-    const effectiveMode = mode === 'sync' ? 'sync' : 'check';
-    const item = reconcileCoverageScript(
-      cwd,
-      workspacePath,
-      effectiveMode,
-      requiredCoverageScript,
-      requiredC8Version,
-    );
-    report.results.push(item);
-
-    if (item.error) {
-      report.ok = false;
-      continue;
-    }
-
-    if (
-      mode === 'check' &&
-      (!item.matchesRequiredCoverageAfter ||
-        !item.hasRequiredTestScriptAfter ||
-        !item.matchesRequiredC8DevDependencyAfter)
-    ) {
-      report.ok = false;
-    }
-  }
-
   if (jsonFile) {
     const outPath = path.resolve(cwd, jsonFile);
     fs.mkdirSync(path.dirname(outPath), { recursive: true });

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

@@ -10,7 +10,7 @@ Behavior:
 - Sync mode applies organization-required root publish scripts:
   - scripts.produck:publish:check = npm run produck:install && npm run produck:format && npm run produck:lint && npm run produck:coverage
   - scripts.produck:publish = npm run produck:publish:check && npm run publish --
-    when scripts.publish exists; otherwise it falls back to lerna publish
+  - If scripts.publish is missing, defaults to "lerna publish"
   - Enforces lerna.json command.version.commitHooks = false so publish/version commits skip git commit hooks
 
 Rules:

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

@@ -26,6 +26,8 @@ const REQUIRED_PUBLISH_SCRIPT_VALUE = [
   'npm run produck:publish:check',
   'npm run publish --',
 ].join(' && ');
+const REQUIRED_ROOT_PUBLISH_SCRIPT_KEY = 'publish';
+const REQUIRED_ROOT_PUBLISH_SCRIPT_VALUE = 'lerna publish';
 const REQUIRED_LERNA_VERSION_COMMIT_HOOKS = false;
 
 export function printSyncPublishHelp() {
@@ -175,31 +177,49 @@ export function runSyncPublish(options) {
     typeof scripts[REQUIRED_PUBLISH_SCRIPT_KEY] === 'string'
       ? scripts[REQUIRED_PUBLISH_SCRIPT_KEY]
       : null;
+  const previousRootPublish =
+    typeof scripts[REQUIRED_ROOT_PUBLISH_SCRIPT_KEY] === 'string' &&
+    scripts[REQUIRED_ROOT_PUBLISH_SCRIPT_KEY].trim() !== ''
+      ? scripts[REQUIRED_ROOT_PUBLISH_SCRIPT_KEY]
+      : null;
 
   const matchesRequiredPublishCheck =
     previousPublishCheck === REQUIRED_PUBLISH_CHECK_SCRIPT_VALUE;
   const matchesRequiredPublish =
     previousPublish === REQUIRED_PUBLISH_SCRIPT_VALUE;
+  const hasRequiredRootPublishBefore = previousRootPublish !== null;
   const lernaRequiresCreation = !lernaExistedBefore && !lernaDefaultCreated;
   const requiresUpdate =
     !matchesRequiredPublishCheck ||
     !matchesRequiredPublish ||
     lernaRequiresCreation ||
-    !matchesRequiredLernaCommitHooks;
-
-  if (
-    mode === 'sync' &&
-    (!matchesRequiredPublishCheck || !matchesRequiredPublish)
-  ) {
-    scripts[REQUIRED_PUBLISH_CHECK_SCRIPT_KEY] =
-      REQUIRED_PUBLISH_CHECK_SCRIPT_VALUE;
-    scripts[REQUIRED_PUBLISH_SCRIPT_KEY] = REQUIRED_PUBLISH_SCRIPT_VALUE;
-    pkg.scripts = scripts;
-    fs.writeFileSync(
-      rootPackageJsonPath,
-      `${JSON.stringify(pkg, null, 2)}\n`,
-      'utf8',
-    );
+    !matchesRequiredLernaCommitHooks ||
+    !hasRequiredRootPublishBefore;
+
+  if (mode === 'sync') {
+    let needsWrite = false;
+
+    if (!matchesRequiredPublishCheck || !matchesRequiredPublish) {
+      scripts[REQUIRED_PUBLISH_CHECK_SCRIPT_KEY] =
+        REQUIRED_PUBLISH_CHECK_SCRIPT_VALUE;
+      scripts[REQUIRED_PUBLISH_SCRIPT_KEY] = REQUIRED_PUBLISH_SCRIPT_VALUE;
+      needsWrite = true;
+    }
+
+    if (!hasRequiredRootPublishBefore) {
+      scripts[REQUIRED_ROOT_PUBLISH_SCRIPT_KEY] =
+        REQUIRED_ROOT_PUBLISH_SCRIPT_VALUE;
+      needsWrite = true;
+    }
+
+    if (needsWrite) {
+      pkg.scripts = scripts;
+      fs.writeFileSync(
+        rootPackageJsonPath,
+        `${JSON.stringify(pkg, null, 2)}\n`,
+        'utf8',
+      );
+    }
   }
 
   const report = {
@@ -232,6 +252,9 @@ export function runSyncPublish(options) {
         !matchesRequiredPublish && mode === 'sync'
           ? true
           : matchesRequiredPublish,
+      hasRequiredRootPublishBefore,
+      hasRequiredRootPublishAfter:
+        mode === 'sync' ? true : hasRequiredRootPublishBefore,
       updated: requiresUpdate && mode === 'sync',
     },
   };

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

@@ -0,0 +1,22 @@
+Usage:
+  agent-toolkit sync-workspace [--cwd <dir>]
+    [--workspace <path>] ... [--check] [--dry-run] [--json <file>]
+
+Behavior:
+  - Adds or updates scripts.produck:coverage in each workspace
+    package.json.
+  - Enforces scripts.test in each workspace package.json.
+  - If scripts.test is missing, generates:
+    node -e "console.log('No tests configured')"
+  - The produck:coverage script in workspaces relies on root-level
+    c8 devDependency (hoisted by npm workspaces).
+  - Organization-reserved script key is scripts.produck:coverage
+
+Rules:
+  - When --workspace is omitted, root package.json workspaces are used
+  - Single-level glob patterns (e.g. packages/*) are expanded automatically
+  - Recursive glob patterns (e.g. packages/**) are rejected
+  - Workspace packages must not duplicate root devDependencies;
+    c8 belongs in root package.json only
+  - --check validates without writing and exits non-zero on mismatch
+  - --dry-run prints planned changes without writing

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

@@ -0,0 +1,340 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { getMulti, 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 PACKAGE_ROOT = path.resolve(COMMAND_DIR, '../../..');
+const REPO_ROOT = path.resolve(PACKAGE_ROOT, '../..');
+const TOOLING_BASELINE_CANDIDATE_PATHS = [
+  path.resolve(
+    REPO_ROOT,
+    '.github/distribution/produck/tooling-version-baseline.json',
+  ),
+  path.resolve(
+    PACKAGE_ROOT,
+    'publish-assets/instructions/produck/tooling-version-baseline.json',
+  ),
+];
+const GLOB_TOKEN_PATTERN = /[*?{}[\]]/;
+const REQUIRED_COVERAGE_SCRIPT_KEY = 'produck:coverage';
+const REQUIRED_TEST_SCRIPT_KEY = 'test';
+const DEFAULT_TEST_SCRIPT_VALUE =
+  'node -e "console.log(\'No tests configured\')"';
+
+export function printSyncWorkspaceHelp() {
+  printTextResource(HELP_FILE);
+}
+
+function parseJsonFile(filePath, label) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    console.error(`${label} is not valid JSON: ${filePath}`);
+    process.exit(2);
+  }
+}
+
+function resolveSemverExact(text) {
+  return text.replace(/^[\^~>=<]+\s*/, '').trim();
+}
+
+function resolveToolVersionFromDevDeps(baseline, toolName) {
+  const baselineVersion = String(
+    baseline?.tools?.[toolName]?.version || '',
+  ).trim();
+  if (baselineVersion && baselineVersion !== 'auto') {
+    return baselineVersion;
+  }
+
+  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) => fs.existsSync(candidatePath),
+  );
+
+  if (!toolingBaselinePath) {
+    console.error(
+      'Tooling baseline file does not exist in expected locations:',
+    );
+    for (const candidatePath of TOOLING_BASELINE_CANDIDATE_PATHS) {
+      console.error(`- ${candidatePath}`);
+    }
+    process.exit(2);
+  }
+
+  const baseline = parseJsonFile(toolingBaselinePath, 'Tooling baseline file');
+  if (typeof baseline.schemaVersion !== 'number') {
+    console.error(
+      `Tooling baseline schemaVersion must be a number: ${toolingBaselinePath}`,
+    );
+    process.exit(2);
+  }
+
+  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}`,
+    );
+    process.exit(2);
+  }
+
+  const coverageTemplate = baseline?.coverage?.scriptTemplate;
+  if (typeof coverageTemplate !== 'string' || coverageTemplate.trim() === '') {
+    console.error(
+      `Tooling baseline coverage.scriptTemplate must be a non-empty string: ${toolingBaselinePath}`,
+    );
+    process.exit(2);
+  }
+
+  return { baseline, toolingBaselinePath };
+}
+
+function buildRequiredCoverageScript(baseline) {
+  const c8Version = String(baseline.tools.c8.version);
+  const coverageTemplate = String(baseline.coverage.scriptTemplate);
+  return coverageTemplate.replace(/\{c8\.version\}/g, c8Version);
+}
+
+function expandGlobPatterns(cwd, entries) {
+  const result = [];
+  for (const entry of entries) {
+    // Reject recursive glob patterns (**) as too dangerous to auto-expand
+    if (entry.includes('**')) {
+      console.error(
+        `Recursive glob pattern '${entry}' is not allowed in workspaces. ` +
+          'Use explicit paths or single-level globs (e.g. packages/*).',
+      );
+      process.exit(2);
+    }
+
+    const starIndex = entry.indexOf('*');
+    if (starIndex === -1) {
+      result.push(entry);
+      continue;
+    }
+
+    // entry is like "packages/*" → split at first *
+    const baseDir = entry.slice(0, starIndex);
+    const basePath = path.resolve(cwd, baseDir);
+
+    if (!fs.existsSync(basePath)) {
+      continue;
+    }
+
+    const dirEntries = fs.readdirSync(basePath, { withFileTypes: true });
+    const remainder = entry.slice(starIndex + 1);
+
+    for (const dirent of dirEntries) {
+      if (dirent.isDirectory()) {
+        const subpath = `${baseDir}${dirent.name}${remainder}`;
+        result.push(subpath);
+      }
+    }
+  }
+  return result.sort();
+}
+
+function resolveWorkspacePaths(cwd, options) {
+  const manual = getMulti(options, '--workspace');
+  if (manual.length > 0) {
+    return manual;
+  }
+
+  const rootPackageJsonPath = path.resolve(cwd, 'package.json');
+  const rootPackageJson = parseJsonFile(
+    rootPackageJsonPath,
+    'Root package.json',
+  );
+  if (!Array.isArray(rootPackageJson.workspaces)) {
+    return [];
+  }
+
+  const raw = rootPackageJson.workspaces.map((entry) => String(entry));
+  if (raw.length === 0) {
+    return [];
+  }
+
+  const hasGlob = raw.some((entry) => GLOB_TOKEN_PATTERN.test(entry));
+  if (hasGlob) {
+    return expandGlobPatterns(cwd, raw);
+  }
+
+  return raw;
+}
+
+function reconcileWorkspace(cwd, workspacePath, mode, requiredCoverageScript) {
+  const packageDir = path.resolve(cwd, workspacePath);
+  const packageJsonPath = path.resolve(packageDir, 'package.json');
+
+  const result = {
+    workspacePath,
+    packageDir,
+    packageJsonPath,
+    exists: false,
+    validJson: false,
+    previousCoverage: null,
+    coverageScript: null,
+    previousTestScript: null,
+    testScript: null,
+    matchesRequiredCoverageBefore: false,
+    matchesRequiredCoverageAfter: false,
+    hasRequiredTestScriptBefore: false,
+    hasRequiredTestScriptAfter: false,
+    updated: false,
+    error: '',
+  };
+
+  if (!fs.existsSync(packageJsonPath)) {
+    result.error = `Workspace package.json does not exist: ${workspacePath}`;
+    return result;
+  }
+  result.exists = true;
+
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    result.validJson = true;
+  } catch {
+    result.error = `Workspace package.json is not valid JSON: ${workspacePath}`;
+    return result;
+  }
+
+  const scripts =
+    pkg.scripts &&
+    typeof pkg.scripts === 'object' &&
+    !Array.isArray(pkg.scripts)
+      ? { ...pkg.scripts }
+      : {};
+
+  const previousCoverage =
+    typeof scripts[REQUIRED_COVERAGE_SCRIPT_KEY] === 'string'
+      ? scripts[REQUIRED_COVERAGE_SCRIPT_KEY]
+      : null;
+  const previousTestScript =
+    typeof scripts[REQUIRED_TEST_SCRIPT_KEY] === 'string' &&
+    scripts[REQUIRED_TEST_SCRIPT_KEY].trim() !== ''
+      ? scripts[REQUIRED_TEST_SCRIPT_KEY]
+      : null;
+  result.previousCoverage = previousCoverage;
+  result.previousTestScript = previousTestScript;
+  result.matchesRequiredCoverageBefore =
+    previousCoverage === requiredCoverageScript;
+  result.hasRequiredTestScriptBefore = previousTestScript !== null;
+
+  if (
+    (!result.matchesRequiredCoverageBefore ||
+      !result.hasRequiredTestScriptBefore) &&
+    mode === 'sync'
+  ) {
+    scripts[REQUIRED_COVERAGE_SCRIPT_KEY] = requiredCoverageScript;
+    if (!result.hasRequiredTestScriptBefore) {
+      scripts[REQUIRED_TEST_SCRIPT_KEY] = DEFAULT_TEST_SCRIPT_VALUE;
+    }
+    pkg.scripts = scripts;
+    fs.writeFileSync(
+      packageJsonPath,
+      `${JSON.stringify(pkg, null, 2)}\n`,
+      'utf8',
+    );
+    result.updated = true;
+  }
+
+  result.coverageScript =
+    mode === 'sync' && !result.matchesRequiredCoverageBefore
+      ? requiredCoverageScript
+      : previousCoverage;
+  result.testScript =
+    mode === 'sync' && !result.hasRequiredTestScriptBefore
+      ? DEFAULT_TEST_SCRIPT_VALUE
+      : previousTestScript;
+
+  result.matchesRequiredCoverageAfter =
+    result.updated || result.matchesRequiredCoverageBefore;
+  result.hasRequiredTestScriptAfter =
+    (mode === 'sync' && !result.hasRequiredTestScriptBefore) ||
+    result.hasRequiredTestScriptBefore;
+  return result;
+}
+
+export function runSyncWorkspace(options) {
+  const cwd = path.resolve(getSingle(options, '--cwd', process.cwd()));
+  const check = hasFlag(options, '--check');
+  const dryRun = hasFlag(options, '--dry-run');
+  const jsonFile = getSingle(options, '--json', '');
+  const { baseline: toolingBaseline, toolingBaselinePath } =
+    loadToolingBaseline();
+  const requiredCoverageScript = buildRequiredCoverageScript(toolingBaseline);
+
+  if (!fs.existsSync(cwd)) {
+    console.error(`CWD does not exist: ${cwd}`);
+    process.exit(2);
+  }
+
+  const mode = dryRun ? 'dry-run' : check ? 'check' : 'sync';
+  const workspacePaths = resolveWorkspacePaths(cwd, options);
+
+  const report = {
+    cwd,
+    mode,
+    toolingBaselinePath,
+    toolingBaseline: {
+      schemaVersion: toolingBaseline.schemaVersion,
+      c8Version: toolingBaseline.tools.c8.version,
+    },
+    requiredCoverageScript,
+    requiredTestScript: DEFAULT_TEST_SCRIPT_VALUE,
+    workspaces: workspacePaths,
+    results: [],
+    ok: true,
+  };
+
+  for (const workspacePath of workspacePaths) {
+    const effectiveMode = mode === 'sync' ? 'sync' : 'check';
+    const item = reconcileWorkspace(
+      cwd,
+      workspacePath,
+      effectiveMode,
+      requiredCoverageScript,
+    );
+    report.results.push(item);
+
+    if (item.error) {
+      report.ok = false;
+      continue;
+    }
+
+    if (
+      mode === 'check' &&
+      (!item.matchesRequiredCoverageAfter || !item.hasRequiredTestScriptAfter)
+    ) {
+      report.ok = false;
+    }
+  }
+
+  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

@@ -31,6 +31,6 @@
     "test": "node test/index.mjs"
   },
   "type": "module",
-  "version": "0.10.0",
-  "gitHead": "d0d432838dddbbc90f340b525bdd41153f8e6502"
+  "version": "0.11.1",
+  "gitHead": "6ed9aad7d47f4483bd865c15543ed0ca4d712d26"
 }

package/publish-assets/gitignore

@@ -138,3 +138,6 @@ dist
 
 # @produck/agent-toolkit
 publish-assets/
+
+# Ensure .github directory is not ignored by any existing rules
+!.github/

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

@@ -51,18 +51,28 @@ The Produck monorepo provides unified configuration across all packages for cons
 
 **Decision rule:**
 
-- If the workspace has no TypeScript source files and no package-level need for
-  shared TypeScript options, do not create/deploy root `tsconfig.json`.
-- If any package uses TypeScript source files or needs centralized strict/type
-  options, create root `tsconfig.json` and let TypeScript packages extend it.
+Root-level `tsconfig.json` is **not** recommended for downstream repositories.
+Prefer per-package `tsconfig.json` that stands alone.
+
+- Do **not** create/deploy root `tsconfig.json` unless there is a clear,
+  unavoidable need for centralized TypeScript configuration (e.g., a shared
+  path alias map or compound project references).
+- Each TypeScript package should manage its own `tsconfig.json` independently.
+- Only introduce root `tsconfig.json` when per-package duplication becomes a
+  proven maintenance burden — not as a proactive measure.
 
 **Governance (enforced by `agent-toolkit sync-typescript`):**
 
-Run `agent-toolkit sync-typescript --package-root packages/<name> --cwd .`
+When root `tsconfig.json` exists, 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.
 
+If no root `tsconfig.json` exists (the recommended default), each TypeScript
+package maintains its own standalone `tsconfig.json` with its own compiler
+options — no `extends` chain is needed.
+
 **Enforced settings:**
 
 - Target: ES2022
@@ -95,7 +105,7 @@ exists, it is skipped without modification.
 
 **Rules:**
 
-- Print width: 100 characters
+- Print width: 80 characters
 - Tab width: 2 spaces
 - Single quotes: true
 - Trailing commas: es5
@@ -185,6 +195,33 @@ For TypeScript configuration, packages may extend root `tsconfig.json` (see
 [TypeScript Configuration](#2-typescript-configuration-tsconfigjson-conditional)
 above).
 
+### Dependency Management in Downstream Repositories
+
+When a monorepo policy is distributed to a downstream repository, sub-package
+`devDependencies` must **not** duplicate workspace-level (root) devDependencies.
+
+**Rationale:**
+
+- Avoids version conflicts between root and sub-package declarations
+- Eliminates ambiguity about which declaration is the source of truth
+- Keeps sub-packages version-stable — root-level upgrades apply uniformly,
+  preventing drift across packages
+- Reduces `npm install` deduplication overhead and `lockfile` churn
+
+**Rule:**
+
+- Shared tooling (ESLint, Prettier, TypeScript, c8, test runners, build tools)
+  belongs in root `devDependencies` only.
+- Sub-packages may list only **package-specific** devDependencies that are not
+  already declared at root level.
+- In the downstream repository, sub-packages that extend root configs (e.g.,
+  `extends` in `tsconfig.json` or `eslint.config.mjs`) inherit their tooling
+  from root and must **not** redeclare those tools in their own
+  `devDependencies`.
+- When a downstream sub-package needs a different version of a root-level tool,
+  use root-level overrides (e.g., `overrides` or `resolutions` in root
+  `package.json`) rather than redeclaring in the sub-package.
+
 ## .editorconfig
 
 **Location:** Root `.editorconfig`

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

@@ -27,7 +27,7 @@
     "@eslint/json": {
       "allowLatest": false,
       "policy": "pinned",
-      "version": "1.2.0"
+      "version": "2.0.0"
     },
     "@eslint/markdown": {
       "allowLatest": false,
@@ -37,7 +37,7 @@
     "@types/node": {
       "allowLatest": false,
       "policy": "pinned",
-      "version": "22.19.19"
+      "version": "24.13.2"
     },
     "c8": {
       "allowLatest": false,
@@ -47,12 +47,12 @@
     "eslint": {
       "allowLatest": false,
       "policy": "pinned",
-      "version": "10.4.0"
+      "version": "10.6.0"
     },
     "globals": {
       "allowLatest": false,
       "policy": "pinned",
-      "version": "17.6.0"
+      "version": "17.7.0"
     },
     "husky": {
       "allowLatest": false,
@@ -67,12 +67,12 @@
     "prettier": {
       "allowLatest": false,
       "policy": "pinned",
-      "version": "3.8.3"
+      "version": "3.9.1"
     },
     "typescript-eslint": {
       "allowLatest": false,
       "policy": "pinned",
-      "version": "8.60.0"
+      "version": "8.62.0"
     },
     "@produck/eslint-rules": {
       "version": "0.4.1",