Documentation
¶
Overview ¶
Package contextbuild assembles deterministic context packages for agent sessions. A context package contains all information needed to work on a phase or RMI, ordered stable→volatile with provenance revisions. Go structs are the source of truth; JSON Schema is generated via invopop/jsonschema.
Design: TRD §15; origin: IDEATION_CHAT_CACHE-OPTIMIZATION.md.
Index ¶
- Constants
- func ContextPackageSchema() []byte
- func GenerateSchema() ([]byte, error)
- func PhaseHandoffSchema() []byte
- type AssignmentSection
- type Builder
- type ContextPackage
- type DependencyEdge
- type DerivedRepo
- type EvidenceEntry
- type EvidenceRef
- type HandoffData
- type HandoffSummary
- type InitiativeSection
- type PhaseHandoff
- type PhaseHandoffProjection
- type PhaseSection
- type ProgramSection
- type Provenance
- type RMIHandoffEntry
- type RMISection
- type RMISummary
- type Sections
- type SpecReference
- type StabilityClass
Constants ¶
const SchemaVersion = "1.0.0"
SchemaVersion is the current version of the context package schema.
Variables ¶
This section is empty.
Functions ¶
func ContextPackageSchema ¶
func ContextPackageSchema() []byte
ContextPackageSchema returns the embedded JSON Schema for ContextPackage.
func GenerateSchema ¶
GenerateSchema generates JSON Schema from the ContextPackage Go type. Run this to regenerate contextpackage.schema.json when types change:
go run -exec "sh -c" -<<'EOF'
package main
import (
"fmt"
"github.com/ProductBuildersHQ/prism-build/pkg/contextbuild"
)
func main() {
out, _ := contextbuild.GenerateSchema()
fmt.Println(string(out))
}
EOF
func PhaseHandoffSchema ¶
func PhaseHandoffSchema() []byte
PhaseHandoffSchema returns the embedded JSON Schema for PhaseHandoffProjection.
Types ¶
type AssignmentSection ¶
type AssignmentSection struct {
Stability StabilityClass `json:"stability"`
Provenance Provenance `json:"provenance"`
ID string `json:"id"`
RMIID string `json:"rmi_id"`
Worker string `json:"worker"`
Status string `json:"status"`
LeaseExpiresAt time.Time `json:"lease_expires_at"`
Workspace string `json:"workspace,omitempty"`
CreatedAt time.Time `json:"created_at"`
CompletedAt *time.Time `json:"completed_at,omitempty"`
// Handoff contains structured handoff state from prior sessions.
Handoff *HandoffData `json:"handoff,omitempty"`
// Evidence lists delivery evidence collected so far.
Evidence []EvidenceRef `json:"evidence,omitempty"`
}
AssignmentSection contains current assignment state.
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder assembles context packages from store data.
func NewBuilder ¶
NewBuilder creates a Builder backed by the given store. doltCommit is the current Dolt HEAD revision for provenance tracking.
func (*Builder) BuildForPhase ¶
BuildForPhase assembles a context package for an entire phase.
func (*Builder) BuildForRMI ¶
BuildForRMI assembles a context package for a specific RMI.
func (*Builder) BuildPhaseHandoff ¶
func (b *Builder) BuildPhaseHandoff(ctx context.Context, phaseID string) (*PhaseHandoffProjection, error)
BuildPhaseHandoff assembles a handoff projection for a phase.
type ContextPackage ¶
type ContextPackage struct {
// Version is the schema version for forwards compatibility.
Version string `json:"version"`
// TargetType is "phase" or "rmi".
TargetType string `json:"target_type"`
// TargetID is the phase ID or RMI ID this package is built for.
TargetID string `json:"target_id"`
// BuildTimestamp is when this package was assembled (operational metadata, last).
BuildTimestamp time.Time `json:"build_timestamp"`
// Sections contains the context data ordered by stability class.
Sections Sections `json:"sections"`
// DerivedRepos is the computed set of repositories relevant to this context.
DerivedRepos []DerivedRepo `json:"derived_repos"`
}
ContextPackage is the complete assembled context for a phase or RMI. All sections are ordered stable→volatile for optimal cache utilization.
func (*ContextPackage) RenderJSON ¶
func (p *ContextPackage) RenderJSON() ([]byte, error)
RenderJSON renders the context package as indented JSON.
func (*ContextPackage) RenderMarkdown ¶
func (p *ContextPackage) RenderMarkdown() string
RenderMarkdown renders the context package as Markdown.
type DependencyEdge ¶
type DependencyEdge struct {
SourceID string `json:"source_id"`
TargetID string `json:"target_id"`
Relationship string `json:"relationship"`
}
DependencyEdge represents a directed dependency between two RMIs.
type DerivedRepo ¶
type DerivedRepo struct {
// ID is the repository ID (e.g., github.com/org/repo).
ID string `json:"id"`
// Role indicates why this repo is included:
// "primary", "dependency_rmi", "repo_dependency", "explicit".
Role string `json:"role"`
// LocalPath is the absolute path on disk.
LocalPath string `json:"local_path,omitempty"`
// DefaultBranch is the repository's default branch.
DefaultBranch string `json:"default_branch"`
// SourceRMI is set when Role is "dependency_rmi" — the RMI that brought this repo in.
SourceRMI string `json:"source_rmi,omitempty"`
// SourceRepo is set when Role is "repo_dependency" — the repo that depends on this one.
SourceRepo string `json:"source_repo,omitempty"`
}
DerivedRepo is a repository in the computed context set.
type EvidenceEntry ¶
type EvidenceEntry struct {
RMIID string `json:"rmi_id"`
RMITitle string `json:"rmi_title"`
Type string `json:"type"`
Reference string `json:"reference"`
OccurredAt *time.Time `json:"occurred_at,omitempty"`
}
EvidenceEntry is a delivery evidence item with RMI context.
type EvidenceRef ¶
type EvidenceRef struct {
Type string `json:"type"`
Reference string `json:"reference"`
OccurredAt *time.Time `json:"occurred_at,omitempty"`
}
EvidenceRef is a compact reference to delivery evidence.
type HandoffData ¶
type HandoffData struct {
Completed []string `json:"completed,omitempty"`
Remaining []string `json:"remaining,omitempty"`
Decisions []string `json:"decisions,omitempty"`
NextAction string `json:"next_action,omitempty"`
}
HandoffData carries compact state for session continuity.
type HandoffSummary ¶
type HandoffSummary struct {
TotalRMIs int `json:"total_rmis"`
CompletedRMIs int `json:"completed_rmis"`
RequiredRMIs int `json:"required_rmis"`
RequiredDone int `json:"required_done"`
InProgress int `json:"in_progress"`
Blocked int `json:"blocked"`
}
HandoffSummary contains aggregated statistics for the phase.
type InitiativeSection ¶
type InitiativeSection struct {
Stability StabilityClass `json:"stability"`
Provenance Provenance `json:"provenance"`
ID string `json:"id"`
Title string `json:"title"`
Description string `json:"description,omitempty"`
Status string `json:"status"`
Priority string `json:"priority,omitempty"`
HomeRepo string `json:"home_repo,omitempty"`
Specs map[string]string `json:"specs,omitempty"`
Decisions []string `json:"decisions,omitempty"`
}
InitiativeSection contains initiative-level context.
type PhaseHandoff ¶
type PhaseHandoff struct {
Stability StabilityClass `json:"stability"`
Provenance Provenance `json:"provenance"`
PhaseID string `json:"phase_id"`
PhaseTitle string `json:"phase_title"`
DerivedStatus string `json:"derived_status"`
Completed []string `json:"completed,omitempty"`
Decisions []string `json:"decisions,omitempty"`
}
PhaseHandoff contains handoff data from a completed prior phase.
type PhaseHandoffProjection ¶
type PhaseHandoffProjection struct {
// Version is the schema version for forwards compatibility.
Version string `json:"version"`
// PhaseID is the phase this handoff is for.
PhaseID string `json:"phase_id"`
// PhaseTitle is the human-readable phase title.
PhaseTitle string `json:"phase_title"`
// Theme is the phase's grouping rationale.
Theme string `json:"theme,omitempty"`
// InitiativeID is the parent initiative.
InitiativeID string `json:"initiative_id"`
// DerivedStatus is the phase status computed from member RMIs.
DerivedStatus string `json:"derived_status"`
// BuildTimestamp is when this projection was assembled.
BuildTimestamp time.Time `json:"build_timestamp"`
// Provenance tracks the Dolt revision used.
Provenance Provenance `json:"provenance"`
// Summary contains aggregated counts and completion stats.
Summary HandoffSummary `json:"summary"`
// RMIHandoffs contains per-RMI handoff data, ordered by sequence.
RMIHandoffs []RMIHandoffEntry `json:"rmi_handoffs"`
// AggregatedDecisions collects all decisions across RMIs.
AggregatedDecisions []string `json:"aggregated_decisions,omitempty"`
// Evidence contains all delivery evidence for the phase.
Evidence []EvidenceEntry `json:"evidence,omitempty"`
}
PhaseHandoffProjection is the complete handoff artifact for a phase. It aggregates member-RMI assignment handoffs, evidence, and derived status.
func (*PhaseHandoffProjection) RenderJSON ¶
func (p *PhaseHandoffProjection) RenderJSON() ([]byte, error)
RenderHandoffJSON renders the handoff projection as indented JSON.
func (*PhaseHandoffProjection) RenderMarkdown ¶
func (p *PhaseHandoffProjection) RenderMarkdown() string
RenderHandoffMarkdown renders the handoff projection as Markdown.
type PhaseSection ¶
type PhaseSection struct {
Stability StabilityClass `json:"stability"`
Provenance Provenance `json:"provenance"`
ID string `json:"id"`
Title string `json:"title"`
Theme string `json:"theme,omitempty"`
SequenceNumber int `json:"sequence_number"`
DerivedStatus string `json:"derived_status"`
// MemberRMIs lists all RMIs in this phase with summary info.
MemberRMIs []RMISummary `json:"member_rmis"`
// DependencyEdges lists inter-RMI dependencies within this phase.
DependencyEdges []DependencyEdge `json:"dependency_edges,omitempty"`
}
PhaseSection contains phase-level context.
type ProgramSection ¶
type ProgramSection struct {
Stability StabilityClass `json:"stability"`
Provenance Provenance `json:"provenance"`
ID string `json:"id"`
Name string `json:"name"`
Description string `json:"description,omitempty"`
}
ProgramSection contains program-level context.
type Provenance ¶
type Provenance struct {
// Source is the data source type: "dolt" for graph data, "git" for spec files.
Source string `json:"source"`
// Revision is the Dolt commit hash or git SHA.
Revision string `json:"revision"`
// Timestamp is when the revision was created.
Timestamp *time.Time `json:"timestamp,omitempty"`
}
Provenance tracks the source revision for a section.
type RMIHandoffEntry ¶
type RMIHandoffEntry struct {
RMIID string `json:"rmi_id"`
Title string `json:"title"`
Status string `json:"status"`
Required bool `json:"required"`
Sequence int `json:"sequence"`
RepoID string `json:"repo_id"`
// Handoff is the structured handoff from the most recent assignment.
Handoff *HandoffData `json:"handoff,omitempty"`
// EvidenceCount is the number of evidence items for this RMI.
EvidenceCount int `json:"evidence_count"`
}
RMIHandoffEntry contains handoff data for a single RMI.
type RMISection ¶
type RMISection struct {
Stability StabilityClass `json:"stability"`
Provenance Provenance `json:"provenance"`
ID string `json:"id"`
Title string `json:"title"`
Description string `json:"description,omitempty"`
ItemType string `json:"item_type"`
Status string `json:"status"`
Priority string `json:"priority,omitempty"`
Required bool `json:"required"`
SequenceNumber int `json:"sequence_number"`
AcceptanceCriteria []string `json:"acceptance_criteria,omitempty"`
RepositoryID string `json:"repository_id"`
// Dependencies lists RMIs this one depends on.
Dependencies []DependencyEdge `json:"dependencies,omitempty"`
// Dependents lists RMIs that depend on this one.
Dependents []DependencyEdge `json:"dependents,omitempty"`
}
RMISection contains detailed RMI context for the target RMI.
type RMISummary ¶
type RMISummary struct {
ID string `json:"id"`
Title string `json:"title"`
Status string `json:"status"`
Required bool `json:"required"`
Sequence int `json:"sequence"`
RepoID string `json:"repo_id"`
}
RMISummary is a compact representation of an RMI for phase context.
type Sections ¶
type Sections struct {
// Program contains program-level context (stability: stable).
Program *ProgramSection `json:"program,omitempty"`
// Initiative contains initiative-level context (stability: stable).
Initiative InitiativeSection `json:"initiative"`
// Phase contains phase-level context (stability: phase_stable).
Phase PhaseSection `json:"phase"`
// PrerequisiteHandoffs contains handoffs from prior phases (stability: phase_stable).
PrerequisiteHandoffs []PhaseHandoff `json:"prerequisite_handoffs,omitempty"`
// CurrentRMI contains the target RMI context (stability: rmi_stable).
// Only present when TargetType is "rmi".
CurrentRMI *RMISection `json:"current_rmi,omitempty"`
// SpecReferences contains paths to spec files with revisions (stability: rmi_stable).
SpecReferences []SpecReference `json:"spec_references,omitempty"`
// Assignment contains current assignment state (stability: volatile).
Assignment *AssignmentSection `json:"assignment,omitempty"`
}
Sections groups context data by stability class, ordered stable→volatile.
type SpecReference ¶
type SpecReference struct {
Stability StabilityClass `json:"stability"`
Provenance Provenance `json:"provenance"`
// Path is the file path relative to the repository root.
Path string `json:"path"`
// RepoID is the repository containing this spec.
RepoID string `json:"repo_id"`
// LocalPath is the absolute path on disk (for agent access).
LocalPath string `json:"local_path,omitempty"`
}
SpecReference points to a spec file with its git revision.
type StabilityClass ¶
type StabilityClass string
StabilityClass indicates how frequently a section's content changes. Sections are ordered from most stable to most volatile.
const ( // Stable content rarely changes (program/initiative definitions, decisions). Stable StabilityClass = "stable" // PhaseStable content changes at phase boundaries (phase objectives, member RMIs). PhaseStable StabilityClass = "phase_stable" // RMIStable content changes per RMI (acceptance criteria, dependencies, repo). RMIStable StabilityClass = "rmi_stable" // Volatile content changes frequently (assignment state, evidence). Volatile StabilityClass = "volatile" )