@produck/agent-toolkit 0.2.0 → 0.3.3

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

@@ -1,33 +1,19 @@
 ---
-applyTo: '**/*.{js,cjs,mjs,ts,tsx,json,yaml,yml}'
+applyTo: '**'
 ---
 
 <!-- managed-by: @produck/agent-toolkit -->
 <!-- source: .github/distribution/produck/10-produck-node.instructions.md -->
 
-# Node.js Initialization Baseline
-
-This document defines the organization-level initialization baseline for Node.js
-repositories.
+# Node.js Baseline (Monorepo + Standalone)
 
 ## Scope
 
-- Applies to all Node.js repositories in the `produck` organization, including
-  services, CLI tools, and script/tooling repositories.
-- Supports two repository modes: monorepo and standalone.
-
-## Mode selection
-
-- Monorepo mode: one repository contains multiple Node.js packages/apps.
-- Standalone mode: one repository represents one Node.js package/app.
-- Repository owners should declare the selected mode in the repository README.
-
-## Common baseline (all modes)
-
-- Node.js version policy: LTS required (no fixed major version at organization
-  level).
-- Package manager: npm only.
-- Module system: ESM by default (`"type": "module"` in `package.json`).
+- Applies to Node.js repositories in the organization.
+- Default package manager: npm.
+- Default language level: modern stable Node.js for current LTS.
+- Module system: ESM by default for executable/publishable Node.js packages
+  (`"type": "module"` in package-level `package.json`).
 - Follow the organization `.gitattributes` baseline (LF default for text files).
 - Follow the organization `.editorconfig` baseline.
 
@@ -35,7 +21,7 @@ Required script keys:
 
 - `deps:install`
 - `test`
-- `coverage`
+- `produck:coverage`
 - `lint`
 - `publish`
 
@@ -44,9 +30,62 @@ Notes:
 - Script key names are fixed and must match exactly.
 - `publish` may be a no-op when repository-specific release workflow does not
   use npm publishing.
+- Coverage governance policy:
+  - Keep the script key name `produck:coverage` (organization-reserved key).
+  - In monorepo mode, workspace subpackage `scripts.produck:coverage` and
+    workspace `devDependencies.c8` are fully governed by organization
+    baseline.
+  - Source of truth for tooling versions/template:
+    `.github/distribution/produck/tooling-version-baseline.json`.
+  - Use central remediation command to deploy coverage scripts:
+    `npm exec -- agent-toolkit sync-coverage-script --cwd .`.
+  - Use central remediation command to deploy local anti-drift hook baseline:
+    `npm exec -- agent-toolkit sync-husky-hooks --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 `devDependencies.c8` and root `devDependencies.lerna` must be pinned
+    to organization baseline fixed versions via `agent-toolkit sync-husky-hooks`.
 
 - Testing strategy and framework are repository-defined.
-- Repositories must keep `npm run test` and `npm run coverage` executable.
+- `test` script implementation is repository-defined and is not overwritten by
+  organization coverage remediation.
+- Repositories should keep `npm run test` and `npm run produck:coverage`
+  executable in steady state.
+- For intermediate commits, temporary non-executable state or failing tests are
+  allowed.
+- Commit prechecks still require passing repository style gates (for example
+  `format:check` and `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-coverage-script` is the hard guard for monorepo coverage
+  governance and is mandatory in monorepo mode.
+- `agent-toolkit sync-husky-hooks` is the hard guard for local anti-drift hook
+  governance and is mandatory in monorepo mode.
+- For simplified downstream execution of mandatory flow (1 -> 2 -> 3 -> 4),
+  use:
+  `npm exec -- agent-toolkit`.
+- Equivalent explicit form:
+  `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.
 
 Test authoring baseline (required):
 
@@ -114,9 +153,69 @@ Repository layout:
 
 Script placement:
 
-- Root `package.json` must provide `deps:install`, `test`, `coverage`, and
-  `lint` orchestration scripts.
+- Root `package.json` must provide `deps:install`, `test`, `produck:coverage`,
+  and `lint` orchestration scripts.
+- Root `package.json` must reserve `produck:precommit-check` for organization
+  anti-drift gate with required value:
+  `npm run format:check && npm run lint`.
+- Root `package.json` must reserve `prepare` for husky setup with required
+  value: `husky`.
 - `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-script`.
+- Root local hook governance must be synchronized by
+  `agent-toolkit sync-husky-hooks`.
+- Root local hook governance must pin root `devDependencies.c8`,
+  `devDependencies.husky`, `devDependencies.lerna`, and
+  `devDependencies.@produck/agent-toolkit` via
+  `agent-toolkit sync-husky-hooks`.
+- Root `package.json` must define a `produck:baseline` script for organization
+  baseline enforcement:
+  ```json
+  "produck:baseline": "npm exec --package=@produck/agent-toolkit@latest -- agent-toolkit enforce-node-baseline --cwd ."
+  ```
+
+Release tooling policy (required):
+
+- 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 invocation:
+  `npm exec -- lerna <subcommand>`.
+- Downstream repositories must not use unversioned `npx lerna` or
+  `lerna@latest` in shared scripts/CI.
+- For high-impact release commands, run dry-run/preview before publish.
+- 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: `deps:install`, `test`, `produck:coverage`, `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:
 
@@ -133,7 +232,12 @@ Repository layout:
 Script placement:
 
 - The repository root `package.json` must define `deps:install`, `test`,
-  `coverage`, `lint`, and `publish`.
+  `produck:coverage`, `lint`, and `publish`.
+- Root `package.json` must define a `produck:baseline` script for organization
+  baseline enforcement:
+  ```json
+  "produck:baseline": "npm exec --package=@produck/agent-toolkit@latest -- agent-toolkit enforce-node-baseline --cwd ."
+  ```
 
 Ignore strategy:
 

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

@@ -34,6 +34,12 @@ This document is maintained directly as a downstream-distributable source.
 - Semicolons: Always required (error)
 - Trailing commas: Always in multiline (error)
 - No inline config allowed: `noInlineConfig: true`
+- The listed ESLint rules can be satisfied either by explicit local
+  declarations or by inherited shared presets.
+- Repositories are not required to redeclare rules locally when those rules are
+  already provided by inherited presets.
+- If a repository overrides inherited rules, include only the deltas and
+  document the rationale.
 
 **Usage in packages:**
 
@@ -47,13 +53,20 @@ export default [
 ];
 ```
 
-### 2. TypeScript Configuration (`tsconfig.json`)
+### 2. TypeScript Configuration (`tsconfig.json`, conditional)
 
-**Location:** Root `tsconfig.json`
+**Location:** Root `tsconfig.json` (only when needed)
 
-**Applies to:** All TypeScript packages
+**Applies to:** TypeScript packages that opt in
 
-**Key settings:**
+**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.
+
+**Recommended key settings when present:**
 
 - Target: ES2022
 - Strict mode: enabled
@@ -61,7 +74,7 @@ export default [
 - Source maps: enabled
 - Declaration files: generated
 
-**Usage in packages:**
+**Usage in TypeScript packages:**
 
 ```json
 {
@@ -121,7 +134,7 @@ export default [
 ### Verification & Quality
 
 ```bash
-# Type check all packages
+# Type check all packages (optional: only when root tsconfig.json is present)
 npm run type-check
 
 # Format check without writing
@@ -140,19 +153,40 @@ npm run test
 npm run coverage
 ```
 
-### Package-Specific Commands
-
-```bash
-# Verify toolkit package
-npm run toolkit:verify
-
-# Verify eslint-rules package
-npm run eslint-rules:verify
-
-# Check package distributions
-npm run toolkit:pack-check
-npm run eslint-rules:pack-check
-```
+### Release & Coverage Tooling
+
+- Monorepo release workflow is `lerna`-based and required.
+- Source of truth for `lerna`/`c8` versions and coverage script template:
+  `.github/distribution/produck/tooling-version-baseline.json`.
+- `lerna` execution version is governed at organization level, not per
+  repository.
+- Required execution baseline: version specified in `tooling-version-baseline.json`.
+- Required `lerna` invocation:
+  `npm exec -- lerna <subcommand>`.
+- Shared scripts/CI must not use unversioned `npx lerna` or `lerna@latest`.
+- Wrapper scripts are allowed, but should keep parity with organization version
+  policy.
+- Workspace subpackage coverage scripts are fully organization-governed.
+- Deploy/repair coverage scripts via central remediation command:
+  `npm exec -- agent-toolkit sync-coverage-script --cwd .`.
+- Root anti-drift local hook baseline is organization-governed.
+- Deploy/repair root local hooks via central remediation command:
+  `npm exec -- agent-toolkit sync-husky-hooks --cwd .`.
+- Deployed coverage scripts use the `c8` version specified in
+  `tooling-version-baseline.json` for each governed workspace package.
+- Deployed local hook baseline uses the `husky` version specified in
+  `tooling-version-baseline.json` for root `devDependencies.husky`.
+- Deployed local hook baseline also pins root
+  `devDependencies.@produck/agent-toolkit` to the fixed version managed by the organization baseline.
+- Shared scripts/CI must not use unversioned `npx c8` or `c8@latest`.
+- `test` script implementation remains repository-defined and is not overwritten
+  by coverage remediation.
+- Root `devDependencies.c8` is pinned at root by `agent-toolkit sync-husky-hooks`;
+  workspace package `devDependencies.c8` is pinned per package by
+  `agent-toolkit sync-coverage-script`.
+- Root local hooks may be bypassed intentionally by developers (for example via
+  `--no-verify`) and are treated as local strong guardrails rather than
+  immutable release gates.
 
 ## Package Integration
 
@@ -162,7 +196,8 @@ npm run eslint-rules:pack-check
 2. Create `packages/my-package/package.json` with workspace configuration
 3. Inherit root configs:
    - ESLint: extend `../../eslint.config.mjs`
-   - TypeScript: extend `../../tsconfig.json`
+   - TypeScript (when root `tsconfig.json` exists): extend
+     `../../tsconfig.json`
    - Prettier: uses root `.prettierrc` automatically
 
 ### Package-Level Overrides
@@ -207,8 +242,8 @@ Applies to all editors supporting EditorConfig (VSCode, Vim, Sublime, etc.):
 - `typescript-eslint`: TypeScript linting support
 - `globals`: Global variables (browser, node)
 - `prettier`: Code formatter
-- `typescript`: TypeScript compiler
-- `@types/node`: Node.js type definitions
+- `typescript`: TypeScript compiler (when TypeScript is used)
+- `@types/node`: Node.js type definitions (when TypeScript is used)
 
 ### Peer Dependencies (Packages)
 
@@ -230,16 +265,13 @@ Root scripts are designed for CI pipelines:
 ```bash
 # Pre-commit checks
 npm run format:check
+# Optional when root tsconfig.json is used
 npm run type-check
 npm run lint
 
 # Testing
 npm run test
 npm run coverage
-
-# Package verification
-npm run toolkit:verify
-npm run eslint-rules:verify
 ```
 
 ## Best Practices
@@ -267,7 +299,7 @@ Root `.prettierrc` and `eslint.config.mjs` are synchronized. If conflict occurs:
 1. Check both configs have matching rules
 2. Run `npm run format` first, then `npm run lint`
 
-### TypeScript includes too many files
+### TypeScript includes too many files (when root tsconfig.json is used)
 
 Update `tsconfig.json` `include` and `exclude` patterns:
 

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

@@ -59,12 +59,6 @@ Allowed tags (fixed whitelist):
 - `[UPGRADE]`
 - `[PUBLISH]`
 
-Legacy-to-canonical mapping (for migration):
-
-- `[ADDED]` -> `[ADD]`
-- `[REMOVED]` -> `[REMOVE]`
-- `[FIXED]` -> `[FIX]`
-
 When using this style:
 
 - `TAG` must be uppercase and must be one of the allowed tags above.
@@ -163,8 +157,30 @@ Avoid vague or low-signal messages such as:
 
 Use the local validator before commit:
 
-- `npm exec --package=@produck/agent-toolkit@latest agent-toolkit
-validate-commit-msg --file <message-file>`
+- AI-agent-authored commits/amends:
+  validation is required before both `git commit` and `git commit --amend`.
+- For AI-agent-authored operations, do not create or amend a commit when
+  validation fails.
+- Human engineer-authored commits/amends:
+  validation is recommended by default and may be enforced by
+  repository-specific hooks/CI.
+- Do not require retroactive rewrite/amend of historical commits solely for
+  commit-message style compliance.
+
+Commit precheck gate (AI-agent required, human recommended):
+
+- For AI-agent-authored operations, complete repository style gates before both
+  `git commit` and `git commit --amend` (for example `format:check` and
+  `lint`).
+- For human engineer-authored operations, style gates are recommended baseline
+  practice unless repository-specific hooks/CI enforce them.
+- Temporary non-executable state or failing tests are allowed for
+  intermediate commits.
+- Test/coverage pass status is not a hard blocker at commit time.
+- Before merge or release, restore executable test commands and fix failing
+  tests.
+
+- `npm exec -- agent-toolkit validate-commit-msg --file <message-file>`
 
 If validation fails, fix the message and rerun until it passes.
 

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

@@ -0,0 +1,32 @@
+{
+  "schemaVersion": 1,
+  "updatedAt": "2026-05-12",
+  "tools": {
+    "c8": {
+      "version": "11.0.0",
+      "policy": "pinned",
+      "allowLatest": false
+    },
+    "husky": {
+      "version": "9.1.7",
+      "policy": "pinned",
+      "allowLatest": false
+    },
+    "lerna": {
+      "version": "9.0.7",
+      "policy": "pinned",
+      "allowLatest": false
+    }
+  },
+  "coverage": {
+    "scriptTemplate": "c8@{c8.version} --reporter=lcov --reporter=html --reporter=text-summary npm test"
+  },
+  "enforce": {
+    "sharedScriptsDisallow": [
+      "npx c8",
+      "c8@latest",
+      "npx lerna",
+      "lerna@latest"
+    ]
+  }
+}

package/templates/help/preflight.txt

@@ -1,3 +0,0 @@
-Usage:
-  agent-toolkit preflight [--cwd <dir>] [--require <path>] ...
-    [--ensure-dir <path>] ... [--json <file>]

package/templates/help/validate-commit-msg.txt

@@ -1,7 +0,0 @@
-Usage:
-  agent-toolkit validate-commit-msg --file <message-file>
-
-Rules:
-  - Every line must start with [TAG]
-  - No empty lines are allowed
-  - Optional target form: [TAG] <target>: <summary>