query

type Finding ¶

type Finding struct {
	Severity    Severity
	Category    string
	Observation string
}

Finding is a single observation from pre-flight validation.

type LintQuery ¶

type LintQuery struct {
	Graph *model.Graph
}

LintQuery captures intent to surface graph integrity issues.

type LintResult ¶

type LintResult struct {
	Entries     []*model.Entry
	TotalIssues int
}

LintResult is the structured output of a LintQuery: every entry that has at least one warning, plus the total warning count for convenience.

type ListQuery ¶

type ListQuery struct {
	Graph  *model.Graph
	Filter model.GraphFilter
}

ListQuery captures intent to filter graph entries.

type ListResult ¶

type ListResult struct {
	Graph   *model.Graph // needed to render derived attributes like status
	Entries []*model.Entry
}

ListResult is the structured output of a ListQuery.

type ParticipantGroup ¶ added in v0.3.0

type ParticipantGroup struct {
	Actor *model.Entry   // the active actor head (kind: actor signal)
	Roles []*model.Entry // derived-active roles whose cascade resolves to this actor's chain
}

ParticipantGroup couples an active actor head with its derived-active role decisions for the status Participants block per plan d-cpt-d34 AC 15. Grouping is materialized in the finder so the presenter stays a pure view layer.

type PreflightQuery ¶

type PreflightQuery struct {
	Entry   *model.Entry
	Graph   *model.Graph
	Model   string        // LLM model identifier (e.g. "claude-haiku-4-5-20251001")
	Timeout time.Duration // hard timeout for the validator call
}

PreflightQuery captures intent to validate an entry against the graph using the pre-flight LLM validator. Pure read — no side effects of its own; the runner dependency injected into the finder handles the LLM call.

type PreflightResult ¶

type PreflightResult struct {
	Findings []Finding
}

PreflightResult holds all findings from a pre-flight validator run. An empty Findings slice means the validator reported no findings.

func (r *PreflightResult) HasBlocking() bool

type SchemaStatusQuery ¶ added in v0.2.0

type SchemaStatusQuery struct {
	// SDDDir is the absolute path to the .sdd/ directory. The query resolves
	// meta.json relative to this path.
	SDDDir string

	// BinaryVersion is the running sdd binary's version string (semver for
	// releases, "dev" or similar for local builds). Dev builds bypass both
	// compatibility gates.
	BinaryVersion string

	// BinarySchemaVersion is the schema version the binary understands. The
	// call site passes model.CurrentGraphSchemaVersion.
	BinarySchemaVersion int
}

SchemaStatusQuery captures intent to evaluate the current binary against the graph's .sdd/meta.json compatibility fields.

The dispatcher-level write-gate runs this query before any command that mutates the graph; read commands bypass the query entirely.

type SchemaStatusResult ¶ added in v0.2.0

type SchemaStatusResult struct {
	// MetaExists is false when .sdd/meta.json is not present on disk. In
	// that case Meta is nil and Compatibility is considered compatible (an
	// uninitialized graph will be set up on the next init).
	MetaExists bool

	// Meta is the parsed contents of .sdd/meta.json when MetaExists is true.
	Meta *model.SchemaMeta

	// Compatibility is the result of checking Meta against the binary's
	// version and schema version. Always populated (with Compatible = true)
	// when MetaExists is false.
	Compatibility model.CompatibilityResult
}

SchemaStatusResult reports whether the binary is permitted to proceed and, when !Compatibility.Compatible, why.

type Severity ¶

type Severity string

Severity classifies a pre-flight finding. The tooling layer decides what to block on (currently: only SeverityHigh blocks); templates describe severity in purely semantic terms and never name a threshold.

const (
	SeverityHigh   Severity = "high"
	SeverityMedium Severity = "medium"
	SeverityLow    Severity = "low"
)

type ShowGroup ¶

type ShowGroup struct {
	Primary    *model.Entry
	Upstream   []model.ShowTreeItem
	Downstream []model.ShowTreeItem
}

ShowGroup is one primary's full tree: the primary entry, its upstream chain, and its downstream chain. Multiple groups are joined with separators.

type ShowQuery ¶

type ShowQuery struct {
	Graph      *model.Graph
	IDs        []string
	MaxDepth   int  // depth limit for upstream/downstream expansion; 0 = no expansion
	Downstream bool // include downstream entries (refd-by, closed-by, superseded-by)
}

ShowQuery captures intent to render a set of entries with their reference chains. Upstream is always included; downstream requires opt-in.

type ShowResult ¶

type ShowResult struct {
	Graph  *model.Graph // needed to render derived attributes like status
	Groups []ShowGroup
}

ShowResult is the structured output for a ShowQuery — one group per primary.

type SkillStatusEntry ¶ added in v0.2.0

type SkillStatusEntry struct {
	Skill    string
	RelPath  string
	AbsPath  string
	Status   model.SkillInstallStatus
	Embedded model.SkillBundleEntry
	// Installed is the parsed on-disk copy. Nil when Status = Missing.
	Installed *model.SkillFile
}

SkillStatusEntry carries the inputs a handler needs to decide whether (and how) to write the file: the embedded source, the parsed on-disk copy (nil if missing), and the computed status classification.

type SkillStatusQuery ¶ added in v0.2.0

type SkillStatusQuery struct {
	Target   model.AgentTarget
	Scope    model.Scope
	RepoRoot string // required for ScopeProject
	UserHome string // required for ScopeUser
}

SkillStatusQuery captures intent to read the install state of the embedded skill bundle against a target agent's skill directory.

type SkillStatusResult ¶ added in v0.2.0

type SkillStatusResult struct {
	// InstallDir is the resolved absolute directory where skills install
	// for this target + scope combination.
	InstallDir string

	// Entries is one row per embedded skill file.
	Entries []SkillStatusEntry
}

SkillStatusResult is a per-entry snapshot of the bundle compared to disk.

type StatusQuery ¶

type StatusQuery struct {
	Graph          *model.Graph
	RecentDone     int // how many recent kind: done signals to include (default 10)
	RecentInsights int // how many recent kind: insight signals to include (default 10)
}

StatusQuery captures intent to summarise current graph state.

type StatusResult ¶

type StatusResult struct {
	Graph            *model.Graph // for top-line counts (entries, decisions, signals)
	LocalParticipant string       // canonical from config; empty means "not configured"
	Language         string       // configured graph language (locale code); empty means English default
	Aspirations      []*model.Entry
	Contracts        []*model.Entry
	Plans            []*model.Entry
	Activities       []*model.Entry
	Directives       []*model.Entry
	Open             []*model.Entry // kind: gap and kind: question signals (the actionable set)
	Insights         []*model.Entry // recent kind: insight signals
	Recent           []*model.Entry // recent kind: done signals
	Participants     []ParticipantGroup
}

StatusResult is the structured snapshot of graph state for the status view. Each decision kind surfaces in its own section — Aspirations guide, Contracts bound, Plans carry multi-step scope with ACs, Activities capture THAT-shaped commitments that specific work happens, Directives are the WHAT-shaped choices. On the signal side, Open carries the closure-gated attention set (gap + question), Insights and Recent are truncated activity streams.

LocalParticipant surfaces the canonical participant name from .sdd/config.local.yaml so agents reading the status header see ground truth without inferring from entries (which may contain drift).

Language surfaces the configured graph language (locale code) from .sdd/config.yaml so the /sdd skill knows at session start whether to load a translation vocabulary and author entries in the configured language. Empty means English (default).

type SyncStatusQuery ¶ added in v0.3.0

type SyncStatusQuery struct {
	// SDDDir is the .sdd/ directory where the last-fetch marker lives.
	SDDDir string
	// RespectCooldown, when true, short-circuits the query with a Skipped
	// state if the last fetch is within the configured cooldown window.
	// When false the fetch runs regardless — useful for callers invoked
	// by an explicit user action rather than incidental to a command.
	RespectCooldown bool
}

SyncStatusQuery captures intent to check whether the local graph is in sync with the upstream branch. Processing involves a (potentially rate-limited) git fetch and several read-only git plumbing calls; the side effect of touching the last-fetch marker is considered internal bookkeeping rather than a domain mutation, matching the PreflightQuery precedent where an LLM call is embedded in a read-intent query.

type WIPListQuery ¶

type WIPListQuery struct {
	GraphDir string
}

WIPListQuery captures intent to list active WIP markers.

type WIPListResult ¶

type WIPListResult struct {
	Markers []*model.WIPMarker
}

WIPListResult is the structured output of a WIPListQuery.