@cleocode/core 2026.4.5 → 2026.4.6

package/src/lifecycle/stage-guidance.ts

@@ -0,0 +1,282 @@
+/**
+ * Stage-Aware LLM Prompt Guidance (Phase 2, refactored Phase 4).
+ *
+ * **Architecture (SSoT)**: The protocol text for each RCASD-IVTR+C stage is
+ * authoritatively encoded in the `@cleocode/skills` package at
+ * `packages/skills/skills/ct-*` — specifically:
+ *
+ *   - Tier 0 (always loaded): `ct-cleo`, `ct-orchestrator`, `ct-task-executor`
+ *   - Stage-specific (per RCASD-IVTR+C stage): see `STAGE_SKILL_MAP` below
+ *
+ * This module is a **thin loader** — it does NOT embed protocol text. It
+ * resolves stage → skill names via `STAGE_SKILL_MAP`, then calls the
+ * existing `prepareSpawnMulti()` helper (from `../skills/dispatch.ts`) to
+ * compose the full prompt from real `SKILL.md` files.
+ *
+ * If the skill files are unavailable at runtime (e.g. fresh install, skills
+ * package missing), we fall back to a minimal structured description built
+ * from `STAGE_DEFINITIONS` alone — never hand-authored prose.
+ *
+ * @task Phase 2 — Pi harness registration + stage guidance injection
+ * @task Phase 4 — SSoT alignment: pull from skill files, not inline text
+ */
+
+import { findSkill } from '../skills/discovery.js';
+import { prepareSpawnMulti } from '../skills/dispatch.js';
+import { STAGE_DEFINITIONS, type Stage } from './stages.js';
+
+// ============================================================================
+// SSoT: Stage → Skill mapping
+// ============================================================================
+
+/**
+ * Canonical mapping from RCASD-IVTR+C pipeline stages to the primary skill
+ * that encodes the protocol for that stage.
+ *
+ * Each pipeline stage maps to exactly one **dedicated** skill that owns
+ * the protocol contract for that stage. The keys here are the canonical
+ * `Stage` union from `./stages.ts`; the values are skill names that MUST
+ * exist under `packages/skills/skills/` and be registered in the global
+ * manifest at `packages/skills/skills/manifest.json`.
+ *
+ * **Relationship to manifest.json:** This table is the runtime authority
+ * for stage→skill resolution by `buildStageGuidance()`. The manifest's
+ * `dispatch_matrix.by_protocol` table is the broader catalog (it also
+ * covers cross-cutting protocols like contribution, artifact-publish, and
+ * provenance which are NOT pipeline stages and therefore are not in this
+ * map). When the two tables overlap, they MUST agree on the skill name.
+ *
+ * **Cross-cutting protocols** (`contribution`, `artifact-publish`,
+ * `provenance`) compose with pipeline stages but are not themselves
+ * stages — see `lifecycle/default-chain.ts#DEFAULT_PROTOCOL_STAGE_MAP`
+ * for the cross-cutting → host-stage mapping.
+ *
+ * @task T260 — replace overloaded ct-validator/ct-dev-workflow assignments
+ *              with dedicated skills (ct-adr-recorder, ct-consensus-voter,
+ *              ct-ivt-looper, ct-release-orchestrator). Validation stays on
+ *              ct-validator now that consensus duties are split out.
+ */
+export const STAGE_SKILL_MAP: Record<Stage, string> = {
+  research: 'ct-research-agent',
+  consensus: 'ct-consensus-voter',
+  architecture_decision: 'ct-adr-recorder',
+  specification: 'ct-spec-writer',
+  decomposition: 'ct-epic-architect',
+  implementation: 'ct-task-executor',
+  validation: 'ct-validator',
+  testing: 'ct-ivt-looper',
+  release: 'ct-release-orchestrator',
+};
+
+/**
+ * Tier 0 skills — always loaded alongside the stage-specific skill.
+ *
+ * - `ct-cleo`: CLEO task management protocol (session, task, memory CLI)
+ * - `ct-orchestrator`: pipeline-aware orchestration constraints (ORC-001..009)
+ *
+ * `ct-task-executor` is NOT unconditionally included because most stages
+ * already resolve to a more-specific executor skill; it's only added when
+ * no stage-specific skill exists.
+ */
+export const TIER_0_SKILLS: readonly string[] = ['ct-cleo', 'ct-orchestrator'];
+
+// ============================================================================
+// Public types
+// ============================================================================
+
+/**
+ * Structured guidance for a single pipeline stage.
+ *
+ * Pi extensions consume the `.prompt` field directly (render via
+ * `{ systemPrompt }` in `before_agent_start`). The structured fields are
+ * exposed for TUI widgets, badges, and logging.
+ */
+export interface StageGuidance {
+  /** The canonical stage identifier. */
+  stage: Stage;
+  /** Human-readable stage name (e.g. "Research"). */
+  name: string;
+  /** Numeric stage order (1-9). */
+  order: number;
+  /** Primary skill loaded for this stage (SSoT from STAGE_SKILL_MAP). */
+  primarySkill: string;
+  /** All skills loaded (Tier 0 + stage primary). */
+  loadedSkills: readonly string[];
+  /** Gates that must pass before the stage can be completed. */
+  requiredGates: readonly string[];
+  /** Artifacts the agent is expected to produce before advancing. */
+  expectedArtifacts: readonly string[];
+  /** Composed prompt text, ready for LLM system prompt injection. */
+  prompt: string;
+  /** Source of the prompt: 'skills' (real SKILL.md files) or 'fallback'. */
+  source: 'skills' | 'fallback';
+}
+
+// ============================================================================
+// Fallback prompt builder — used only when skills are unavailable
+// ============================================================================
+
+/**
+ * Build a minimal stage prompt from canonical metadata when the skill files
+ * cannot be resolved. Uses only `STAGE_DEFINITIONS` — no hand-authored prose.
+ *
+ * This intentionally produces a compact prompt that tells the agent what
+ * stage it's in and where to find the authoritative protocol. It is NOT a
+ * substitute for the real skill content.
+ */
+function buildFallbackPrompt(stage: Stage, primarySkill: string): string {
+  const def = STAGE_DEFINITIONS[stage];
+  const lines: string[] = [];
+  lines.push(`## CLEO Pipeline Stage: ${def.name} (stage ${def.order}/9)`);
+  lines.push('');
+  lines.push(`**Description**: ${def.description}`);
+  lines.push(`**Category**: ${def.category}`);
+  lines.push(`**Skippable**: ${def.skippable ? 'yes' : 'no'}`);
+  lines.push('');
+  lines.push('### Required Gates');
+  for (const gate of def.requiredGates) {
+    lines.push(`- \`${gate}\``);
+  }
+  lines.push('');
+  lines.push('### Expected Artifacts');
+  for (const artifact of def.expectedArtifacts) {
+    lines.push(`- \`${artifact}\``);
+  }
+  lines.push('');
+  lines.push('### Primary Skill');
+  lines.push(
+    `- **${primarySkill}** — protocol unavailable at runtime. Install \`@cleocode/skills\` or run \`cleo admin scaffold-hub\` to provision.`,
+  );
+  lines.push('');
+  lines.push('### Tier 0 Skills (always loaded)');
+  for (const s of TIER_0_SKILLS) {
+    lines.push(`- ${s}`);
+  }
+  lines.push('');
+  lines.push(
+    '> Fallback guidance — the full `SKILL.md` files could not be resolved. ' +
+      'Check skill installation with `cleo skills list`.',
+  );
+  return lines.join('\n');
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Build structured stage guidance for a given pipeline stage.
+ *
+ * Resolves the primary skill for the stage from `STAGE_SKILL_MAP`, composes
+ * a prompt from the real `SKILL.md` files via `prepareSpawnMulti()`, and
+ * returns a `StageGuidance` object suitable for Pi extension injection or
+ * direct CLI rendering.
+ *
+ * If the skills cannot be resolved, returns a fallback prompt built from
+ * `STAGE_DEFINITIONS` metadata only — no hand-authored protocol text.
+ *
+ * @param stage - The canonical pipeline stage identifier
+ * @param cwd - Optional project root override for skill resolution
+ * @returns Structured guidance with `.prompt` ready for LLM injection
+ *
+ * @example
+ * ```typescript
+ * const guidance = buildStageGuidance('implementation');
+ * // guidance.primarySkill === 'ct-task-executor'
+ * // guidance.loadedSkills === ['ct-task-executor', 'ct-cleo', 'ct-orchestrator']
+ * // guidance.prompt starts with "## Skills Loaded (3 total)"
+ * ```
+ */
+export function buildStageGuidance(stage: Stage, cwd?: string): StageGuidance {
+  const def = STAGE_DEFINITIONS[stage];
+  const primarySkill = STAGE_SKILL_MAP[stage];
+
+  // Primary first, then Tier 0 (de-dup if the primary is itself tier 0)
+  const skillNames = [primarySkill, ...TIER_0_SKILLS.filter((s) => s !== primarySkill)];
+
+  // Verify every skill can actually be found before calling prepareSpawnMulti
+  const allFound = skillNames.every((name) => findSkill(name, cwd) !== null);
+
+  if (!allFound) {
+    return {
+      stage,
+      name: def.name,
+      order: def.order,
+      primarySkill,
+      loadedSkills: skillNames,
+      requiredGates: def.requiredGates,
+      expectedArtifacts: def.expectedArtifacts,
+      prompt: buildFallbackPrompt(stage, primarySkill),
+      source: 'fallback',
+    };
+  }
+
+  try {
+    const composition = prepareSpawnMulti(skillNames, {}, cwd);
+    return {
+      stage,
+      name: def.name,
+      order: def.order,
+      primarySkill,
+      loadedSkills: skillNames,
+      requiredGates: def.requiredGates,
+      expectedArtifacts: def.expectedArtifacts,
+      prompt: composition.prompt,
+      source: 'skills',
+    };
+  } catch {
+    return {
+      stage,
+      name: def.name,
+      order: def.order,
+      primarySkill,
+      loadedSkills: skillNames,
+      requiredGates: def.requiredGates,
+      expectedArtifacts: def.expectedArtifacts,
+      prompt: buildFallbackPrompt(stage, primarySkill),
+      source: 'fallback',
+    };
+  }
+}
+
+/**
+ * Format stage guidance as a Markdown-wrapped system prompt.
+ *
+ * Since `buildStageGuidance()` now returns the already-composed prompt in
+ * `.prompt`, this helper simply passes it through with a header banner
+ * identifying which skills are loaded and which stage is active.
+ *
+ * @param guidance - The structured guidance from `buildStageGuidance()`
+ * @returns Markdown text suitable for LLM system prompt injection
+ *
+ * @example
+ * ```typescript
+ * const g = buildStageGuidance('research');
+ * const text = formatStageGuidance(g);
+ * return { systemPrompt: text };  // Pi before_agent_start hook return
+ * ```
+ */
+export function formatStageGuidance(guidance: StageGuidance): string {
+  const banner = [
+    `## CLEO Stage-Aware Injection`,
+    `**Stage**: ${guidance.name} (${guidance.order}/9) — primary skill: \`${guidance.primarySkill}\``,
+    `**Loaded skills**: ${guidance.loadedSkills.join(', ')}`,
+    `**Source**: ${guidance.source}`,
+    `**Required gates**: ${guidance.requiredGates.map((g) => `\`${g}\``).join(', ')}`,
+    '',
+    '---',
+    '',
+  ].join('\n');
+  return banner + guidance.prompt;
+}
+
+/**
+ * Convenience wrapper: build AND format in a single call.
+ *
+ * @param stage - The canonical pipeline stage identifier
+ * @param cwd - Optional project root override for skill resolution
+ * @returns Markdown text ready for LLM system prompt injection
+ */
+export function renderStageGuidance(stage: Stage, cwd?: string): string {
+  return formatStageGuidance(buildStageGuidance(stage, cwd));
+}

package/src/metrics/__tests__/provider-detection.test.js

@@ -11,27 +11,39 @@ function makeDetection(overrides) {
             pathGlobal: '',
             pathProject: '',
             instructFile: 'CLAUDE.md',
-            configKey: 'mcpServers',
-            configFormat: 'json',
-            configPathGlobal: '',
-            configPathProject: '.claude.json',
             pathSkills: '',
             pathProjectSkills: '',
             detection: { methods: ['binary'], binary: 'claude' },
-            supportedTransports: ['stdio'],
-            supportsHeaders: false,
             priority: 'high',
             status: 'active',
             agentSkillsCompatible: true,
             capabilities: {
+                mcp: {
+                    configKey: 'mcpServers',
+                    configFormat: 'json',
+                    configPathGlobal: '',
+                    configPathProject: '.claude.json',
+                    supportedTransports: ['stdio'],
+                    supportsHeaders: false,
+                },
+                harness: null,
                 skills: { agentsGlobalPath: null, agentsProjectPath: null, precedence: 'agents-first' },
-                hooks: { supported: [], hookConfigPath: null, hookFormat: null },
+                hooks: {
+                    supported: [],
+                    hookConfigPath: null,
+                    hookConfigPathProject: null,
+                    hookFormat: null,
+                    nativeEventCatalog: 'canonical',
+                    canInjectSystemPrompt: false,
+                    canBlockTools: false,
+                },
                 spawn: {
                     supportsSubagents: true,
                     supportsProgrammaticSpawn: true,
                     supportsInterAgentComms: false,
                     supportsParallelSpawn: true,
                     spawnMechanism: 'cli',
+                    spawnCommand: null,
                 },
             },
         },

package/src/metrics/__tests__/provider-detection.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider-detection.test.js","sourceRoot":"","sources":["provider-detection.test.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"provider-detection.test.js","sourceRoot":"","sources":["provider-detection.test.ts"],"names":[],"mappings":"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"}

package/src/orchestration/__tests__/protocol-validators.test.js

@@ -8,7 +8,7 @@
 import { ExitCode } from '@cleocode/contracts';
 import { describe, expect, it } from 'vitest';
 import { CleoError } from '../../errors.js';
-import { PROTOCOL_EXIT_CODES, PROTOCOL_TYPES, validateArtifactPublishProtocol, validateConsensusProtocol, validateContributionProtocol, validateDecompositionProtocol, validateImplementationProtocol, validateProtocol, validateProvenanceProtocol, validateReleaseProtocol, validateResearchProtocol, validateSpecificationProtocol, } from '../protocol-validators.js';
+import { PROTOCOL_EXIT_CODES, PROTOCOL_TYPES, validateArchitectureDecisionProtocol, validateArtifactPublishProtocol, validateConsensusProtocol, validateContributionProtocol, validateDecompositionProtocol, validateImplementationProtocol, validateProtocol, validateProvenanceProtocol, validateReleaseProtocol, validateResearchProtocol, validateSpecificationProtocol, validateTestingProtocol, validateValidationProtocol, } from '../protocol-validators.js';
 // ============================================================
 // Helper: create valid manifest entry for a protocol
 // ============================================================
@@ -314,13 +314,222 @@ describe('Provenance Protocol', () => {
     });
 });
 // ============================================================
+// 10. ARCHITECTURE DECISION RECORD PROTOCOL (exit code 84)
+// ============================================================
+describe('Architecture Decision Record Protocol', () => {
+    const adrEntry = (overrides = {}) => ({
+        ...validEntry('decision'),
+        consensus_manifest_id: 'manifest_consensus_2026_04_07',
+        ...overrides,
+    });
+    it('passes a complete ADR entry', () => {
+        const result = validateArchitectureDecisionProtocol(adrEntry(), {
+            status: 'proposed',
+            adrContent: '## Context\n## Options Evaluated\n## Decision\n## Rationale\n## Consequences\n',
+            persistedInDb: true,
+        });
+        expect(result.valid).toBe(true);
+        expect(result.protocol).toBe('architecture-decision');
+    });
+    it('fails without a consensus manifest link (ADR-001)', () => {
+        const result = validateArchitectureDecisionProtocol(adrEntry({ consensus_manifest_id: undefined }));
+        expect(result.valid).toBe(false);
+        expect(result.violations).toContainEqual(expect.objectContaining({ requirement: 'ADR-001' }));
+    });
+    it('fails when accepted without HITL review (ADR-003)', () => {
+        const result = validateArchitectureDecisionProtocol(adrEntry(), {
+            status: 'accepted',
+            hitlReviewed: false,
+            adrContent: '## Context\n## Options\n## Decision\n## Rationale\n## Consequences\n',
+            persistedInDb: true,
+        });
+        expect(result.valid).toBe(false);
+        expect(result.violations).toContainEqual(expect.objectContaining({ requirement: 'ADR-003' }));
+    });
+    it('fails when required sections are missing (ADR-004)', () => {
+        const result = validateArchitectureDecisionProtocol(adrEntry(), {
+            status: 'proposed',
+            adrContent: '## Context only',
+            persistedInDb: true,
+        });
+        expect(result.valid).toBe(false);
+        expect(result.violations).toContainEqual(expect.objectContaining({ requirement: 'ADR-004' }));
+    });
+    it('fails superseded ADR without downstream flag (ADR-005)', () => {
+        const result = validateArchitectureDecisionProtocol(adrEntry(), {
+            status: 'superseded',
+            downstreamFlagged: false,
+            adrContent: '## Context\n## Options\n## Decision\n## Rationale\n## Consequences\n',
+            persistedInDb: true,
+        });
+        expect(result.valid).toBe(false);
+        expect(result.violations).toContainEqual(expect.objectContaining({ requirement: 'ADR-005' }));
+    });
+    it('fails when not persisted in SQLite (ADR-006)', () => {
+        const result = validateArchitectureDecisionProtocol(adrEntry(), {
+            status: 'proposed',
+            persistedInDb: false,
+            adrContent: '## Context\n## Options\n## Decision\n## Rationale\n## Consequences\n',
+        });
+        expect(result.valid).toBe(false);
+        expect(result.violations).toContainEqual(expect.objectContaining({ requirement: 'ADR-006' }));
+    });
+    it('fails with wrong agent_type (ADR-007)', () => {
+        const result = validateArchitectureDecisionProtocol(adrEntry({ agent_type: 'specification' }));
+        expect(result.valid).toBe(false);
+        expect(result.violations).toContainEqual(expect.objectContaining({ requirement: 'ADR-007' }));
+    });
+});
+// ============================================================
+// 11. VALIDATION PROTOCOL (exit code 80)
+// ============================================================
+describe('Validation Protocol', () => {
+    it('passes a complete validation entry', () => {
+        const result = validateValidationProtocol(validEntry('validation'), {
+            specMatchConfirmed: true,
+            testSuitePassed: true,
+            protocolComplianceChecked: true,
+        });
+        expect(result.valid).toBe(true);
+        expect(result.protocol).toBe('validation');
+    });
+    it('fails when spec-match not confirmed (VALID-001)', () => {
+        const result = validateValidationProtocol(validEntry('validation'), {
+            specMatchConfirmed: false,
+        });
+        expect(result.valid).toBe(false);
+        expect(result.violations).toContainEqual(expect.objectContaining({ requirement: 'VALID-001' }));
+    });
+    it('fails when test suite failed (VALID-002)', () => {
+        const result = validateValidationProtocol(validEntry('validation'), {
+            testSuitePassed: false,
+        });
+        expect(result.valid).toBe(false);
+        expect(result.violations).toContainEqual(expect.objectContaining({ requirement: 'VALID-002' }));
+    });
+    it('fails without key_findings (VALID-005)', () => {
+        const result = validateValidationProtocol(validEntry('validation', { key_findings: [] }));
+        expect(result.valid).toBe(false);
+        expect(result.violations).toContainEqual(expect.objectContaining({ requirement: 'VALID-005' }));
+    });
+    it('fails with wrong agent_type (VALID-006)', () => {
+        const result = validateValidationProtocol(validEntry('implementation'));
+        expect(result.valid).toBe(false);
+        expect(result.violations).toContainEqual(expect.objectContaining({ requirement: 'VALID-006' }));
+    });
+});
+// ============================================================
+// 12. TESTING PROTOCOL (project-agnostic IVT loop)
+// ============================================================
+describe('Testing Protocol', () => {
+    it('passes a complete testing entry with any framework', () => {
+        const result = validateTestingProtocol(validEntry('testing'), {
+            framework: 'vitest',
+            testsRun: 42,
+            testsPassed: 42,
+            testsFailed: 0,
+            ivtLoopConverged: true,
+        });
+        expect(result.valid).toBe(true);
+        expect(result.protocol).toBe('testing');
+    });
+    it('is project-agnostic — accepts any supported framework', () => {
+        const frameworks = [
+            'vitest',
+            'jest',
+            'pytest',
+            'go-test',
+            'cargo-test',
+            'rspec',
+            'bats',
+            'other',
+        ];
+        for (const framework of frameworks) {
+            const result = validateTestingProtocol(validEntry('testing'), {
+                framework,
+                testsRun: 1,
+                testsPassed: 1,
+                testsFailed: 0,
+                ivtLoopConverged: true,
+            });
+            expect(result.valid).toBe(true);
+        }
+    });
+    it('fails without a detected framework (TEST-001)', () => {
+        const result = validateTestingProtocol(validEntry('testing'), {
+            testsRun: 10,
+            testsPassed: 10,
+            testsFailed: 0,
+            ivtLoopConverged: true,
+        });
+        expect(result.valid).toBe(false);
+        expect(result.violations).toContainEqual(expect.objectContaining({ requirement: 'TEST-001' }));
+    });
+    it('fails when tests failed (TEST-004)', () => {
+        const result = validateTestingProtocol(validEntry('testing'), {
+            framework: 'vitest',
+            testsRun: 10,
+            testsPassed: 8,
+            testsFailed: 2,
+            ivtLoopConverged: false,
+        });
+        expect(result.valid).toBe(false);
+        expect(result.violations).toContainEqual(expect.objectContaining({ requirement: 'TEST-004' }));
+    });
+    it('fails when IVT loop has not converged (TEST-005)', () => {
+        const result = validateTestingProtocol(validEntry('testing'), {
+            framework: 'vitest',
+            ivtLoopConverged: false,
+        });
+        expect(result.valid).toBe(false);
+        expect(result.violations).toContainEqual(expect.objectContaining({ requirement: 'TEST-005' }));
+    });
+    it('warns on coverage below threshold (non-blocking)', () => {
+        const result = validateTestingProtocol(validEntry('testing'), {
+            framework: 'vitest',
+            testsRun: 10,
+            testsPassed: 10,
+            testsFailed: 0,
+            ivtLoopConverged: true,
+            coveragePercent: 70,
+            coverageThreshold: 80,
+        });
+        expect(result.violations).toContainEqual(expect.objectContaining({ requirement: 'TEST-004', severity: 'warning' }));
+    });
+    it('fails with wrong agent_type (TEST-007)', () => {
+        const result = validateTestingProtocol(validEntry('implementation'), {
+            framework: 'vitest',
+            ivtLoopConverged: true,
+        });
+        expect(result.valid).toBe(false);
+        expect(result.violations).toContainEqual(expect.objectContaining({ requirement: 'TEST-007' }));
+    });
+});
+// ============================================================
 // UNIFIED DISPATCHER
 // ============================================================
 describe('validateProtocol (unified dispatcher)', () => {
-    it('dispatches to all 9 protocols', () => {
+    it('dispatches to all 12 protocols', () => {
         for (const protocol of PROTOCOL_TYPES) {
-            const agentType = protocol === 'consensus' ? 'analysis' : protocol;
-            const entry = validEntry(agentType);
+            // Map protocol name to expected agent_type
+            const agentTypeMap = {
+                research: 'research',
+                consensus: 'analysis',
+                'architecture-decision': 'decision',
+                specification: 'specification',
+                decomposition: 'decomposition',
+                implementation: 'implementation',
+                contribution: 'contribution',
+                validation: 'validation',
+                testing: 'testing',
+                release: 'release',
+                'artifact-publish': 'artifact-publish',
+                provenance: 'provenance',
+            };
+            const entry = {
+                ...validEntry(agentTypeMap[protocol]),
+                consensus_manifest_id: 'mf_consensus_test',
+            };
             // All should not throw without strict mode
             const result = validateProtocol(protocol, entry);
             expect(result.protocol).toBe(protocol);
@@ -331,7 +540,7 @@ describe('validateProtocol (unified dispatcher)', () => {
         expect(() => validateProtocol('research', entry, {}, true)).toThrow(CleoError);
     });
     it('uses correct exit codes for each protocol', () => {
-        // Verify exit code mapping covers range 60-67
+        // Pipeline codes 60-67 + dedicated codes for cross-cutting protocols
         const exitCodes = new Set(Object.values(PROTOCOL_EXIT_CODES));
         expect(exitCodes.has(ExitCode.PROTOCOL_MISSING)).toBe(true); // 60
         expect(exitCodes.has(ExitCode.INVALID_RETURN_MESSAGE)).toBe(true); // 61
@@ -341,6 +550,10 @@ describe('validateProtocol (unified dispatcher)', () => {
         expect(exitCodes.has(ExitCode.HANDOFF_REQUIRED)).toBe(true); // 65
         expect(exitCodes.has(ExitCode.RESUME_FAILED)).toBe(true); // 66
         expect(exitCodes.has(ExitCode.CONCURRENT_SESSION)).toBe(true); // 67
+        expect(exitCodes.has(ExitCode.LIFECYCLE_GATE_FAILED)).toBe(true); // 80 (validation)
+        expect(exitCodes.has(ExitCode.PROVENANCE_REQUIRED)).toBe(true); // 84 (ADR)
+        expect(exitCodes.has(ExitCode.ARTIFACT_PUBLISH_FAILED)).toBe(true); // 88
+        expect(exitCodes.has(ExitCode.ATTESTATION_INVALID)).toBe(true); // 94
     });
     it('strict mode throws with correct exit code per protocol', () => {
         const testCases = [
@@ -351,7 +564,11 @@ describe('validateProtocol (unified dispatcher)', () => {
             { protocol: 'implementation', expectedCode: ExitCode.AUTONOMOUS_BOUNDARY },
             { protocol: 'contribution', expectedCode: ExitCode.HANDOFF_REQUIRED },
             { protocol: 'release', expectedCode: ExitCode.RESUME_FAILED },
-            { protocol: 'artifact-publish', expectedCode: ExitCode.CONCURRENT_SESSION },
+            { protocol: 'testing', expectedCode: ExitCode.CONCURRENT_SESSION },
+            { protocol: 'validation', expectedCode: ExitCode.LIFECYCLE_GATE_FAILED },
+            { protocol: 'architecture-decision', expectedCode: ExitCode.PROVENANCE_REQUIRED },
+            { protocol: 'artifact-publish', expectedCode: ExitCode.ARTIFACT_PUBLISH_FAILED },
+            { protocol: 'provenance', expectedCode: ExitCode.ATTESTATION_INVALID },
         ];
         for (const { protocol, expectedCode } of testCases) {
             const entry = validEntry('wrong-type');
@@ -366,14 +583,17 @@ describe('validateProtocol (unified dispatcher)', () => {
             }
         }
     });
-    it('PROTOCOL_TYPES contains all 9 protocols', () => {
-        expect(PROTOCOL_TYPES).toHaveLength(9);
+    it('PROTOCOL_TYPES contains all 12 protocols', () => {
+        expect(PROTOCOL_TYPES).toHaveLength(12);
         expect(PROTOCOL_TYPES).toContain('research');
         expect(PROTOCOL_TYPES).toContain('consensus');
+        expect(PROTOCOL_TYPES).toContain('architecture-decision');
         expect(PROTOCOL_TYPES).toContain('specification');
         expect(PROTOCOL_TYPES).toContain('decomposition');
         expect(PROTOCOL_TYPES).toContain('implementation');
         expect(PROTOCOL_TYPES).toContain('contribution');
+        expect(PROTOCOL_TYPES).toContain('validation');
+        expect(PROTOCOL_TYPES).toContain('testing');
         expect(PROTOCOL_TYPES).toContain('release');
         expect(PROTOCOL_TYPES).toContain('artifact-publish');
         expect(PROTOCOL_TYPES).toContain('provenance');