index

Documentation

Overview

Package index provides task index persistence helpers.

Package index provides task index persistence helpers.

Package index defines the task index data model and JSON mapping.

Package index provides task index sanity checks.

Package index provides helpers for updating task state and attempts.

Index

• Variables
• func IncrementTaskAttempt(idx *Index, taskID string) error
• func IncrementTaskFailedAttempt(idx *Index, taskID string) error
• func SanityCheck(idx Index, warn func(string)) error
• func Save(path string, idx Index) (err error)
• func SaveWithLock(path string, idx Index, lock *WriteLock) error
• func TransitionTaskStateWithAudit(idx *Index, taskID string, to TaskState, auditor TransitionAuditor) error
• func TransitionTaskToBlocked(idx *Index, taskID string) error
• func TransitionTaskToConflict(idx *Index, taskID string) error
• func TransitionTaskToDone(idx *Index, taskID string) error
• func TransitionTaskToImplemented(idx *Index, taskID string) error
• func TransitionTaskToMergeable(idx *Index, taskID string) error
• func TransitionTaskToMerged(idx *Index, taskID string) error
• func TransitionTaskToOpen(idx *Index, taskID string) error
• func TransitionTaskToResolved(idx *Index, taskID string) error
• func TransitionTaskToReviewed(idx *Index, taskID string) error
• func TransitionTaskToTested(idx *Index, taskID string) error
• func TransitionTaskToTriaged(idx *Index, taskID string) error
• func TransitionTaskToWorked(idx *Index, taskID string) error
• type AttemptCounters
• type Digests
• type ExecutionMetrics
• type Index
  • func Load(path string) (Index, error)
• type RetryPolicy
• type Role
• type Task
• type TaskKind
• type TaskState
• type TransitionAuditor
• type WriteLock
  • func AcquireWriteLock(path string) (*WriteLock, error)
  • func (lock *WriteLock) Release() error

Variables

var (
	// ErrLockHeld indicates another process currently holds the index write lock.
	ErrLockHeld = errors.New("task index lock already held")
)

Functions

func IncrementTaskAttempt

func IncrementTaskAttempt(idx *Index, taskID string) error

IncrementTaskAttempt increments the total attempt counter for a task.

func IncrementTaskFailedAttempt

func IncrementTaskFailedAttempt(idx *Index, taskID string) error

IncrementTaskFailedAttempt increments the failed attempt counter for a task.

func SanityCheck

func SanityCheck(idx Index, warn func(string)) error

SanityCheck inspects the index for obvious issues and reports warnings.

func Save

func Save(path string, idx Index) (err error)

Save writes a task index JSON file to disk deterministically.

func SaveWithLock

func SaveWithLock(path string, idx Index, lock *WriteLock) error

SaveWithLock writes a task index while holding an externally-acquired write lock.

func TransitionTaskStateWithAudit

func TransitionTaskStateWithAudit(idx *Index, taskID string, to TaskState, auditor TransitionAuditor) error

TransitionTaskStateWithAudit moves a task to the target state and records an audit entry.

func TransitionTaskToBlocked

func TransitionTaskToBlocked(idx *Index, taskID string) error

TransitionTaskToBlocked moves a task from triaged, implemented, tested, mergeable, conflict, or resolved to blocked.

func TransitionTaskToConflict

func TransitionTaskToConflict(idx *Index, taskID string) error

TransitionTaskToConflict moves a task from tested, mergeable, or resolved to conflict.

func TransitionTaskToDone

func TransitionTaskToDone(idx *Index, taskID string) error

func TransitionTaskToImplemented

func TransitionTaskToImplemented(idx *Index, taskID string) error

TransitionTaskToImplemented moves a task from triaged to implemented.

func TransitionTaskToMergeable

func TransitionTaskToMergeable(idx *Index, taskID string) error

TransitionTaskToMergeable marks a reviewed or resolved task as mergeable.

func TransitionTaskToMerged

func TransitionTaskToMerged(idx *Index, taskID string) error

TransitionTaskToMerged moves a task from mergeable or resolved to merged.

func TransitionTaskToOpen

func TransitionTaskToOpen(idx *Index, taskID string) error

func TransitionTaskToResolved

func TransitionTaskToResolved(idx *Index, taskID string) error

TransitionTaskToResolved moves a task from conflict to resolved.

func TransitionTaskToReviewed

func TransitionTaskToReviewed(idx *Index, taskID string) error

TransitionTaskToReviewed marks a tested task as reviewed.

func TransitionTaskToTested

func TransitionTaskToTested(idx *Index, taskID string) error

TransitionTaskToTested moves a task from implemented to tested.

func TransitionTaskToTriaged

func TransitionTaskToTriaged(idx *Index, taskID string) error

TransitionTaskToTriaged moves a task from blocked to triaged.

func TransitionTaskToWorked

func TransitionTaskToWorked(idx *Index, taskID string) error

Legacy wrappers kept for compatibility.

Types

type AttemptCounters

type AttemptCounters struct {
	Total  int `json:"total"`
	Failed int `json:"failed"`
}

AttemptCounters tracks how many attempts have been made.

type Digests

type Digests struct {
	GovernatorMD string            `json:"governator_md"`
	PlanningDocs map[string]string `json:"planning_docs"`
}

Digests captures content digests for planning artifacts and governance docs.

type ExecutionMetrics

type ExecutionMetrics struct {
	DurationMs     int64 `json:"duration_ms,omitempty"`     // Total wall time in milliseconds across all stages
	TokensPrompt   int   `json:"tokens_prompt,omitempty"`   // Total input tokens consumed
	TokensResponse int   `json:"tokens_response,omitempty"` // Total output tokens generated
	TokensTotal    int   `json:"tokens_total,omitempty"`    // Total tokens (prompt + response)
}

ExecutionMetrics captures execution statistics for retrospective analysis.

type Index

type Index struct {
	SchemaVersion int     `json:"schema_version"`
	Digests       Digests `json:"digests"`
	Tasks         []Task  `json:"tasks"`
}

Index represents the canonical task index persisted as JSON.

func Load

func Load(path string) (Index, error)

Load reads a task index JSON file from disk.

type RetryPolicy

type RetryPolicy struct {
	MaxAttempts int `json:"max_attempts"`
}

RetryPolicy defines the retry limits for a task.

type Role

type Role string

Role names the worker role assigned to a task.

type Task

type Task struct {
	ID            string           `json:"id"`
	Title         string           `json:"title,omitempty"`
	Path          string           `json:"path"`
	Kind          TaskKind         `json:"kind"`
	State         TaskState        `json:"state"`
	Role          Role             `json:"role"`
	AssignedRole  string           `json:"assigned_role,omitempty"`
	BlockedReason string           `json:"blocked,omitempty"`
	MergeConflict bool             `json:"merge_conflict,omitempty"`
	PID           int              `json:"pid,omitempty"`
	Dependencies  []string         `json:"dependencies"`
	Retries       RetryPolicy      `json:"retries"`
	Attempts      AttemptCounters  `json:"attempts"`
	Metrics       ExecutionMetrics `json:"metrics,omitempty"`
	Order         int              `json:"order"`
	Overlap       []string         `json:"overlap"`
}

Task captures a single task entry from the task index.

type TaskKind

type TaskKind string

TaskKind distinguishes planning work from execution work.

const (
	// TaskKindPlanning identifies a planning step in the planning workstream.
	TaskKindPlanning TaskKind = "planning"
	// TaskKindExecution identifies implementation work run during execution.
	TaskKindExecution TaskKind = "execution"
)

type TaskState

type TaskState = state.TaskState

TaskState labels the lifecycle state for a task.

const (
	// TaskStateBacklog indicates the task is awaiting triage.
	TaskStateBacklog TaskState = state.TaskStateBacklog
	// TaskStateTriaged indicates the task has been triaged and awaits implementation.
	TaskStateTriaged TaskState = state.TaskStateTriaged
	// TaskStateImplemented indicates the task has implementation work done and awaits testing.
	TaskStateImplemented TaskState = state.TaskStateImplemented
	// TaskStateTested indicates the task has been tested and awaits review.
	TaskStateTested TaskState = state.TaskStateTested
	// TaskStateReviewed indicates the task has been reviewed and is merge-ready.
	TaskStateReviewed TaskState = state.TaskStateReviewed
	// TaskStateMergeable indicates the task is ready to be merged.
	TaskStateMergeable TaskState = state.TaskStateMergeable
	// TaskStateMerged indicates the task has been merged into main.
	TaskStateMerged TaskState = state.TaskStateMerged
	// TaskStateBlocked indicates the task cannot proceed without intervention.
	TaskStateBlocked TaskState = state.TaskStateBlocked
	// TaskStateConflict indicates the task has a merge or execution conflict.
	TaskStateConflict TaskState = state.TaskStateConflict
	// TaskStateResolved indicates a previously conflicted task has been resolved.
	TaskStateResolved TaskState = state.TaskStateResolved
	// Backwards compatibility aliases
	TaskStateOpen   TaskState = TaskStateTriaged
	TaskStateWorked TaskState = TaskStateImplemented
	TaskStateDone   TaskState = TaskStateMerged
)

type TransitionAuditor

type TransitionAuditor interface {
	LogTaskTransition(taskID string, role string, from string, to string) error
}

TransitionAuditor records task lifecycle transitions for audit logging.

type WriteLock

type WriteLock struct {
	// contains filtered or unexported fields
}

WriteLock is an exported handle for a held task index write lock.

func AcquireWriteLock

func AcquireWriteLock(path string) (*WriteLock, error)

AcquireWriteLock acquires an exclusive advisory write lock for the task index at path.

func (*WriteLock) Release

func (lock *WriteLock) Release() error

Release unlocks and closes the underlying lock file.