@produck/agent-toolkit 0.9.2 → 0.11.0

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.11.0",
+  "gitHead": "736364d5debd737ee92440818c9d0671db1c6974"
 }

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/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)
 
@@ -54,29 +51,49 @@ export default [
 
 **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`):**
+
+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.
 
-**Recommended key settings when present:**
+**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"
+  }
 }
 ```
 
@@ -88,7 +105,7 @@ export default [
 
 **Rules:**
 
-- Print width: 100 characters
+- Print width: 80 characters
 - Tab width: 2 spaces
 - Single quotes: true
 - Trailing commas: es5
@@ -161,32 +178,49 @@ 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:
+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.
 
-**ESLint example:**
+For TypeScript configuration, packages may extend root `tsconfig.json` (see
+[TypeScript Configuration](#2-typescript-configuration-tsconfigjson-conditional)
+above).
 
-```javascript
-import rootConfig from '../../eslint.config.mjs';
-import onlyWarn from 'eslint-plugin-only-warn';
+### Dependency Management in Downstream Repositories
 
-export default [
-  ...rootConfig,
-  {
-    plugins: { 'only-warn': onlyWarn },
-    rules: {
-      'custom-rule': 'warn', // package-specific override
-    },
-  },
-];
-```
+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