@dtlabs/ai-toolkit 0.12.0 → 0.13.0

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

@@ -14,17 +14,98 @@ with their declared `model:` frontmatter honoured and producing accurate per-age
 
 ---
 
+## Step 0 — Agent Preflight (fail-closed, AC-19)
+
+Before starting the pipeline, verify that every pipeline agent is installed and verified.
+
+1. **Derive the feature prefix** from the `<path-to-feature.md>` argument (e.g. path contains `FTR-017` → prefix = `FTR-017`). Derive the ledger directory as the directory containing the feature.md file.
+
+2. **Open the preflight ledger entry** (fail-closed — if this fails, do NOT proceed):
+   ```bash
+   ai-toolkit ledger open \
+     --prefix {PREFIX} \
+     --agent agent-preflight:implement-feature \
+     --phase phase3 \
+     --dir {LEDGER_DIR}
+   ```
+   If the command exits non-zero, **STOP IMMEDIATELY** — report the error and do not continue.
+
+3. **Run the preflight check:**
+   ```bash
+   ai-toolkit agents preflight --project . --pipeline implement-feature
+   ```
+
+4. **On success** (exit 0): close the ledger entry:
+   ```bash
+   ai-toolkit ledger close \
+     --prefix {PREFIX} \
+     --agent agent-preflight:implement-feature \
+     --dir {LEDGER_DIR}
+   ```
+   Then continue to Step 1.
+
+5. **On failure** (exit non-zero): mark the ledger entry failed and STOP:
+   ```bash
+   ai-toolkit ledger fail \
+     --prefix {PREFIX} \
+     --agent agent-preflight:implement-feature \
+     --error "agent preflight failed — one or more pipeline agents unverified" \
+     --dir {LEDGER_DIR}
+   ```
+   Report the preflight error to the user. Do NOT continue to Step 1.
+
+---
+
 ## Step 1 — Invoke pm-phase1 (Documentation Phase)
 
-Invoke the `pm-phase1` workflow with the feature path:
+### Step 1a — Tier 1 dispatch guard (AC-06, AC-07, AC-20)
 
+Before dispatching, resolve and verify the pm-phase1 orchestrator:
+
+```bash
+ai-toolkit agents resolve \
+  --project . \
+  --id gaia.orchestrator.feature.phase1 \
+  --require-verified
 ```
-subagent_type: pm-phase1
+
+If exit non-zero → **HARD STOP**: report the error, do not dispatch pm-phase1.
+
+Store the resolution record fields: `nativeName`, `sha256` (definitionHash), `scope` (resolutionScope), `toolkitVersion`.
+
+Open the dispatch ledger entry (fail-closed):
+
+```bash
+ai-toolkit ledger open \
+  --prefix {PREFIX} \
+  --agent pm-phase1:dispatch \
+  --phase phase3 \
+  --dir {LEDGER_DIR} \
+  --metadata-json '{"agentId":"gaia.orchestrator.feature.phase1","nativeAgentName":"{nativeName}","platform":"claude","toolkitVersion":"{toolkitVersion}","resolutionScope":"{scope}","definitionHash":"{sha256}"}'
+```
+
+If exit non-zero → **HARD STOP** (fail-closed): do not dispatch.
+
+### Step 1b — Invoke pm-phase1 using verified nativeName
+
+Invoke the workflow using ONLY the resolved `nativeName` (never a hardcoded name):
+
+```
+subagent_type: {nativeName}
 prompt: <path-to-feature.md>
 ```
 
 Wait for the workflow to complete. Do NOT proceed until it returns.
 
+After the workflow returns, close the dispatch ledger entry:
+
+```bash
+ai-toolkit ledger close \
+  --prefix {PREFIX} --agent pm-phase1:dispatch --dir {LEDGER_DIR}
+```
+
+If ledger close fails → **HARD STOP**: report the error and do not continue.
+
 Extract from the result:
 - `prefix` — feature prefix (e.g. `FTR-009`)
 - `requirements.summary` — requirements file summary
@@ -93,10 +174,36 @@ If the file is missing or incomplete, write it again before proceeding.
 
 ## Step 3 — Invoke pm-phase2 (Work Breakdown Phase)
 
-Invoke the `pm-phase2` workflow:
+### Step 3a — Tier 1 dispatch guard
+
+Resolve and verify pm-phase2:
+
+```bash
+ai-toolkit agents resolve \
+  --project . \
+  --id gaia.orchestrator.feature.phase2 \
+  --require-verified
+```
+
+If exit non-zero → **HARD STOP**: do not dispatch pm-phase2.
+
+Open the dispatch ledger entry (fail-closed):
+
+```bash
+ai-toolkit ledger open \
+  --prefix {PREFIX} \
+  --agent pm-phase2:dispatch \
+  --phase phase3 \
+  --dir {LEDGER_DIR} \
+  --metadata-json '{"agentId":"gaia.orchestrator.feature.phase2","nativeAgentName":"{nativeName}","platform":"claude","toolkitVersion":"{toolkitVersion}","resolutionScope":"{scope}","definitionHash":"{sha256}"}'
+```
+
+If exit non-zero → **HARD STOP** (fail-closed).
+
+### Step 3b — Invoke pm-phase2 using verified nativeName
 
 ```
-subagent_type: pm-phase2
+subagent_type: {nativeName}
 prompt: <path-to-feature.md>
 ```
 
@@ -109,6 +216,15 @@ Wait for the workflow to complete. Extract from the result:
 - `agent_estimate` — agent parallel estimate
 - `token_ledger` — per-agent token data from phase 2
 
+Close the dispatch ledger entry after the workflow returns:
+
+```bash
+ai-toolkit ledger close \
+  --prefix {PREFIX} --agent pm-phase2:dispatch --dir {LEDGER_DIR}
+```
+
+If ledger close fails → **HARD STOP**: report the error. Do not continue to Gate 2. The error is not swallowed (AC-22).
+
 ---
 
 ## Step 4 — Present Gate 2 (HARD STOP — present in main loop)
@@ -179,10 +295,52 @@ git checkout feature/{PREFIX}-{short-slug}
 Pre-condition check: read `{PREFIX}-Approvals.md` and verify BOTH Gate 1 ✅ and Gate 2 ✅.
 If either is missing, return to the missing gate.
 
-Invoke the `pm-phase3` workflow:
+### Step 6a — Tier 1 dispatch guard (Gate 2 post-approval, AC-06, AC-07, AC-08)
+
+After Gate 2 approval, resolve and verify pm-phase3 with `--require-verified`. Only a `verified` status permits dispatch:
+
+```bash
+ai-toolkit agents resolve \
+  --project . \
+  --id gaia.orchestrator.feature.phase3 \
+  --require-verified
+```
+
+If exit non-zero → **HARD STOP** (AC-08): pm-phase3 is absent or tampered. Report the error with remediation instructions:
+
+```
+⛔ HARD STOP — pm-phase3 cannot be dispatched.
+
+Remediation:
+  1. Run: ai-toolkit agents resolve --project . --id gaia.orchestrator.feature.phase3
+  2. Check the status field in the output for the failure reason.
+  3. Re-install the toolkit if the status is not-installed or hash-mismatch.
+  4. Contact the toolkit team if the issue persists.
+
+Do NOT use an alternative workflow name or any fallback. This pipeline requires verified agents.
+```
+
+Do NOT use any alternative workflow name or fallback.
+
+Open the dispatch ledger entry (fail-closed):
+
+```bash
+ai-toolkit ledger open \
+  --prefix {PREFIX} \
+  --agent pm-phase3:dispatch \
+  --phase phase3 \
+  --dir {LEDGER_DIR} \
+  --metadata-json '{"agentId":"gaia.orchestrator.feature.phase3","nativeAgentName":"{nativeName}","platform":"claude","toolkitVersion":"{toolkitVersion}","resolutionScope":"{scope}","definitionHash":"{sha256}"}'
+```
+
+If exit non-zero → **HARD STOP** (fail-closed): do not dispatch.
+
+### Step 6b — Invoke pm-phase3 using verified nativeName
+
+Invoke the workflow using ONLY the resolved `nativeName` (never a hardcoded name):
 
 ```
-subagent_type: pm-phase3
+subagent_type: {nativeName}
 prompt: <path-to-feature.md> --branch feature/{PREFIX}-{short-slug}
 ```
 
@@ -194,6 +352,26 @@ Wait for the workflow to complete. Capture its full result, including the `<usag
 
 If `issues_summary.escalations > 0`, report the escalation details to the user.
 
+**If pm-phase3 returned an error or escalation:** mark the dispatch ledger entry failed before stopping:
+
+```bash
+ai-toolkit ledger fail \
+  --prefix {PREFIX} --agent pm-phase3:dispatch \
+  --error "pm-phase3 returned an error or escalation" \
+  --dir {LEDGER_DIR}
+```
+
+If `ledger fail` itself exits non-zero → **HARD STOP** (AC-22): report both the original workflow error and the ledger failure. The error is NOT swallowed.
+
+**On successful completion:** close the dispatch ledger entry:
+
+```bash
+ai-toolkit ledger close \
+  --prefix {PREFIX} --agent pm-phase3:dispatch --dir {LEDGER_DIR}
+```
+
+If ledger close fails → **HARD STOP** (AC-22): report the error. The pipeline does not silently swallow ledger failures after dispatch returns.
+
 ---
 
 ## Step 7 — Complete Token Estimate file
@@ -207,7 +385,7 @@ Read `{PREFIX}-Token-Estimate.md`. Append the orchestrator row and grand total:
 > **Null-compatibility — actuals reading and cost calculation:** Treat a token value of `null`, `0`, or `not_available` as **data unavailable** — never as a real, observable zero consumption. Render unavailable values as `—` in the Actual tokens and Actual cost columns; exclude them from sums, averages, and grand totals. Preventing resume clobber and legacy misinterpretation requires that no unavailable measurement is coerced into a real zero.
 
 ```markdown
-| project-manager/pm-phase3 (orchestrator) | — | sonnet | 80,000 (estimated) | {subagent_tokens} (actual) | ±{delta} | {duration} |
+| pm-phase3 (orchestrator) | — | sonnet | 80,000 (estimated) | {subagent_tokens} (actual) | ±{delta} | {duration} |
 
 ---
 
@@ -216,7 +394,7 @@ Read `{PREFIX}-Token-Estimate.md`. Append the orchestrator row and grand total:
 | Agent | Task / Scope | Model | Est. tokens | Actual tokens | Delta | Est. cost ($) | Actual cost ($) | Duration |
 |-------|-------------|-------|------------|---------------|-------|--------------|----------------|----------|
 {one row per entry in token_ledger — from phase 1, 2, and 3; for any entry where actual tokens is null, 0, or not_available show — in Actual tokens and Actual cost and exclude that row from totals}
-| project-manager/pm-phase3 (orchestrator) | — | sonnet | 80,000 | {subagent_tokens} | ±{delta} | $0.4320 | ${actual_cost} | {duration} |
+| pm-phase3 (orchestrator) | — | sonnet | 80,000 | {subagent_tokens} | ±{delta} | $0.4320 | ${actual_cost} | {duration} |
 
 ## Estimation accuracy by agent type
 

package/src/claude/skills/init-agents/SKILL.md

@@ -4,10 +4,10 @@ argument-hint: "[path-to-project-root]"
 disable-model-invocation: true
 ---
 
-Spawn the `init-agents-md` agent with the arguments provided by the user:
+Spawn the `gaia-init-agents-md` agent with the arguments provided by the user:
 
 ```
-subagent_type: init-agents-md
+subagent_type: gaia-init-agents-md
 prompt: [path-to-project-root]
 ```
 

package/src/claude/skills/install-toolkit/SKILL.md

@@ -4,10 +4,10 @@ argument-hint: "[path-to-destination] [--force]"
 disable-model-invocation: true
 ---
 
-Spawn the `install-toolkit` agent with the arguments provided by the user:
+Spawn the `gaia-install-toolkit` agent with the arguments provided by the user:
 
 ```
-subagent_type: install-toolkit
+subagent_type: gaia-install-toolkit
 prompt: <path-to-destination> [--force]
 ```
 

package/src/claude/workflows/pm-phase1.js

@@ -9,11 +9,69 @@ export const meta = {
   ],
 }
 
+// ── Tier 2 resolution guard ───────────────────────────────────────────────────
+// All worker agents must be resolved via the CLI before dispatch.
+// No direct require('lib/agent-registry') — resolution goes through the CLI facade.
+const RESOLVE_SCHEMA = {
+  type: 'object',
+  properties: {
+    nativeName:  { type: 'string' },
+    status:      { type: 'string' },
+    agentId:     { type: 'string' },
+    exitNonZero: { type: 'boolean' },
+    error:       { type: 'string' },
+  },
+}
+
+async function resolveAgentTier2(agentId, label, phaseName) {
+  const result = await agent(
+    `Run this command via Bash:\n\nai-toolkit agents resolve --project . --id ${agentId} --require-verified\n\nIf the command exits 0: parse the JSON from stdout and return it with exitNonZero: false.\nIf the command exits non-zero: return {"exitNonZero": true, "error": "<stderr text>", "agentId": "${agentId}"}.`,
+    { label, phase: phaseName, model: 'haiku', schema: RESOLVE_SCHEMA }
+  )
+  if (!result || result.exitNonZero || !result.nativeName) {
+    throw new Error(`HARD STOP — Tier 2 resolution failed for ${agentId}: ${result && result.error ? result.error : 'no nativeName returned'}`)
+  }
+  return result.nativeName
+}
+
+// ── Tier 3 — self-ledger helper ───────────────────────────────────────────────
+const SELF_LEDGER_SCHEMA = {
+  type: 'object',
+  properties: {
+    exitCode: { type: 'number' },
+    stdout:   { type: 'string' },
+    stderr:   { type: 'string' },
+  },
+  required: ['exitCode'],
+}
+
+async function selfLedgerOp(cmd, label, phaseName) {
+  const result = await agent(
+    `Run this shell command via Bash and return the exit code as structured output.\n\nCommand: ${cmd}\n\nCapture: exitCode (integer), stdout (string), stderr (string). Return all three.`,
+    { label, phase: phaseName, model: 'haiku', schema: SELF_LEDGER_SCHEMA }
+  )
+  const status = (result && typeof result.exitCode === 'number') ? result.exitCode : 1
+  if (status !== 0) {
+    throw new Error(`HARD STOP — self-ledger operation failed. Exit code: ${status}. Command: ${cmd}`)
+  }
+}
+
 // ── Parse args ────────────────────────────────────────────────────────────────
 // args is the raw prompt string: "<path-to-feature.md> [--force]"
 const featurePath = args.split(/\s+/)[0]
 const force       = typeof args === 'string' && args.includes('--force')
 
+// Derive prefix and feature dir early (before Discovery agent) for self-registration
+const featureDirEarly  = featurePath.replace(/[/\\][^/\\]+$/, '')
+const prefixEarlyMatch = featureDirEarly.match(/([A-Z]+-\d+)/)
+const prefixEarly      = prefixEarlyMatch ? prefixEarlyMatch[1] : 'FTR-000'
+
+// ── Tier 3 self-registration (open BEFORE any main logic, fail-closed) ────────
+await selfLedgerOp(
+  `ai-toolkit ledger open --prefix ${prefixEarly} --agent pm-phase1:self --phase phase1 --dir "${featureDirEarly}" --attempt 1`,
+  'ledger-open-pm-phase1-self', 'Discovery'
+)
+
 // ── Discovery ─────────────────────────────────────────────────────────────────
 phase('Discovery')
 
@@ -87,13 +145,14 @@ const tokenLedger = []
 const errors      = []
 
 if (discoveryResult.needs_requirements) {
+  const reqNativeName = await resolveAgentTier2('gaia.agent.planner.requirements', 'resolve-generate-requirements', 'Requirements')
   const reqKey = 'generate-requirements:phase1'
   await agent(
     `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger open --dir ${feature_dir} --prefix ${prefix} --agent ${reqKey} --phase phase1 --model haiku --attempt 1\n\nReturn no output.`,
     { label: 'ledger-open-requirements', phase: 'Requirements', model: 'haiku' }
   )
   const beforeReq = budget.spent()
-  const reqResult = await agent(featurePath, { agentType: 'generate-requirements', label: 'generate-requirements', phase: 'Requirements' })
+  const reqResult = await agent(featurePath, { agentType: reqNativeName, label: 'generate-requirements', phase: 'Requirements' })
   const reqTokens = budget.spent() - beforeReq
   await agent(
     `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger close --dir ${feature_dir} --prefix ${prefix} --agent ${reqKey} --tokens ${reqTokens} --attempt 1\n\nReturn no output.`,
@@ -109,13 +168,14 @@ if (discoveryResult.needs_requirements) {
 phase('Tech-Spec')
 
 if (discoveryResult.needs_tech_spec) {
+  const specNativeName = await resolveAgentTier2('gaia.agent.planner.tech-spec', 'resolve-generate-tech-spec', 'Tech-Spec')
   const specKey = 'generate-tech-spec:phase1'
   await agent(
     `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger open --dir ${feature_dir} --prefix ${prefix} --agent ${specKey} --phase phase1 --model haiku --attempt 1\n\nReturn no output.`,
     { label: 'ledger-open-tech-spec', phase: 'Tech-Spec', model: 'haiku' }
   )
   const beforeSpec = budget.spent()
-  const specResult = await agent(featurePath, { agentType: 'generate-tech-spec', label: 'generate-tech-spec', phase: 'Tech-Spec' })
+  const specResult = await agent(featurePath, { agentType: specNativeName, label: 'generate-tech-spec', phase: 'Tech-Spec' })
   const specTokens = budget.spent() - beforeSpec
   await agent(
     `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger close --dir ${feature_dir} --prefix ${prefix} --agent ${specKey} --tokens ${specTokens} --attempt 1\n\nReturn no output.`,
@@ -130,6 +190,11 @@ if (discoveryResult.needs_tech_spec) {
 // ── validate-feature-docs (revision loop, max 3 cycles) ──────────────────────
 phase('Validation')
 
+// Resolve all validation-phase agents once before the loop (Tier 2 guard)
+const valNativeName = await resolveAgentTier2('gaia.agent.planner.validate-feature-docs', 'resolve-validate-feature-docs', 'Validation')
+const reqRevNativeName = await resolveAgentTier2('gaia.agent.planner.requirements', 'resolve-generate-requirements-rev', 'Validation')
+const specRevNativeName = await resolveAgentTier2('gaia.agent.planner.tech-spec', 'resolve-generate-tech-spec-rev', 'Validation')
+
 let validationSummary = 'skipped'
 let lastValText       = ''
 const MAX_CYCLES = 3
@@ -142,7 +207,7 @@ for (let cycle = 1; cycle <= MAX_CYCLES; cycle++) {
     { label: `ledger-open-validate-cycle-${cycle}`, phase: 'Validation', model: 'haiku' }
   )
   const beforeVal = budget.spent()
-  const valResult = await agent(featurePath, { agentType: 'validate-feature-docs', label: `validate-feature-docs (cycle ${cycle})`, phase: 'Validation' })
+  const valResult = await agent(featurePath, { agentType: valNativeName, label: `validate-feature-docs (cycle ${cycle})`, phase: 'Validation' })
   const valTokens = budget.spent() - beforeVal
   await agent(
     `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger close --dir ${feature_dir} --prefix ${prefix} --agent ${valKey} --tokens ${valTokens} --attempt 1\n\nReturn no output.`,
@@ -167,10 +232,10 @@ for (let cycle = 1; cycle <= MAX_CYCLES; cycle++) {
   if (cycle < MAX_CYCLES) {
     // Re-run failing docs before next validation cycle
     if (resultText.includes('Requirements')) {
-      await agent(featurePath, { agentType: 'generate-requirements', label: `generate-requirements (revision ${cycle})`, phase: 'Validation' })
+      await agent(featurePath, { agentType: reqRevNativeName, label: `generate-requirements (revision ${cycle})`, phase: 'Validation' })
     }
     if (resultText.includes('Tech-Spec')) {
-      await agent(featurePath, { agentType: 'generate-tech-spec', label: `generate-tech-spec (revision ${cycle})`, phase: 'Validation' })
+      await agent(featurePath, { agentType: specRevNativeName, label: `generate-tech-spec (revision ${cycle})`, phase: 'Validation' })
     }
   } else {
     validationSummary = 'gaps remain after 3 cycles'
@@ -289,5 +354,11 @@ const gate1Payload = {
   errors,
 }
 
+// ── Tier 3 self-registration — close on successful completion ─────────────────
+await selfLedgerOp(
+  `ai-toolkit ledger close --prefix ${prefix} --agent pm-phase1:self --dir "${feature_dir}" --attempt 1`,
+  'ledger-close-pm-phase1-self', 'Validation'
+)
+
 log(`pm-phase1 complete — gate1_payload ready`)
 return gate1Payload

package/src/claude/workflows/pm-phase2.js

@@ -49,6 +49,31 @@ function normalizeError(err) {
   try { return JSON.stringify(err) } catch (_) { return '<unknown error>' }
 }
 
+// ── Tier 2 resolution guard ───────────────────────────────────────────────────
+// All worker agents must be resolved via the CLI before dispatch.
+// No direct require('lib/agent-registry') — resolution goes through the CLI facade.
+const RESOLVE_SCHEMA = {
+  type: 'object',
+  properties: {
+    nativeName:  { type: 'string' },
+    status:      { type: 'string' },
+    agentId:     { type: 'string' },
+    exitNonZero: { type: 'boolean' },
+    error:       { type: 'string' },
+  },
+}
+
+async function resolveAgentTier2(agentId, label, phaseName) {
+  const result = await agent(
+    `Run this command via Bash:\n\nai-toolkit agents resolve --project . --id ${agentId} --require-verified\n\nIf the command exits 0: parse the JSON from stdout and return it with exitNonZero: false.\nIf the command exits non-zero: return {"exitNonZero": true, "error": "<stderr text>", "agentId": "${agentId}"}.`,
+    { label, phase: phaseName, model: 'haiku', schema: RESOLVE_SCHEMA }
+  )
+  if (!result || result.exitNonZero || !result.nativeName) {
+    throw new Error(`HARD STOP — Tier 2 resolution failed for ${agentId}: ${result && result.error ? result.error : 'no nativeName returned'}`)
+  }
+  return result.nativeName
+}
+
 // ── Parse args ────────────────────────────────────────────────────────────────
 
 // args: "<path-to-feature.md>"
@@ -72,12 +97,41 @@ const featureDir  = deriveFeatureDir(featurePath)
 const prefixMatch = featureDir.match(/([A-Z]+-\d+)/)
 const prefix      = prefixMatch ? prefixMatch[1] : 'FTR-000'
 
+// ── Tier 3 — self-ledger helper ───────────────────────────────────────────────
+const SELF_LEDGER_SCHEMA = {
+  type: 'object',
+  properties: {
+    exitCode: { type: 'number' },
+    stdout:   { type: 'string' },
+    stderr:   { type: 'string' },
+  },
+  required: ['exitCode'],
+}
+
+async function selfLedgerOp(cmd, label, phaseName) {
+  const result = await agent(
+    `Run this shell command via Bash and return the exit code as structured output.\n\nCommand: ${cmd}\n\nCapture: exitCode (integer), stdout (string), stderr (string). Return all three.`,
+    { label, phase: phaseName, model: 'haiku', schema: SELF_LEDGER_SCHEMA }
+  )
+  const status = (result && typeof result.exitCode === 'number') ? result.exitCode : 1
+  if (status !== 0) {
+    throw new Error(`HARD STOP — self-ledger operation failed. Exit code: ${status}. Command: ${cmd}`)
+  }
+}
+
+// ── Tier 3 self-registration (open BEFORE any main logic, fail-closed) ────────
+await selfLedgerOp(
+  `ai-toolkit ledger open --prefix ${prefix} --agent pm-phase2:self --phase phase2 --dir "${featureDir}" --attempt 1`,
+  'ledger-open-pm-phase2-self', 'Work Breakdown'
+)
+
 // ── generate-work-breakdown ───────────────────────────────────────────────────
 phase('Work Breakdown')
 
 const tokenLedger = []
 
 log(`Running generate-work-breakdown for ${featurePath}`)
+const wbNativeName = await resolveAgentTier2('gaia.agent.planner.work-breakdown', 'resolve-generate-work-breakdown', 'Work Breakdown')
 const wbKey = 'generate-work-breakdown:phase2'
 await agent(
   `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger open --dir ${featureDir} --prefix ${prefix} --agent ${wbKey} --phase phase2 --model haiku --attempt 1\n\nReturn no output.`,
@@ -85,7 +139,7 @@ await agent(
 )
 const beforeWB = budget.spent()
 await agent(featurePath, {
-  agentType: 'generate-work-breakdown',
+  agentType: wbNativeName,
   label:     'generate-work-breakdown',
   phase:     'Work Breakdown',
 })
@@ -165,6 +219,7 @@ const semanticKey = 'validate-work-breakdown-semantic:phase2'
 if (!wbValidatorPassed) {
   log('validate-work-breakdown-semantic: skipped (wb-validate did not pass)')
 } else {
+  const semanticNativeName = await resolveAgentTier2('gaia.agent.planner.validate-work-breakdown', 'resolve-validate-work-breakdown-semantic', 'Work Breakdown')
   await agent(
     `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger open --dir ${featureDir} --prefix ${prefix} --agent ${semanticKey} --phase phase2 --model sonnet --attempt 1\n\nReturn no output.`,
     { label: 'ledger-open-semantic-validator', phase: 'Work Breakdown', model: 'haiku' }
@@ -176,7 +231,7 @@ if (!wbValidatorPassed) {
       {
         label:     'validate-work-breakdown-semantic',
         phase:     'Work Breakdown',
-        agentType: 'validate-work-breakdown-semantic',
+        agentType: semanticNativeName,
         schema:    WB_SEMANTIC_SCHEMA,
       }
     )
@@ -495,6 +550,12 @@ ${phase2Events}`,
   { label: 'append-process-log', phase: 'Effort Estimate' }
 )
 
+// ── Tier 3 self-registration — close on successful completion ─────────────────
+await selfLedgerOp(
+  `ai-toolkit ledger close --prefix ${prefix} --agent pm-phase2:self --dir "${featureDir}" --attempt 1`,
+  'ledger-close-pm-phase2-self', 'Effort Estimate'
+)
+
 return {
   prefix:                metrics.prefix || prefix,
   feature_path:          featurePath,

package/src/claude/workflows/pm-phase3.js

@@ -11,6 +11,40 @@ export const meta = {
   ],
 }
 
+// ── Tier 2 resolution guard ───────────────────────────────────────────────────
+// All worker agents must be resolved via the CLI before dispatch.
+// No direct require('lib/agent-registry') — resolution goes through the CLI facade.
+const RESOLVE_SCHEMA = {
+  type: 'object',
+  properties: {
+    nativeName:  { type: 'string' },
+    status:      { type: 'string' },
+    agentId:     { type: 'string' },
+    exitNonZero: { type: 'boolean' },
+    error:       { type: 'string' },
+  },
+}
+
+async function resolveAgentTier2(agentId, label, phaseName) {
+  const result = await agent(
+    `Run this command via Bash:\n\nai-toolkit agents resolve --project . --id ${agentId} --require-verified\n\nIf the command exits 0: parse the JSON from stdout and return it with exitNonZero: false.\nIf the command exits non-zero: return {"exitNonZero": true, "error": "<stderr text>", "agentId": "${agentId}"}.`,
+    { label, phase: phaseName, model: 'haiku', schema: RESOLVE_SCHEMA }
+  )
+  if (!result || result.exitNonZero || !result.nativeName) {
+    throw new Error(`HARD STOP — Tier 2 resolution failed for ${agentId}: ${result && result.error ? result.error : 'no nativeName returned'}`)
+  }
+  return result.nativeName
+}
+
+// Map from Work-Breakdown agent_type values to canonical agent IDs.
+// Used by the Tier 2 guard to resolve before each dispatch.
+const IMPL_AGENT_IDS = {
+  'developer-backend':  'gaia.agent.developer.backend',
+  'developer-frontend': 'gaia.agent.developer.frontend',
+  'developer-testing':  'gaia.agent.developer.testing',
+  'review-solution':    'gaia.agent.review.solution',
+}
+
 // ── Ledger facade helpers ─────────────────────────────────────────────────────
 // Route all ledger I/O through the ai-toolkit CLI facade.
 // Open calls fire-and-forget (matching pm-phase1/pm-phase2 pattern).
@@ -64,6 +98,12 @@ const prefixMatch = featureDir.match(/([A-Z]+-\d+)/)
 const prefix      = prefixMatch ? prefixMatch[1] : 'FTR-000'
 const csvPath     = `${featureDir}/${prefix}-Work-Breakdown.csv`
 
+// ── Tier 3 self-registration (open BEFORE any main logic, fail-closed) ────────
+await ledgerTerminal(
+  `ai-toolkit ledger open --prefix ${prefix} --agent pm-phase3:self --phase phase3 --dir "${featureDir}" --attempt 1`,
+  'ledger-open-pm-phase3-self', 'Parse'
+)
+
 log(`Reading CSV: ${csvPath}`)
 
 const csvKey = 'read-wb-csv:phase3'
@@ -160,6 +200,13 @@ const buildWaves = (phases) => {
 const waves = buildWaves(wb.phases)
 log(`Execution plan: ${waves.length} wave(s) — ${waves.map((w, i) => `wave${i+1}:[${w.map(p => p.phase_id).join(',')}]`).join(' ')}`)
 
+// Pre-resolve all implementation agent types (Tier 2 guard, fail-closed before any phase runs)
+const resolvedNativeNames = {}
+for (const [legacyName, canonicalId] of Object.entries(IMPL_AGENT_IDS)) {
+  resolvedNativeNames[legacyName] = await resolveAgentTier2(canonicalId, `resolve-${legacyName}`, 'Parse')
+}
+log(`Tier 2 resolution complete: ${Object.keys(resolvedNativeNames).join(', ')}`)
+
 let phasesDone   = 0
 const usPassed   = []
 const usEscalated = []
@@ -203,16 +250,18 @@ const executePhase = async (implPhase) => {
       let implFailed = false
       let implErrMsg = ''
       try {
-        await parallel(implPhase.impl_groups.map(group => () =>
-          agent(
+        await parallel(implPhase.impl_groups.map(group => () => {
+          const nativeName = resolvedNativeNames[group.agent_type]
+          if (!nativeName) throw new Error(`HARD STOP — Tier 2: no resolved nativeName for agent_type: ${group.agent_type}`)
+          return agent(
             `${featurePath} ${group.task_ids.join(',')}${reworkSuffix}`,
             {
-              agentType: group.agent_type,
+              agentType: nativeName,
               label:     `${group.agent_type}:${implPhase.phase_id}${reworkCycle > 0 ? ':rework' + reworkCycle : ''}`,
               phase:     'Implementation',
             }
           )
-        ))
+        }))
       } catch (err) {
         implFailed = true
         implErrMsg = err && err.message ? err.message.slice(0, 120) : 'impl dispatch failed'
@@ -244,16 +293,18 @@ const executePhase = async (implPhase) => {
       let testFailed = false
       let testErrMsg = ''
       try {
-        await parallel(implPhase.test_groups.map(group => () =>
-          agent(
+        await parallel(implPhase.test_groups.map(group => () => {
+          const nativeName = resolvedNativeNames[group.agent_type]
+          if (!nativeName) throw new Error(`HARD STOP — Tier 2: no resolved nativeName for agent_type: ${group.agent_type}`)
+          return agent(
             `${featurePath} ${group.task_ids.join(',')}${reworkSuffix}`,
             {
-              agentType: group.agent_type,
+              agentType: nativeName,
               label:     `${group.agent_type}:${implPhase.phase_id}${reworkCycle > 0 ? ':rework' + reworkCycle : ''}`,
               phase:     'Implementation',
             }
           )
-        ))
+        }))
       } catch (err) {
         testFailed = true
         testErrMsg = err && err.message ? err.message.slice(0, 120) : 'test dispatch failed'
@@ -284,7 +335,7 @@ const executePhase = async (implPhase) => {
     const review = await agent(
       `${featurePath} --scope ${implPhase.phase_id}`,
       {
-        agentType: 'review-solution',
+        agentType: resolvedNativeNames['review-solution'],
         label:     `review-solution:${implPhase.phase_id}`,
         phase:     'Implementation',
         schema:    REVIEW_SCHEMA,
@@ -759,6 +810,12 @@ If there is nothing to commit (all files already committed), that is fine — re
   { label: 'commit-actuals', phase: 'Actuals' }
 )
 
+// ── Tier 3 self-registration — close on successful completion ─────────────────
+await ledgerTerminal(
+  `ai-toolkit ledger close --prefix ${prefix} --agent pm-phase3:self --dir "${featureDir}" --attempt 1`,
+  'ledger-close-pm-phase3-self', 'Actuals'
+)
+
 return {
   pr_url:       prResult.pr_url,
   token_ledger: tokenLedger,