programreport

Documentation

Overview

Package programreport folds the project's ONGOING PROGRAMS — the work classes internal/worktype marks as never-"done" frontiers (kernel-optimization cache-optimization, and human-operator-effectiveness) — into one read-only report envelope with a durable JSONL trend ledger. It is the ongoing-program sibling of internal/milestonereport.

The distinction the two reports draw together (see internal/worktype for the law):

• milestonereport's ROADMAP measures DISCRETE epics by child-completion % — the right lens for a deliverable that converges on 100% and closes.
• programreport measures the ONGOING programs by a FRONTIER + a TREND — the right lens for a process that is never done. There is no completion % here on purpose; a "60% complete" line on kernel-opt, cache-opt, or human-steerability is a category error.

The program frontier signals (WITNESSED, never self-reported):

• KERNEL OPTIMIZATION — the trailing-window count of ships stamped on a perf/kernel leaf (the decode/prefill/quant/parity lanes), read from git through the SAME hooks.StampOf grammar the pre-commit lint binds to. It is an activity proxy, honestly labeled: it asserts the program is being worked, not a tok/s number (the throughput claim lives in the benchmark authority rows). A quiet window is HOLDING, not regressed.
• CACHE OPTIMIZATION — the realized KV-reuse ratio over the dogfood cache-value ledger, read through cachevalueledger's #1066-fenced trend gate (the same gate `fak cachevalue` enforces, so the two never disagree). The honesty fence (the marginal-over-tuned-warm-KV value family) is carried onto the signal.
• HUMAN OPERATOR EFFECTIVENESS — the operator-heaviness lightness proxy, read from the source-reading scorecard: max(0, 100 - heaviness_pressure), forced to zero when hard heaviness_debt exists. It is a first deterministic proxy for "can a human still steer this system without drowning in the surface?".

The report is a REPORT CONTRACT, not a second quality gate (the milestonereport posture): --check fails ONLY when the programs dimension could not be MEASURED. A regressed frontier is a MEASURED fact surfaced as an advisory line; the per-program ratchet (the cache-value trend gate, the perf-parity RSI loop) owns the real gate.

The pure surface (the interpreter, the fold, the ledger parse/trend, render, gate) lives in programreport.go and is unit-testable with no process and no repo. The impure runners (the cache-value ledger read, the perf-lane git window, and the operator-heaviness source read) live in collect.go.

Index

• Constants
• func AppendLedgerLine(row LedgerRow) (string, error)
• func CheckGate(r Report) (int, string)
• func CheckGateTriaged(r Report, enforce bool) (int, string)
• func HeadCommit(root string) string
• func Render(r Report) string
• func TriageSelfcheck() error
• type FoldOpts
• type LedgerRow
  • func ParseLedger(content string) []LedgerRow
  • func RowFromReport(r Report) LedgerRow
• type Programs
  • func Collect(root, cacheLedgerPath string, windowDays int) Programs
  • func InterpretPrograms(signals []Signal) Programs
• type Report
  • func Fold(p Programs, opts FoldOpts) Report
  • func (r Report) WithGate(code int, message string) Report
  • func (r Report) WithTrend(t Trend) Report
• type Signal
• type Trend
  • func TrendVsLast(row LedgerRow, prior []LedgerRow) Trend

Constants

const DefaultLedgerRel = "docs/programs/history.jsonl"

DefaultLedgerRel is the committed, append-only history ledger (one JSONL row per program tick). It lives under docs/ so it is durable trunk evidence, not a regenerable build artifact.

const DefaultWindowDays = 7

DefaultWindowDays is the trailing window the kernel-opt activity signal counts over.

const LedgerSchema = "fak-program-ledger/1"

LedgerSchema tags each durable history row so a reader can validate the line.

const Schema = "fak-program-report/1"

Schema is the stable control-pane schema identifier for the report envelope.

Functions

func AppendLedgerLine

func AppendLedgerLine(row LedgerRow) (string, error)

AppendLedgerLine renders the JSONL line for a row (no trailing newline).

func CheckGate

func CheckGate(r Report) (int, string)

CheckGate is the advisory CI gate over a folded report. It fails ONLY when the programs dimension could not be measured — the report is a mirror, not a second quality gate (a regressed frontier is a measured fact, not an incomplete report).

0  programs recorded (clear or advisory)
1  the programs dimension failed to measure

func CheckGateTriaged

func CheckGateTriaged(r Report, enforce bool) (int, string)

CheckGateTriaged is CheckGate with the decenter-the-human fold applied at the source: an INCOMPLETE report whose NextAction is a runnable rerun routes to the fleet instead of paging. Soaks behind enforce (the CLI reads FAK_PROGRAM_TRIAGE_GATE); enforce=false is byte-for-byte CheckGate.

func HeadCommit

func HeadCommit(root string) string

HeadCommit returns the short HEAD commit of root, or "unknown" — inlined git plumbing so this tier-1 leaf imports no sibling composer (the milestonereport pattern).

func Render

func Render(r Report) string

Render produces the human snapshot.

func TriageSelfcheck

func TriageSelfcheck() error

TriageSelfcheck proves the program report's source-level page-vs-act fold with no I/O, delegating to the shared trendreport proof.

Types

type FoldOpts

type FoldOpts struct {
	Workspace   string
	Commit      string
	GeneratedAt string
	Date        string
}

FoldOpts carries the ambient context the fold stamps onto the envelope.

type LedgerRow

type LedgerRow struct {
	Schema       string  `json:"schema"`
	Date         string  `json:"date"`
	Commit       string  `json:"commit"`
	GeneratedAt  string  `json:"generated_at"`
	Verdict      string  `json:"verdict"`
	Tracked      int     `json:"tracked"`
	Measured     int     `json:"measured"`
	Advancing    int     `json:"advancing"`
	Regressed    int     `json:"regressed"`
	KernelMetric float64 `json:"kernel_metric"`
	KernelDir    string  `json:"kernel_dir,omitempty"`
	CacheMetric  float64 `json:"cache_metric"`
	CacheDir     string  `json:"cache_dir,omitempty"`
	HumanMetric  float64 `json:"human_metric"`
	HumanDir     string  `json:"human_dir,omitempty"`
}

LedgerRow is one durable, append-only history line (a flattened per-class projection so the ledger is a self-describing time series).

func ParseLedger

func ParseLedger(content string) []LedgerRow

ParseLedger parses an append-only JSONL ledger, tolerating blank + garbled lines.

func RowFromReport

func RowFromReport(r Report) LedgerRow

RowFromReport projects a folded report into one durable ledger row.

type Programs

type Programs struct {
	Signals     []Signal `json:"signals"`
	Tracked     int      `json:"tracked"`
	Measured    int      `json:"measured"`
	Advancing   int      `json:"advancing"`
	Regressed   int      `json:"regressed"`
	PartialNote string   `json:"partial_note,omitempty"`
	Err         string   `json:"err,omitempty"`
	OK          bool     `json:"ok"`
}

Programs is the PROGRAMS dimension: the per-program signals folded for a tick. Err is set only when EVERY program failed to measure (a true unmeasured dimension that gates); a partial failure records a non-gating PartialNote and leaves Err == "" so one flaky ledger read never reds the whole report.

func Collect

func Collect(root, cacheLedgerPath string, windowDays int) Programs

Collect measures both ongoing programs' frontier signals: kernel-opt from the perf-lane git ship window, cache-opt from the cache-value reuse trend gate. A signal that cannot be read carries Err (never a silent zero), and the pure InterpretPrograms folds the partial/whole-failure verdict.

func InterpretPrograms

func InterpretPrograms(signals []Signal) Programs

InterpretPrograms folds the per-program signals into the PROGRAMS dimension. The signals arrive already measured (collect.go does the impure reads); this is the pure tally so the verdict logic and the JSON shape are unit-testable with no disk.

type Report

type Report struct {
	Schema      string   `json:"schema"`
	OK          bool     `json:"ok"`
	Verdict     string   `json:"verdict"`
	Finding     string   `json:"finding"`
	Reason      string   `json:"reason"`
	NextAction  string   `json:"next_action"`
	Workspace   string   `json:"workspace"`
	Commit      string   `json:"commit"`
	GeneratedAt string   `json:"generated_at"`
	Date        string   `json:"date"`
	Programs    Programs `json:"programs"`
	Trend       *Trend   `json:"trend,omitempty"`
	GateExit    *int     `json:"gate_exit,omitempty"`
	GateMessage string   `json:"gate_message,omitempty"`
}

Report is one folded ongoing-program control-pane envelope.

func Fold

func Fold(p Programs, opts FoldOpts) Report

Fold folds the programs dimension into one report envelope. The verdict ladder mirrors milestonereport's REPORT contract, not a second quality gate: it is ACTION only when the dimension could not be MEASURED (every program's frontier signal failed), and OK otherwise — a regressed program frontier is surfaced as an advisory line, never a gate (a frontier can dip for honest reasons; the per-program ratchet, e.g. the cache-value trend gate, owns the real regression gate).

func (Report) WithGate

func (r Report) WithGate(code int, message string) Report

WithGate returns a copy reconciled to a CheckGate decision, for --check --json.

func (Report) WithTrend

func (r Report) WithTrend(t Trend) Report

WithTrend attaches a per-tick trend and applies the advisory rewrite.

type Signal

type Signal struct {
	Class     worktype.Class `json:"class"`
	Label     string         `json:"label"`
	Doc       string         `json:"doc,omitempty"`    // the program's operating-plan doc
	Frontier  string         `json:"frontier"`         // the best-witnessed frontier reading (human string)
	Metric    float64        `json:"metric"`           // the numeric frontier reading the trend is computed on
	Direction string         `json:"direction"`        // advancing | holding | regressed | unknown
	Activity  int            `json:"activity"`         // recent shipped frontier-moves over the window
	Window    string         `json:"window,omitempty"` // the window the activity is counted over (e.g. "7d")
	Note      string         `json:"note,omitempty"`   // an honesty fence / caveat (e.g. the #1066 reuse-family label)
	Err       string         `json:"err,omitempty"`
	OK        bool           `json:"ok"`
}

Signal is one ongoing program's measured frontier-activity for a tick. It is deliberately NOT a completion %: Frontier is the best-witnessed number/state (e.g. the realized reuse ratio, or the trailing perf-ship count), Direction is whether the frontier is advancing, and Activity is the recent shipped work that moved it. A program whose signal could not be measured sets Err — never a silent zero, the same honesty seam the milestone roadmap carries for an unreadable epic.

type Trend

type Trend struct {
	PrevDate          string  `json:"prev_date"`
	PrevCommit        string  `json:"prev_commit"`
	Direction         string  `json:"direction"` // improved | regressed | flat | new
	KernelMetricFrom  float64 `json:"kernel_metric_from"`
	KernelMetricTo    float64 `json:"kernel_metric_to"`
	KernelMetricDelta float64 `json:"kernel_metric_delta"`
	CacheMetricFrom   float64 `json:"cache_metric_from"`
	CacheMetricTo     float64 `json:"cache_metric_to"`
	CacheMetricDelta  float64 `json:"cache_metric_delta"`
	HumanMetricFrom   float64 `json:"human_metric_from"`
	HumanMetricTo     float64 `json:"human_metric_to"`
	HumanMetricDelta  float64 `json:"human_metric_delta"`
	AdvancingFrom     int     `json:"advancing_from"`
	AdvancingTo       int     `json:"advancing_to"`
	Summary           string  `json:"summary"`
}

Trend is the per-tick delta vs the previous ledger row.

func TrendVsLast

func TrendVsLast(row LedgerRow, prior []LedgerRow) Trend

TrendVsLast computes the per-tick trend vs the most recent prior row. The direction is driven by the two program metrics: a rise in either frontier metric is "improved", a fall in either (with no rise) is "regressed". With no prior row it is "new".