@cleocode/core 2026.4.9 → 2026.4.12

package/src/validation/__tests__/error-hints.test.ts

@@ -0,0 +1,97 @@
+/**
+ * Regression tests: CleoError fix hints on validation-layer throws.
+ *
+ * Each test invokes a validation function with invalid input and asserts that
+ * the thrown CleoError carries a non-empty `fix` string and, where applicable,
+ * a `details.field` identifying the failing field.
+ *
+ * @task T341
+ * @epic T335
+ */
+
+import { describe, expect, it } from 'vitest';
+import { CleoError } from '../../errors.js';
+import { sanitizeFilePath } from '../engine.js';
+import { loadManifestEntryByTaskId, loadManifestEntryFromFile } from '../protocols/_shared.js';
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+function assertErrorHints(
+  fn: () => unknown,
+  opts: { fixIncludes?: string; detailsField?: string },
+): void {
+  let caught: unknown;
+  try {
+    fn();
+  } catch (err) {
+    caught = err;
+  }
+  expect(caught).toBeInstanceOf(CleoError);
+  const e = caught as CleoError;
+  expect(e.fix).toBeTruthy();
+  if (opts.fixIncludes) {
+    expect(e.fix).toContain(opts.fixIncludes);
+  }
+  if (opts.detailsField) {
+    expect(e.details).toBeDefined();
+    expect(e.details!.field).toBe(opts.detailsField);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// sanitizeFilePath — engine.ts
+// ---------------------------------------------------------------------------
+
+describe('error-hints: sanitizeFilePath', () => {
+  it('empty path — fix mentions file path, field=path', () => {
+    assertErrorHints(() => sanitizeFilePath(''), {
+      detailsField: 'path',
+    });
+  });
+
+  it('path with shell metachar — fix mentions shell metacharacters, field=path', () => {
+    assertErrorHints(() => sanitizeFilePath('/tmp/file;rm -rf /'), {
+      fixIncludes: 'metacharacter',
+      detailsField: 'path',
+    });
+  });
+
+  it('path ending in backslash — fix mentions backslash, field=path', () => {
+    assertErrorHints(() => sanitizeFilePath('/tmp/file\\'), {
+      fixIncludes: 'backslash',
+      detailsField: 'path',
+    });
+  });
+
+  it('path with newline — fix mentions newline, field=path', () => {
+    assertErrorHints(() => sanitizeFilePath('/tmp/file\ninjected'), {
+      fixIncludes: 'newline',
+      detailsField: 'path',
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// loadManifestEntryByTaskId — protocols/_shared.ts
+// ---------------------------------------------------------------------------
+
+describe('error-hints: loadManifestEntryByTaskId', () => {
+  it('task not in manifest — fix mentions manifest entry, field=taskId', () => {
+    // This will always throw NOT_FOUND since no manifest exists in test env
+    assertErrorHints(() => loadManifestEntryByTaskId('T9999'), {
+      fixIncludes: 'manifest',
+      detailsField: 'taskId',
+    });
+  });
+});
+
+describe('error-hints: loadManifestEntryFromFile', () => {
+  it('manifest file not found — fix mentions manifest file path, field=manifestFile', () => {
+    assertErrorHints(() => loadManifestEntryFromFile('/nonexistent/path/manifest.json'), {
+      fixIncludes: 'manifest',
+      detailsField: 'manifestFile',
+    });
+  });
+});

package/src/validation/engine.ts

@@ -94,7 +94,10 @@ const SHELL_METACHARACTERS = new Set([
  */
 export function sanitizeFilePath(path: string): string {
   if (!path) {
-    throw new CleoError(ExitCode.VALIDATION_ERROR, 'Empty path provided');
+    throw new CleoError(ExitCode.VALIDATION_ERROR, 'Empty path provided', {
+      fix: 'Provide a non-empty file path',
+      details: { field: 'path' },
+    }); /* internal invariant — no user action */
   }
 
   for (const char of path) {
@@ -102,6 +105,10 @@ export function sanitizeFilePath(path: string): string {
       throw new CleoError(
         ExitCode.VALIDATION_ERROR,
         `Path contains shell metacharacters - potential injection attempt: ${path}`,
+        {
+          fix: 'Remove shell metacharacters from the file path',
+          details: { field: 'path', actual: path },
+        },
       );
     }
   }
@@ -110,6 +117,10 @@ export function sanitizeFilePath(path: string): string {
     throw new CleoError(
       ExitCode.VALIDATION_ERROR,
       'Path ends with backslash - potential injection attempt',
+      {
+        fix: 'Remove trailing backslash from the file path',
+        details: { field: 'path', actual: path },
+      },
     );
   }
 
@@ -117,6 +128,10 @@ export function sanitizeFilePath(path: string): string {
     throw new CleoError(
       ExitCode.VALIDATION_ERROR,
       'Path contains newline/carriage return - potential injection attempt',
+      {
+        fix: 'Remove newline characters from the file path',
+        details: { field: 'path', actual: path },
+      },
     );
   }
 

package/src/validation/param-utils.ts

@@ -56,7 +56,7 @@ interface ParamDef {
   items?: { type: ParamType };
   cli?: ParamCliDef;
   /** Schema config for dispatch adapter. */
-  mcp?: ParamSchemaDef;
+  dispatch?: ParamSchemaDef;
 }
 
 // ---------------------------------------------------------------------------
@@ -79,7 +79,7 @@ export interface JSONSchemaObject {
 }
 
 // ---------------------------------------------------------------------------
-// 1. buildMcpInputSchema (name kept for backward compat)
+// 1. buildDispatchInputSchema
 // ---------------------------------------------------------------------------
 
 /**
@@ -87,18 +87,18 @@ export interface JSONSchemaObject {
  *
  * Algorithm:
  *  1. Iterate `def.params`
- *  2. Skip params where schema `mcp.hidden === true`
+ *  2. Skip params where schema `dispatch.hidden === true`
  *  3. Map ParamType → JSON Schema type
  *  4. Collect names where `required === true` into `required[]`
  *  5. Return { type: 'object', properties, required }
  */
-export function buildMcpInputSchema(def: OperationDef): JSONSchemaObject {
+export function buildDispatchInputSchema(def: OperationDef): JSONSchemaObject {
   const properties: Record<string, JsonSchemaProperty> = {};
   const required: string[] = [];
 
   for (const param of def.params ?? []) {
     // Skip CLI-only params from dispatch schema
-    if (param.mcp?.hidden === true) continue;
+    if (param.dispatch?.hidden === true) continue;
 
     const prop: JsonSchemaProperty = {
       type: paramTypeToJsonSchema(param.type),
@@ -109,8 +109,8 @@ export function buildMcpInputSchema(def: OperationDef): JSONSchemaObject {
       prop.items = { type: 'string' };
     }
 
-    if (param.mcp?.enum) {
-      prop.enum = param.mcp.enum;
+    if (param.dispatch?.enum) {
+      prop.enum = param.dispatch.enum;
     }
 
     properties[param.name] = prop;
@@ -123,6 +123,9 @@ export function buildMcpInputSchema(def: OperationDef): JSONSchemaObject {
   return { type: 'object', properties, required };
 }
 
+/** @deprecated Use {@link buildDispatchInputSchema} instead. */
+export const buildMcpInputSchema = buildDispatchInputSchema;
+
 function paramTypeToJsonSchema(t: ParamDef['type']): JsonSchemaType {
   switch (t) {
     case 'string':

package/src/validation/protocols/_shared.ts

@@ -46,7 +46,10 @@ export function loadManifestEntryByTaskId(taskId: string): ManifestEntryInput {
   const manifestPath = getManifestPath();
   const entry = findManifestEntry(taskId, manifestPath);
   if (!entry) {
-    throw new CleoError(ExitCode.NOT_FOUND, `No manifest entry found for task ${taskId}`);
+    throw new CleoError(ExitCode.NOT_FOUND, `No manifest entry found for task ${taskId}`, {
+      fix: `Ensure the agent wrote a manifest entry for ${taskId} before validation`,
+      details: { field: 'taskId', actual: taskId },
+    });
   }
   return JSON.parse(entry) as ManifestEntryInput;
 }
@@ -59,7 +62,10 @@ export function loadManifestEntryByTaskId(taskId: string): ManifestEntryInput {
  */
 export function loadManifestEntryFromFile(manifestFile: string): ManifestEntryInput {
   if (!existsSync(manifestFile)) {
-    throw new CleoError(ExitCode.NOT_FOUND, `Manifest file not found: ${manifestFile}`);
+    throw new CleoError(ExitCode.NOT_FOUND, `Manifest file not found: ${manifestFile}`, {
+      fix: `Ensure the manifest file exists at: ${manifestFile}`,
+      details: { field: 'manifestFile', actual: manifestFile },
+    });
   }
   return JSON.parse(readFileSync(manifestFile, 'utf-8')) as ManifestEntryInput;
 }
@@ -78,11 +84,13 @@ export function throwIfStrictFailed(
 ): void {
   if (!opts.strict || result.valid) return;
   const code = PROTOCOL_EXIT_CODES[protocol];
+  const errorViolations = result.violations.filter((v) => v.severity === 'error');
   throw new CleoError(
     code,
-    `${protocol} protocol violations for ${taskId}: ${result.violations
-      .filter((v) => v.severity === 'error')
-      .map((v) => v.message)
-      .join('; ')}`,
+    `${protocol} protocol violations for ${taskId}: ${errorViolations.map((v) => v.message).join('; ')}`,
+    {
+      fix: `Review ${protocol} protocol requirements and correct the listed violations`,
+      details: { field: 'protocol', actual: protocol },
+    },
   );
 }

package/src/validation/protocols/cant/architecture-decision.cant

@@ -0,0 +1,80 @@
+---
+kind: protocol
+version: 1.0.0
+id: ADR
+title: "Architecture Decision Record Protocol"
+status: active
+type: conditional
+audience: "llm-agent, orchestrator"
+tags: "adr, architecture, decisions"
+skillRef: ct-adr-recorder
+lastUpdated: 2026-04-07
+enforcement: advisory
+---
+
+# Architecture Decision Record (ADR) Protocol
+#
+# Provenance: @task T4798 (ADR-006 Implementation)
+# Type: Conditional Protocol
+# Stage: RCADSD - A (ADR)
+# Max Active: 3 protocols (including base)
+#
+# Trigger Conditions
+#
+# This protocol activates when the task involves:
+#   Decision Recording: "decision", "adr", "architecture decision"
+#   Stage Transition: "after consensus", "begin adr"
+#   Formalization: "lock in decision", "formalize choice", "decide"
+#   Architectural Shift: "pivot", "new architecture", "supersede"
+#   Record Creation: "create adr", "write adr", "record decision"
+#
+# Explicit Override: --protocol adr flag on task creation.
+#
+# Requirements (RFC 2119)
+#
+# MUST:
+#   ADR-001: MUST be generated from an accepted Consensus report verdict
+#   ADR-002: MUST include a consensus_manifest_id linking to its originating consensus
+#   ADR-003: MUST require explicit HITL approval to transition from proposed to accepted
+#   ADR-004: MUST include Context, Options Evaluated, Decision, Rationale, and Consequences sections
+#   ADR-005: MUST trigger downstream invalidation if superseded
+#   ADR-006: MUST be stored in the canonical decisions SQLite table via Drizzle ORM
+#   ADR-007: MUST set agent_type: "decision" in manifest entry
+#   ADR-008: MUST block the Specification stage until the ADR status is accepted
+#
+# SHOULD:
+#   ADR-010: SHOULD document the exact data structures or schema changes required
+#   ADR-011: SHOULD explicitly list which existing ADRs are superseded, with rationale
+#   ADR-012: SHOULD flag known technical debt introduced by the decision
+#   ADR-013: SHOULD document rejected alternatives with rationale for rejection
+#
+# MAY:
+#   ADR-020: MAY include diagrams (Mermaid) illustrating the architectural shift
+#   ADR-021: MAY link to external prior art or research documents
+#   ADR-022: MAY reference related ADRs that are not superseded but contextually relevant
+#
+# Decision Status Lifecycle:
+#   proposed -> accepted -> superseded
+#                       \-> deprecated
+#
+# HITL Gate:
+#   1. Agent drafts the ADR based on consensus verdict
+#   2. Status is set to proposed
+#   3. Pipeline pauses (HANDOFF_REQUIRED - exit code 65)
+#   4. Human reviews the proposed ADR
+#   5. If approved, status transitions to accepted
+#   6. Only an accepted ADR unlocks the Specification stage
+#
+# Exit Codes:
+#   65: HANDOFF_REQUIRED - ADR drafted as proposed, awaiting HITL acceptance
+#   84: PROVENANCE_REQUIRED - Attempted to create ADR without linked Consensus report
+#   18: CASCADE_FAILED - Downstream work blocked because governing ADR was superseded
+#
+# Anti-Patterns:
+#   - Creating ADR without consensus (decisions lack evidence foundation)
+#   - Auto-accepting without HITL review (bypasses human oversight gate)
+#   - Omitting downstream impact section (future implementers unaware of cascade)
+#   - Superseding without updating specs (creates orphaned specifications)
+#   - Using ADR to define implementation requirements (that is Specification's role)
+#   - Storing ADR only as markdown without SQLite record (loses relational queries)
+#   - Skipping rejected alternatives (loses institutional knowledge)

package/src/validation/protocols/cant/artifact-publish.cant

@@ -0,0 +1,95 @@
+---
+kind: protocol
+version: 1.0.0
+id: ART
+title: "Artifact Publish Protocol"
+status: active
+type: cross-cutting
+audience: "llm-agent, orchestrator"
+tags: "artifact, publish, distribution"
+skillRef: ct-artifact-publisher
+lastUpdated: 2026-04-07
+enforcement: advisory
+---
+
+# Artifact Publish Protocol
+#
+# Type: Conditional Protocol
+# Max Active: 3 protocols (including base)
+#
+# Relationship to Release Protocol:
+#   This protocol orchestrates artifact building and publishing.
+#   Release orchestrates version bumping, tagging, and changelog.
+#   They compose: release triggers artifact-publish for distribution phase.
+#
+# Trigger Conditions
+#
+# This protocol activates when the task involves:
+#   Package Publish: "publish", "package", "distribute"
+#   Artifact Build: "artifact", "build artifact", "bundle"
+#   Container Push: "docker push", "container registry", "image publish"
+#   Language Package: "crate", "gem", "wheel", "sdist"
+#   Multi-Artifact: "publish all", "release artifacts", "multi-package"
+#
+# Explicit Override: --protocol artifact-publish flag on task creation.
+#
+# Requirements (RFC 2119)
+#
+# MUST:
+#   ARTP-001: MUST validate artifact configuration before build
+#   ARTP-002: MUST execute dry-run before any real publish
+#   ARTP-003: MUST follow handler interface contract: validate -> build -> publish
+#   ARTP-004: MUST generate SHA-256 checksums for all built artifacts
+#   ARTP-005: MUST record provenance metadata via record_release()
+#   ARTP-006: MUST use sequential execution for multi-artifact publish
+#   ARTP-007: MUST set agent_type: "artifact-publish" in manifest
+#   ARTP-008: MUST NOT store credentials in config, output, or manifest
+#   ARTP-009: MUST halt pipeline and attempt rollback on first publish failure
+#
+# SHOULD:
+#   ARTP-010: SHOULD verify registry reachability before publish
+#   ARTP-011: SHOULD validate version consistency between config and artifact metadata
+#   ARTP-012: SHOULD log all publish operations to audit trail
+#   ARTP-013: SHOULD verify build output exists and is non-empty before publish
+#
+# MAY:
+#   ARTP-020: MAY batch validation across all artifacts before starting builds
+#   ARTP-021: MAY generate SBOM alongside artifacts (delegate to provenance)
+#   ARTP-022: MAY sign artifacts using configured signing method (delegate to provenance)
+#
+# Artifact Lifecycle State Machine:
+#   configured -> validated -> built -> published
+#                    |            |         |
+#                  failed       failed    failed -> rollback
+#
+# Registered Handlers (9 types):
+#   npm-package, python-wheel, python-sdist, go-module,
+#   cargo-crate, ruby-gem, docker-image, github-release, generic-tarball
+#
+# Multi-Artifact Pipeline Phases:
+#   Phase 1: Pre-validate all artifacts
+#   Phase 2: Build sequential per artifact
+#   Phase 3: Publish with rollback on failure
+#
+# Credential Handling:
+#   Agents MUST NOT store, log, or embed credentials
+#   Resolution order: env var -> CI secret -> credential manager (future)
+#
+# Error Codes (85-89):
+#   85: E_ARTIFACT_TYPE_UNKNOWN
+#   86: E_ARTIFACT_VALIDATION_FAILED
+#   87: E_ARTIFACT_BUILD_FAILED
+#   88: E_ARTIFACT_PUBLISH_FAILED (rollback attempted)
+#   89: E_ARTIFACT_ROLLBACK_FAILED
+#
+# Anti-Patterns:
+#   - Publishing without dry-run first (irreversible registry state)
+#   - Storing credentials in config.json (committed to VCS)
+#   - Parallel multi-artifact publish (race conditions)
+#   - Skipping checksum generation (cannot verify integrity)
+#   - Publishing without version check (duplicate version errors)
+#   - Ignoring publish failures (inconsistent state)
+#   - Logging credential values (exposure in audit trail)
+#   - Building without validation (wastes time)
+#   - Manual rollback without recording (lost provenance chain)
+#   - Hardcoding registry URLs (breaks across environments)

package/src/validation/protocols/cant/consensus.cant

@@ -0,0 +1,74 @@
+---
+kind: protocol
+version: 1.0.0
+id: CONS
+title: "Consensus Protocol"
+status: active
+type: conditional
+audience: "llm-agent, orchestrator"
+tags: "consensus, voting, validation"
+skillRef: ct-consensus-voter
+lastUpdated: 2026-04-07
+enforcement: strict
+---
+
+# Consensus Protocol
+#
+# Provenance: @task T3155, @epic T3147
+# Type: Conditional Protocol
+# Max Active: 3 protocols (including base)
+#
+# Trigger Conditions
+#
+# This protocol activates when the task involves:
+#   Decision Making: "vote", "decide", "choose", "select"
+#   Agreement: "consensus", "agree", "alignment"
+#   Conflict Resolution: "resolve", "dispute", "conflict"
+#   Validation: "validate claim", "verify assertion"
+#
+# Explicit Override: --protocol consensus flag on task creation.
+#
+# Requirements (RFC 2119)
+#
+# MUST:
+#   CONS-001: MUST use structured voting format
+#   CONS-002: MUST document rationale for each position
+#   CONS-003: MUST include confidence scores (0.0-1.0)
+#   CONS-004: MUST cite evidence supporting positions
+#   CONS-005: MUST flag conflicts with severity levels
+#   CONS-006: MUST escalate to HITL when threshold not reached
+#   CONS-007: MUST set agent_type: "analysis" in manifest
+#
+# SHOULD:
+#   CONS-010: SHOULD present multiple perspectives
+#   CONS-011: SHOULD identify hidden assumptions
+#   CONS-012: SHOULD document rejected alternatives
+#   CONS-013: SHOULD include uncertainty notes for low confidence
+#
+# MAY:
+#   CONS-020: MAY propose compromise positions
+#   CONS-021: MAY defer non-critical decisions
+#   CONS-022: MAY request additional research
+#
+# Verdict Thresholds:
+#   PROVEN: 3/5 agents OR 50%+ weighted confidence, reproducible evidence
+#   REFUTED: Counter-evidence invalidates, counter-proof exists
+#   CONTESTED: 3/5 split after 2 challenge rounds, document both sides
+#   INSUFFICIENT_EVIDENCE: Cannot reach verdict, request investigation
+#
+# HITL Escalation:
+#   - Contested verdict (3/5 split): Present conflict to user
+#   - Critical severity conflict: Immediate escalation
+#   - Insufficient evidence: Request user guidance
+#   - Unanimous suspicious consensus: Verify with user
+#
+# Exit Codes:
+#   EXIT_PROTOCOL_CONSENSUS (61) - Consensus protocol violation
+#   EXIT_PROTOCOL_GENERIC (67) - Generic protocol error
+#
+# Anti-Patterns:
+#   - Accepting unanimous consensus without scrutiny (may indicate groupthink)
+#   - Skipping evidence citations (decisions lack foundation)
+#   - Binary voting without confidence (loses nuance)
+#   - Ignoring minority positions (may miss valid concerns)
+#   - Premature escalation (wastes human attention)

package/src/validation/protocols/cant/contribution.cant

@@ -0,0 +1,82 @@
+---
+kind: protocol
+version: 1.0.0
+id: CONT
+title: "Contribution Protocol"
+status: active
+type: cross-cutting
+audience: "llm-agent, orchestrator"
+tags: "contribution, commit, pr"
+skillRef: ct-contribution
+lastUpdated: 2026-02-24
+enforcement: strict
+---
+
+# Contribution Protocol
+#
+# Provenance: @task T3155, @epic T3147
+# Type: Cross-Cutting Protocol
+# Applies To: All RCASD-IVTR+C stages
+# Max Active: 3 protocols (including base)
+#
+# Cross-Cutting Nature: This protocol applies across ALL stages of RCASD-IVTR+C.
+# Unlike stage-specific protocols, contribution tracking is active whenever
+# multi-agent coordination or attribution is needed.
+#
+# Trigger Conditions
+#
+# This protocol activates when the task involves:
+#   Shared File Modification: Modifying CLAUDE.md, AGENTS.md, shared configs
+#   PR Creation: "pull request", "PR", "merge request"
+#   Cross-Session Work: Multiple agents on same epic
+#   Audit Trail: Provenance, attribution, tracking
+#
+# Explicit Override: --protocol contribution flag on task creation.
+#
+# Requirements (RFC 2119)
+#
+# MUST:
+#   CONT-001: MUST follow commit message conventions
+#   CONT-002: MUST include provenance tags in code comments
+#   CONT-003: MUST pass all validation gates before merge
+#   CONT-004: MUST document decisions with rationale
+#   CONT-005: MUST flag conflicts with other sessions
+#   CONT-006: MUST write contribution record to manifest
+#   CONT-007: MUST set agent_type: "implementation" in manifest
+#
+# SHOULD:
+#   CONT-010: SHOULD include test coverage for changes
+#   CONT-011: SHOULD link to related tasks and research
+#   CONT-012: SHOULD document rejected alternatives
+#   CONT-013: SHOULD request review for significant changes
+#
+# MAY:
+#   CONT-020: MAY batch related changes into single contribution
+#   CONT-021: MAY defer documentation updates
+#   CONT-022: MAY propose follow-up improvements
+#
+# Commit Message Format:
+#   <type>(<scope>): <summary>
+#   Types: feat, fix, docs, test, refactor, chore, perf
+#
+# Validation Gates:
+#   Schema: JSON Schema validation (MUST pass)
+#   Tests: All tests pass (MUST pass)
+#   Lint: Code style compliance (SHOULD pass)
+#   Security: No secrets committed (MUST pass)
+#   Conflicts: No unresolved conflicts (MUST resolve)
+#
+# Provenance Thresholds:
+#   New code: 100%
+#   Existing code: 80%
+#   Legacy code: 50%
+#
+# Exit Codes:
+#   EXIT_PROTOCOL_CONTRIBUTION (65) - Contribution protocol violation
+#
+# Anti-Patterns:
+#   - Committing without provenance (breaks audit trail)
+#   - Skipping validation gates (quality regression)
+#   - Ignoring conflicts (creates merge debt)
+#   - Large unfocused commits (hard to review/revert)
+#   - Missing decision documentation (lost context)

package/src/validation/protocols/cant/decomposition.cant

@@ -0,0 +1,92 @@
+---
+kind: protocol
+version: 2.0.0
+id: DCMP
+title: "Decomposition Protocol"
+status: active
+type: conditional
+audience: "llm-agent, orchestrator"
+tags: "decomposition, hierarchy, atomicity, planning"
+skillRef: ct-epic-architect
+lastUpdated: 2026-02-24
+provenanceTask: T3155
+enforcement: strict
+---
+
+# Decomposition Protocol
+#
+# Provenance: @task T3155, @epic T3147
+# Type: Conditional Protocol
+# Max Active: 3 protocols (including base)
+#
+# Trigger Conditions
+#
+# This protocol activates when the task involves:
+#   Epic Planning: "epic", "project", "initiative"
+#   Breakdown: "decompose", "break down", "split"
+#   Planning: "plan", "roadmap", "phases"
+#   Analysis: "scope", "estimate complexity"
+#
+# Explicit Override: --protocol decomposition flag on task creation.
+#
+# Hard Invariants (always enforced):
+#   - Parent must exist: parent task ID must be present in the task store
+#   - No circular references: moving a task under its own descendant is rejected
+#   - Dependency DAG integrity: blockedBy/blocks must remain acyclic
+#
+# Configurable Limits (profile-driven):
+#   maxSiblings: default 0 (unlimited for llm-agent-first); 7 for human-cognitive
+#   maxActiveSiblings: default 32 (operational concurrency guard)
+#   maxDepth: default 3 (epic -> task -> subtask)
+#
+# Enforcement Profiles:
+#   llm-agent-first (default): maxSiblings=0, maxActiveSiblings=32, maxDepth=3
+#   human-cognitive: maxSiblings=7, maxActiveSiblings=3, maxDepth=3
+#
+# Requirements (RFC 2119)
+#
+# MUST:
+#   DCMP-001: MUST follow MECE principle (Mutually Exclusive, Collectively Exhaustive)
+#   DCMP-002: MUST map dependencies between tasks
+#   DCMP-003: MUST respect the configured hierarchy.maxDepth policy (default: 3)
+#   DCMP-004: MUST verify atomicity for leaf tasks
+#   DCMP-005: MUST NOT include time estimates (use size: small/medium/large)
+#   DCMP-006: MUST include acceptance criteria for each task
+#   DCMP-007: Siblings MUST respect the configured hierarchy.maxSiblings policy
+#   DCMP-008: Depth MUST respect the configured hierarchy.maxDepth policy
+#   DCMP-009: MUST set agent_type: "analysis" in manifest
+#
+# SHOULD:
+#   DCMP-010: SHOULD identify parallel execution opportunities
+#   DCMP-011: SHOULD flag unclear requirements for HITL
+#   DCMP-012: SHOULD consider existing task overlap
+#   DCMP-013: SHOULD assign phase to each task
+#
+# MAY:
+#   DCMP-020: MAY propose multiple decomposition options
+#   DCMP-021: MAY identify risks and mitigations
+#   DCMP-022: MAY suggest task consolidation
+#
+# Atomicity Criteria (6-Point Test):
+#   1. Single File Scope: Affects <=3 tightly-coupled files
+#   2. Single Cognitive Concern: One bounded concern per task
+#   3. Clear Acceptance Criteria: Testable completion condition
+#   4. No Context Switching: Completable within a single agent session
+#   5. No Hidden Sub-Decisions: All choices made at decomposition
+#   6. Programmatic Validation: Result verifiable by code/test
+#
+# Size Definitions:
+#   small: 1-2 files, single concern, MUST be atomic
+#   medium: 3-7 files, related concerns, SHOULD be atomic
+#   large: 8+ files, multiple concerns, MUST decompose further
+#
+# Exit Codes:
+#   EXIT_PROTOCOL_DECOMPOSITION (63) - Decomposition protocol violation
+#
+# Anti-Patterns:
+#   - Time estimates (cannot predict duration accurately)
+#   - Non-atomic leaf tasks (create hidden work)
+#   - Missing dependencies (incorrect execution order)
+#   - Exceeding configured maxDepth (complexity explosion)
+#   - Overlapping scopes (not MECE - duplicate work)
+#   - Skipping atomicity check (quality regression)