@dtlabs/ai-toolkit 0.12.0 → 0.13.0

package/lib/execution-ledger.js

@@ -244,6 +244,73 @@ function _isLockStale(content, stat) {
   return mtimeAge > LOCK_ORPHAN_THRESHOLD_MS ? 'reclaimable' : 'wait';
 }
 
+// ── Metadata whitelist and reserved-field protection (INFRA-TASK-BE-03) ─────
+
+const METADATA_WHITELIST = new Set([
+  'agentId',
+  'nativeAgentName',
+  'platform',
+  'toolkitVersion',
+  'resolutionScope',
+  'definitionHash',
+]);
+
+const RESERVED_FIELDS = new Set([
+  'operation_id',
+  'agent',
+  'phase',
+  'model',
+  'status',
+  'started_at',
+  'completed_at',
+  'phase_delta_tokens',
+  'error',
+]);
+
+function _validateMetadata(metadata) {
+  for (const key of Object.keys(metadata)) {
+    if (RESERVED_FIELDS.has(key)) {
+      const err = new Error(
+        'open: metadata key "' + key + '" is a reserved field and cannot be set via metadata'
+      );
+      err.code = 'METADATA_RESERVED_FIELD';
+      err.key = key;
+      throw err;
+    }
+    if (!METADATA_WHITELIST.has(key)) {
+      const err = new Error(
+        'open: metadata key "' + key + '" is not in the whitelist; ' +
+        'allowed keys: ' + Array.from(METADATA_WHITELIST).join(', ')
+      );
+      err.code = 'METADATA_UNKNOWN_KEY';
+      err.key = key;
+      throw err;
+    }
+  }
+}
+
+function _extractStoredMetadata(entry) {
+  const result = {};
+  for (const key of METADATA_WHITELIST) {
+    if (Object.prototype.hasOwnProperty.call(entry, key)) {
+      result[key] = entry[key];
+    }
+  }
+  return result;
+}
+
+function _metadataEqual(storedEntry, newMetadata) {
+  const stored    = _extractStoredMetadata(storedEntry);
+  const storedKeys = Object.keys(stored).sort();
+  const newKeys    = Object.keys(newMetadata).sort();
+
+  if (storedKeys.length !== newKeys.length) return false;
+  for (var i = 0; i < newKeys.length; i++) {
+    if (stored[newKeys[i]] !== newMetadata[newKeys[i]]) return false;
+  }
+  return true;
+}
+
 // ── Public API (stubs — implemented by INFRA-TASK-BE-02 and US-0x tasks) ────
 
 function computeOperationId(prefix, agent, attempt) {
@@ -251,9 +318,14 @@ function computeOperationId(prefix, agent, attempt) {
   return crypto.createHash('sha256').update(input, 'utf8').digest('hex').slice(0, 32);
 }
 
-function open(dir, prefix, agent, phase, model, attempt) {
+function open(dir, prefix, agent, phase, model, attempt, metadata) {
   if (attempt == null) attempt = 1;
 
+  // Validate metadata keys BEFORE any lock or I/O (fail-closed).
+  if (metadata != null) {
+    _validateMetadata(metadata);
+  }
+
   const ledgerPath = path.join(dir, prefix + '-token-ledger.json');
   const lockPath   = ledgerPath + '.lock';
 
@@ -268,11 +340,24 @@ function open(dir, prefix, agent, phase, model, attempt) {
     });
 
     if (existingIndex !== -1) {
+      // Idempotent re-open: check metadata conflict BEFORE writing anything.
+      if (metadata != null) {
+        if (!_metadataEqual(entries[existingIndex], metadata)) {
+          const err = new Error(
+            'open: metadata conflict for operation_id ' + operation_id +
+            ' — supplied metadata differs from stored metadata; re-open rejected (fail-closed)'
+          );
+          err.code = 'METADATA_CONFLICT';
+          err.operation_id = operation_id;
+          throw err;
+        }
+      }
       // Resume: idempotently preserve original started_at and any positive
       // phase_delta_tokens — only reset status to running.
       entries[existingIndex] = Object.assign({}, entries[existingIndex], { status: 'running' });
     } else {
-      entries.push({
+      // First open: store standard fields, then spread validated metadata fields.
+      const newEntry = {
         operation_id:       operation_id,
         agent:              agent,
         phase:              phase,
@@ -281,7 +366,11 @@ function open(dir, prefix, agent, phase, model, attempt) {
         started_at:         started_at,
         completed_at:       null,
         phase_delta_tokens: null,
-      });
+      };
+      if (metadata != null) {
+        Object.assign(newEntry, metadata);
+      }
+      entries.push(newEntry);
     }
 
     _writeLedger(ledgerPath, entries);
@@ -512,4 +601,9 @@ module.exports = {
   _acquireLock,
   _releaseLock,
   _isLockStale,
+  _validateMetadata,
+  _extractStoredMetadata,
+  _metadataEqual,
+  METADATA_WHITELIST,
+  RESERVED_FIELDS,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtlabs/ai-toolkit",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "AI Toolkit — reusable agents and procedures for developers to build AI-powered applications.",
   "files": [
     "docs/",

package/src/claude/agents/{concurrency-safety-assessment.md → gaia-concurrency-safety-assessment.md}

@@ -1,5 +1,5 @@
 ---
-name: concurrency-safety-assessment
+name: gaia-concurrency-safety-assessment
 description: "Concurrency Safety Assessment — identifies race conditions, shared mutable state corruption, and non-deterministic behaviour in concurrent or event-driven systems. Language-agnostic; produces structured findings with severity, evidence, and mitigation patterns. Output: {ASSESS_PREFIX}-Concurrency-Assessment.md"
 tools: Read, Grep, Glob, Bash, Write
 model: haiku

package/src/claude/agents/{define-feature.md → gaia-define-feature.md}

@@ -1,5 +1,5 @@
 ---
-name: define-feature
+name: gaia-define-feature
 description: "Define Feature — grills the user with targeted questions to define a new feature, then writes feature.md in docs/features/FTR-XXX-slug/. Output: feature.md ready for /implement-feature"
 model: sonnet
 ---

package/src/claude/agents/{dependency-injection-refactoring.md → gaia-dependency-injection-refactoring.md}

@@ -1,5 +1,5 @@
 ---
-name: dependency-injection-refactoring
+name: gaia-dependency-injection-refactoring
 description: "Dependency Injection Refactoring — guides the incremental conversion of tightly coupled or statically accessed dependencies to constructor-injected services, preserving build integrity at every step. Language-agnostic; reads AGENTS.md for framework-specific DI patterns. Input: target classes from intervention document"
 model: sonnet
 ---

package/src/claude/agents/{dependency-supply-chain-security.md → gaia-dependency-supply-chain-security.md}

@@ -1,5 +1,5 @@
 ---
-name: dependency-supply-chain-security
+name: gaia-dependency-supply-chain-security
 description: "Dependency Supply Chain Security — guides the implementation of dependency integrity controls: trusted package sources, deterministic restore via lock files, unused dependency audit, and SCA integration in CI/CD pipelines. Works with npm, pip, NuGet, Maven, and other package managers; reads AGENTS.md for project stack. Output: remediated configuration files + CI/CD pipeline changes"
 model: sonnet
 ---

package/src/claude/agents/{developer-backend.md → gaia-developer-backend.md}

@@ -1,5 +1,5 @@
 ---
-name: developer-backend
+name: gaia-developer-backend
 description: "Senior Backend Developer — implements backend tasks (DB, BE, INFRA domains) from the Work Breakdown following project conventions. Input: path to feature.md + task IDs"
 model: sonnet
 ---

package/src/claude/agents/{developer-frontend.md → gaia-developer-frontend.md}

@@ -1,5 +1,5 @@
 ---
-name: developer-frontend
+name: gaia-developer-frontend
 description: "Senior Frontend Developer — implements frontend tasks (FE domain) from the Work Breakdown following project conventions. Input: path to feature.md + task IDs"
 model: sonnet
 ---

package/src/claude/agents/{developer-testing.md → gaia-developer-testing.md}

@@ -1,5 +1,5 @@
 ---
-name: developer-testing
+name: gaia-developer-testing
 description: "Senior Test Engineer — creates unit/integration tests for implemented features (TEST domain). Input: path to feature.md + task IDs"
 model: sonnet
 ---

package/src/claude/agents/{domain-model-refactoring.md → gaia-domain-model-refactoring.md}

@@ -1,5 +1,5 @@
 ---
-name: domain-model-refactoring
+name: gaia-domain-model-refactoring
 description: "Domain Model Refactoring — guides the decomposition of monolithic domain model files, introduction of type hierarchies for structurally similar types, and alignment of model names with domain ubiquitous language. Language-agnostic; reads AGENTS.md for project conventions. Input: target model directory from intervention document"
 model: sonnet
 ---

package/src/claude/agents/{generate-requirements.md → gaia-generate-requirements.md}

@@ -1,5 +1,5 @@
 ---
-name: generate-requirements
+name: gaia-generate-requirements
 description: "Generates a functional requirements document from a feature description. Input: path to feature.md"
 model: haiku
 tools: Read, Glob, Grep, Write

package/src/claude/agents/{generate-tech-spec.md → gaia-generate-tech-spec.md}

@@ -1,5 +1,5 @@
 ---
-name: generate-tech-spec
+name: gaia-generate-tech-spec
 description: "Generates a technical specification document from a feature description and requirements. Input: path to feature.md"
 model: haiku
 tools: Read, Glob, Grep, Write

package/src/claude/agents/{generate-work-breakdown.md → gaia-generate-work-breakdown.md}

@@ -1,5 +1,5 @@
 ---
-name: generate-work-breakdown
+name: gaia-generate-work-breakdown
 description: "Generates a structured work breakdown (User Stories + Tasks) from validated and approved Requirements and Tech-Spec. Input: path to feature.md"
 model: haiku
 tools: Read, Glob, Grep, Write
@@ -24,7 +24,7 @@ The user provides the path to a `feature.md` file. From the same directory, read
 ```
 Cannot generate work breakdown: `{file}` not found.
 The work breakdown requires validated and approved Requirements + Tech-Spec.
-Run /agent-project-manager to orchestrate the full pipeline (including validation and approval gates).
+Run /implement-feature to orchestrate the full pipeline (including validation and approval gates).
 ```
 
 ---
@@ -63,7 +63,7 @@ Every task must be the **smallest independently implementable, verifiable, and c
 
 - **One observable outcome** — the task produces exactly one concrete artifact or behavioral change (one file, one endpoint, one migration, one test suite for one check). State it in the `outcome` field as a factual sentence describing what exists after the task is done.
 - **One domain** — choose exactly one: `BE`, `FE`, `DB`, `DevOps`, `INFRA`, or `TEST`.
-- **One agent type** — choose exactly one: `developer-backend`, `developer-frontend`, `developer-testing`, `developer-database`, or `review-solution`.
+- **One agent type** — choose exactly one: `developer-backend`, `developer-frontend`, `developer-testing`, or `review-solution`. (`developer-database` is deprecated — use `developer-backend` for DB domain tasks.)
 - **One commit** — supply a single `commit.subject` describing the change.
 - **Estimated ≤ 15 minutes of agent time** — this is the target. If a task cannot be scoped to ≤ 15 minutes, split it further. Tasks up to 20 minutes are acceptable but above target. Tasks over 30 minutes are invalid and will be rejected by the validator.
 
@@ -126,7 +126,7 @@ Decomposition strategy by domain:
 | `title` | string | Short descriptive title; must not contain `\|`, CR, or LF |
 | `outcome` | string | Single observable outcome — what exists after this task is done |
 | `domain` | string | One of: `BE`, `FE`, `DB`, `DevOps`, `INFRA`, `TEST` |
-| `agentType` | string | One of: `developer-backend`, `developer-frontend`, `developer-testing`, `developer-database`, `review-solution` |
+| `agentType` | string | One of: `developer-backend`, `developer-frontend`, `developer-testing`, `review-solution` (deprecated: `developer-database` — maps to `developer-backend`) |
 | `dependsOn` | array of strings | Task IDs this task depends on; may be empty `[]`; all IDs must be defined within this same JSON |
 | `acceptanceCriteria` | array of strings | AC IDs from Requirements that this task covers; may be empty `[]` |
 | `verification` | object | `{ "commands": ["..."] }` — one or more shell commands that verify the task output; array must be non-empty |
@@ -136,7 +136,7 @@ Decomposition strategy by domain:
 | `commit` | object | `{ "type": "feat", "subject": "..." }` — subject must not contain `\|`, CR, or LF |
 
 **Domain → agentType mapping (default):**
-- `DB` → `developer-database`
+- `DB` → `developer-backend` (note: `developer-database` is a deprecated alias that still resolves — do NOT use it in new Work Breakdowns)
 - `BE`, `INFRA`, `DevOps` → `developer-backend`
 - `FE` → `developer-frontend`
 - `TEST` → `developer-testing`

package/src/claude/agents/{generic-software-assessment.md → gaia-generic-software-assessment.md}

@@ -1,5 +1,5 @@
 ---
-name: generic-software-assessment
+name: gaia-generic-software-assessment
 description: "Generic Software Assessment — performs a broad quality analysis across architecture, code quality, security, testability, observability, and DevOps. Reads AGENTS.md for project conventions. Output: {ASSESS_PREFIX}-Generic-Assessment.md"
 tools: Read, Grep, Glob, Bash, Write
 model: haiku

package/src/claude/agents/{god-class-decomposition.md → gaia-god-class-decomposition.md}

@@ -1,5 +1,5 @@
 ---
-name: god-class-decomposition
+name: gaia-god-class-decomposition
 description: "God Class Decomposition — guides the safe, incremental decomposition of oversized classes and methods using responsibility cluster analysis, extract-method, extract-class, and parameter object refactoring. Language-agnostic; reads AGENTS.md for project conventions. Input: target class(es) from intervention document"
 model: sonnet
 ---

package/src/claude/agents/{init-agents-md.md → gaia-init-agents-md.md}

@@ -1,5 +1,5 @@
 ---
-name: init-agents-md
+name: gaia-init-agents-md
 description: "Analyzes a project codebase and generates a complete AGENTS.md file with tech stack, conventions, real code patterns, build/test commands, and hard constraints. Input: (optional) path to project root — defaults to current working directory."
 model: sonnet
 tools: Read, Glob, Grep, Bash, Write

package/src/claude/agents/{install-toolkit.md → gaia-install-toolkit.md}

@@ -1,5 +1,5 @@
 ---
-name: install-toolkit
+name: gaia-install-toolkit
 description: "Installs the ai-toolkit into a destination project by copying agents, skills, commands, and procedures. Input: [path-to-destination] [--force] — defaults to current working directory"
 model: sonnet
 ---

package/src/claude/agents/{intervention-documentation-standard.md → gaia-intervention-documentation-standard.md}

@@ -1,5 +1,5 @@
 ---
-name: intervention-documentation-standard
+name: gaia-intervention-documentation-standard
 description: "Intervention Documentation Standard — generates structured, self-contained intervention documents from assessment findings. Each document is independently actionable by an architect or developer agent. Input: assessment findings; Output: {ASSESS_PREFIX}-INT-NNN-{slug}.md per finding + Interventions-Index.md"
 model: sonnet
 tools: Read, Grep, Glob, Bash, Write

package/src/claude/agents/{layered-architecture-assessment.md → gaia-layered-architecture-assessment.md}

@@ -1,5 +1,5 @@
 ---
-name: layered-architecture-assessment
+name: gaia-layered-architecture-assessment
 description: "Layered Architecture Assessment — audits a codebase for layer boundary violations, missing separation of concerns, and namespace/package misalignment. Produces a violation inventory and a recommended layer model. Language-agnostic; reads AGENTS.md for project conventions. Output: {ASSESS_PREFIX}-Layer-Assessment.md"
 tools: Read, Grep, Glob, Bash, Write
 model: haiku

package/src/claude/agents/{review-solution.md → gaia-review-solution.md}

@@ -1,5 +1,5 @@
 ---
-name: review-solution
+name: gaia-review-solution
 description: "Senior Architect — full solution review across quality, reuse, architecture, and security dimensions. Reports findings without auto-fixing. Input: scope (files, US-XX, or git diff)"
 model: opus
 tools: Read, Grep, Glob, Bash

package/src/claude/agents/{security-hardening.md → gaia-security-hardening.md}

@@ -1,5 +1,5 @@
 ---
-name: security-hardening
+name: gaia-security-hardening
 description: "Security Hardening — guides the implementation of targeted security fixes: input validation at system boundaries, parameterised queries, secret management, log sanitisation, and TLS/transport configuration. Language-agnostic; reads AGENTS.md for project-specific patterns. Input: security findings from assessment"
 model: sonnet
 ---

package/src/claude/agents/{validate-feature-docs.md → gaia-validate-feature-docs.md}

@@ -1,5 +1,5 @@
 ---
-name: validate-feature-docs
+name: gaia-validate-feature-docs
 description: "Validates Requirements and Tech-Spec documents against feature.md. Triggers targeted revision of failing documents if gaps are found. Input: path to feature.md"
 model: haiku
 tools: Read, Glob, Grep, Write
@@ -18,7 +18,7 @@ A QA agent that cross-references `feature.md` against `{PREFIX}-Requirements.md`
    - `feature.md` — source of truth
    - `{PREFIX}-Requirements.md`
    - `{PREFIX}-Tech-Spec.md`
-3. If either output document is missing, abort and report: "Cannot validate: `{file}` not found. Run /agent-project-manager first."
+3. If either output document is missing, abort and report: "Cannot validate: `{file}` not found. Run /implement-feature first."
 
 ---
 

package/src/claude/agents/{validate-work-breakdown-semantic.md → gaia-validate-work-breakdown-semantic.md}

@@ -1,5 +1,5 @@
 ---
-name: validate-work-breakdown-semantic
+name: gaia-validate-work-breakdown-semantic
 description: "Semantic validator for Work Breakdown JSON — analyzes task coherence, scope alignment, and estimate realism. Runs after wb-validate.js exits 0. Input: path to {PREFIX}-Work-Breakdown.json"
 model: sonnet
 tools: Read, Glob, Grep

package/src/claude/commands/next-task.md

@@ -23,14 +23,14 @@ Steps:
 
    Suggested agent: <subagent_type>
    Suggested invocation:
-     subagent_type: <developer-backend | developer-frontend | developer-testing>
+     subagent_type: <gaia-developer-backend | gaia-developer-frontend | gaia-developer-testing>
      prompt: <feature-md-path> <task-id>
    ```
 
    Domain → agent mapping:
-   - `DB`, `BE`, `INFRA` → `developer-backend`
-   - `FE` → `developer-frontend`
-   - `TEST` → `developer-testing`
+   - `DB`, `BE`, `INFRA` → `gaia-developer-backend`
+   - `FE` → `gaia-developer-frontend`
+   - `TEST` → `gaia-developer-testing`
 
 5. If no unblocked task remains, output: `✅ All tasks are either done, in progress, or blocked. Check blockers.`
 

package/src/claude/skills/assess-codebase/SKILL.md

@@ -157,7 +157,7 @@ Append a horizontal rule (`---`) followed by:
 |-------|------------|-------|-------------|---------------|-------|---------------|-----------------|----------|
 | {agent} | {scope} | {model} | {est} | {actual} | {±delta} | {est_cost} | {actual_cost} | {Xmin Ys} |
 ...
-| assessment-manager/am-phase1 (orchestrator) | — | sonnet | 80,000 | {actual} | ±{delta} | $0.4320 | ${actual_cost} | {duration} |
+| am-phase1 (orchestrator) | — | sonnet | 80,000 | {actual} | ±{delta} | $0.4320 | ${actual_cost} | {duration} |
 ```
 
 Column rules:

package/src/claude/skills/define-feature/SKILL.md

@@ -3,10 +3,10 @@ description: "Define Feature — reads existing repo context, then grills only o
 disable-model-invocation: true
 ---
 
-Spawn the `define-feature` agent, passing through whatever the user provided as a source reference (a backlog entry, ticket path, spec path, or free-text description). If the user gave nothing, pass an empty source.
+Spawn the `gaia-define-feature` agent, passing through whatever the user provided as a source reference (a backlog entry, ticket path, spec path, or free-text description). If the user gave nothing, pass an empty source.
 
 ```
-subagent_type: define-feature
+subagent_type: gaia-define-feature
 prompt: |
   Start the feature definition session.
   Source reference (may be empty): {{user arguments verbatim}}

package/src/claude/skills/hi-gaia/SKILL.md

@@ -37,7 +37,7 @@ Here's what I know and what's available for you:
 - `/feature-status`, `/check-docs`, `/next-task`, `/pr-description`
 - `/assessment-status`
 
-**Specialized agents** (spawnable): project-manager, developer-backend, developer-frontend, developer-testing, review-solution, assessment-manager, and more.
+**Specialized agents** (spawnable): developer-backend, developer-frontend, developer-testing, review-solution, and more.
 
 Let me take a look at your workspace to understand the context…