Skip to main content

ADR-056: Action-Level Task Tracking Protocol

Status​

ACCEPTED - January 5, 2026

Context​

Current State​

CODITECT uses a track-based task nomenclature system (ADR-054) for project planning:

  • Task IDs follow format: Track.Section.Task[.Subtask] (e.g., A.9.1.3)
  • Tasks are tracked in PILOT-PARALLEL-EXECUTION-PLAN.md (SSOT)
  • Cloud sync (ADR-053) enables TaskTracking model synchronization

Problem Statement​

When AI agents execute tasks, individual tool calls (Bash, Read, Edit, Glob, Grep) are not correlated to their parent task IDs. This creates:

  1. Lost Audit Trail: Cannot determine which actions were taken for which task
  2. Session Log Gaps: Actions appear without context in session logs
  3. Retrospective Blind Spots: Cannot analyze task execution patterns
  4. Cloud Sync Limitations: TaskTracking model cannot link to specific actions

Observed Anti-Pattern​

# Agent executes task A.9.1.3 but tool calls lack context:
Bash(description="Check migration status")           # What task?
Bash(description="List files in directory")          # Why?
Bash(description="Run Django command")               # For which goal?

Requirements​

  1. Traceability: Every tool call must be traceable to a task ID
  2. Automation: Protocol must be enforceable via hooks
  3. Consistency: Same format across all tool types
  4. Backward Compatibility: Existing tasks continue to work
  5. Platform-Wide: Applies to all CODITECT-managed projects

Decision​

We adopt Action-Level Task Tracking as Automation Principle #12 with the following protocol:

Protocol Format​

Every tool call description MUST include the task ID prefix:

{Task ID}: {Action Description}

Tool-Specific Patterns​

ToolPattern
BashBash(description="{Task ID}: {action}")
ReadState in response: "Reading for {Task ID}"
EditState in response: "{Task ID}: Updated X"
WriteState in response: "{Task ID}: Created X"
Glob/GrepState in response: "{Task ID}: Searching for X"
TaskInclude task ID in prompt context

Examples​

Correct:

Bash(description="A.9.1.3: Check if migration is applied to production")
Bash(description="A.9.1.3: Run Django migrate for context app")
Bash(description="F.5.4: Create ADR-056 for action-level tracking")

Incorrect:

Bash(description="Check migration status")        # Missing task ID
Bash(description="List files")                    # Too generic
Bash(description="Run command")                   # No context

Enforcement Levels​

LevelBehavior
warnLog warning, allow operation (default)
softDisplay warning to user, allow operation
strictBlock operation until task ID provided

Hook Implementation​

# hooks/task-tracking-enforcer.py (PreToolUse)
# Validates Bash description parameter starts with task ID pattern
# Pattern: [A-Z]+ . d+( . d+)*:

TASK_ID_PREFIX = re.compile(r'^[A-Z]+\.\d+(\.\d+)*:\s')

def validate_bash_description(description: str) -> bool:
    return TASK_ID_PREFIX.match(description) is not None

Consequences​

Positive​

  1. Complete Audit Trail: Every action linked to its parent task
  2. Automated Session Logs: /session-log auto-correlates actions
  3. Retrospective Intelligence: Analyze task execution patterns
  4. Cloud Sync Ready: TaskTracking model can link to actions
  5. Quality Improvement: Identify inefficient task execution

Negative​

  1. Verbosity: Descriptions become longer
  2. Learning Curve: Agents must adopt new pattern
  3. Enforcement Overhead: Hook runs on every Bash call

Neutral​

  1. Migration: Existing sessions unaffected (forward-only)
  2. Optional Strictness: Teams choose enforcement level

Implementation​

Phase 1: Documentation (Completed)​

  • Update CLAUDE.md Section 2 with protocol
  • Add Principle #12 to CODITECT-STANDARD-AUTOMATION.md
  • Update rollout-master/CLAUDE.md reference
  • Create this ADR

Phase 2: Hook Enhancement (Pending)​

  • Update task-tracking-enforcer.py to validate Bash descriptions
  • Add --level flag support (warn/soft/strict)
  • Add metrics collection for compliance rate

Phase 3: Cloud Integration (Pending)​

  • Link task actions to TaskTracking model
  • Enable action-level reporting in cloud dashboard
  • Add retrospective analysis queries

Compliance​

This ADR establishes Automation Principle #12 in:

  • coditect-core-standards/CODITECT-STANDARD-AUTOMATION.md
  • coditect-core/CLAUDE.md Section 2
  • rollout-master/CLAUDE.md Track Nomenclature section

All CODITECT-managed projects inherit this protocol via symlink architecture.

  • ADR-053: Cloud Context Sync Architecture
  • ADR-054: Track Nomenclature Extensibility
  • Standard: CODITECT-STANDARD-AUTOMATION.md (Principle #12)
  • Standard: CODITECT-STANDARD-TRACK-NOMENCLATURE.md
  • Hook: hooks/task-tracking-enforcer.py

Version: 1.0.0 Author: Hal Casteel Approved By: Platform Architecture Team