@dtlabs/ai-toolkit 0.11.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:
 
 ```
-subagent_type: pm-phase3
+⛔ 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: {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
@@ -204,8 +382,10 @@ From the `<usage>` block of the pm-phase3 result, read:
 
 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} |
 
 ---
 
@@ -213,14 +393,14 @@ 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}
-| project-manager/pm-phase3 (orchestrator) | — | sonnet | 80,000 | {subagent_tokens} | ±{delta} | $0.4320 | ${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}
+| pm-phase3 (orchestrator) | — | sonnet | 80,000 | {subagent_tokens} | ±{delta} | $0.4320 | ${actual_cost} | {duration} |
 
 ## Estimation accuracy by agent type
 
 | Model | Count | Avg est. tokens | Avg actual tokens | Avg delta | Trend |
 |-------|-------|----------------|------------------|-----------|-------|
-{one row per model tier (haiku, sonnet) — exclude N/A rows from averages}
+{one row per model tier (haiku, sonnet) — exclude rows where actual tokens is null, 0, or not_available from averages}
 
 ## Grand Total
 

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,36 +9,51 @@ export const meta = {
   ],
 }
 
-// ── Ledger helper functions ───────────────────────────────────────────────────
+// ── 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 appendLedgerEntry(featureDir, prefix, entry) {
-  const ledgerPath = `${featureDir}/${prefix}-token-ledger.json`
-  // started_at is generated via Bash inside the agent to get a real UTC timestamp with time
-  const entryWithoutTs = JSON.stringify({ ...entry, started_at: '__TS__', completed_at: null })
-  await agent(
-    `Append a JSON object to the ledger array at: ${ledgerPath}\n\n` +
-    `1. Run: date -u +"%Y-%m-%dT%H:%M:%SZ" and capture the output as NOW.\n` +
-    `2. Read the file. If it does not exist or cannot be parsed as a JSON array, start with [].\n` +
-    `3. Push this object onto the array, replacing "__TS__" in started_at with NOW: ${entryWithoutTs}\n` +
-    `4. Write the full array back (JSON, 2-space indent). Return no output.`,
-    { label: 'append-ledger', phase: 'Requirements', model: 'haiku' }
+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
 }
 
-async function updateLedgerEntry(featureDir, prefix, agentKey, updates) {
-  const ledgerPath = `${featureDir}/${prefix}-token-ledger.json`
-  // completed_at is generated via Bash inside the agent to get a real UTC timestamp with time
-  const updatesWithoutTs = JSON.stringify({ ...updates, completed_at: '__TS__' })
-  await agent(
-    `Update an entry in the ledger array at: ${ledgerPath}\n\n` +
-    `1. Run: date -u +"%Y-%m-%dT%H:%M:%SZ" and capture the output as NOW.\n` +
-    `2. Read the file. If it does not exist or cannot be parsed as a JSON array, do nothing.\n` +
-    `3. Search from the end for the last entry where agent === "${agentKey}".\n` +
-    `4. If found, merge these fields into that entry, replacing "__TS__" in completed_at with NOW: ${updatesWithoutTs}\n` +
-    `5. Write the full array back (JSON, 2-space indent). Return no output.\n` +
-    `6. If not found, do nothing.`,
-    { label: 'update-ledger', phase: 'Requirements', model: 'haiku' }
+// ── 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 ────────────────────────────────────────────────────────────────
@@ -46,6 +61,17 @@ async function updateLedgerEntry(featureDir, prefix, agentKey, updates) {
 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')
 
@@ -104,7 +130,7 @@ log(`needs_requirements=${discoveryResult.needs_requirements} needs_tech_spec=${
 
 // ── Ensure ledger file exists (US-02-T02) ─────────────────────────────────────
 // If define-feature was not used, the ledger file will not exist yet.
-// Touch it with an empty array so appendLedgerEntry can always assume a valid base.
+// Touch it with an empty array so the ledger facade can always assume a valid base.
 const ledgerFilePath = `${feature_dir}/${prefix}-token-ledger.json`
 await agent(
   `Check whether the file ${ledgerFilePath} exists.\n\n1. Try to read the file using the Read tool.\n2. If the file does NOT exist: write it now using the Write tool with contents: []\n3. If the file already exists and is a valid JSON array: do nothing.\n4. If the file exists but is not valid JSON: overwrite it with: []\n5. Return no output.`,
@@ -119,24 +145,19 @@ 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 appendLedgerEntry(feature_dir, prefix, {
-    agent: reqKey,
-    phase: 'phase1',
-    model: 'haiku',
-    status: 'running',
-    phase_delta_tokens: 0,
-    started_at: '__TS__',
-    completed_at: null,
-  })
+  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 updateLedgerEntry(feature_dir, prefix, reqKey, {
-    status: 'done',
-    completed_at: '__TS__',
-    phase_delta_tokens: reqTokens,
-  })
+  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.`,
+    { label: 'ledger-close-requirements', phase: 'Requirements', model: 'haiku' }
+  )
   tokenLedger.push({ agent: 'generate-requirements', model: 'haiku', phase_delta_tokens: reqTokens })
   log(`generate-requirements done — phase delta: ${reqTokens} tokens`)
 } else {
@@ -147,24 +168,19 @@ 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 appendLedgerEntry(feature_dir, prefix, {
-    agent: specKey,
-    phase: 'phase1',
-    model: 'haiku',
-    status: 'running',
-    phase_delta_tokens: 0,
-    started_at: '__TS__',
-    completed_at: null,
-  })
+  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 updateLedgerEntry(feature_dir, prefix, specKey, {
-    status: 'done',
-    completed_at: '__TS__',
-    phase_delta_tokens: specTokens,
-  })
+  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.`,
+    { label: 'ledger-close-tech-spec', phase: 'Tech-Spec', model: 'haiku' }
+  )
   tokenLedger.push({ agent: 'generate-tech-spec', model: 'haiku', phase_delta_tokens: specTokens })
   log(`generate-tech-spec done — phase delta: ${specTokens} tokens`)
 } else {
@@ -174,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
@@ -181,23 +202,17 @@ const MAX_CYCLES = 3
 for (let cycle = 1; cycle <= MAX_CYCLES; cycle++) {
   log(`validate-feature-docs cycle ${cycle}`)
   const valKey = `validate-feature-docs:phase1:cycle${cycle}`
-  await appendLedgerEntry(feature_dir, prefix, {
-    agent: valKey,
-    phase: 'phase1',
-    model: 'haiku',
-    status: 'running',
-    phase_delta_tokens: 0,
-    started_at: '__TS__',
-    completed_at: null,
-  })
+  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 ${valKey} --phase phase1 --model haiku --attempt 1\n\nReturn no output.`,
+    { 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 updateLedgerEntry(feature_dir, prefix, valKey, {
-    status: 'done',
-    completed_at: '__TS__',
-    phase_delta_tokens: valTokens,
-  })
+  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.`,
+    { label: `ledger-close-validate-cycle-${cycle}`, phase: 'Validation', model: 'haiku' }
+  )
   tokenLedger.push({ agent: `validate-feature-docs (cycle ${cycle})`, model: 'haiku', phase_delta_tokens: valTokens })
 
   // valResult is the agent's text output — check for gap indicators
@@ -217,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'
@@ -339,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