@dtlabs/ai-toolkit 0.11.0 → 0.13.0

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
 ---
@@ -80,56 +80,53 @@ Ask the user to **confirm or correct the draft**. Then grill ONLY on the `❓` g
 
 ## Phase 1 — Setup
 
-### 1a. Discover the next FTR number
+### 1a. Resolve the features root (MANDATORY — single source of truth)
 
-Scan `docs/features/` for existing folders matching the pattern `FTR-[0-9]+*`. Extract the highest number and increment by 1. If no folders exist, start at `FTR-001`.
+Before any file-system operation, run the following command **once** via Bash and capture its stdout into `featuresRoot`:
 
+```bash
+featuresRoot=$(ai-toolkit resolve-features-root) && echo "$featuresRoot"
 ```
-docs/features/FTR-001-user-management/  → max = 1
-docs/features/FTR-002-product-catalog/  → max = 2
+
+If the command exits non-zero, stop immediately and report the error to the user — do not proceed.
+
+This single captured value (`featuresRoot`) is the **sole source of truth** for the features root in every subsequent step. Do **not** hard-code `docs/features/`, `internal_docs/features/`, or any other path. Both the directory under which `feature.md` is written (step 1d) and the `--dir` argument passed to the ledger facade must use this exact value — they must always agree, with no divergent or duplicate roots.
+
+### 1b. Discover the next FTR number
+
+Scan `{featuresRoot}` for existing folders matching the pattern `FTR-[0-9]+*`. Extract the highest number and increment by 1. If no folders exist, start at `FTR-001`.
+
+```
+{featuresRoot}/FTR-001-user-management/  → max = 1
+{featuresRoot}/FTR-002-product-catalog/  → max = 2
 → next = FTR-003
 ```
 
-### 1b. Ask for a feature name
+### 1c. Ask for a feature name
 
 Ask the user: **"What is the name of this feature?"** (short, descriptive, in their language). Use it to build the folder slug in kebab-case.
 
 Example: "Supplier Onboarding" → `FTR-003-supplier-onboarding`
 
-### 1c. Create feature directory and initialize ledger
+### 1d. Create feature directory and open ledger entry
 
-Once you know the PREFIX (from 1a) and the feature slug (from 1b), do the following **before asking any grilling questions**:
+Once you know the PREFIX (from 1b) and the feature slug (from 1c), do the following **before asking any grilling questions**:
 
-1. Compute the paths:
-   - `featureDir` = `docs/features/{PREFIX}-{slug}` (e.g. `docs/features/FTR-003-supplier-onboarding`)
-   - `ledgerPath` = `{featureDir}/{PREFIX}-token-ledger.json`
+1. Compute `featureDir` using the captured `featuresRoot`:
+   - `featureDir` = `{featuresRoot}/{PREFIX}-{slug}` (e.g. `{featuresRoot}/FTR-003-supplier-onboarding`)
+   - This path is also the `--dir` value for every `ai-toolkit ledger` call that follows.
 
 2. Create the feature directory via Bash:
    ```bash
-   mkdir -p {featureDir}
+   mkdir -p "{featureDir}"
    ```
 
-3. Capture the current UTC timestamp via Bash:
+3. Open the ledger entry via the facade. Run the following command via Bash (quote the `--dir` path to handle spaces):
    ```bash
-   started_at=$(date -u +"%Y-%m-%dT%H:%M:%SZ") && echo $started_at
+   ai-toolkit ledger open --dir "{featureDir}" --prefix {PREFIX} --agent define-feature:define --phase define --model sonnet --attempt 1
    ```
 
-4. Write the initial ledger file at `{ledgerPath}` using the Write tool with exactly this content (substitute the actual PREFIX and timestamp):
-   ```json
-   [
-     {
-       "agent": "define-feature:define",
-       "phase": "define",
-       "model": "sonnet",
-       "status": "running",
-       "phase_delta_tokens": 0,
-       "started_at": "<started_at from step 3>",
-       "completed_at": null
-     }
-   ]
-   ```
-
-The ledger records that the define-feature agent is now running. Proceed to Phase 2.
+The ledger now records that the define-feature agent is running. Proceed to Phase 2.
 
 ---
 
@@ -254,12 +251,12 @@ Synthesize all answers into a structured `feature.md` file.
 ### Output path
 
 ```
-docs/features/{PREFIX}-{slug}/feature.md
+{featuresRoot}/{PREFIX}-{slug}/feature.md
 ```
 
-Example: `docs/features/FTR-003-supplier-onboarding/feature.md`
+Example: `{featuresRoot}/FTR-003-supplier-onboarding/feature.md`
 
-The directory was created in Phase 1c. If for any reason it doesn't exist, create it now.
+The directory was created in Phase 1d using `featuresRoot`. If for any reason it doesn't exist, create it now using the same `featuresRoot` path — do not substitute a different root.
 
 ### feature.md template
 
@@ -352,34 +349,13 @@ For each entity: name, key fields (name, type, constraints), relationships.
 
 ### 4b. Finalize ledger entry
 
-After writing `feature.md`, update the ledger entry to record successful completion:
+After writing `feature.md`, close the ledger entry via the facade. Run the following command via Bash (quote the `--dir` path to handle spaces):
 
-1. Capture the current UTC timestamp via Bash:
-   ```bash
-   completed_at=$(date -u +"%Y-%m-%dT%H:%M:%SZ") && echo $completed_at
-   ```
+```bash
+ai-toolkit ledger close --dir "{featureDir}" --prefix {PREFIX} --agent define-feature:define --attempt 1
+```
 
-2. Read the ledger file at `{featureDir}/{PREFIX}-token-ledger.json` using the Read tool.
-
-3. Write the updated ledger file using the Write tool, replacing the entry's fields:
-   - `"status"`: `"done"`
-   - `"completed_at"`: the timestamp captured in step 1
-   - `"phase_delta_tokens"`: leave as `0` — token measurement is not available to the agent directly
-
-   Example final ledger content:
-   ```json
-   [
-     {
-       "agent": "define-feature:define",
-       "phase": "define",
-       "model": "sonnet",
-       "status": "done",
-       "phase_delta_tokens": 0,
-       "started_at": "<original started_at>",
-       "completed_at": "<completed_at from step 1>"
-     }
-   ]
-   ```
+**Important:** `--tokens` is intentionally omitted. The ledger facade records `phase_delta_tokens` as `null` when `--tokens` is not supplied. `define-feature` is an interactive/LLM activity whose token consumption cannot be observed from within the agent itself — do **not** pass `0` or any estimate.
 
 ---
 
@@ -392,7 +368,7 @@ After writing `feature.md`:
 3. Tell the user the next step:
 
 ```
-✅ feature.md written at docs/features/{PREFIX}-{slug}/feature.md
+✅ feature.md written at {featuresRoot}/{PREFIX}-{slug}/feature.md
 
 Summary:
   Actors:               N
@@ -400,7 +376,7 @@ Summary:
   Acceptance criteria:  N (Must: N, Should: N, Could: N)
   Open questions:       N
 
-Next step: run /implement-feature docs/features/{PREFIX}-{slug}/feature.md
+Next step: run /implement-feature {featuresRoot}/{PREFIX}-{slug}/feature.md
            to start the full pipeline (requirements → spec → implementation → PR).
 ```
 

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/scripts/wb-render.js

@@ -105,6 +105,38 @@ function sanitizeField(str) {
     .trim()
 }
 
+// ── Verification-command helpers (LOSSLESS — never sanitized) ─────────────────
+//
+// Verification commands are executable and MUST survive verbatim: operators like
+// `||`, shell pipes `|`, and regex alternations `grep -E 'a|b|c'` are destroyed by
+// sanitizeField (which maps `|` → space to protect table/CSV column structure).
+// These commands are therefore rendered in a dedicated section as fenced code
+// blocks whose content is byte-equivalent to the source JSON. The task table shows
+// only a reference (a count + anchor link), never a sanitized copy of a command.
+
+function getVerificationCommands(task) {
+  const v = task && (task.verificationCommands ?? task.verification?.commands)
+  return Array.isArray(v) ? v : []
+}
+
+// Stable, deterministic HTML anchor id for a task's authoritative detail block.
+// The summary table links here; the "Task Details" section renders every field.
+function taskAnchor(id) {
+  const s = typeof id === 'string' ? id : String(id ?? '')
+  return 'task-' + s.replace(/[^A-Za-z0-9_-]/g, '-')
+}
+
+// Render a single command inside a fenced code block, byte-equivalent to `cmd`.
+// The fence length is chosen to exceed the longest backtick run in the content so a
+// command that itself contains backticks can never prematurely close the fence.
+function fencedCommandBlock(cmd) {
+  const s = typeof cmd === 'string' ? cmd : String(cmd ?? '')
+  const runs = s.match(/`+/g) || []
+  const maxRun = runs.reduce((m, r) => Math.max(m, r.length), 0)
+  const fence = '`'.repeat(Math.max(3, maxRun + 1))
+  return `${fence}\n${s}\n${fence}`
+}
+
 function buildCommitSubject(task) {
   if (!task.commit || typeof task.commit !== 'object') {
     return 'chore: implement task'
@@ -189,8 +221,15 @@ function renderMarkdown(wb, prefix, phaseDepsMap) {
     const est      = mins !== null ? String(mins) : '—'
     const depArr   = Array.isArray(task.dependsOn) && task.dependsOn.length > 0 ? task.dependsOn : null
     const deps     = depArr ? depArr.join(', ') : '—'
-    const verifArr = task.verificationCommands ?? task.verification?.commands ?? []
-    const verif    = verifArr.length > 0 ? sanitizeField(verifArr.join('; ')) : '—'
+    // The summary table is a digest only. Verification commands are NOT rendered
+    // in-table (sanitizeField would destroy their operators). The cell links to the
+    // authoritative per-task "Task Details" section, which carries every field
+    // (outcome, acceptance criteria, estimates, grouping rationale, commit, and the
+    // lossless verification commands). See renderTaskDetails / fencedCommandBlock.
+    const verifCmds = getVerificationCommands(task)
+    const verif     = verifCmds.length > 0
+      ? `${verifCmds.length} cmd — [details](#${taskAnchor(task.id)})`
+      : `[details](#${taskAnchor(task.id)})`
     return `| ${id} | ${title} | ${outcome} | ${domain} | ${est} | ${deps} | ${verif} |`
   }
 
@@ -263,6 +302,66 @@ function renderMarkdown(wb, prefix, phaseDepsMap) {
     }
   }
 
+  // ── Task Details (AUTHORITATIVE) ──
+  // The summary tables above are a digest. This section is the authoritative,
+  // self-contained representation of every task: it renders each field integrally so
+  // the Work Breakdown Markdown (plus the dispatch CSV) is a complete deliverable —
+  // the intermediate JSON is not required by any downstream consumer.
+  //
+  // Free-text fields (title, outcome, grouping rationale, commit subject) are rendered
+  // OUTSIDE any table and are therefore preserved verbatim — including pipes, which
+  // sanitizeField would otherwise map to spaces to protect table/CSV columns.
+  // Verification commands are emitted as fenced code blocks that are byte-equivalent
+  // to the source; the fence length exceeds any backtick run in the command so a
+  // command containing backticks can never break out of its block.
+  const raw = v => (typeof v === 'string' ? v : String(v ?? ''))
+  const getTokens = task => {
+    const t = task.estimate?.tokens ?? task.tokens
+    return (t !== undefined && t !== null) ? String(t) : '—'
+  }
+  const listOrDash = arr =>
+    (Array.isArray(arr) && arr.length > 0) ? arr.join(', ') : '—'
+
+  L.push('## Task Details')
+  L.push('')
+  L.push('> Authoritative per-task detail. Every field is rendered integrally so this document, together with the dispatch CSV, is a complete deliverable requiring no separate JSON. Verification commands are preserved **verbatim** in fenced code blocks — operators such as `||`, shell pipes `|`, and regex alternations (`grep -E \'a|b|c\'`) survive byte-for-byte. Each command is an independent fenced block.')
+  L.push('')
+  for (const phase of wb.phases) {
+    for (const task of (Array.isArray(phase.tasks) ? phase.tasks : [])) {
+      const cmds    = getVerificationCommands(task)
+      const mins    = getAgentMinutes(task)
+      L.push(`<a id="${taskAnchor(task.id)}"></a>`)
+      L.push(`### ${raw(task.id)}`)
+      L.push('')
+      L.push(`- **Task ID:** ${raw(task.id)}`)
+      L.push(`- **Title:** ${raw(task.title)}`)
+      L.push(`- **Outcome:** ${raw(task.outcome)}`)
+      L.push(`- **Domain:** ${raw(task.domain)}`)
+      L.push(`- **Agent type:** ${raw(task.agentType)}`)
+      L.push(`- **Dependencies:** ${listOrDash(task.dependsOn)}`)
+      L.push(`- **Acceptance criteria:** ${listOrDash(task.acceptanceCriteria)}`)
+      L.push(`- **Estimate — agent minutes:** ${mins !== null ? String(mins) : '—'}`)
+      L.push(`- **Estimate — tokens:** ${getTokens(task)}`)
+      L.push(`- **Output count:** ${task.outputCount != null ? String(task.outputCount) : '—'}`)
+      L.push(`- **Grouping rationale:** ${task.groupingRationale != null ? raw(task.groupingRationale) : '—'}`)
+      L.push(`- **Commit type:** ${task.commit && task.commit.type != null ? raw(task.commit.type) : '—'}`)
+      L.push(`- **Commit scope:** ${task.commit && task.commit.scope != null ? raw(task.commit.scope) : '—'}`)
+      L.push(`- **Commit subject:** ${task.commit && task.commit.subject != null ? raw(task.commit.subject) : '—'}`)
+      L.push('')
+      L.push('**Verification commands:**')
+      L.push('')
+      if (cmds.length === 0) {
+        L.push('_No verification commands._')
+        L.push('')
+      } else {
+        for (const cmd of cmds) {
+          L.push(fencedCommandBlock(cmd))
+          L.push('')
+        }
+      }
+    }
+  }
+
   // ── Statistics ──
   L.push('## Statistics')
   L.push('')

package/src/claude/scripts/wb-validate.js

@@ -59,6 +59,36 @@ const ERRORS = {
   EMPTY_PHASE:                  'empty_phase',                   // check 23
 }
 
+// ── Markdown table row splitter ─────────────────────────────────────────────
+// Splits a Markdown table row into cells on unescaped pipe separators only.
+// A backslash-escaped pipe (\|) is treated as a literal pipe *inside* the cell
+// rather than a column separator and is unescaped in the returned cell, so a
+// criterion such as `ai-toolkit ledger open\|close\|fail\|skip` stays in a
+// single cell and does not shift the "Related UC" column.
+// Returns the raw split including the leading/trailing empty cells produced by
+// the row's outer pipes, matching the previous `line.split('|')` contract so
+// callers can keep using `.slice(1, -1)`.
+function splitTableRow(line) {
+  const cells = []
+  let current = ''
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i]
+    if (ch === '\\' && line[i + 1] === '|') {
+      current += '|' // unescape: keep the literal pipe inside this cell
+      i++            // consume the escaped '|'
+      continue
+    }
+    if (ch === '|') {
+      cells.push(current)
+      current = ''
+      continue
+    }
+    current += ch
+  }
+  cells.push(current)
+  return cells
+}
+
 // ── AC table parser (prerequisite for checks 19–21) ─────────────────────────
 
 function parseAcTable(requirementsPath) {
@@ -122,7 +152,7 @@ function parseAcTable(requirementsPath) {
   }
 
   // ── Validate column headers ────────────────────────────────────────────────
-  const headerCells = lines[tableHeaderIdx].split('|').slice(1, -1).map(c => c.trim())
+  const headerCells = splitTableRow(lines[tableHeaderIdx]).slice(1, -1).map(c => c.trim())
   if (headerCells.length < 3) {
     process.stderr.write('Error: AC table header has fewer than 3 columns\n')
     process.exit(2)
@@ -143,7 +173,7 @@ function parseAcTable(requirementsPath) {
     if (!line.trim().startsWith('|')) break
 
     // Skip separator rows: every cell is only dashes, colons, or spaces
-    const rawCells = line.split('|').slice(1, -1)
+    const rawCells = splitTableRow(line).slice(1, -1)
     if (rawCells.every(c => /^[\s\-:]+$/.test(c))) continue
 
     const cells = rawCells.map(c => c.trim())

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…