@dtlabs/ai-toolkit 0.8.0 → 0.10.0

package/.claude/scripts/tests/fixtures/ac-table-format.md

@@ -0,0 +1,48 @@
+# Requirements — Sample Feature for AC Parser Tests
+
+This file is a test fixture for the AC table parser (wb-validate.js, Section 3.2 contract).
+It contains UC metadata tables with Priority fields and a ## 7. Acceptance Criteria section
+with an AC table in the exact format the parser expects.
+
+---
+
+## 5. Use Cases
+
+### UC-01: Parse and validate work breakdown JSON
+
+| Field | Value |
+|-------|-------|
+| ID | UC-01 |
+| Actor | wb-validate.js |
+| Priority | Must |
+| Trigger | pm-phase2 invokes the validator CLI |
+
+**Description:** The validator reads a Work-Breakdown.json file, parses it according to schema
+v2, and emits a structured JSON report. It must detect all 23 categories of structural error
+without invoking an LLM.
+
+---
+
+### UC-02: Render human-readable and CSV output
+
+| Field | Value |
+|-------|-------|
+| ID | UC-02 |
+| Actor | wb-render.js |
+| Priority | Should |
+| Trigger | pm-phase2 invokes the renderer CLI after a successful validate pass |
+
+**Description:** The renderer reads the validated JSON and produces a Markdown file for human
+review and a pipe-separated CSV file for pm-phase3 consumption.
+
+---
+
+## 7. Acceptance Criteria
+
+| ID | Criterion | Related UC |
+|----|-----------|------------|
+| AC-01 | Given a valid Work-Breakdown.json when wb-validate.js runs then it exits 0 and emits a JSON report with valid=true | UC-01 |
+| AC-02 | Given a JSON file with a duplicate task ID when wb-validate.js runs then it exits 1 and reports category unique_id_violation | UC-01 |
+| AC-03 | Given a Work-Breakdown.json that passes structural validation when wb-render.js runs then it writes both a .md and a .csv file to the feature directory | UC-01, UC-02 |
+| AC-04 | Given a CSV produced by wb-render.js when pm-phase3 parses it then all phases are scheduled in the correct wave order | UC-02 |
+| AC-05 | Given any validator or renderer invocation when it completes then a ledger entry is written with the correct status and token count | All UCs |

package/.claude/scripts/tests/fixtures/test-feature/TEST-001-Work-Breakdown.json

@@ -0,0 +1,234 @@
+{
+  "schemaVersion": 2,
+  "feature": "TEST-001",
+  "phases": [
+    {
+      "id": "INFRA",
+      "type": "infrastructure",
+      "title": "Shared infrastructure setup for JWT authentication",
+      "commit": { "type": "feat", "subject": "shared infrastructure for JWT auth" },
+      "tasks": [
+        {
+          "id": "INFRA-TASK-DB-01",
+          "title": "Register database context and User entity",
+          "outcome": "User entity is mapped in the database context; schema includes users table with id, email, passwordHash columns",
+          "domain": "DB",
+          "agentType": "developer-database",
+          "dependsOn": [],
+          "acceptanceCriteria": [],
+          "verification": { "commands": ["npx tsc --noEmit"] },
+          "estimate": { "agentMinutes": 8, "tokens": 18000 },
+          "outputCount": 1,
+          "groupingRationale": null,
+          "commit": { "type": "feat", "subject": "add User entity and database context registration" }
+        },
+        {
+          "id": "INFRA-TASK-DB-02",
+          "title": "Create RefreshToken entity and migration",
+          "outcome": "RefreshToken entity is mapped; migration creates refresh_tokens table with token, userId, expiresAt columns",
+          "domain": "DB",
+          "agentType": "developer-database",
+          "dependsOn": ["INFRA-TASK-DB-01"],
+          "acceptanceCriteria": [],
+          "verification": { "commands": ["npx tsc --noEmit"] },
+          "estimate": { "agentMinutes": 8, "tokens": 18000 },
+          "outputCount": 1,
+          "groupingRationale": null,
+          "commit": { "type": "feat", "subject": "add RefreshToken entity and migration" }
+        },
+        {
+          "id": "INFRA-TASK-BE-01",
+          "title": "Configure JWT signing secret and token expiry constants",
+          "outcome": "JWT_SECRET, ACCESS_TOKEN_EXPIRY (15m), and REFRESH_TOKEN_EXPIRY (7d) constants are loaded from environment variables and exported",
+          "domain": "BE",
+          "agentType": "developer-backend",
+          "dependsOn": [],
+          "acceptanceCriteria": [],
+          "verification": { "commands": ["npx tsc --noEmit"] },
+          "estimate": { "agentMinutes": 5, "tokens": 10000 },
+          "outputCount": 1,
+          "groupingRationale": null,
+          "commit": { "type": "feat", "subject": "add JWT signing secret and expiry config constants" }
+        },
+        {
+          "id": "INFRA-TASK-BE-02",
+          "title": "Implement JwtService — sign and verify helpers",
+          "outcome": "JwtService class exists with signAccessToken(userId) and verifyToken(token) methods; uses INFRA-TASK-BE-01 constants",
+          "domain": "BE",
+          "agentType": "developer-backend",
+          "dependsOn": ["INFRA-TASK-BE-01"],
+          "acceptanceCriteria": [],
+          "verification": { "commands": ["npx tsc --noEmit"] },
+          "estimate": { "agentMinutes": 10, "tokens": 22000 },
+          "outputCount": 1,
+          "groupingRationale": null,
+          "commit": { "type": "feat", "subject": "add JwtService sign and verify helpers" }
+        },
+        {
+          "id": "INFRA-TASK-BE-03",
+          "title": "Implement PasswordService — hash and compare helpers",
+          "outcome": "PasswordService class exists with hashPassword(plain) and comparePassword(plain, hash) methods using bcrypt",
+          "domain": "BE",
+          "agentType": "developer-backend",
+          "dependsOn": [],
+          "acceptanceCriteria": [],
+          "verification": { "commands": ["npx tsc --noEmit"] },
+          "estimate": { "agentMinutes": 8, "tokens": 15000 },
+          "outputCount": 1,
+          "groupingRationale": null,
+          "commit": { "type": "feat", "subject": "add PasswordService bcrypt helpers" }
+        }
+      ]
+    },
+    {
+      "id": "US-01",
+      "type": "user-story",
+      "title": "As an anonymous user, I want to register with email and password, so that I can access the system",
+      "commit": { "type": "feat", "subject": "implement US-01 user registration" },
+      "tasks": [
+        {
+          "id": "US-01-TASK-BE-01",
+          "title": "Implement RegisterUserService",
+          "outcome": "RegisterUserService class exists with register(email, password) method; validates uniqueness, hashes password via PasswordService, persists User, returns user id and email",
+          "domain": "BE",
+          "agentType": "developer-backend",
+          "dependsOn": ["INFRA-TASK-DB-01", "INFRA-TASK-BE-03"],
+          "acceptanceCriteria": ["AC-01", "AC-02", "AC-03"],
+          "verification": { "commands": ["npx tsc --noEmit"] },
+          "estimate": { "agentMinutes": 13, "tokens": 30000 },
+          "outputCount": 1,
+          "groupingRationale": null,
+          "commit": { "type": "feat", "subject": "add RegisterUserService with uniqueness and hash validation" }
+        },
+        {
+          "id": "US-01-TASK-BE-02",
+          "title": "Implement POST /auth/register endpoint",
+          "outcome": "POST /auth/register controller action exists; validates request body (email, password), delegates to RegisterUserService, returns 201 on success or 409 on duplicate email",
+          "domain": "BE",
+          "agentType": "developer-backend",
+          "dependsOn": ["US-01-TASK-BE-01"],
+          "acceptanceCriteria": ["AC-01", "AC-02"],
+          "verification": { "commands": ["npx tsc --noEmit"] },
+          "estimate": { "agentMinutes": 10, "tokens": 22000 },
+          "outputCount": 1,
+          "groupingRationale": null,
+          "commit": { "type": "feat", "subject": "add POST /auth/register endpoint" }
+        },
+        {
+          "id": "US-01-TASK-TEST-01",
+          "title": "Tests: user registration — success, duplicate email, password hashing",
+          "outcome": "Jest test suite for RegisterUserService and POST /auth/register covering 201 success, 409 conflict, and bcrypt hash verification",
+          "domain": "TEST",
+          "agentType": "developer-testing",
+          "dependsOn": ["US-01-TASK-BE-01", "US-01-TASK-BE-02"],
+          "acceptanceCriteria": ["AC-01", "AC-02", "AC-03"],
+          "verification": { "commands": ["npx jest --testPathPattern=register"] },
+          "estimate": { "agentMinutes": 15, "tokens": 35000 },
+          "outputCount": 1,
+          "groupingRationale": null,
+          "commit": { "type": "test", "subject": "add registration unit and integration tests" }
+        }
+      ]
+    },
+    {
+      "id": "US-02",
+      "type": "user-story",
+      "title": "As a registered user, I want to log in with my credentials, so that I receive JWT access and refresh tokens",
+      "commit": { "type": "feat", "subject": "implement US-02 user login" },
+      "tasks": [
+        {
+          "id": "US-02-TASK-BE-01",
+          "title": "Implement LoginService",
+          "outcome": "LoginService class exists with login(email, password) method; validates credentials via PasswordService, signs access and refresh tokens via JwtService, persists RefreshToken, returns both tokens",
+          "domain": "BE",
+          "agentType": "developer-backend",
+          "dependsOn": ["INFRA-TASK-DB-01", "INFRA-TASK-DB-02", "INFRA-TASK-BE-02", "INFRA-TASK-BE-03"],
+          "acceptanceCriteria": ["AC-04", "AC-05"],
+          "verification": { "commands": ["npx tsc --noEmit"] },
+          "estimate": { "agentMinutes": 14, "tokens": 32000 },
+          "outputCount": 1,
+          "groupingRationale": null,
+          "commit": { "type": "feat", "subject": "add LoginService with credential validation and token issuance" }
+        },
+        {
+          "id": "US-02-TASK-BE-02",
+          "title": "Implement POST /auth/login endpoint",
+          "outcome": "POST /auth/login controller action exists; validates request body, delegates to LoginService, returns 200 with accessToken and refreshToken or 401 on invalid credentials",
+          "domain": "BE",
+          "agentType": "developer-backend",
+          "dependsOn": ["US-02-TASK-BE-01"],
+          "acceptanceCriteria": ["AC-04", "AC-05"],
+          "verification": { "commands": ["npx tsc --noEmit"] },
+          "estimate": { "agentMinutes": 9, "tokens": 20000 },
+          "outputCount": 1,
+          "groupingRationale": null,
+          "commit": { "type": "feat", "subject": "add POST /auth/login endpoint" }
+        },
+        {
+          "id": "US-02-TASK-TEST-01",
+          "title": "Tests: user login — success, invalid password, unknown email",
+          "outcome": "Jest test suite for LoginService and POST /auth/login covering 200 with tokens, 401 on bad password, and 401 on unknown email",
+          "domain": "TEST",
+          "agentType": "developer-testing",
+          "dependsOn": ["US-02-TASK-BE-01", "US-02-TASK-BE-02"],
+          "acceptanceCriteria": ["AC-04", "AC-05"],
+          "verification": { "commands": ["npx jest --testPathPattern=login"] },
+          "estimate": { "agentMinutes": 14, "tokens": 32000 },
+          "outputCount": 1,
+          "groupingRationale": null,
+          "commit": { "type": "test", "subject": "add login unit and integration tests" }
+        }
+      ]
+    },
+    {
+      "id": "US-03",
+      "type": "user-story",
+      "title": "As an authenticated client, I want to refresh my access token, so that I stay logged in without re-entering credentials",
+      "commit": { "type": "feat", "subject": "implement US-03 token refresh" },
+      "tasks": [
+        {
+          "id": "US-03-TASK-BE-01",
+          "title": "Implement TokenRefreshService",
+          "outcome": "TokenRefreshService class exists with refresh(refreshToken) method; validates token via JwtService, invalidates old RefreshToken, issues new access and refresh tokens, persists new RefreshToken",
+          "domain": "BE",
+          "agentType": "developer-backend",
+          "dependsOn": ["INFRA-TASK-DB-02", "INFRA-TASK-BE-02"],
+          "acceptanceCriteria": ["AC-06", "AC-07"],
+          "verification": { "commands": ["npx tsc --noEmit"] },
+          "estimate": { "agentMinutes": 13, "tokens": 30000 },
+          "outputCount": 1,
+          "groupingRationale": null,
+          "commit": { "type": "feat", "subject": "add TokenRefreshService with rotation logic" }
+        },
+        {
+          "id": "US-03-TASK-BE-02",
+          "title": "Implement POST /auth/refresh endpoint",
+          "outcome": "POST /auth/refresh controller action exists; validates request body, delegates to TokenRefreshService, returns 200 with new accessToken and refreshToken or 401 on invalid/expired token",
+          "domain": "BE",
+          "agentType": "developer-backend",
+          "dependsOn": ["US-03-TASK-BE-01"],
+          "acceptanceCriteria": ["AC-06", "AC-07"],
+          "verification": { "commands": ["npx tsc --noEmit"] },
+          "estimate": { "agentMinutes": 9, "tokens": 20000 },
+          "outputCount": 1,
+          "groupingRationale": null,
+          "commit": { "type": "feat", "subject": "add POST /auth/refresh endpoint" }
+        },
+        {
+          "id": "US-03-TASK-TEST-01",
+          "title": "Tests: token refresh — success with rotation, expired token, reuse of invalidated token",
+          "outcome": "Jest test suite for TokenRefreshService and POST /auth/refresh covering 200 with rotated tokens, 401 on expired token, and 401 on reuse of already-invalidated token",
+          "domain": "TEST",
+          "agentType": "developer-testing",
+          "dependsOn": ["US-03-TASK-BE-01", "US-03-TASK-BE-02"],
+          "acceptanceCriteria": ["AC-06", "AC-07"],
+          "verification": { "commands": ["npx jest --testPathPattern=refresh"] },
+          "estimate": { "agentMinutes": 15, "tokens": 35000 },
+          "outputCount": 1,
+          "groupingRationale": null,
+          "commit": { "type": "test", "subject": "add token refresh unit and integration tests" }
+        }
+      ]
+    }
+  ]
+}

package/.claude/scripts/tests/fixtures/test-feature/TEST-001-semantic-output.json

@@ -0,0 +1,4 @@
+{
+  "valid": true,
+  "findings": []
+}

package/.claude/scripts/tests/fixtures/test-feature/feature.md

@@ -0,0 +1,45 @@
+# Feature: TEST-001 — JWT Authentication
+
+## Overview
+
+Add user authentication to the API using JSON Web Tokens (JWT). Users register with an email and password, log in to receive a signed access token, and present that token on protected endpoints. A token refresh flow is also supported.
+
+## Goals
+
+- Allow new users to register with a unique email address and a hashed password.
+- Allow registered users to log in and receive a short-lived JWT access token and a long-lived refresh token.
+- Allow clients to exchange a valid refresh token for a new access token without re-entering credentials.
+- Protect designated API routes so that only requests bearing a valid JWT are accepted.
+
+## Non-Goals
+
+- OAuth / social login is out of scope.
+- Role-based access control beyond "authenticated vs. anonymous" is out of scope.
+
+## Actors
+
+- **Anonymous user** — not yet authenticated; may register or log in.
+- **Authenticated user** — holds a valid JWT; may call protected endpoints and refresh tokens.
+
+## Use Cases
+
+### UC-01: User Registration
+An anonymous user submits an email and password. The system validates the input, checks the email is not already taken, hashes the password, persists a new user record, and returns a 201 response.
+
+### UC-02: User Login
+A registered user submits their email and password. The system validates credentials, signs a JWT access token (15-minute expiry) and a refresh token (7-day expiry), persists the refresh token, and returns both tokens.
+
+### UC-03: Token Refresh
+An authenticated client presents a valid refresh token. The system validates the token, rotates it (invalidates the old one, issues a new one), and returns a fresh access token and new refresh token.
+
+## Acceptance Criteria
+
+| ID    | Priority | User Story | Description |
+|-------|----------|-----------|-------------|
+| AC-01 | Must     | US-01      | POST /auth/register returns 201 with user id and email on valid input |
+| AC-02 | Must     | US-01      | POST /auth/register returns 409 when email already exists |
+| AC-03 | Must     | US-01      | Passwords are stored as bcrypt hashes; plain text is never persisted |
+| AC-04 | Must     | US-02      | POST /auth/login returns 200 with accessToken and refreshToken on valid credentials |
+| AC-05 | Must     | US-02      | POST /auth/login returns 401 on invalid credentials |
+| AC-06 | Must     | US-03      | POST /auth/refresh returns 200 with a new accessToken and rotated refreshToken |
+| AC-07 | Must     | US-03      | POST /auth/refresh returns 401 when refresh token is expired or invalid |

package/.claude/scripts/tests/fixtures/wb-invalid-bad-domain.json

@@ -0,0 +1,39 @@
+{
+  "schemaVersion": 2,
+  "feature": "FTR-014",
+  "phases": [
+    {
+      "id": "INFRA",
+      "type": "infrastructure",
+      "title": "Shared infrastructure setup",
+      "commit": {
+        "type": "feat",
+        "subject": "add shared infrastructure"
+      },
+      "tasks": [
+        {
+          "id": "INFRA-TASK-INFRA-01",
+          "title": "Create scripts directory",
+          "outcome": "The .claude/scripts directory exists",
+          "domain": "BACKEND",
+          "agentType": "developer-backend",
+          "dependsOn": [],
+          "acceptanceCriteria": [],
+          "verification": {
+            "commands": ["ls .claude/scripts"]
+          },
+          "estimate": {
+            "agentMinutes": 5,
+            "tokens": 8000
+          },
+          "outputCount": 1,
+          "groupingRationale": null,
+          "commit": {
+            "type": "feat",
+            "subject": "create .claude/scripts directory"
+          }
+        }
+      ]
+    }
+  ]
+}

package/.claude/scripts/tests/fixtures/wb-invalid-cycle.json

@@ -0,0 +1,61 @@
+{
+  "schemaVersion": 2,
+  "feature": "FTR-014",
+  "phases": [
+    {
+      "id": "INFRA",
+      "type": "infrastructure",
+      "title": "Shared infrastructure setup",
+      "commit": {
+        "type": "feat",
+        "subject": "add shared infrastructure"
+      },
+      "tasks": [
+        {
+          "id": "INFRA-TASK-INFRA-01",
+          "title": "Task A — depends on Task B (forms a cycle)",
+          "outcome": "Task A exists and triggers task_cycle_detected when validated",
+          "domain": "INFRA",
+          "agentType": "developer-backend",
+          "dependsOn": ["INFRA-TASK-INFRA-02"],
+          "acceptanceCriteria": [],
+          "verification": {
+            "commands": ["npm test"]
+          },
+          "estimate": {
+            "agentMinutes": 5,
+            "tokens": 8000
+          },
+          "outputCount": 1,
+          "groupingRationale": null,
+          "commit": {
+            "type": "feat",
+            "subject": "add task A"
+          }
+        },
+        {
+          "id": "INFRA-TASK-INFRA-02",
+          "title": "Task B — depends on Task A (forms a cycle)",
+          "outcome": "Task B exists and triggers task_cycle_detected when validated",
+          "domain": "INFRA",
+          "agentType": "developer-backend",
+          "dependsOn": ["INFRA-TASK-INFRA-01"],
+          "acceptanceCriteria": [],
+          "verification": {
+            "commands": ["npm test"]
+          },
+          "estimate": {
+            "agentMinutes": 5,
+            "tokens": 8000
+          },
+          "outputCount": 1,
+          "groupingRationale": null,
+          "commit": {
+            "type": "feat",
+            "subject": "add task B"
+          }
+        }
+      ]
+    }
+  ]
+}

package/.claude/scripts/tests/fixtures/wb-invalid-duplicate-id.json

@@ -0,0 +1,72 @@
+{
+  "schemaVersion": 2,
+  "feature": "FTR-014",
+  "phases": [
+    {
+      "id": "INFRA",
+      "type": "infrastructure",
+      "title": "Shared infrastructure setup",
+      "commit": {
+        "type": "feat",
+        "subject": "add shared infrastructure"
+      },
+      "tasks": [
+        {
+          "id": "INFRA-TASK-INFRA-01",
+          "title": "Create scripts directory",
+          "outcome": "The .claude/scripts directory exists",
+          "domain": "INFRA",
+          "agentType": "developer-backend",
+          "dependsOn": [],
+          "acceptanceCriteria": [],
+          "verification": {
+            "commands": ["ls .claude/scripts"]
+          },
+          "estimate": {
+            "agentMinutes": 5,
+            "tokens": 8000
+          },
+          "outputCount": 1,
+          "groupingRationale": null,
+          "commit": {
+            "type": "feat",
+            "subject": "create .claude/scripts directory"
+          }
+        }
+      ]
+    },
+    {
+      "id": "US-01",
+      "type": "user-story",
+      "title": "Implement validator entry point",
+      "commit": {
+        "type": "feat",
+        "subject": "implement validator entry point"
+      },
+      "tasks": [
+        {
+          "id": "INFRA-TASK-INFRA-01",
+          "title": "Duplicate task ID — same as INFRA-TASK-INFRA-01 above",
+          "outcome": "This task intentionally reuses INFRA-TASK-INFRA-01 to trigger unique_id_violation",
+          "domain": "BE",
+          "agentType": "developer-backend",
+          "dependsOn": [],
+          "acceptanceCriteria": [],
+          "verification": {
+            "commands": ["npm test"]
+          },
+          "estimate": {
+            "agentMinutes": 8,
+            "tokens": 12000
+          },
+          "outputCount": 1,
+          "groupingRationale": null,
+          "commit": {
+            "type": "feat",
+            "subject": "add duplicate task"
+          }
+        }
+      ]
+    }
+  ]
+}

package/.claude/scripts/tests/fixtures/wb-invalid-missing-field.json

@@ -0,0 +1,38 @@
+{
+  "schemaVersion": 2,
+  "feature": "FTR-014",
+  "phases": [
+    {
+      "id": "INFRA",
+      "type": "infrastructure",
+      "title": "Shared infrastructure setup",
+      "commit": {
+        "type": "feat",
+        "subject": "add shared infrastructure"
+      },
+      "tasks": [
+        {
+          "id": "INFRA-TASK-INFRA-01",
+          "title": "Create scripts directory",
+          "domain": "INFRA",
+          "agentType": "developer-backend",
+          "dependsOn": [],
+          "acceptanceCriteria": [],
+          "verification": {
+            "commands": ["ls .claude/scripts"]
+          },
+          "estimate": {
+            "agentMinutes": 5,
+            "tokens": 8000
+          },
+          "outputCount": 1,
+          "groupingRationale": null,
+          "commit": {
+            "type": "feat",
+            "subject": "create .claude/scripts directory"
+          }
+        }
+      ]
+    }
+  ]
+}