Functional Specification: M49 - Decision Execution Tracker

Version: 1.0 Date: October 29, 2025 Status: Draft

1.0 Executive Summary

1.1 Purpose

This document provides the functional and technical specifications for the M49: Decision Execution Tracker. This system represents a strategic evolution of ChainAlign's architecture, moving beyond simple task management to a sophisticated "Decision Loop" model. Its purpose is to create an auditable, learning-oriented system where every task is an explicit execution artifact of a recorded decision.

1.2 Problem Statement

The current integration with external task managers (e.g., Linear) creates a dependency that makes them first-class citizens in the decision loop. This introduces risks such as rate-limiting, external outages, and a fragmented audit trail. The "Judgment Graph" (notes -> problems -> scenarios -> decisions) lacks a native "execution layer," making it difficult to track the real-world outcome and effectiveness of a decision.

1.3 Solution Overview

The Decision Execution Tracker reframes a "task" as a "Decision Loop," a structured cycle of intent, context, action, and learning. This will be achieved by introducing a new TaskService as the source of truth for execution, and a TaskSyncService to treat external platforms like Linear or Jira as optional, decoupled synchronization layers. This ensures that ChainAlign's core decision-making process remains intact and auditable, regardless of external system availability. The entire system will be exposed through an extended GraphQL API, reinforcing the "Judgment Graph" as the central nervous system of the platform.

1.4 Demo Scope vs. Post-MVP

MVP (Demo Phase - M49 v1.0):

Decision confirmation flow with drag-confirm gesture
TaskService CRUD for DecisionTasks (status: PENDING → IN_PROGRESS → COMPLETED)
Task display in home screen task list
Manual outcome recording (narrative + optional metrics)
Single-user task assignment and tracking
GraphQL queries for decision-to-task relationships

Post-MVP (Future Versions):

TaskSyncService with external adapters (Linear, Jira, Asana)
Two-way webhook synchronization with external systems
Personal task management (separate from decision tasks)
Advanced conflict resolution for external/internal state divergence
ERP integration for auto-detection of task completion
AI-driven task recommendations and auto-categorization

2.0 Core Design Principles

Tasks as Decision Loops: A task is not a "to-do." It is the operational evidence of a decision, linking intent (origin_decision_id) to execution and outcome.
Judgment Graph Integration: Tasks are native nodes in the Judgment Graph, enabling analysis of which decisions lead to the most effective execution.
Decoupled Synchronization: External task managers are sync targets, not the source of truth. This makes the core platform resilient to external API failures and rate limits.
Document Reasoning, Not Just Results: The system captures the "why" behind a task by linking it directly to a decision, reinforcing ChainAlign's core value proposition.
GraphQL-First: The entire Decision Loop will be queryable via a unified GraphQL API, enabling rich, contextual data retrieval for both UIs and AI agents.

3.0 System Architecture

The Decision Execution Tracker introduces two new services within Layer 3 (The GraphRAG & Judgment Engine) and formalizes their interaction with the data layer and external systems.

3.1 Service Diagram

3.2 Service Roles

Service	Responsibility	Phase
`TaskService.js`	[MVP] Owns the CRUD lifecycle and business logic for `decision_tasks`. Manages status, priority, and assignment internally. Publishes events (e.g., `task.created`, `task.status.changed`) for other services to consume. Exposes all task-related GraphQL resolvers. Home screen integration pulls tasks from this service.	MVP
`TaskSyncService.js`	[Post-MVP] Listens for events from `TaskService`. Contains provider-specific "Adapters" (e.g., `LinearAdapter`, `JiraAdapter`) that translate internal tasks into external issues and vice-versa. Manages all external API communication, including rate limiting, retry logic, and webhook ingestion.	Post-MVP
`LinearJudgmentEngineService.js`	[Existing] Current Linear integration remains functional. Will be absorbed by `TaskSyncService`'s `LinearAdapter` in Post-MVP phase. Not required for demo.	Existing
`AIGateway.js`	Monitors any LLM-driven task creation or modification, ensuring all AI-initiated actions are logged in the `llm_interaction_audit` table for governance.	MVP

4.0 Database Schema

To support the Decision Execution Tracker, the PostgreSQL schema will be extended with new tables. The decision_tasks and outcomes tables are required for MVP. The external_syncs table is deferred to Post-MVP.

4.1 `decision_tasks` Table

[MVP] This is the new source of truth for all execution tasks.

CREATE TABLE decision_tasks (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
    origin_decision_id UUID NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
    origin_constraint_id UUID REFERENCES constraints(id) ON DELETE SET NULL,
    
    title TEXT NOT NULL,
    description TEXT,
    
    task_type VARCHAR(50) NOT NULL CHECK (task_type IN ('ELEVATE', 'EXPLOIT', 'SUBORDINATE', 'AUDIT')),
    priority_score NUMERIC(5, 2),
    priority INTEGER,
    
    status VARCHAR(50) NOT NULL DEFAULT 'PENDING' CHECK (status IN ('PENDING', 'IN_PROGRESS', 'COMPLETED', 'BLOCKED')),
    
    assignee_id UUID REFERENCES users(id) ON DELETE SET NULL,
    due_date TIMESTAMPTZ,
    
    is_external_synced BOOLEAN DEFAULT FALSE,
    external_ref_id VARCHAR(255),
    
    completion_notes TEXT,
    metadata JSONB,
    
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

4.2 `external_syncs` Table

[Post-MVP] This table tracks the relationship between an internal task and its external counterparts. Deferred until TaskSyncService implementation.

CREATE TABLE external_syncs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    task_id UUID NOT NULL REFERENCES decision_tasks(id) ON DELETE CASCADE,
    system VARCHAR(50) NOT NULL, -- 'Linear', 'Jira', 'Asana'
    external_id VARCHAR(255) NOT NULL,
    sync_status VARCHAR(50) NOT NULL CHECK (sync_status IN ('ACTIVE', 'RATE_LIMITED', 'FAILED', 'DISCONNECTED')),
    last_synced_at TIMESTAMPTZ,
    metadata JSONB, -- Store external URL, etc.
    UNIQUE(task_id, system)
);

4.3 `outcomes` Table

[MVP] This table captures the qualitative and quantitative results of a completed task. Used for manual outcome recording in the demo.

CREATE TABLE outcomes (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    task_id UUID NOT NULL REFERENCES decision_tasks(id) ON DELETE CASCADE,
    metrics JSONB, -- Quantitative outcome (e.g., { "cost_saved": 50000, "efficiency_gain_percent": 10 })
    narrative TEXT, -- Qualitative learning or summary of what happened
    recorded_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    recorded_by UUID NOT NULL REFERENCES users(id)
);

5.0 GraphQL Schema & API

The GraphQL API will be extended to expose the new entities and their relationships within the Judgment Graph.

5.1 Schema Definition (SDL)

# Core task entity, now named DecisionTask to be explicit
type DecisionTask {
  id: ID!
  title: String!
  description: String
  
  # Link back to the core decision
  decision: Decision!
  
  # TOC Framework
  taskType: String! # ELEVATE, EXPLOIT, SUBORDINATE, AUDIT
  priorityScore: Float!
  
  status: TaskStatus!
  priority: Int
  dueDate: DateTime
  assignee: User
  
  # Syncing and outcomes
  externalSyncs: [ExternalSync!]!
  outcome: Outcome
  
  createdAt: DateTime!
  updatedAt: DateTime!
}

enum TaskStatus {
  PENDING
  IN_PROGRESS
  COMPLETED
  BLOCKED
}

type ExternalSync {
  system: String! # e.g., "Linear", "Jira"
  externalId: String
  syncStatus: SyncStatus!
  lastSyncedAt: DateTime
  url: String # Added for direct linking
}

enum SyncStatus {
  ACTIVE
  RATE_LIMITED
  FAILED
  DISCONNECTED
}

type Outcome {
  id: ID!
  metrics: JSON
  narrative: String
  recordedAt: DateTime
}

# Extend the existing Decision type to create the link
extend type Decision {
  executionTasks: [DecisionTask!]!
  executionStatus: String! # Calculated field, e.g., "75% Complete"
}

# --- Mutations ---

type Mutation {
  createTask(input: CreateTaskInput!): DecisionTask!
  updateTaskStatus(id: ID!, status: TaskStatus!): DecisionTask!
  recordTaskOutcome(id: ID!, input: OutcomeInput!): Outcome!
  syncTaskToExternal(id: ID!, system: String!): ExternalSync!
}

input CreateTaskInput {
  decisionId: ID!
  title: String!
  description: String
  taskType: String!
  priority: Int
  dueDate: DateTime
  assigneeId: ID
}

input OutcomeInput {
  metrics: JSON
  narrative: String!
}

5.2 Example Query

This demonstrates how the frontend can query the entire decision-to-outcome loop in a single request.

query GetDecisionExecutionDetails($decisionId: ID!) {
  decision(id: $decisionId) {
    id
    title
    rationale
    executionStatus
    executionTasks {
      id
      title
      status
      priorityScore
      assignee {
        name
        email
      }
      externalSyncs {
        system
        externalId
        url
        syncStatus
      }
      outcome {
        narrative
        metrics
      }
    }
  }
}

6.0 User Journey Example

6.1 MVP Demo Flow

Decision Suggested: The Real-Time Scenario Workbench (FSD-AI) suggests a decision to "Increase safety stock for Widget-Pro by 20% to mitigate supplier risk."
Decision Confirmed: The S&OP planner uses the drag-confirm gesture to confirm the decision. This triggers the creation of a Decision record and emits a decision.confirmed event.
Task Created Automatically: The TaskService listens for the decision.confirmed event and automatically creates a DecisionTask with:
- status: PENDING
- origin_decision_id linked to the confirmed decision
- task_type inferred from the decision context (e.g., 'ELEVATE')
Task Visible in Home Screen: The task appears in the user's home screen task list, showing decision details and current status.
Manual Status Update: As the user implements the decision (e.g., updating safety stock in their ERP), they mark the task as IN_PROGRESS.
Implementation Monitoring: The system monitors for changes in the next data pull from the ERP source. If the change is detected, the user is prompted to confirm completion.
Outcome Recording: Once the decision is implemented and its effects observed, the user records the outcome using the recordTaskOutcome mutation:
- narrative: "Safety stock increased by 20%. Monitored for one week, no supply issues observed."
- metrics (optional): { "days_safe_stock_increased": 10, "cost_impact_percent": -2.5 }
Task Marked Complete: The task status moves to COMPLETED.
Audit & Learning: The entire loop (decision → task → outcome) is now captured in ChainAlign's Judgment Graph, enabling learning about which decisions drive successful outcomes.

6.2 Post-MVP Enhancement Flow

Note: The following steps are deferred to Post-MVP and require TaskSyncService implementation:

External Sync: User clicks "Sync to Linear" to push task to Linear (optional)
Bidirectional Updates: Linear webhook handlers sync task status back to ChainAlign
Automatic Completion Detection: ERP system webhooks auto-detect implementation without manual user intervention

7.0 Non-Functional Requirements

Resilience: The TaskService and core UI must remain 100% functional even if the TaskSyncService or an external API (Linear, Jira) is down.
Performance: API response times for querying tasks linked to a decision must be < 300ms.
Data Integrity: The system must handle potential race conditions where a task is updated both internally and externally simultaneously, with the internal state taking precedence.
Security: All external API credentials must be stored securely in a secret manager (e.g., HashiCorp Vault, Google Secret Manager) and never exposed in logs or code.

1.0 Executive Summary​

1.1 Purpose​

1.2 Problem Statement​

1.3 Solution Overview​

1.4 Demo Scope vs. Post-MVP​

2.0 Core Design Principles​

3.0 System Architecture​

3.1 Service Diagram​

3.2 Service Roles​

4.0 Database Schema​

4.1 decision_tasks Table​

4.2 external_syncs Table​

4.3 outcomes Table​

5.0 GraphQL Schema & API​

5.1 Schema Definition (SDL)​

5.2 Example Query​

6.0 User Journey Example​

6.1 MVP Demo Flow​

6.2 Post-MVP Enhancement Flow​

7.0 Non-Functional Requirements​