feat(0.2): pillar lift batch 3 — portfolio + explain schemas + benchmarks + analyze error UX

[pmclSF]

Replaces closed PR #170 (auto-closed when its stacked base branch was deleted on merge of #169).

Same content as #170, rebased onto main with #168 + #169 commits dropped.

Cells lifted

Pillar	Area	Cell	Before → After
Understand	core_analyze_pipeline	P5	3 → 4
Understand	core_analyze_pipeline	E5	3 → 4
Understand	insights_impact_explain	P3	3 → 4
Understand	insights_impact_explain	P4	3 → 4
Understand	insights_impact_explain	E4	3 → 4
Understand	insights_impact_explain	E5	3 → 4
Understand	insights_impact_explain	E7	3 → 4
Understand	summary_posture_metrics_focus	E7	3 → 4
Align	portfolio	E4	2 → 4
Align	portfolio	V3	2 → 4
Align	portfolio	P5	3 → 4

Highlights

• docs/schema/portfolio.md + docs/schema/explain.md — published JSON schema contracts
• docs/user-guides/drilling-into-findings.md — four-command playbook + confidence model
• benchmarks/baseline.txt — reference performance numbers
• internal/insights/insights_bench_test.go — Build perf benchmarks
• EmptyNoPortfolio empty-state wired
• analyzeFailureRemediation + runPortfolio error UX

Test plan

• go test ./... green
• make pillar-parity shows the 11 cells lifted

[github-actions]

Terrain AI Risk Review

Metric	Value
AI surfaces	13
Eval scenarios	17
Impacted scenarios	0
Uncovered surfaces	13

Decision: PASS — AI surfaces are covered.

[github-actions]

[RISK] Terrain — Merge with caution

High-severity gaps found in changed code.

Metric	Value
Changed files	10 (4 source · 1 test)
Impacted units	9
Protection gaps	4
Tests selected	5 of 800 (<1% of suite)

---

Coverage gaps in changed code

• cmd/terrain/cmd_analyze.go [LOW] — cmd_analyze.go has no observed test coverage.
  → Add unit tests for cmd_analyze.go.
• cmd/terrain/cmd_insights.go [LOW] — cmd_insights.go has no observed test coverage.
  → Add unit tests for cmd_insights.go.
• internal/reporting/empty_states.go [MED] — Exported class EmptyState has no observed test coverage.
  → Add unit tests for exported class EmptyState — this is public API surface.
• internal/reporting/portfolio_report.go [MED] — Exported function RenderPortfolioSection has no observed test coverage.
  → Add unit tests for exported function RenderPortfolioSection — this is public API surface.

4 pre-existing issues on changed files

• cmd/terrain/cmd_analyze.go [HIGH] — [blastRadiusHotspot] Changes to this file propagate to 183 tests (183 direct, 0 indirect). High blast radius increases regression risk.
• cmd/terrain/cmd_insights.go [HIGH] — [blastRadiusHotspot] Changes to this file propagate to 183 tests (183 direct, 0 indirect). High blast radius increases regression risk.
• internal/reporting/empty_states.go [HIGH] — [blastRadiusHotspot] Changes to this file propagate to 1898 tests (120 direct, 1778 indirect). High blast radius increases regression risk.
• internal/reporting/portfolio_report.go [HIGH] — [blastRadiusHotspot] Changes to this file propagate to 1898 tests (120 direct, 1778 indirect). High blast radius increases regression risk.

---

Recommended tests

5 test(s) with exact coverage of 5 impacted unit(s). 4 impacted unit(s) have no covering tests in the selected set.

Confidence: 5 exact (5 tests selected)

Test	Confidence	Why
internal/insights/insights_bench_test.go	exact	test file directly changed
internal/reporting/empty_state_goldens_test.go	exact	exact coverage of EmptyStateKind, RenderEmptyState
internal/reporting/empty_states_test.go	exact	exact coverage of EmptyStateFor, EmptyStateMarkdown
internal/testdata/e2e_workflows_test.go	exact	exact coverage of RenderPortfolioReport
internal/testdata/golden_test.go	exact	exact coverage of RenderPortfolioReport

---

Owners: PMCLSF

Limitations

• No coverage artifacts provided; protection gaps reflect missing data, not measured absence. Provide --coverage to improve accuracy.
• Mixed test cultures reduce cross-framework optimization confidence. Consider standardizing on fewer frameworks.

_{Generated by Terrain · terrain pr --json for machine-readable output}

Targeted Test Results

Terrain selected 5 test(s) instead of the full suite.

• Go tests: passed