eslint-plugin-traceability 1.0.1 → 1.0.2

package/.github/workflows/ci-cd.yml

@@ -39,6 +39,9 @@ jobs:
       - name: Run tests with coverage
         run: npm run test
 
+      - name: Run CLI Integration Tests
+        run: node cli-integration.js
+
       - name: Check code formatting
         run: npm run format:check
 
@@ -76,3 +79,15 @@ jobs:
         run: npm publish --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  smoke-test:
+    name: Post-Deployment Smoke Test
+    needs: publish
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Install dependencies
+        run: npm ci
+      - name: Smoke Test Published Package
+        run: node cli-integration.js

package/.voder/history.md

@@ -1,164 +1,194 @@
-Here’s a concise history of what’s been accomplished in the project so far:
-
-1. Project Bootstrap  
-   • Initialized an npm-based TypeScript ESLint plugin (ES2020/CommonJS/strict) with src/ and tests/  
-   • Set up ESLint (flat), Prettier, Jest, tsconfig.json and npm scripts for build, type-check, lint, test, format, duplicate-code check, audit  
-
-2. Security & Quality-of-Code  
-   • Applied an npm-audit override for js-yaml prototype-pollution  
-   • Enforced ESLint complexity limits and integrated jscpd for duplicate code detection  
-   • Added .env.example and tightened package.json (peerDependencies, engines)  
-
-3. Custom ESLint Rules  
-   • Implemented require-story and branch-annotation rules covering all control flows  
-   • Scaffolded a valid-annotation-format rule with RuleTester unit tests  
-
-4. Build Artifacts & Git Hooks  
-   • Committed compiled lib/ artifacts to source control  
-   • Configured Husky + lint-staged: pre-commit runs format & lint; pre-push runs full build, checks, tests  
-
-5. Documentation  
-   • Authored docs/rules/*.md for each rule  
-   • Overhauled README (install, usage, examples, rule list)  
-   • Added CONTRIBUTING.md, CLI-integration and config-presets guides, ESLint-9 setup guide  
-   • Tuned Jest coverage thresholds and .prettierignore  
-
-6. CI & Plugin Infrastructure  
-   • Defined “recommended” and “strict” plugin configs  
-   • Set up GitHub Actions to run jscpd, build, type-check, lint, tests, format-check, audit  
-   • Added unit tests for index exports, registry, configs and end-to-end ESLint-CLI integration tests  
-
-7. Final Rules & CLI Integration  
-   • Implemented valid-story-reference and valid-req-reference (with existence checks, path-traversal protection, caching)  
-   • Registered new rules in src/index.ts and included them in plugin configs  
-   • Expanded CLI integration test coverage  
-
-8. Ongoing Maintenance & Release Preparation  
-   • Refined ESLint overrides, lint-staged patterns, Prettier ignores; limited CI node matrix to 18.x and 20.x  
-   • Prepared v0.1.0: created CHANGELOG.md, documented key rules, updated README’s “Available Rules,” tightened pre-commit hooks  
-
-9. Maintenance-Tools Module  
-   • Scaffolded utilities (detectStaleAnnotations, updateAnnotationReferences, etc.) with unit tests and shared file-traversal helpers  
-
-10. CLI Fixes & Emergency CI Patches  
-    • Adjusted CLI loader for dynamic paths and experimental-vm-modules support  
-    • Enhanced GitHub Actions with a release job, packaging verification, config tweaks, threshold ratcheting and ADR updates  
-    • Fixed CI failures (plugin resolution, Prettier, Codecov inputs), removed stray files, updated .gitignore  
-
-11. Emergency Pipeline Failure Resolutions  
-    • Diagnosed and fixed CI breakages in integration tests by tweaking experimental flags  
-    • Restricted release-job triggers to tags only and made audit failures block the build  
-    • Ignored .voder/ directory, aligned Husky pre-push hook with CI, and verified all local quality checks  
-
-12. Most Recent Changes  
-    • Removed “.voder/” from .gitignore and committed the .voder directory (tracking internal state/history)  
-    • Lowered ESLint thresholds: max-lines-per-function from 120→100, max-lines from 600→500 in eslint.config.js  
-    • Ran full quality suite (build, lint, type-check, duplication, tests, format-check, audit) locally—zero errors or warnings—and pushed all changes; CI is green.
+Here’s a concise recap of everything we’ve done so far, in chronological order:
+
+• Project Bootstrap  
+  – Initialized an npm-based TypeScript ESLint plugin (ES2020/CommonJS/strict) with `src/` and `tests/`  
+  – Configured ESLint (flat), Prettier, Jest, `tsconfig.json` and npm scripts for build, type-check, lint, test, format, duplicate-code check and audit  
+
+• Security & Code-Quality Hardening  
+  – Applied an npm-audit override for the js-yaml prototype-pollution issue  
+  – Enforced ESLint complexity limits and integrated jscpd for duplicate-code detection  
+  – Added `.env.example` and tightened `package.json` (peerDependencies, engines)  
+
+• Custom ESLint Rules  
+  – Built `require-story` and `branch-annotation` rules covering all control flows  
+  – Scaffolded `valid-annotation-format` with RuleTester unit tests  
+  – Later implemented `valid-story-reference` and `valid-req-reference` (with existence checks, path-traversal protection, caching) and registered them in plugin configs  
+
+• Build Artifacts & Git Hooks  
+  – Committed compiled `lib/` artifacts  
+  – Set up Husky + lint-staged: pre-commit runs format & lint; pre-push runs full build, checks, tests  
+
+• Documentation  
+  – Authored `docs/rules/*.md` for each rule  
+  – Overhauled `README` (install, usage, examples, rule list)  
+  – Added `CONTRIBUTING.md`, CLI-integration and config-presets guides, ESLint-9 setup guide  
+  – Tuned Jest coverage thresholds and `.prettierignore`  
+
+• CI & Plugin Infrastructure  
+  – Defined “recommended” and “strict” plugin configs  
+  – Configured GitHub Actions to run jscpd, build, type-check, lint, tests, format-check, audit  
+  – Added unit tests for index exports, registry, configs and end-to-end ESLint-CLI integration  
+
+• Release Preparation & Ongoing Maintenance  
+  – Refined ESLint overrides, lint-staged patterns, Prettier ignores; limited CI node matrix to 18.x & 20.x  
+  – Prepared v0.1.0: created `CHANGELOG.md`, documented key rules, updated README’s “Available Rules,” tightened pre-commit hooks  
+
+• Maintenance-Tools Module  
+  – Scaffolded utilities (`detectStaleAnnotations`, `updateAnnotationReferences`, etc.) with unit tests and shared file-traversal helpers  
+
+• CLI Fixes & Emergency CI Patches  
+  – Adjusted CLI loader for dynamic paths and experimental-vm-modules support  
+  – Enhanced GitHub Actions with a release job, packaging verification, threshold ratcheting and ADR updates  
+  – Fixed CI failures (plugin resolution, Prettier, Codecov inputs), removed stray files, updated `.gitignore`  
+
+• Emergency Pipeline Failure Resolutions  
+  – Diagnosed and fixed integration-test breakages by tweaking experimental flags  
+  – Restricted release-job triggers to tags only and enforced audit failures as build blockers  
+  – Ignored `.voder/` directory, aligned Husky pre-push hook with CI, verified all local quality checks  
+
+• Most Recent Changes  
+  – Committed `.voder/` directory to track internal state/history  
+  – Lowered ESLint thresholds (max-lines-per-function 120→100, max-lines 600→500)  
+  – Further tightened to 90 lines/function & 400 lines/file, refactored maintenance tests to use OS temp directories for isolation, enabled trailing commas in Prettier  
+  – Ran full quality suite (build, lint, type-check, duplication, tests, format-check, audit) locally and on CI—no errors or warnings, all pipelines green.
 
 **Most recently we've executed the following action:**
 
 ---
-Used tool: run_command with input: {"command":"npm","args":["run","lint","--","--format=json"]}
-Used tool: list_directory with input: {"dirPath":""}
 Used tool: list_directory with input: {"dirPath":"."}
-Used tool: read_file with input: {"filePath":"eslint.config.js"}
-Used tool: read_file with input: {"filePath":"tests/maintenance/detect.test.ts"}
-Used tool: search_file_content with input: {"filePath":"","pattern":"tests/fixtures"}
-Used tool: find_files with input: {"pattern":"detect*.test.ts","directory":"tests/maintenance"}
-Used tool: list_directory with input: {"dirPath":"tests/maintenance"}
-Used tool: read_file with input: {"filePath":"tests/maintenance/update.test.ts"}
-Used tool: read_file with input: {"filePath":"tests/maintenance/detect-isolated.test.ts"}
-Used tool: list_directory with input: {"dirPath":"tests/fixtures"}
-Used tool: read_file with input: {"filePath":"src/maintenance/batch.ts"}
-Used tool: modify_file with input: {"filePath":"eslint.config.js","instruction":"In ESLint configuration, update the max-lines-per-function and max-lines rules: change max-lines-per-function max from 100 to 90 and max-lines from 500 to 400 in both TS and JS rule blocks."}
-Used tool: run_command with input: {"command":"npm","args":["run","lint","--","--format=json"]}
-Used tool: search_file_content with input: {"filePath":".","pattern":"no-stale"}
-Used tool: check_file_exists with input: {"filePath":"tests/fixtures/no-stale"}
-Used tool: list_directory with input: {"dirPath":"tests/fixtures/update"}
-Used tool: read_file with input: {"filePath":"tests/maintenance/batch.test.ts"}
-Used tool: read_file with input: {"filePath":"tests/maintenance/report.test.ts"}
+Used tool: list_directory with input: {"dirPath":".github/workflows"}
 Used tool: read_file with input: {"filePath":"package.json"}
-Used tool: find_files with input: {"pattern":"*","directory":"tests/fixtures"}
-Used tool: search_file_content with input: {"filePath":".","pattern":"no-stale"}
-Used tool: run_command with input: {"command":"npm","args":["run","lint","--","--format=json"]}
-Used tool: search_file_content with input: {"filePath":"tests/maintenance/detect.test.ts","pattern":"tests/fixtures"}
-Used tool: find_files with input: {"pattern":"empty","directory":"tests/fixtures"}
-Used tool: read_file with input: {"filePath":"src/maintenance/report.ts"}
-Used tool: run_command with input: {"command":"npm","args":["test"]}
-Used tool: read_file with input: {"filePath":"tests/maintenance/update-isolated.test.ts"}
-Used tool: list_directory with input: {"dirPath":"tests/fixtures"}
-Used tool: read_file with input: {"filePath":"src/maintenance/update.ts"}
-Used tool: read_file with input: {"filePath":"src/maintenance/detect.ts"}
+Used tool: list_directory with input: {"dirPath":"src"}
+Used tool: read_file with input: {"filePath":"src/index.ts"}
+Used tool: read_file with input: {"filePath":".github/workflows/ci.yml"}
+Used tool: create_directory with input: {"dirPath":"user-docs"}
+Used tool: list_directory with input: {"dirPath":"docs"}
+Used tool: list_directory with input: {"dirPath":"docs/rules"}
+Used tool: read_file with input: {"filePath":"README.md"}
+Used tool: generate_file with input: {"filePath":"user-docs/api-reference.md","content":"# API Reference\n\n## Rules\n\nThe following ESLint rules are exposed by this plugin:\n\n- traceability/require-story-annotation\n- traceability/require-req-annotation\n- traceability/require-branch-annotation\n- traceability/valid-annotation-format\n- traceability/valid-story-reference\n- traceability/valid-req-reference\n\n## Configuration Presets\n\nThe plugin exposes two configuration presets:\n\n- `recommended`\n- `strict`\n"}
+Used tool: read_file with input: {"filePath":"docs/rules/require-story-annotation.md"}
+Used tool: read_file with input: {"filePath":"docs/config-presets.md"}
+Used tool: read_file with input: {"filePath":"docs/rules/require-branch-annotation.md"}
+Used tool: read_file with input: {"filePath":".github/workflows/deploy.yml"}
+Used tool: git_add_all with input: {}
+Used tool: git_commit with input: {"message":"chore: add skeleton user-docs/api-reference.md"}
+Used tool: read_file with input: {"filePath":"user-docs/api-reference.md"}
+Used tool: generate_file with input: {"filePath":"user-docs/api-reference.md","overwrite":true,"content":"# API Reference\n\nCreated autonomously by [voder.ai](https://voder.ai).\n\n## Rules\n\nEach rule enforces traceability conventions in your code. Below is a summary of each rule exposed by this plugin.\n\n### traceability/require-story-annotation\nDescription: Ensures every function declaration has a JSDoc comment with an `@story` annotation referencing the related user story.\nOptions: None\nDefault Severity: `error`\nExample:\n```javascript\n/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction initAuth() {\n  // authentication logic\n}\n```\n\n### traceability/require-req-annotation\nDescription: Ensures every function declaration has an `@req` annotation in its JSDoc, linking to the specific requirement.\nOptions: None\nDefault Severity: `error`\nExample:\n```javascript\n/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction initAuth() {\n  // authentication logic\n}\n```\n\n### traceability/require-branch-annotation\nDescription: Ensures significant code branches (if/else, loops, switch cases, try/catch) have both `@story` and `@req` annotations in preceding comments.\nOptions: None\nDefault Severity: `error`\nExample:\n```javascript\n// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md\n// @req REQ-BRANCH-DETECTION\nif (error) {\n  handleError();\n}\n```\n\n### traceability/valid-annotation-format\nDescription: Validates that all traceability annotations (`@story`, `@req`) follow the correct JSDoc or inline comment format.\nOptions: None\nDefault Severity: `error`\nExample:\n```javascript\n/**\n * @story docs/stories/005.0-DEV-VALIDATION.story.md\n * @req REQ-FORMAT-VALIDATION\n */\nfunction example() {\n  // ...\n}\n```\n\n### traceability/valid-story-reference\nDescription: Checks that the file paths in `@story` annotations point to existing story markdown files.\nOptions: None\nDefault Severity: `error`\nExample:\n```javascript\n/**\n * @story docs/stories/006.0-DEV-STORY-EXISTS.story.md\n * @req REQ-STORY-EXISTS\n */\nfunction example() {\n  // ...\n}\n```\n\n### traceability/valid-req-reference\nDescription: Verifies that the IDs used in `@req` annotations match known requirement identifiers.\nOptions: None\nDefault Severity: `error`\nExample:\n```javascript\n/**\n * @story docs/stories/007.0-DEV-REQ-REFERENCE.story.md\n * @req REQ-VALID-REFERENCE\n */\nfunction example() {\n  // ...\n}\n```\n\n## Configuration Presets\n\nThe plugin provides two built-in presets for easy configuration:\n\n### recommended\nEnables the core traceability rules at the `error` level.\nUsage:\n```javascript\nimport js from \"@eslint/js\";\nimport traceability from \"eslint-plugin-traceability\";\n\nexport default [\n  js.configs.recommended,\n  traceability.configs.recommended,\n];\n```\n\n### strict\nCurrently mirrors the **recommended** preset, reserved for future stricter policies.\nUsage:\n```javascript\nimport js from \"@eslint/js\";\nimport traceability from \"eslint-plugin-traceability\";\n\nexport default [\n  js.configs.recommended,\n  traceability.configs.strict,\n];\n```\n"}
+Used tool: git_add_all with input: {}
+Used tool: git_commit with input: {"message":"docs: add detailed API reference in user-docs/api-reference.md"}
+Used tool: modify_file with input: {"filePath":"README.md","instruction":"Insert links to user-docs/api-reference.md under documentation section; update README to reference the API reference and examples in user-docs directory. Add `## API Reference` section below `## Quick Start` with link, and `## Examples` section linking to user-docs/examples.md."}
 Used tool: git_add_all with input: {}
-Used tool: git_commit with input: {"message":"chore: adjust ESLint size thresholds to 90 lines/function and 400 lines/file"}
-Used tool: read_file with input: {"filePath":"tests/fixtures/stale/example.ts"}
+Used tool: git_commit with input: {"message":"docs: update README with links to API Reference and Examples"}
+Used tool: generate_file with input: {"filePath":"user-docs/examples.md","content":"# Examples\n\nCreated autonomously by [voder.ai](https://voder.ai).\n\nThis document provides runnable examples demonstrating how to use the `eslint-plugin-traceability` plugin in real-world scenarios.\n\n## 1. ESLint Flat Config with Recommended Preset\n\nCreate an ESLint config file (`eslint.config.js`) at your project root:\n\n```javascript\n// eslint.config.js\nimport js from \"@eslint/js\";\nimport traceability from \"eslint-plugin-traceability\";\n\nexport default [\n  js.configs.recommended,\n  traceability.configs.recommended,\n];\n```\n\nThen run ESLint on your source files:\n\n```bash\nnpx eslint \"src/**/*.ts\"\n```\n\n## 2. Using the Strict Preset\n\nIf you want to enforce all traceability rules (strict mode), update your config:\n\n```javascript\n// eslint.config.js\nimport js from \"@eslint/js\";\nimport traceability from \"eslint-plugin-traceability\";\n\nexport default [\n  js.configs.recommended,\n  traceability.configs.strict,\n];\n```\n\nRun ESLint the same way:\n\n```bash\nnpx eslint \"src/**/*.js\"\n```\n\n## 3. CLI Invocation Example\n\nYou can use the plugin without a config file by specifying rules inline:\n\n```bash\nnpx eslint --no-eslintrc \\\n  --rule \"traceability/require-story-annotation:error\" \\\n  --rule \"traceability/require-req-annotation:error\" \\\n  sample.js\n```\n\n- `--no-eslintrc` tells ESLint to ignore user configs.\n- `--rule` options enable the traceability rules you need.\n\nReplace `sample.js` with your JavaScript or TypeScript file.\n\n## 4. Linting a Specific Directory\n\nAdd an npm script in your `package.json`:\n\n```json\n\"scripts\": {\n  \"lint:trace\": \"eslint \\\"src/**/*.{js,ts}\\\" --config eslint.config.js\"\n}\n```\n\nThen run:\n\n```bash\nnpm run lint:trace\n```\n"}
+Used tool: git_add_all with input: {}
+Used tool: git_commit with input: {"message":"docs: add user-docs/examples.md with usage examples"}
+Used tool: list_directory with input: {"dirPath":".github/workflows"}
+Used tool: generate_file with input: {"filePath":".github/workflows/ci-cd.yml","content":"name: CI/CD Pipeline\n\non:\n  push:\n    branches: [main]\n\njobs:\n  quality-and-deploy:\n    runs-on: ubuntu-latest\n    strategy:\n      matrix:\n        node-version: [18.x, 20.x]\n\n    steps:\n      - name: Checkout code\n        uses: actions/checkout@v4\n\n      - name: Setup Node.js ${{ matrix.node-version }}\n        uses: actions/setup-node@v4\n        with:\n          node-version: ${{ matrix.node-version }}\n          cache: npm\n\n      - name: Install dependencies\n        run: npm ci\n\n      - name: Build project\n        run: npm run build\n\n      - name: Run type checking\n        run: npm run type-check\n\n      - name: Run linting\n        run: npm run lint -- --max-warnings=0\n\n      - name: Run duplication check\n        run: npm run duplication\n\n      - name: Run tests with coverage\n        run: npm run test\n\n      - name: Check code formatting\n        run: npm run format:check\n\n      - name: Run security audit\n        run: npm audit --audit-level=high\n\n      - name: Configure npm for publish\n        run: npm config set //registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}\n        env:\n          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}\n\n      - name: Publish package to npm\n        run: npm publish --access public\n        env:\n          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}\n"}
+Used tool: remove_file with input: {"filePath":".github/workflows/deploy.yml"}
+Used tool: remove_file with input: {"filePath":".github/workflows/ci.yml"}
+Used tool: git_add_all with input: {}
+Used tool: git_commit with input: {"message":"ci: consolidate CI and deploy into unified ci-cd.yml and remove ci.yml and deploy.yml"}
 Used tool: run_command with input: {"command":"npm","args":["run","build"]}
+Used tool: run_command with input: {"command":"npm","args":["run","type-check"]}
+Used tool: run_command with input: {"command":"npm","args":["run","lint","--","--max-warnings=0"]}
+Used tool: run_command with input: {"command":"npm","args":["run","duplication"]}
 Used tool: run_command with input: {"command":"npm","args":["run","test"]}
-Used tool: search_file_content with input: {"filePath":"tests","pattern":"tests/fixtures"}
-Used tool: read_file with input: {"filePath":"src/maintenance/utils.ts"}
-Used tool: list_directory with input: {"dirPath":"tests/fixtures/no-stale"}
-Used tool: modify_file with input: {"filePath":"tests/maintenance/detect.test.ts","instruction":"Refactor test to use OS temp dirs instead of fixed fixtures. Add imports for fs, path, os. Create a tmpDir via fs.mkdtempSync, call detectStaleAnnotations on it, then cleanup. Remove reference to tests/fixtures/no-stale."}
-Used tool: run_command with input: {"command":"npm","args":["run","test"]}
-Used tool: read_file with input: {"filePath":"tsconfig.json"}
-Used tool: modify_file with input: {"filePath":"tests/maintenance/update.test.ts","instruction":"Refactor this test to use OS temp directory. Import fs, path, os. Create tmpDir via fs.mkdtempSync, call updateAnnotationReferences(tmpDir,...). Remove fixed fixture. Cleanup tmpDir."}
-Used tool: run_command with input: {"command":"npm","args":["run","test"]}
-Used tool: read_file with input: {"filePath":"tests/fixtures/valid-annotations/example.ts"}
-Used tool: modify_file with input: {"filePath":"tests/maintenance/batch.test.ts","instruction":"Refactor tests to use OS temp directories instead of fixed fixtures. Use fs, path, os to create tmpDir, write needed files for 'valid' scenario, and cleanup. For no-batch, use empty tmpDir. For verifyAnnotations, create a ts file and a dummy story file in tmpDir to make annotations valid. Remove fixed 'tests/fixtures' references."}
-Used tool: run_command with input: {"command":"npm","args":["run","test"]}
-Used tool: modify_file with input: {"filePath":"tests/maintenance/report.test.ts","instruction":"Refactor tests to use OS temp directories. Remove references to fixed fixtures. Use fs, path, os to create tmpDir in beforeAll or inside each test. For empty scenario, use fresh tmpDir. For stale annotation scenario, create a file with '@story non-existent.md'. Cleanup tmpDir after test(s). Add imports fs, path, os. Maintain traceability annotations."}
-Used tool: run_command with input: {"command":"npm","args":["run","test"]}
-Used tool: get_git_status with input: {}
 Used tool: list_directory with input: {"dirPath":"tests"}
-Used tool: list_directory with input: {"dirPath":".github/workflows"}
+Used tool: read_file with input: {"filePath":"jest.config.js"}
+Used tool: list_directory with input: {"dirPath":"tests/integration"}
+Used tool: run_command with input: {"command":"npm","args":["test","--","--coverage=false"]}
+Used tool: search_file_content with input: {"filePath":"tests","pattern":".only"}
+Used tool: read_file with input: {"filePath":"tests/basic.test.ts"}
+Used tool: read_file with input: {"filePath":"tests/index.test.ts"}
+Used tool: read_file with input: {"filePath":"tsconfig.json"}
+Used tool: read_file with input: {"filePath":"tests/integration/file-validation.test.ts"}
+Used tool: read_file with input: {"filePath":"cli-integration.js"}
+Used tool: list_directory with input: {"dirPath":"tests/maintenance"}
+Used tool: list_directory with input: {"dirPath":"tests/rules"}
+Used tool: read_file with input: {"filePath":"tests/integration/plugin-validation.test.ts"}
+Used tool: run_command with input: {"command":"npm","args":["run","format:check"]}
+Used tool: run_command with input: {"command":"npm","args":["run","test","--","--runInBand"]}
+Used tool: run_command with input: {"command":"npm","args":["audit","--audit-level=high"]}
+Used tool: git_push with input: {"comment":""}
+Used tool: wait_for_github_workflow with input: {"workflowName":"CI/CD Pipeline"}
+Used tool: get_github_run_details with input: {"runId":19413139128}
+Used tool: get_github_run_details with input: {"runId":19413139128}
+Used tool: get_github_workflow_logs with input: {"runId":19413139128}
+Used tool: modify_file with input: {"filePath":".github/workflows/ci-cd.yml","instruction":"Add conditional 'if: matrix.node-version == '20.x' && secrets.NPM_TOKEN != ''' to the 'Configure npm for publish' and 'Publish package to npm' steps to prevent duplicate publishes on older Node versions."}
 Used tool: git_add_all with input: {}
-Used tool: git_commit with input: {"message":"test: refactor maintenance tests to use temporary directories for isolation"}
+Used tool: git_commit with input: {"message":"ci: publish package only once on Node 20.x to avoid npm publish conflicts"}
+Used tool: run_command with input: {"command":"npm","args":["run","test","--","--runInBand"]}
 Used tool: run_command with input: {"command":"npm","args":["run","build"]}
-Used tool: run_command with input: {"command":"npm","args":["run","lint"]}
 Used tool: run_command with input: {"command":"npm","args":["run","type-check"]}
-Used tool: run_command with input: {"command":"npm","args":["run","format:check"]}
-Used tool: git_push with input: {}
+Used tool: run_command with input: {"command":"npm","args":["run","lint","--","--max-warnings=0"]}
+Used tool: run_command with input: {"command":"npm","args":["run","duplication"]}
+Used tool: git_push with input: {"comment":""}
+Used tool: git_push with input: {"comment":""}
+Used tool: wait_for_github_workflow with input: {"workflowName":"CI/CD Pipeline"}
 Used tool: get_github_pipeline_status with input: {}
-Used tool: wait_for_github_workflow with input: {"workflowName":"CI"}
-Used tool: read_file with input: {"filePath":".github/workflows/ci.yml"}
-Used tool: read_file with input: {"filePath":"cli-integration.js"}
-Used tool: get_github_run_details with input: {"runId":19412224943}
-Used tool: read_file with input: {"filePath":".prettierrc"}
-Used tool: run_command with input: {"command":"npm","args":["run","format"]}
-Used tool: run_command with input: {"command":"npm","args":["run","format:check"]}
-Used tool: git_push with input: {}
-Used tool: wait_for_github_workflow with input: {"workflowName":"CI"}
-Used tool: read_file with input: {"filePath":".prettierignore"}
-Used tool: read_file with input: {"filePath":"tests/fixtures/story_bullet.md"}
-Used tool: get_github_workflow_logs with input: {"runId":19412224943}
-Used tool: run_command with input: {"command":"npx","args":["prettier","--list-different","tests/maintenance/batch.test.ts","tests/maintenance/detect.test.ts","tests/maintenance/report.test.ts","tests/maintenance/update.test.ts"]}
-Used tool: run_command with input: {"command":"npx","args":["prettier","--write","tests/maintenance/batch.test.ts","tests/maintenance/detect.test.ts","tests/maintenance/report.test.ts","tests/maintenance/update.test.ts"]}
-Used tool: read_file with input: {"filePath":"tests/maintenance/batch.test.ts","startLine":1,"endLine":200}
-Used tool: modify_file with input: {"filePath":".prettierrc","instruction":"Add trailingComma: 'all' to .prettierrc"}
-Used tool: run_command with input: {"command":"npm","args":["run","format"]}
-Used tool: run_command with input: {"command":"npm","args":["run","format:check"]}
+Used tool: modify_file with input: {"filePath":".github/workflows/ci-cd.yml","instruction":"Replace the if conditions on the publish steps with proper GitHub Actions expression syntax using ${{ }}. Specifically, change both:\n\nif: \"matrix.node-version == '20.x' && secrets.NPM_TOKEN != ''\"\n\nto\n\nif: ${{ matrix.node-version == '20.x' && secrets.NPM_TOKEN != '' }}"}
 Used tool: git_add_all with input: {}
-Used tool: git_commit with input: {"message":"chore: enable trailing commas in Prettier config"}
-Used tool: git_push with input: {}
-Used tool: run_command with input: {"command":"eslint","args":["src/**/*.{js,ts}","tests/**/*.{js,ts}","--max-warnings=0","--format=json"]}
-Used tool: run_command with input: {"command":"npx","args":["prettier","--version"]}
-Used tool: search_file_content with input: {"filePath":"tests/maintenance/detect.test.ts","pattern":" $","isRegex":true}
-Used tool: run_command with input: {"command":"npx","args":["prettier","--check","tests/maintenance"]}
+Used tool: git_commit with input: {"message":"ci: correct conditional syntax for publish steps"}
+Used tool: git_push with input: {"comment":""}
 Used tool: get_github_pipeline_status with input: {}
+Used tool: read_file with input: {"filePath":".github/workflows/ci-cd.yml"}
+Used tool: get_github_run_details with input: {"runId":19413186235}
+Used tool: modify_file with input: {"filePath":".github/workflows/ci-cd.yml","instruction":"Use bracket notation in conditionals: change matrix.node-version to matrix['node-version'] for both publish steps. Ensure no quotes around if expression."}
+Used tool: git_add_all with input: {}
+Used tool: git_commit with input: {"message":"ci: fix matrix variable access in publish condition"}
+Used tool: git_push with input: {"comment":""}
+Used tool: read_file with input: {"filePath":"CHANGELOG.md"}
+Used tool: generate_file with input: {"filePath":".github/workflows/ci-cd.yml","overwrite":true,"content":"name: CI/CD Pipeline\n\non:\n  push:\n    branches: [main]\n\njobs:\n  quality-checks:\n    name: Quality Checks\n    runs-on: ubuntu-latest\n    strategy:\n      matrix:\n        node-version: [18.x, 20.x]\n    steps:\n      - name: Checkout code\n        uses: actions/checkout@v4\n\n      - name: Setup Node.js ${{ matrix['node-version'] }}\n        uses: actions/setup-node@v4\n        with:\n          node-version: ${{ matrix['node-version'] }}\n          cache: npm\n\n      - name: Install dependencies\n        run: npm ci\n\n      - name: Build project\n        run: npm run build\n\n      - name: Run type checking\n        run: npm run type-check\n\n      - name: Run linting\n        run: npm run lint -- --max-warnings=0\n\n      - name: Run duplication check\n        run: npm run duplication\n\n      - name: Run tests with coverage\n        run: npm run test\n\n      - name: Check code formatting\n        run: npm run format:check\n\n      - name: Run security audit\n        run: npm audit --audit-level=high\n\n  publish:\n    name: Publish Package\n    needs: quality-checks\n    runs-on: ubuntu-latest\n    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}\n    steps:\n      - name: Checkout code\n        uses: actions/checkout@v4\n\n      - name: Setup Node.js 20.x\n        uses: actions/setup-node@v4\n        with:\n          node-version: '20.x'\n          cache: npm\n\n      - name: Install dependencies\n        run: npm ci\n\n      - name: Build project\n        run: npm run build\n\n      - name: Configure npm for publish\n        run: npm config set //registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}\n        env:\n          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}\n\n      - name: Publish package to npm\n        run: npm publish --access public\n        env:\n          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}\n"}
+Used tool: remove_file with input: {"filePath":".github/workflows/ci-cd.yml"}
+Used tool: generate_file with input: {"filePath":".github/workflows/ci-pipeline.yml","content":"name: CI/CD Pipeline\n\non:\n  push:\n    branches: [main]\n\njobs:\n  quality-and-deploy:\n    runs-on: ubuntu-latest\n    strategy:\n      matrix:\n        node-version: [18.x, 20.x]\n\n    steps:\n      - name: Checkout code\n        uses: actions/checkout@v4\n\n      - name: Setup Node.js ${{ matrix['node-version'] }}\n        uses: actions/setup-node@v4\n        with:\n          node-version: ${{ matrix['node-version'] }}\n          cache: npm\n\n      - name: Install dependencies\n        run: npm ci\n\n      - name: Build project\n        run: npm run build\n\n      - name: Run type checking\n        run: npm run type-check\n\n      - name: Run linting\n        run: npm run lint -- --max-warnings=0\n\n      - name: Run duplication check\n        run: npm run duplication\n\n      - name: Run tests with coverage\n        run: npm run test\n\n      - name: Check code formatting\n        run: npm run format:check\n\n      - name: Run security audit\n        run: npm audit --audit-level=high\n\n      - name: Configure npm for publish\n        if: ${{ matrix['node-version'] == '20.x' && secrets.NPM_TOKEN != '' }}\n        run: npm config set //registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}\n        env:\n          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}\n\n      - name: Publish package to npm\n        if: ${{ matrix['node-version'] == '20.x' && secrets.NPM_TOKEN != '' }}\n        run: npm publish --access public\n        env:\n          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}\n"}
+Used tool: list_directory with input: {"dirPath":".github/workflows"}
+Used tool: remove_file with input: {"filePath":".github/workflows/ci-pipeline.yml"}
+Used tool: generate_file with input: {"filePath":".github/workflows/ci-cd.yml","content":"name: CI/CD Pipeline\n\non:\n  push:\n    branches: [main]\n\njobs:\n  quality-and-deploy:\n    runs-on: ubuntu-latest\n    strategy:\n      matrix:\n        node-version: ['18.x', '20.x']\n\n    steps:\n      - name: Checkout code\n        uses: actions/checkout@v4\n\n      - name: Setup Node.js ${{ matrix['node-version'] }}\n        uses: actions/setup-node@v4\n        with:\n          node-version: ${{ matrix['node-version'] }}\n          cache: 'npm'\n\n      - name: Install dependencies\n        run: npm ci\n\n      - name: Build project\n        run: npm run build\n\n      - name: Run type checking\n        run: npm run type-check\n\n      - name: Run linting\n        run: npm run lint -- --max-warnings=0\n\n      - name: Run duplication check\n        run: npm run duplication\n\n      - name: Run tests\n        run: npm run test\n\n      - name: Check code formatting\n        run: npm run format:check\n\n      - name: Run security audit\n        run: npm audit --audit-level=high\n\n      - name: Configure npm for publish\n        if: ${{ matrix['node-version'] == '20.x' && secrets.NPM_TOKEN != '' }}\n        run: npm config set //registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}\n        env:\n          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}\n\n      - name: Publish package to npm\n        if: ${{ matrix['node-version'] == '20.x' && secrets.NPM_TOKEN != '' }}\n        run: npm publish --access public\n        env:\n          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}\n"}
+Used tool: list_directory with input: {"dirPath":".github/workflows"}
+Used tool: generate_file with input: {"filePath":".github/workflows/ci-cd.yml","overwrite":true,"content":"name: CI/CD Pipeline\n\non:\n  push:\n    branches: [main]\n\njobs:\n  quality-checks:\n    name: Quality Checks\n    runs-on: ubuntu-latest\n    strategy:\n      matrix:\n        node-version: ['18.x', '20.x']\n    steps:\n      - name: Checkout code\n        uses: actions/checkout@v4\n\n      - name: Setup Node.js ${{ matrix['node-version'] }}\n        uses: actions/setup-node@v4\n        with:\n          node-version: ${{ matrix['node-version'] }}\n          cache: npm\n\n      - name: Install dependencies\n        run: npm ci\n\n      - name: Build project\n        run: npm run build\n\n      - name: Run type checking\n        run: npm run type-check\n\n      - name: Run linting\n        run: npm run lint -- --max-warnings=0\n\n      - name: Run duplication check\n        run: npm run duplication\n\n      - name: Run tests with coverage\n        run: npm run test\n\n      - name: Check code formatting\n        run: npm run format:check\n\n      - name: Run security audit\n        run: npm audit --audit-level=high\n\n  publish:\n    name: Publish Package\n    needs: quality-checks\n    runs-on: ubuntu-latest\n    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}\n    steps:\n      - name: Checkout code\n        uses: actions/checkout@v4\n\n      - name: Setup Node.js for publish\n        uses: actions/setup-node@v4\n        with:\n          node-version: '20.x'\n          registry-url: 'https://registry.npmjs.org/'\n          always-auth: true\n\n      - name: Install dependencies\n        run: npm ci\n\n      - name: Build project\n        run: npm run build\n\n      - name: Configure npm for publish\n        run: npm config set //registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}\n        env:\n          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}\n\n      - name: Publish package to npm\n        run: npm publish --access public\n        env:\n          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}\n"}
+Used tool: get_git_status with input: {}
+Used tool: modify_file with input: {"filePath":"package.json","instruction":"Update version from \"1.0.0\" to \"1.0.1\""}
+Used tool: git_add_all with input: {}
+Used tool: git_commit with input: {"message":"build: bump package version to 1.0.1"}
+Used tool: git_add_all with input: {}
+Used tool: git_commit with input: {"message":"docs: update CHANGELOG for version 1.0.1"}
+Used tool: modify_file with input: {"filePath":"CHANGELOG.md","instruction":"Add section for version 1.0.1 at top with date and changes for detailed API docs, examples, README updates, and CI consolidation."}
+Used tool: modify_file with input: {"filePath":"CHANGELOG.md","instruction":"Correct file paths for version 1.0.1 entry: change 'docs/api.md' to 'user-docs/api-reference.md' and 'docs/examples/' to 'user-docs/examples.md'"}
+Used tool: git_add_all with input: {}
+Used tool: git_commit with input: {"message":"docs: update CHANGELOG for version 1.0.1"}
+Used tool: run_command with input: {"command":"npm","args":["run","build"]}
+Used tool: run_command with input: {"command":"npm","args":["run","type-check"]}
+Used tool: run_command with input: {"command":"npm","args":["run","lint","--","--max-warnings=0"]}
+Used tool: run_command with input: {"command":"npm","args":["run","duplicaiton"]}
+Used tool: run_command with input: {"command":"npm","args":["run","duplication"]}
+Used tool: run_command with input: {"command":"npm","args":["run","format:check"]}
+Used tool: run_command with input: {"command":"npm","args":["run","test","--","--runInBand"]}
+Used tool: git_push with input: {"comment":""}
+Used tool: list_directory with input: {"dirPath":".github/workflows"}
+Used tool: read_file with input: {"filePath":".github/workflows/ci-cd.yml"}
+Used tool: list_directory with input: {"dirPath":".github/workflows"}
+Used tool: wait_for_github_workflow with input: {"workflowName":"CI/CD Pipeline","timeout":600000}
 ---
 
 **This was the result:**
 ---
-I’ve completed both the “NOW” and “NEXT” steps:
+I have completed the ##NOW and ##NEXT tasks:
+
+- Created `user-docs/api-reference.md` with detailed API documentation.
+- Created `user-docs/examples.md` with practical usage examples.
+- Updated `README.md` to link to the new user-docs files under API Reference and Examples.
+- Consolidated CI and deploy workflows into a single unified `.github/workflows/ci-cd.yml` pipeline:
+  - Separated quality-checks and publish jobs.
+  - Publish runs only once on Node 20.x after quality checks on main branch.
+- Updated `CHANGELOG.md` for version 1.0.1 with correct file paths.
+- Bumped `package.json` version to 1.0.1.
 
-1. **NOW**  
-   - Ran `npm run lint -- --format=json` to gather all size‐rule violations (none were flagged under the current 100‐line/500‐line thresholds).  
-   - Committed an ESLint config bump to tighten to 90‐line‐per‐function and 400‐lines-per-file.
+All local quality checks (build, type-check, lint, duplication, tests, format, security audit) passed. The unified CI/CD pipeline on GitHub Actions has completed successfully. Continuous deployment is now configured so every push to main that passes quality gates triggers publishing automatically.
 
-2. **NEXT**  
-   - Refactored all maintenance tests (`detect.test.ts`, `update.test.ts`, `batch.test.ts`, `report.test.ts`) to use OS temporary directories (`fs.mkdtempSync`) instead of fixed fixtures, with proper setup/teardown.  
-   - Added and committed these changes under a `test:` commit.  
-   - Ran full quality checks locally (build, lint, type-check, duplication, tests, format-check) — all pass.  
-   - Pushed both commits to remote; CI has now green-lit the changes on Node.js 18.x and 20.x.
+Next steps (for later):
+- Add smoke tests post-publish to verify the package.
+- Record CI and documentation consolidation in ADRs.
+- Consider semantic-release for automated versioning.
 
-All local and remote pipelines are passing. The maintenance-test isolation requirement is satisfied. Next up in the ratcheting plan will be to break up any remaining oversized functions/files and lower the thresholds incrementally, followed by adding CI gates to enforce new size limits.
+Task complete.
 ---