mlpscore

Documentation

Overview

Package mlpscore grades epic #3256's first-lovable-cut contract from committed, machine-checkable witness manifests.

Index

• Constants
• func KernelPayload(s Score) scorecard.Payload
• func MarkdownDoc(s Score) scorecard.MarkdownDoc
• func Render(s Score) string
• func RenderMarkdown(s Score) string
• func WitnessRefs() []string
• func Workstreams() []string
• type Criterion
• type FoldOpts
• type GitSnapshot
  • func LoadGitSnapshot(root string) (*GitSnapshot, error)
  • func (s *GitSnapshot) Commit() string
  • func (s *GitSnapshot) Exists(rel string) bool
  • func (s *GitSnapshot) ReadFile(rel string) ([]byte, error)
• type Score
  • func Grade(snapshot Snapshot, opts FoldOpts) Score
• type Snapshot
• type WitnessClaim
• type WitnessManifest

Constants

const (
	VerdictLovable = "lovable"
	VerdictNotYet  = "not-yet"
)

VerdictLovable / VerdictNotYet are the closed mlp_verdict vocabulary.

const (
	// Schema is the stable JSON contract emitted by `fak mlp-score --json`.
	Schema = "fak-mlp-score/1"
	// WitnessSchema is the contract each committed criterion witness must use.
	WitnessSchema = "fak-mlp-witness/1"
	// WitnessDir is the canonical home for MLP witness manifests.
	WitnessDir = "docs/mlp/witnesses"

	GradeWitnessed = "witnessed"
	GradeNotYet    = "not-yet"
)

const DebtKey = "mlp_debt"

DebtKey is the headline HARD integer the control-pane folds (corpus.mlp_debt): the number of acceptance criteria still without a committed witness.

Functions

func KernelPayload

func KernelPayload(s Score) scorecard.Payload

KernelPayload re-presents a graded Score as the shared control-pane payload: the same envelope every sibling card emits, and the shape --compare diffs. It reads the corpus and KPIs Grade already folded, so it can never disagree with the score it came from.

func MarkdownDoc

func MarkdownDoc(s Score) scorecard.MarkdownDoc

MarkdownDoc is the per-card prose for the kernel's committed-snapshot renderer, used by the shared --markdown surface when a caller wants the family-standard page body.

func Render

func Render(s Score) string

Render returns the compact terminal view.

func RenderMarkdown

func RenderMarkdown(s Score) string

RenderMarkdown returns the deterministic milestone-ready rollup.

func WitnessRefs

func WitnessRefs() []string

WitnessRefs returns the canonical manifest paths in stable order.

func Workstreams

func Workstreams() []string

Workstreams returns the declared criterion order for contract tests and milestone projections.

Types

type Criterion

type Criterion struct {
	Key            string         `json:"key"`
	Workstream     string         `json:"workstream"`
	Title          string         `json:"title"`
	OwnerIssues    []int          `json:"owner_issues"`
	Grade          string         `json:"grade"`
	WitnessRef     string         `json:"witness_ref"`
	RequiredClaims []string       `json:"required_claims"`
	Evidence       []WitnessClaim `json:"evidence"`
	Missing        []string       `json:"missing,omitempty"`
}

Criterion is one stable row in the scorecard JSON and markdown rollup.

type FoldOpts

type FoldOpts = trendreport.Opts

type GitSnapshot

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

GitSnapshot is an immutable view of one repository HEAD. It intentionally ignores staged, modified, and untracked files.

func LoadGitSnapshot

func LoadGitSnapshot(root string) (*GitSnapshot, error)

LoadGitSnapshot captures the path set and short commit at HEAD.

func (*GitSnapshot) Commit

func (s *GitSnapshot) Commit() string

Commit returns the short commit the snapshot grades.

func (*GitSnapshot) Exists

func (s *GitSnapshot) Exists(rel string) bool

func (*GitSnapshot) ReadFile

func (s *GitSnapshot) ReadFile(rel string) ([]byte, error)

type Score

type Score struct {
	trendreport.Envelope
	Criteria   []Criterion     `json:"criteria"`
	Witnessed  int             `json:"witnessed"`
	Total      int             `json:"total"`
	Debt       int             `json:"mlp_debt"`
	Lovable    bool            `json:"lovable"`
	MLPVerdict string          `json:"mlp_verdict"` // lovable | not-yet
	Corpus     map[string]any  `json:"corpus"`
	KPIs       []scorecard.KPI `json:"kpis"`
}

Score is the stable MLP scorecard envelope.

Corpus and KPIs are the shared pkg/scorecard control-pane envelope this card folds through (kernel.go). They are additive: every field this payload emitted before the kernel migration is still here and still carries the same number, and a control-pane reader now also finds corpus.mlp_debt / corpus.grade / corpus.value / corpus.pressure in exactly the place it finds them on every sibling card.

func Grade

func Grade(snapshot Snapshot, opts FoldOpts) Score

Grade folds the declared criteria against one committed snapshot. A manifest passes only when its schema and criterion match, every required claim appears exactly once, and every claim links to a committed proof artifact. A nil snapshot fails closed with every criterion not-yet.

The rows are this card's own domain judgement; everything downstream of them -- the debt integer, the grade, the composite/value, the ok+verdict decision and the envelope prose -- is stamped from the shared pkg/scorecard fold (kernel.go), so this card cannot drift from its siblings and never computes the same number twice.

type Snapshot

type Snapshot interface {
	ReadFile(rel string) ([]byte, error)
	Exists(rel string) bool
}

Snapshot is the committed-tree view used by Grade. The CLI supplies a HEAD snapshot, so an untracked note or proof artifact cannot make the score move.

type WitnessClaim

type WitnessClaim struct {
	Key     string `json:"key"`
	Kind    string `json:"kind"` // test | captured-run
	Path    string `json:"path"`
	Command string `json:"command"`
}

WitnessClaim binds one acceptance claim to a reproducible proof artifact.

type WitnessManifest

type WitnessManifest struct {
	Schema    string         `json:"schema"`
	Criterion string         `json:"criterion"`
	Claims    []WitnessClaim `json:"claims"`
}

WitnessManifest is the committed evidence contract for one criterion. Each required claim must link to a committed test or captured-run artifact.