contextbuild

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Aug 1, 2026 License: MIT Imports: 13 Imported by: 0

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

View Source
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

func GenerateSchema() ([]byte, error)

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

func NewBuilder(s store.Store, doltCommit string) *Builder

NewBuilder creates a Builder backed by the given store. doltCommit is the current Dolt HEAD revision for provenance tracking.

func (*Builder) BuildForPhase

func (b *Builder) BuildForPhase(ctx context.Context, phaseID string) (*ContextPackage, error)

BuildForPhase assembles a context package for an entire phase.

func (*Builder) BuildForRMI

func (b *Builder) BuildForRMI(ctx context.Context, rmiID string) (*ContextPackage, error)

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"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL