Day 89 — Capstone harden & evidence

Updated

July 30, 2026

Day 89 — Capstone harden & evidence

Stage VIII · ~3h
Goal: Produce an evidence pack proving the capstone meets Stage VII–VIII quality: tests, static analysis, govulncheck, performance note, security checklist delta, and packaging verification—no new features.

Important

No new features. Hardening converts “it worked on my machine” into reproducible proof for Day 90.

Why this day exists

A demo without evidence is a slideshow. Reviewers (employers, future you, Stage gates) want commands that regenerate proof. Day 89 is the close ritual before retrospective—not the day to invent domain scope.

Theory 1 — Evidence pack layout

Create evidence/ (or docs/evidence/):

evidence/
  README.md           # index of artifacts + how to regenerate
  test.txt            # go test -count=1 ./... output
  vet.txt
  staticcheck.txt
  govulncheck.txt
  bench-or-pprof.md   # summary + commands (profiles gitignored)
  load.md             # optional short load re-run
  security.md         # checklist delta from day81
  container-or-release.md
  demo-log.txt        # scripted demo output
# evidence/README.md
Go version:
Git SHA:
Date:
Regenerate: `./scripts/evidence.sh`

What belongs in git

Commit Do not commit
Text logs Multi-MB pprof blobs
Markdown summaries Secrets / .env
Scripts Machine-specific absolute paths only

Theory 2 — Evidence script

#!/usr/bin/env bash
# scripts/evidence.sh
set -euo pipefail
mkdir -p evidence
{
  echo "go: $(go version)"
  echo "sha: $(git rev-parse --short HEAD 2>/dev/null || echo none)"
  echo "date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
} | tee evidence/README.md

go test -count=1 ./... 2>&1 | tee evidence/test.txt
go vet ./... 2>&1 | tee evidence/vet.txt
staticcheck ./... 2>&1 | tee evidence/staticcheck.txt
govulncheck ./... 2>&1 | tee evidence/govulncheck.txt

# optional load/bench — keep short
# go test -bench=. -benchmem ./internal/... | tee evidence/bench.txt

./demo.sh 2>&1 | tee evidence/demo-log.txt

Make executable: chmod +x scripts/evidence.sh demo.sh.

Commit text evidence; keep large profiles out of git (link paths in markdown).

Theory 3 — What “harden” means today

Action Yes No
Fix failing tests ✓
Fix govulncheck hits ✓
Tighten timeouts/body limits ✓
New features ✗
Drive-by refactors ✗ unless unblock tests

If a test is flake: fix or delete with reason—do not ignore.

Flake protocol

## known issues
- TestX flaked once under -count=20: root cause fixed by ...

Theory 4 — Security delta vs Day 81

Re-apply the security checklist to this SHA, not the Stage VI service.

# evidence/security.md
Compared to day81 checklist applied to capstone SHA abcdef1

| Item | Status | Fix if GAP |
|------|--------|------------|
| ReadHeaderTimeout | PASS | set 5s |
| Body limit | PASS | 1MiB MaxBytesReader |
| SQL placeholders | PASS | |
| pprof bind | PASS | 127.0.0.1:6060 |
| Auth on writes | PASS | bearer |
| govulncheck | PASS | clean |
| Secrets in repo | PASS | rg review |
| TLS story | PASS/N/A | day60 notes |

Quick secret scan:

rg -n "API_KEY|SECRET|password\s*=" --glob '!**/*_test.go' || true

Lab runbook (ordered)

1. Tests (45–60 min)

go test -count=1 ./...
go test -race ./...   # if time and pure-Go; skip if known cgo issues

Add only missing critical tests (auth deny, one domain rule, one adapter).

2. Static & vulns (20 min)

go vet ./...
staticcheck ./...
govulncheck ./...

Upgrade reachable vulns; re-test.

3. Performance snapshot (30 min)

Pick one:

  • Re-run a microbenchmark on hot package
  • 20s vegeta/hey against local service
  • One CPU pprof under demo load

Write evidence/bench-or-pprof.md with numbers + interpretation (not raw only).

4. Security delta (20 min)

Produce evidence/security.md with PASS/GAP.

5. Packaging (20 min)

docker build -t capstone:evidence .   # A/B
# or
./scripts/build-release.sh            # C

Record size/file output in evidence/container-or-release.md.

6. Demo freeze (15 min)

./demo.sh → save log. If fail, fix until pass—this blocks Day 90.

Worked example — performance note

## evidence/bench-or-pprof.md
Command: hey -z 20s -c 20 http://127.0.0.1:8080/v1/items
Result: ~900 RPS, p99 40ms, 0% errors
Bottleneck hypothesis: JSON encode dominates (pprof top: encoding/json)
Decision: acceptable for demo; future pool buffers

Worked example — container note

## evidence/container-or-release.md
docker build -t capstone:evidence .
Size: 18MB
User: nonroot
Health: /healthz
file bin/app: ELF 64-bit LSB executable, x86-64, statically linked

Regenerating evidence after a fix

./scripts/evidence.sh
git add evidence scripts
git commit -m "day89: refresh evidence after timeout fix"

What reviewers look for

  1. Commands are copy-pasteable
  2. SHA and go version match the demo binary
  3. Failures are not hidden (set -e)
  4. Interpretation accompanies numbers
  5. Demo log is from the same SHA as tests

Option-specific emphasis

Option Extra evidence
A Collector mock tests; metrics series present; safe defaults
B Migration idempotent; auth negative test; shutdown demo note
C Multi-arch file outputs; exit code tests; --help snapshot

CLI help snapshot

go run ./cmd/mytool --help 2>&1 | tee evidence/help.txt

Theory 5 — Minimum bar vs stretch evidence

Minimum (must have):

Artifact Command idea
Tests go test -count=1 ./...
Vet go vet ./...
Staticcheck staticcheck ./...
Vulns govulncheck ./...
Demo log ./demo.sh
Index evidence/README.md with SHA + go version

Stretch (pick ≥1 if time):

Artifact When useful
-race log Concurrency-heavy A/B
Bench numbers Hot path exists
hey/vegeta 20s HTTP service B/A
help.txt Option C UX proof
docker history summary Image layer curiosity

Do not burn the day on stretch if minimum is red.

Accepted-risk template (govulncheck)

## Accepted risk
ID: GO-20XX-XXXX
Module: example.com/dep@v1.2.3
Reachable: no / yes (path)
Why not upgraded: breaks API X; upgrade planned after demo
Mitigation: code path disabled behind flag; network not exposed
Owner: you
Review by: <date>

Commit this next to govulncheck.txt so Day 90 reviewers are not surprised.

CI sketch (optional)

# awareness — not required to implement today
# on PR: go test, vet, staticcheck, govulncheck
# main: plus docker build smoke

If you already have CI from earlier days, capture one green run URL or log snippet in evidence/ci-note.md.

Hour-by-hour suggestion

Time Focus
0:00–1:00 Tests + race if feasible
1:00–1:30 vet/staticcheck/govulncheck
1:30–2:10 perf/load note
2:10–2:40 security delta + packaging
2:40–3:00 evidence.sh + demo log

Common gotchas

Gotcha Fix
Evidence with absolute machine paths only Prefer commands regenerable
Committing 200MB profiles Summaries only
race detector + racy still shipping Fix or document known issue
demo pass but tests fail Tests gate demo
“I’ll gather evidence tomorrow” Day 90 is retro—not the day to discover red CI
Editing code without re-running pack evidence.sh is the close ritual
staticcheck not installed Install or note GAP with install command
Accepting vuln without note Document accepted risk + ticket

Checkpoint

  • evidence/ pack complete with index
  • go test green (logged)
  • vet + staticcheck + govulncheck logged
  • Perf or load note written
  • Security delta written
  • Packaging verified
  • demo.sh log captured
  • No new features added

Commit

git add .
git commit -m "day89: capstone harden evidence pack"

Write three personal gotchas before continuing.

Tomorrow

Day 90 — Retrospective & roadmap: run the demo checklist, write RETRO.md, and chart the next 30 days of Go learning.