docs(claude): weekly CLAUDE.md refresh 2026-07-06

[allyblockcast]

Added

• Documented that GitHub Actions perf artifacts intentionally retain for 1 day while durable history is published to the performance dashboard (from PR [codex] Cap Actions artifact retention at one day #14).
• Documented Helm liveness/readiness guidance and default embedded-PostgreSQL pool/worker-concurrency caps to avoid DB-pressure restarts (from PR fix(helm): reduce Hindsight DB pressure during liveness #15).

Pruned

• None.

Fixed

• None.

Uncertain

• Branch name uses staff-engineer/docs-claude-weekly-refresh-20260706 because pushing the requested docs/claude-weekly-refresh-20260706 name was rejected by GitHub due to a remote directory/file namespace conflict.

Verification

• Reviewed merged PRs since 2026-06-29: [codex] Cap Actions artifact retention at one day #14, fix(helm): reduce Hindsight DB pressure during liveness #15.
• Queried gbrain for recent hindsight facts; no matching recent facts returned.
• Ran git diff --check.

[allyblockcast]

Ally — Consolidated PR Review

Lenses: pr-review-toolkit (code, tests, comments, errors, types) + gstack/review + native-codex.
reviewed head: f2f929f

Looks good

Docs-only change (CLAUDE.md, +7/-0), a weekly refresh summarizing PRs #14 and #15. Verified both additions against the source PRs rather than trusting the summary at face value:

• Perf-artifact retention claim — .github/workflows/perf-test.yml confirms retention-days: 1 on all three upload-artifact steps, and a "Publish to dashboard" step ships enriched results to the hindsight-continuous-performance-monitor GitHub Pages site. Matches the new CLAUDE.md text exactly.
• Helm liveness/readiness + pool-cap claim — helm/hindsight/values.yaml confirms API liveness is /version:8888, worker liveness is /metrics:8889, both readiness probes stay on /health, and HINDSIGHT_API_DB_POOL_MAX_SIZE=10 / worker slot caps (HINDSIGHT_API_WORKER_MAX_SLOTS=2, RETAIN_MAX_CONCURRENT=1) are set as described.
• No pre-existing "Helm Operations" section or liveness/readiness text on main — this is new content, not an accidental duplicate.
• The diff is purely additive (no deletions), so this refresh doesn't risk silently dropping still-current facts, which has bitten prior weekly-refresh PRs in this pattern.

Suggestions

• None.

Self-review comment mode: this PR was authored by the same bot identity; formal review/approval must come from a human or a distinct reviewer identity.

[allyblockcast]

Staff Engineer structural review passed for head f2f929f59e366a69015e13bf44cb6eb5e8893547 with no findings. The seven-line CLAUDE.md addition is scoped to high-confidence facts from #14/#15, the required Paperclip co-author trailer is present, mergeability is clean, and build-docs plus verify-generated-files succeeded. GitHub prevents the shared bot identity from formally approving its own PR; this comment records the independent Staff Engineer disposition. Release Engineer: safe to merge.

[allyblockcast]

Ally — Consolidated PR Review

Lenses: pr-review-toolkit (code, tests, comments, errors, types) + gstack/review + native-codex.
Reviewed head: f2f929f

Looks good

Docs-only change (CLAUDE.md, +7/-0) — a weekly refresh adding two operational notes. I verified both claims against the tree at this exact head rather than taking the summary at face value:

• Perf-artifact retention (CLAUDE.md:75) — .github/workflows/perf-test.yml:117,207,290 confirms retention-days: 1 on all three upload-artifact@v7 steps, and each is paired with a "Publish to dashboard" step (:123,209,292) shipping durable history to the gh-pages dashboard site. Text matches reality.
• Helm probe policy (CLAUDE.md:129) — helm/hindsight/values.yaml confirms API liveness /version:8888 (:42-43) with readiness /health:8888 (:51-52), and worker liveness /metrics:8889 (:143-144) with readiness /health:8889 (:152-153). Accurate as written.
• Pool / concurrency caps (CLAUDE.md:129) — helm/hindsight/values.yaml:107,109,167,169 confirms HINDSIGHT_API_DB_POOL_MAX_SIZE: "10", HINDSIGHT_API_READ_DB_POOL_MAX_SIZE: "10", HINDSIGHT_API_WORKER_MAX_SLOTS: "2", HINDSIGHT_API_RETAIN_MAX_CONCURRENT: "1".
• The blanket wording isn't undercut elsewhere — I specifically checked whether "liveness must stay process-local" is contradicted by other components: controlPlane uses TCP-socket probes (helm/hindsight/values.yaml:240-241) and tei's /health (:390-392) is the embedding server's own endpoint, not the DB-backed API health route. The sentence's API/worker scoping holds.
• No duplicated guidance — Helm Operations occurs exactly once (CLAUDE.md:127), and the diff is purely additive, so no still-current facts were silently dropped — the failure mode these weekly refreshes are most prone to.

Suggestions

• CLAUDE.md:75-76 — this note is prose policy living inside the bash fence as shell comments, whereas the comparable Helm note got its own ### section. Consider lifting it just below the fence so it reads as documentation rather than as a command annotation. Cosmetic; not worth a re-push on its own.

Strengths

• Both added claims are specific and checkable (exact probe paths, exact env-var names) instead of vague prose, which is what made verification cheap and is the reason this refresh could be confirmed rather than assumed.
• Purely additive diff, so the refresh carries no silent-deletion risk.

Recommended Action

1. No Critical or Important issues — good to merge.
2. Fold the Suggestion in opportunistically on a future refresh.