core

package
v1.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 29, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var TerminalStatuses = []string{"done", "accepted", "archived", "shipped", "abandoned", "rejected"}

TerminalStatuses lists the artifact statuses that satisfy the downward blocking cascade check. A parent may only move to a terminal status when all of its children are in one of these states.

Functions 

func AddArtifactLink(ctx context.Context, ws *Workspace, sourceID, targetID, linkType string) error

AddArtifactLink persists an outgoing semantic link to Markdown first and then the SQLite cache.

func AddItemToShipment 

func AddItemToShipment(ctx context.Context, ws *Workspace, shipmentID, itemID string) error

AddItemToShipment associates an artifact ID with a shipment. The item must not already belong to another active shipment.

Worker: Check the item is not already assigned to another shipment (return ErrItemAlreadyAssigned if so), append the item ID to the shipment's items list in frontmatter, rewrite the file atomically, and upsert into the database. Emit slog.Debug for item association and events.jsonl record.

func AddStashEntry 

func AddStashEntry(ctx context.Context, ws *Workspace, kind, priority, text string) (*stash.Entry, error)

AddStashEntry appends a new active entry to the stash file and indexes it.

func ApplyFieldDefaults 

func ApplyFieldDefaults(artifact *models.Artifact, headerDef *config.HeaderDefConfig) error

ApplyFieldDefaults sets default values on artifact fields where the field is optional and the current value is the zero value.

func AutoArchive 

func AutoArchive(ctx context.Context, database *sql.DB, ws *Workspace, policy *ArchivePolicy) (int, error)

AutoArchive scans for items in terminal statuses past the retention window and archives them according to the policy.

func CascadeStatusUpdate 

func CascadeStatusUpdate(ctx context.Context, db *sql.DB, ws *Workspace, itemID string) error

CascadeStatusUpdate propagates a status change to parent artifacts up the hierarchy.

func CheckChildrenTerminal 

func CheckChildrenTerminal(ctx context.Context, database *sql.DB, parentID string, opts ...StatusOption) error

CheckChildrenTerminal verifies that every child of parentID has a terminal status. It returns a *ChildBlockingError when any non-terminal children are found, and nil when all children are terminal (or the parent has no children). Pass SkipChildCheck() to bypass this check entirely.

func ClaimShipment 

func ClaimShipment(ctx context.Context, ws *Workspace, shipmentID string) (*models.Artifact, error)

ClaimShipment moves a queued shipment to active and marks the included work scope active.

func ComputeParentStatus 

func ComputeParentStatus(ctx context.Context, db *sql.DB, parentID string) (models.ArtifactStatus, error)

ComputeParentStatus determines the rollup status for a parent artifact based on the statuses of its children.

func CreateArtifact 

func CreateArtifact(ctx context.Context, ws *Workspace, title string, artifactType string, opts ...Option) (*models.Artifact, error)

CreateArtifact creates a new artifact with atomic file write.

func CreateShipment 

func CreateShipment(ctx context.Context, ws *Workspace, title string, itemIDs []string) (*models.Artifact, error)

CreateShipment creates a new shipment artifact in the workspace with the given title and associates the specified item IDs with it. The shipment owns the items list as an aggregate root.

Worker: Create a new shipment Markdown artifact with YAML frontmatter containing the items list, set status to queued, generate ID with S prefix, write to queue directory, and upsert into the database index.

func DeleteArtifact added in v1.1.0 

func DeleteArtifact(ctx context.Context, ws *Workspace, id string) error

DeleteArtifact removes an artifact from both the filesystem and the SQLite index in a crash-safe order. The file is renamed to a temporary path (with ".deleting" inserted before the ".md" extension) before the DB delete, so that a crash between the rename and the DB operation leaves the artifact discoverable via rehydration rather than invisible to artifact scanning. If the DB delete fails, the renamed file is restored to its original path.

Callers that previously inlined db.DeleteItemCascade + os.Remove should migrate to this function to gain crash-safety guarantees.

func EnsureStashFile 

func EnsureStashFile(rootPath string) error

EnsureStashFile creates the canonical stash storage if it does not already exist.

func FindArtifactPath 

func FindArtifactPath(_ context.Context, ws *Workspace, id string) (string, error)

Returns the absolute file path or an error if not found.

func FormatHierarchicalID 

func FormatHierarchicalID(segment int, layout *config.QueueLayoutConfig) string

FormatHierarchicalID formats a numeric segment with zero-padding to match the queue layout naming convention (e.g., 1 → "001").

func GetShipment 

func GetShipment(ctx context.Context, ws *Workspace, shipmentID string) (*models.Artifact, error)

GetShipment retrieves a shipment artifact by ID from the workspace.

Worker: Look up the shipment by ID in the database index, parse the Markdown source file, and return the populated Artifact with items list in CustomFields.

func IsOrphan 

func IsOrphan(a *models.Artifact) bool

IsOrphan returns true when an item has no parent_id but its hierarchical ID suggests it originated under a parent (contains a dot separator).

func LevelForType 

func LevelForType(layout *config.QueueLayoutConfig, artifactType string) (int, error)

LevelForType returns the hierarchy level number for the given artifact type based on the QueueLayoutConfig mapping. Returns (0, error) when layout is nil.

func LinkCommit 

func LinkCommit(ctx context.Context, db *sql.DB, ws *Workspace, itemID, commitSHA, message, author string) error

LinkCommit associates a git commit SHA and author with an artifact in the SQLite index and appends a commit_tracked event to the item's JSONL log for rehydration durability.

func MoveArtifactFile 

func MoveArtifactFile(_ context.Context, storageRoot string, currentPath string, newDir string) (string, error)

MoveArtifactFile relocates an artifact file within the .backlogit storage root atomically.

func MoveInQueue 

func MoveInQueue(_ context.Context, _ *sql.DB, _ string, _ int) error

MoveInQueue updates the queue position record for an item. NOTE: Persistent ordinal reordering is not yet implemented. This operation is intentionally rejected so callers receive explicit feedback rather than a silent no-op.

func MoveShipmentStatus 

func MoveShipmentStatus(ctx context.Context, ws *Workspace, shipmentID string, newStatus ShipmentStatus) error

MoveShipmentStatus transitions a shipment's status. Valid transitions: queued->active, active->shipped, active->abandoned.

Worker: Validate the transition is legal, update the Markdown frontmatter, rewrite the file atomically, and upsert the new status into the database. Emit slog.Info for status transition and events.jsonl record.

func NextHierarchicalID 

func NextHierarchicalID(db *sql.DB, parentID string, layout *config.QueueLayoutConfig) (string, error)

NextHierarchicalID computes the next available ID at a given hierarchy level by querying the SQLite index for the maximum existing sibling ordinal. Root-level IDs must be purely numeric segments (e.g., "001", "002"); items with non-numeric IDs such as legacy prefix IDs ("T001", "BUG-3") are excluded from the ordinal computation.

func NextID 

func NextID(ctx context.Context, db *sql.DB, artifactType string, typeCfg *config.ArtifactTypeConfig) (int, error)

NextID queries for the next sequential artifact ID.

func NextTypedHierarchicalID 

func NextTypedHierarchicalID(
	ctx context.Context,
	db *sql.DB,
	parentID string,
	artifactType string,
	typeCfg *config.ArtifactTypeConfig,
	layout *config.QueueLayoutConfig,
) (string, error)

NextTypedHierarchicalID computes the next available typed hierarchical ID for the given artifact type and parent.

func ParseHierarchicalID 

func ParseHierarchicalID(id string) ([]int, error)

ParseHierarchicalID splits a hierarchical ID (e.g., "001.002.003") into its component level segments as integers.

func ReconcileCompletionScope 

func ReconcileCompletionScope(ctx context.Context, ws *Workspace, parentID string) error

ReconcileCompletionScope enforces completion consistency for a done parent:

  1. Returns an error if the parent artifact is not in done status.
  2. Recursively marks every queued or active descendant as done.

func RelocateArtifactFile 

func RelocateArtifactFile(ctx context.Context, ws *Workspace, artifactType, artifactID, newStatus string) (string, error)

RelocateArtifactFile moves an artifact's Markdown file from its current location to the directory mapped by the new (type, status) pair in registry.yaml. artifactType is passed by the caller to avoid a DB lookup when the in-memory artifact is already available, keeping this function DB-cache-independent. 

func RemoveArtifactLink(ctx context.Context, ws *Workspace, sourceID, targetID, linkType string) error

RemoveArtifactLink removes an outgoing semantic link from Markdown first and then the SQLite cache.

func RemoveStashEntry 

func RemoveStashEntry(ctx context.Context, ws *Workspace, stashID string) (*stash.Entry, error)

RemoveStashEntry permanently removes an active stash entry by ID. The entry is removed from the JSONL file and marked as removed in the DB index.

func RenderCommandMapMarkdown 

func RenderCommandMapMarkdown(catalog *MetadataCatalog) string

RenderCommandMapMarkdown renders the unified command map as Markdown for agent caching.

func ResolveFileName 

func ResolveFileName(cfg *config.ArtifactTypeConfig, artifactID string, title string, maxSlugLen int) string

ResolveFileName generates the on-disk filename stem for an artifact. When no file_name_format is configured, the stable artifact ID is used.

func ResolveHierarchicalPath 

func ResolveHierarchicalPath(layout *config.QueueLayoutConfig, parentID string, artifactType string) (string, error)

ResolveHierarchicalPath determines the target file path for a new artifact within the hierarchical queue layout based on its parent ID and artifact type.

func ResolveName 

func ResolveName(cfg *config.ArtifactTypeConfig, title string, nextID int, maxSlugLen int) string

ResolveName generates an artifact filename from the naming template.

func ResolveTargetDir 

func ResolveTargetDir(registry *config.RegistryConfig, artifactType string, status string) string

ResolveTargetDir determines the filesystem directory for an artifact.

func ReturnBlockedItem 

func ReturnBlockedItem(ctx context.Context, ws *Workspace, shipmentID, itemID, reason string) error

ReturnBlockedItem removes an item from shipment and sets its status to blocked with a reason. This is an explicit operation, not a side effect.

Worker: Remove the item ID from the shipment's items list, set the item's status to blocked, append a blocked_reason field to the item's frontmatter, rewrite both files atomically, and emit slog.Info + events.jsonl for the return. Return ErrCannotReturnItem if the item is not in this shipment.

func RollbackMigration 

func RollbackMigration(ws *Workspace) error

RollbackMigration reverses a previous migration using the state file (.backlogit/.migration-state) to restore the pre-migration layout.

func SafeResolve 

func SafeResolve(workspaceRoot, target string) (string, error)

SafeResolve returns an absolute path within the workspace root or an error if the target escapes the workspace boundary.

func Slugify 

func Slugify(title string, maxLen int) string

Slugify converts a title to a lowercase kebab-case slug.

func StashFilePath 

func StashFilePath(rootPath string) string

StashFilePath returns the canonical hidden stash file path for a workspace root.

func TranslateExternalMap 

func TranslateExternalMap(fieldConfig *config.FieldConfig, value any) (any, error)

TranslateExternalMap converts a local field value to its external representation.

func UnarchiveItem 

func UnarchiveItem(ctx context.Context, database *sql.DB, ws *Workspace, itemID string) error

UnarchiveItem restores an artifact from the archive back to its original path.

func UpdateArtifact 

func UpdateArtifact(ctx context.Context, ws *Workspace, id string, updates map[string]any) (*models.Artifact, error)

UpdateArtifact updates an existing artifact's fields.

func ValidateArtifactFields 

func ValidateArtifactFields(artifact *models.Artifact, headerDef *config.HeaderDefConfig) error

ValidateArtifactFields checks that all required fields for the artifact's type are present and valid according to the header-def.yaml field definitions.

func ValidateFields 

func ValidateFields(fieldConfigs map[string]*config.FieldConfig, fields map[string]any) error

ValidateFields checks custom field values against their configured types.

func ValidateTransition 

func ValidateTransition(cfg *StatusConfig, artifactType, currentStatus, newStatus string) error

ValidateTransition checks whether moving from currentStatus to newStatus is allowed for the given artifact type.

func VerifyPostShipConsistency 

func VerifyPostShipConsistency(_ context.Context, ws *Workspace, archivedIDs []string) error

VerifyPostShipConsistency verifies that all items in archivedIDs are absent from non-archive workspace directories. It returns an error listing any stale artifact IDs found, indicating a partial or failed archive operation.

func WorkspaceLogsRoot 

func WorkspaceLogsRoot(rootPath string) string

WorkspaceLogsRoot returns the .backlogit\logs directory for a workspace root.

func WorkspaceStorageRoot 

func WorkspaceStorageRoot(rootPath string) string

WorkspaceStorageRoot returns the .backlogit directory for a workspace root.

func WriteArtifactFile 

func WriteArtifactFile(artifact *models.Artifact, filePath string) error

WriteArtifactFile atomically writes an artifact to the given file path.

func WriteCommandMap 

func WriteCommandMap(workspaceRoot, targetPath string, catalog *MetadataCatalog, format string) (string, error)

WriteCommandMap writes a catalog snapshot to a workspace-relative path.

Types

type AdoptItemResult 

type AdoptItemResult struct {
	ItemID               string   `json:"item_id"`
	NewID                string   `json:"new_id,omitempty"`
	NewParentID          string   `json:"new_parent_id"`
	OriginFeature        string   `json:"origin_feature,omitempty"`
	IsOrphan             bool     `json:"was_orphan"`
	RewrittenArtifactIDs []string `json:"rewritten_artifact_ids,omitempty"`
}

AdoptItemResult summarizes the outcome of an adopt operation.

func AdoptItem 

func AdoptItem(ctx context.Context, ws *Workspace, itemID, newParentID string) (*AdoptItemResult, error)

AdoptItem sets an orphaned or unparented item's parent_id to a new feature, atomically rewriting its hierarchical ID, renaming files, updating dependency and link edges, and syncing the index. The return value includes the new ID so callers can update their own references. Adoption rewrites internal backlogit references only; external references are the caller's responsibility.

type ArchiveOpt 

type ArchiveOpt func(*archiveConfig)

ArchiveOpt configures optional behavior for ArchiveItem.

func WithCommitSHA 

func WithCommitSHA(sha string) ArchiveOpt

WithCommitSHA attaches a git commit SHA to the archive event for traceability.

func WithTopLevel 

func WithTopLevel(topLevel bool) ArchiveOpt

WithTopLevel sets whether this archive call is a top-level operation. When false, post-hooks that emit external events (event emission, webhooks) skip to prevent duplicate notifications from nested operations. Default is true when not specified.

type ArchivePolicy 

type ArchivePolicy struct {
	TerminalStatuses []string `json:"terminal_statuses" yaml:"terminal_statuses"`
	RetentionDays    int      `json:"retention_days" yaml:"retention_days"`
	ArchiveDir       string   `json:"archive_dir" yaml:"archive_dir"`
}

ArchivePolicy defines rules for automatic archiving of completed artifacts.

type ArchiveRecord 

type ArchiveRecord struct {
	ID           string    `json:"id"`
	ArchivedAt   time.Time `json:"archived_at"`
	ArchivedBy   string    `json:"archived_by"`
	OriginalPath string    `json:"original_path"`
	ArchivePath  string    `json:"archive_path"`
}

ArchiveRecord tracks the metadata for a single archived artifact.

func ArchiveItem 

func ArchiveItem(ctx context.Context, database *sql.DB, ws *Workspace, itemID string, opts ...ArchiveOpt) (*ArchiveRecord, error)

ArchiveItem moves an artifact from its active directory to the archive directory, updating the SQLite index and storing the original path in frontmatter for restoration.

type ArchivedStashEntry 

type ArchivedStashEntry struct {
	ID                  string     `json:"id"`
	Priority            string     `json:"priority"`
	Kind                string     `json:"kind"`
	Text                string     `json:"text"`
	CreatedAt           *time.Time `json:"created_at,omitempty"`
	DeliberationID      string     `json:"deliberation_id,omitempty"`
	RemovedAt           time.Time  `json:"removed_at"`
	RemovalReason       string     `json:"removal_reason"`
	HarvestedArtifactID string     `json:"harvested_artifact_id,omitempty"`
}

ArchivedStashEntry is the record written to .backlogit/archive/stash.jsonl when an active stash entry is removed or harvested into a backlog artifact.

type BulkUpdateResult 

type BulkUpdateResult struct {
	Succeeded int      `json:"succeeded"`
	Failed    []string `json:"failed"`
	Err       error    `json:"error,omitempty"`
}

BulkUpdateResult summarises the outcome of a BulkUpdateStatus operation. Succeeded counts items whose Markdown file and DB index were both updated. Failed lists item IDs that could not be updated (e.g., missing Markdown file). Err carries a non-nil value only for workspace-level failures that prevent the batch from starting at all (nil workspace, etc.).

func BulkUpdateStatus 

func BulkUpdateStatus(ctx context.Context, _ *sql.DB, ws *Workspace, itemIDs []string, newStatus string) (*BulkUpdateResult, error)

BulkUpdateStatus changes the status of multiple items using a Markdown-first write path. Each item is updated independently: failures are collected in BulkUpdateResult.Failed rather than aborting the entire batch. The SQLite index is updated only after the Markdown file has been successfully written.

type ChildBlockingError 

type ChildBlockingError struct {
	ParentID string
	Children []ChildStatus
}

ChildBlockingError is returned when a parent artifact cannot move to a terminal status because one or more of its children are still in progress.

func (*ChildBlockingError) Error 

func (e *ChildBlockingError) Error() string

Error implements the error interface.

func (*ChildBlockingError) Is 

func (e *ChildBlockingError) Is(target error) bool

Is enables errors.Is matching against ErrChildrenNotTerminal.

type ChildStatus 

type ChildStatus struct {
	ID     string `json:"id"`
	Status string `json:"status"`
}

ChildStatus captures the ID and current status of a non-terminal child.

type CommandInfo 

type CommandInfo struct {
	Command     string   `json:"command"`
	Use         string   `json:"use"`
	Short       string   `json:"short,omitempty"`
	Long        string   `json:"long,omitempty"`
	Example     string   `json:"example,omitempty"`
	Subcommands []string `json:"subcommands,omitempty"`
}

CommandInfo describes a CLI command for agent discovery and caching.

func DescribeCLICommands 

func DescribeCLICommands(root *cobra.Command) []CommandInfo

DescribeCLICommands flattens a cobra command tree into agent-readable command info.

type CommitLinkInfo 

type CommitLinkInfo struct {
	ItemID    string `json:"item_id"`
	CommitSHA string `json:"commit_sha"`
	Message   string `json:"message"`
	Author    string `json:"author"`
}

CommitLinkInfo contains the metadata linking an artifact to a git commit.

func AutoLinkCommits 

func AutoLinkCommits(ctx context.Context, db *sql.DB, ws *Workspace, depth int) ([]CommitLinkInfo, error)

AutoLinkCommits scans recent git log messages for artifact ID references and creates links automatically. depth=0 returns immediately with no links. 

func GetCommitLinks(ctx context.Context, db *sql.DB, itemID string) ([]CommitLinkInfo, error)

GetCommitLinks retrieves all commit associations for a given artifact.

type CommitMetadata 

type CommitMetadata struct {
	SHA     string `json:"sha,omitempty"`
	Message string `json:"message,omitempty"`
	Author  string `json:"author,omitempty"`
}

CommitMetadata captures the merge or release commit that closed a shipment.

type CompactQueueGroup 

type CompactQueueGroup struct {
	Label string                   `json:"label"`
	Items []models.CompactArtifact `json:"items"`
	Count int                      `json:"count"`
}

CompactQueueGroup mirrors QueueGroup but with CompactArtifact items.

type CompactQueueView 

type CompactQueueView struct {
	Items      []models.CompactArtifact `json:"items"`
	TotalCount int                      `json:"total_count"`
	GroupedBy  string                   `json:"grouped_by,omitempty"`
	Groups     []CompactQueueGroup      `json:"groups,omitempty"`
}

CompactQueueView is a token-efficient projection of QueueView, replacing full Artifact slices with CompactArtifact slices for list and queue responses.

func CompactView 

func CompactView(v *QueueView) *CompactQueueView

CompactView converts a QueueView into its compact projection.

type DoctorFinding 

type DoctorFinding struct {
	Type        DoctorFindingType `json:"type"`
	ArtifactID  string            `json:"artifact_id"`
	Description string            `json:"description"`
}

DoctorFinding describes a single integrity issue detected by Doctor.

type DoctorFindingType 

type DoctorFindingType string

DoctorFindingType classifies an integrity issue found by Doctor. 

const (
	// FindingOrphanedArtifact indicates a level-2+ artifact with no parent_id
	// and no evidence of intentional orphaning (e.g., returned_to_backlog event).
	FindingOrphanedArtifact DoctorFindingType = "orphaned_artifact"

	// FindingDuplicateID indicates the same artifact ID appears in two or more
	// workspace directories simultaneously (e.g., both queue and archive, or
	// across multiple registry-routed directories).
	FindingDuplicateID DoctorFindingType = "duplicate_id"
)

type DoctorOptions 

type DoctorOptions struct {
	// CheckOrphans enables the orphaned-artifact check.
	CheckOrphans bool
	// CheckDuplicates enables the queue/archive duplicate-ID check.
	CheckDuplicates bool
}

DoctorOptions controls which checks Doctor performs.

type DoctorReport 

type DoctorReport struct {
	Findings  []DoctorFinding `json:"findings"`
	CheckedAt time.Time       `json:"checked_at"`
}

DoctorReport summarises the results of a Doctor run.

func Doctor 

func Doctor(ctx context.Context, ws *Workspace, opts *DoctorOptions) (*DoctorReport, error)

Doctor scans the workspace for structural integrity issues and returns a DoctorReport summarising any findings. An empty Findings slice indicates the workspace is clean.

type EditStashOptions 

type EditStashOptions struct {
	Text     string `json:"text,omitempty"`
	Kind     string `json:"kind,omitempty"`
	Priority string `json:"priority,omitempty"`
}

EditStashOptions controls which fields to update on a stash entry.

type FetchStashOptions 

type FetchStashOptions struct {
	Priority        string `json:"priority,omitempty"`
	Kind            string `json:"kind,omitempty"`
	GroupByPriority bool   `json:"group_by_priority,omitempty"`
	Limit           int    `json:"limit,omitempty"` // max entries to return (0 = no limit)
}

FetchStashOptions controls stash fetch filtering and grouping.

type FetchedStashResult 

type FetchedStashResult struct {
	Entries           []StashEntryView            `json:"entries"`
	GroupBy           string                      `json:"group_by,omitempty"`
	EntriesByPriority map[string][]StashEntryView `json:"entries_by_priority,omitempty"`
}

FetchedStashResult describes fetched stash entries, with optional grouping.

func FetchStash 

func FetchStash(ctx context.Context, ws *Workspace, opts FetchStashOptions) (*FetchedStashResult, error)

FetchStash returns the currently active stash entries.

type HarvestStashOptions 

type HarvestStashOptions struct {
	StashID      string `json:"stash_id,omitempty"`
	Priority     string `json:"priority,omitempty"`
	ArtifactType string `json:"artifact_type"`
	Title        string `json:"title,omitempty"`
	Description  string `json:"description,omitempty"`
	Status       string `json:"status,omitempty"`
	ParentID     string `json:"parent_id,omitempty"`
}

HarvestStashOptions controls single-entry and batch priority harvest behavior.

type HarvestedStashBatchResult 

type HarvestedStashBatchResult struct {
	Priority string                 `json:"priority"`
	Results  []HarvestedStashResult `json:"results"`
}

HarvestedStashBatchResult describes a priority-based stash harvest operation.

func HarvestStashByPriority 

func HarvestStashByPriority(ctx context.Context, ws *Workspace, opts HarvestStashOptions) (*HarvestedStashBatchResult, error)

HarvestStashByPriority harvests all active stash entries matching a priority. It acquires the stash lock once for the entire batch to prevent TOCTOU races between reading the entry list and harvesting individual entries.

type HarvestedStashResult 

type HarvestedStashResult struct {
	Entry    StashEntryView `json:"entry"`
	Artifact any            `json:"artifact"`
}

HarvestedStashResult describes a stash harvest operation.

func HarvestStashEntry 

func HarvestStashEntry(ctx context.Context, ws *Workspace, harvestOpts HarvestStashOptions) (*HarvestedStashResult, error)

HarvestStashEntry creates a backlogit artifact from a stash entry, links it, and removes the active stash line from the hidden stash file.

type HierarchyLevel 

type HierarchyLevel = config.HierarchyLevel

HierarchyLevel is an alias for config.HierarchyLevel, kept for backward compatibility.

type MetadataCatalog 

type MetadataCatalog struct {
	Workspace     MetadataWorkspaceInfo `json:"workspace"`
	ArtifactTypes []WITMetadata         `json:"artifact_types"`
	Registry      []MetadataRoute       `json:"registry"`
	Templates     []TemplateInfo        `json:"templates"`
	Migration     *MetadataMigration    `json:"migration,omitempty"`
	Stash         MetadataStashInfo     `json:"stash"`
	CLI           []CommandInfo         `json:"cli"`
	MCPTools      []ToolInfo            `json:"mcp_tools"`
}

MetadataCatalog is the unified agent-facing metadata view of a workspace.

func BuildMetadataCatalog 

func BuildMetadataCatalog(
	ws *Workspace,
	templateInfos []TemplateInfo,
	registry *config.RegistryConfig,
	migration *config.MigrationConfig,
	cliRoot *cobra.Command,
	mcpTools []ToolInfo,
) (*MetadataCatalog, error)

BuildMetadataCatalog assembles a unified workspace metadata catalog for agents.

type MetadataMigration 

type MetadataMigration struct {
	DefaultLayout   string                       `json:"default_layout"`
	DocumentClasses []config.DocumentClassConfig `json:"document_classes"`
	SourcePaths     []config.SourcePathConfig    `json:"source_paths"`
}

MetadataMigration summarizes configured migration behavior.

type MetadataRoute 

type MetadataRoute struct {
	Path   string   `json:"path"`
	Status []string `json:"status,omitempty"`
	Types  []string `json:"types,omitempty"`
}

MetadataRoute describes a single registry routing rule.

type MetadataStashInfo 

type MetadataStashInfo struct {
	Path                 string   `json:"path"`
	SupportedKinds       []string `json:"supported_kinds"`
	SupportedPriorities  []string `json:"supported_priorities"`
	DefaultPriority      string   `json:"default_priority"`
	SupportsDeliberation bool     `json:"supports_deliberation"`
	DeliberationType     string   `json:"deliberation_type,omitempty"`
}

MetadataStashInfo describes stash conventions and supported kinds.

type MetadataWorkspaceInfo 

type MetadataWorkspaceInfo struct {
	RootPath      string `json:"root_path"`
	StorageRoot   string `json:"storage_root"`
	QueuePath     string `json:"queue_path"`
	ArchivePath   string `json:"archive_path"`
	LogsPath      string `json:"logs_path"`
	DatabasePath  string `json:"database_path"`
	StashPath     string `json:"stash_path"`
	TemplatesPath string `json:"templates_path"`
	QueueRootDir  string `json:"queue_root_dir"`
}

MetadataWorkspaceInfo describes key workspace paths and layout.

type MigrateCustomFieldLinksResult 

type MigrateCustomFieldLinksResult struct {
	// Scanned is the number of artifact files examined.
	Scanned int `json:"scanned"`
	// Migrated is the number of item_links rows inserted.
	Migrated int `json:"migrated"`
	// Skipped is the number of fields whose target was not a resolvable item ID.
	Skipped int `json:"skipped"`
}

MigrateCustomFieldLinksResult summarises the outcome of a custom-field link migration run. 

func MigrateCustomFieldLinks(ctx context.Context, ws *Workspace) (*MigrateCustomFieldLinksResult, error)

MigrateCustomFieldLinks scans all artifacts in the workspace and converts known relationship custom_fields into item_links rows:

  • linked_deliberation_id → link_type "informs" (skipped when target is not an item)
  • linked_stash_id → always skipped (stash IDs are not item IDs)
  • source_stash_id → always skipped (stash IDs are not item IDs)

Original custom_fields values are preserved as read-only provenance and are not removed by this migration. AddLink uses INSERT OR IGNORE so re-running is idempotent and does not create duplicate rows.

type MigrateDBOnlyLinksResult 

type MigrateDBOnlyLinksResult struct {
	// Checked is the number of (source, target, type) triples examined.
	Checked int `json:"checked"`
	// Written is the number of link entries written to Markdown frontmatter.
	Written int `json:"written"`
	// Skipped is the number of links skipped because the source file was not
	// found or could not be written.
	Skipped int `json:"skipped"`
}

MigrateDBOnlyLinksResult summarises the outcome of a DB-only links migration run. 

func MigrateDBOnlyLinks(ctx context.Context, ws *Workspace) (*MigrateDBOnlyLinksResult, error)

MigrateDBOnlyLinks reads every row in item_links and writes any link that is not already reflected in the source artifact's Markdown frontmatter. This is a startup migration guard that must be called BEFORE the first db.Rehydrate invocation that clears item_links, ensuring that no links accumulated in the old SQLite-only model are silently dropped during the transition to Markdown-first link storage.

The function is idempotent and best-effort: source artifacts that cannot be located on disk are logged at Debug level and counted as skipped. Links already present in Markdown frontmatter are never duplicated.

type MigrationReport 

type MigrationReport struct {
	FilesMoved   int
	FilesSkipped int
	Errors       []string
	DryRun       bool
}

MigrationReport summarizes the results of a flat-to-hierarchical migration.

func MigrateFlatToHierarchical 

func MigrateFlatToHierarchical(ws *Workspace, dryRun bool) (*MigrationReport, error)

MigrateFlatToHierarchical converts an existing flat per-type directory layout to the flat .backlogit/queue/ structure. When dryRun is true, no files are moved but the report reflects what would happen.

type Option 

type Option func(*createOptions)

Option configures artifact creation.

func WithAssignedTo 

func WithAssignedTo(user string) Option

WithAssignedTo sets the assigned user.

func WithCommit 

func WithCommit(commit string) Option

WithCommit sets the artifact commit hash.

func WithDependencies 

func WithDependencies(deps []string) Option

WithDependencies sets the artifact dependencies.

func WithDescription 

func WithDescription(desc string) Option

WithDescription sets the artifact description.

func WithFields 

func WithFields(fields map[string]any) Option

WithFields sets custom fields.

func WithLabels 

func WithLabels(labels []string) Option

WithLabels sets the artifact labels.

func WithOwner 

func WithOwner(owner string) Option

WithOwner sets the artifact owner.

func WithParent 

func WithParent(id string) Option

WithParent sets the parent artifact ID.

func WithPriority 

func WithPriority(priority string) Option

WithPriority sets the artifact priority.

func WithReferences 

func WithReferences(refs []string) Option

WithReferences sets the artifact references.

func WithSprint 

func WithSprint(id string) Option

WithSprint sets the sprint ID.

func WithStatus 

func WithStatus(status string) Option

WithStatus sets the initial status.

type QueueFilter 

type QueueFilter struct {
	Types       []string `json:"types,omitempty"`
	Statuses    []string `json:"statuses,omitempty"`
	ParentID    string   `json:"parent_id,omitempty"`
	Sprint      string   `json:"sprint,omitempty"`
	AssignedTo  string   `json:"assigned_to,omitempty"`
	Labels      []string `json:"labels,omitempty"`
	GroupBy     string   `json:"group_by,omitempty"`
	SortBy      string   `json:"sort_by,omitempty"`
	SortOrder   string   `json:"sort_order,omitempty"`
	Limit       int      `json:"limit,omitempty"`
	Offset      int      `json:"offset,omitempty"`
	OrphansOnly bool     `json:"orphans_only,omitempty"` // when true, return only orphaned items
}

QueueFilter defines the filter criteria for queue queries.

type QueueGroup 

type QueueGroup struct {
	Label string             `json:"label"`
	Items []*models.Artifact `json:"items"`
	Count int                `json:"count"`
}

QueueGroup represents a group of items within a queue view.

type QueueLayoutConfig 

type QueueLayoutConfig = config.QueueLayoutConfig

QueueLayoutConfig is an alias for config.QueueLayoutConfig, kept for backward compatibility.

type QueueView 

type QueueView struct {
	Items      []*models.Artifact `json:"items"`
	TotalCount int                `json:"total_count"`
	GroupedBy  string             `json:"grouped_by,omitempty"`
	Groups     []QueueGroup       `json:"groups,omitempty"`
}

QueueView represents a filtered, ordered view of the backlog queue.

func QueryQueue 

func QueryQueue(ctx context.Context, db *sql.DB, filter *QueueFilter) (*QueueView, error)

QueryQueue retrieves artifacts matching the filter criteria, with optional grouping.

type SectionInfo 

type SectionInfo struct {
	Name     string `json:"name"`
	Required bool   `json:"required"`
}

SectionInfo describes a single section within a template.

type ShipShipmentResult 

type ShipShipmentResult struct {
	ShipmentID     string   `json:"shipment_id"`
	ShipmentStatus string   `json:"shipment_status"`
	ArchivedIDs    []string `json:"archived_ids"`
	ReturnedIDs    []string `json:"returned_ids"`
	CommitSHA      string   `json:"commit_sha,omitempty"`
}

ShipShipmentResult summarizes shipment release hygiene actions.

func ShipShipment 

func ShipShipment(ctx context.Context, ws *Workspace, shipmentID string, commit *CommitMetadata) (*ShipShipmentResult, error)

ShipShipment closes a shipped scope, returns untouched descendants to backlog, archives the released artifacts, and records the closing commit in item logs.

type ShipmentStatus 

type ShipmentStatus string

ShipmentStatus represents the lifecycle state of a shipment. 

const (
	// ShipmentQueued indicates the shipment is created but not yet started.
	ShipmentQueued ShipmentStatus = "queued"
	// ShipmentActive indicates the shipment is in progress.
	ShipmentActive ShipmentStatus = "active"
	// ShipmentShipped indicates the shipment has been delivered.
	ShipmentShipped ShipmentStatus = "shipped"
	// ShipmentAbandoned indicates the shipment was cancelled.
	ShipmentAbandoned ShipmentStatus = "abandoned"
)

type StashEntryView 

type StashEntryView struct {
	ID             string           `json:"id"`
	Priority       string           `json:"priority"`
	DeliberationID string           `json:"deliberation_id,omitempty"`
	Kind           string           `json:"kind"`
	Text           string           `json:"text"`
	AgeDays        *int             `json:"age_days,omitempty"`
	Deliberation   *models.Artifact `json:"deliberation,omitempty"`
}

StashEntryView describes a stash entry plus any linked deliberation artifact.

func EditStashEntry 

func EditStashEntry(ctx context.Context, ws *Workspace, stashID string, opts EditStashOptions) (*StashEntryView, error)

EditStashEntry updates mutable fields of an active stash entry. Only non-empty option fields are applied.

func GetStashEntry 

func GetStashEntry(ctx context.Context, ws *Workspace, stashID string) (*StashEntryView, error)

GetStashEntry returns a single active stash entry enriched with any linked deliberation.

func LinkDeliberationToStashEntry 

func LinkDeliberationToStashEntry(ctx context.Context, ws *Workspace, stashID, deliberationID string) (*StashEntryView, error)

LinkDeliberationToStashEntrylinks an existing deliberation artifact to an active stash entry.

type StatusConfig 

type StatusConfig struct {
	ValidStatuses []string                          `json:"valid_statuses" yaml:"valid_statuses"`
	Transitions   []StatusTransitionRule            `json:"transitions"    yaml:"transitions"`
	TypeOverrides map[string][]StatusTransitionRule `json:"type_overrides,omitempty" yaml:"type_overrides,omitempty"`
}

StatusConfig holds the complete status configuration for the workspace.

type StatusOption 

type StatusOption func(*statusCheckOptions)

StatusOption configures optional behavior for status-change operations.

func SkipChildCheck 

func SkipChildCheck() StatusOption

SkipChildCheck returns a StatusOption that bypasses the child-terminal check during a status transition. Shipment automation uses this when releasing items in batch so it is not blocked by its own cascade logic.

type StatusTransitionRule 

type StatusTransitionRule struct {
	From string `json:"from" yaml:"from"`
	To   string `json:"to"   yaml:"to"`
}

StatusTransitionRule defines a valid state transition for an artifact type.

type TemplateInfo 

type TemplateInfo struct {
	TypeName    string        `json:"type_name"`
	DisplayName string        `json:"display_name"`
	Sections    []SectionInfo `json:"sections"`
}

TemplateInfo describes a registered template and its section metadata.

type ToolInfo 

type ToolInfo struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
}

ToolInfo describes an MCP tool for agent discovery and caching.

type WITDirectoryMeta 

type WITDirectoryMeta struct {
	Active  string `json:"active"`
	Archive string `json:"archive"`
}

WITDirectoryMeta describes the active and archive directories for a type.

type WITFieldMeta 

type WITFieldMeta struct {
	Type     string   `json:"type"`
	Values   []string `json:"values,omitempty"`
	Required bool     `json:"required"`
	Default  string   `json:"default,omitempty"`
}

WITFieldMeta describes a single field's metadata for agent consumption.

type WITMetadata 

type WITMetadata struct {
	TypeName        string                  `json:"type"`
	Prefix          string                  `json:"prefix,omitempty"`
	Description     string                  `json:"description"`
	HierarchyLevel  int                     `json:"hierarchy_level"`
	IDFormat        string                  `json:"id_format"`
	AllowedChildren []string                `json:"allowed_children,omitempty"`
	Fields          map[string]WITFieldMeta `json:"fields"`
	Sections        []WITSectionMeta        `json:"sections"`
	Relationships   []WITRelationship       `json:"relationships"`
	Directories     WITDirectoryMeta        `json:"directories"`
}

WITMetadata represents complete metadata for a work item type, merging data from header-def.yaml, template config, and workspace config.

func DescribeType 

func DescribeType(
	artifactType string,
	headerDef *config.HeaderDefConfig,
	templates []*config.TemplateConfig,
	layout *config.QueueLayoutConfig,
) (*WITMetadata, error)

DescribeType merges header-def, template, and workspace config to produce complete WIT metadata for a given artifact type.

func ListTypes 

func ListTypes(
	headerDef *config.HeaderDefConfig,
	templates []*config.TemplateConfig,
	layout *config.QueueLayoutConfig,
) ([]WITMetadata, error)

ListTypes returns a summary of all configured WIT types with their hierarchy levels and descriptions.

type WITRelationship 

type WITRelationship struct {
	RelatedType string `json:"related_type"`
	Relation    string `json:"relation"`
	Description string `json:"description"`
}

WITRelationship describes a relationship between WIT types.

type WITSectionMeta 

type WITSectionMeta struct {
	Name        string `json:"name"`
	Required    bool   `json:"required"`
	Description string `json:"description"`
}

WITSectionMeta describes a template section.

type Workspace 

type Workspace struct {
	RootPath  string
	Config    *config.WorkspaceConfig
	DB        *sql.DB
	HeaderDef *config.HeaderDefConfig
	Templates []*config.TemplateConfig
	// HookRunner dispatches lifecycle hooks. May be nil in tests that
	// construct Workspace{} directly; all call sites must nil-guard.
	HookRunner *hooks.HookRunner
	// Hooks holds the parsed hooks.yaml configuration.
	Hooks *config.HooksConfig
	// contains filtered or unexported fields
}

Workspace coordinates cross-store operations across Markdown, SQLite, and JSONL.

func NewWorkspace 

func NewWorkspace(ctx context.Context, rootPath string) (*Workspace, error)

NewWorkspace creates a workspace, loads config, opens DB, and ensures schema.

func (*Workspace) Close 

func (ws *Workspace) Close() error

Close drains any in-flight webhook dispatches and closes the database connection.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.