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

[allyblockcast]

Weekly CLAUDE.md maintenance for hindsight (BLO-32603, dispatcher BLO-32585).

Do not merge on my account — this is a proposal for human review.

Scope of the audit

Zero PRs merged and zero commits landed on main in the 7-day window, so there is no
merge-derived drift:

$ gh pr list --repo Blockcast/hindsight --state merged \
    --search "merged:>=2026-08-31" --json number,title,mergedAt
[]
$ git log --since=2026-08-31 --oneline origin/main | wc -l
0

gbrain returned no hindsight facts for the window either.

I therefore audited the document against the tree itself rather than against a merge list.
All 47 paths, every symbol, and every CI job name cited in CLAUDE.md resolve on main
(run_for_dialect, _CONFIGURABLE_FIELDS, _get_raw_config, _parse_cli_args,
assert_meets_criteria, VALID_INTEGRATIONS, the check-unused-code / detect-changes /
test-crewai-integration jobs, test_bundled_template_matches_repo_root, the hs_llm_core
and hs_llm_mat markers). The worker-capacity and DB-pool-cap claims also check out exactly
against helm/hindsight/values.yaml:172-175 and :107-111.

One factual error surfaced.

Added

• (nothing — no merged PR this week established a new convention)

Pruned

• CLAUDE.md "Helm Operations": the clause readiness remains DB-backed on /health.
  It is false against the chart and it contradicts the Helm Health Probes section
  directly beneath it. Ground truth at this head:

  • API readiness → /version — helm/hindsight/values.yaml:53
  • worker readiness → /metrics — helm/hindsight/values.yaml:156
  • the only /health probes belong to the optional TEI reranker/embeddings sidecars
    on ports 8090/8091 (values.yaml:396-447) — unrelated to API/worker readiness.

  values.yaml:49-50 states the intent in as many words: "Keep readiness on the cheap
  process/version endpoint so DB pressure cannot cascade into kube probe failures."

  Provenance — and note this is not traceable to a this-week merge. git blame puts
  the clause in docs(claude): weekly CLAUDE.md refresh 2026-07-06 #16 (8df7368f, 2026-08-25, the newest commit on main), which regressed
  the fact docs(claude): weekly CLAUDE.md refresh 2026-07-27 #21 (ead5161c, 2026-08-11) had established eleven seconds after docs(claude): weekly CLAUDE.md refresh 2026-08-10 #23 landed.
  docs(claude): weekly CLAUDE.md refresh 2026-07-06 #16 appended a new "Helm Operations" section immediately above the existing
  "Helm Health Probes" section without reconciling the two.

  Why it is worth a PR in a no-merge week: a reader following line 129 would repoint
  readiness at /health, reintroducing the DB-pressure → probe-failure restart cascade that
  fix(helm): reduce Hindsight DB pressure during liveness #15, fix(helm): align Hindsight probes and worker caps #18, fix(helm): align Hindsight probes with DB pressure remediation #20 and docs(claude): weekly CLAUDE.md refresh 2026-07-27 #21 were each filed to remove. Nothing tests prose, so this survives
  indefinitely on its own.

Fixed

• Cross-referenced Helm Health Probes from the Helm Operations paragraph instead of
  restating readiness there, so the two sections cannot diverge again.
• Added the missing blank line between the paragraph and the ### Helm Health Probes
  heading (they were flush against each other).

Liveness endpoints and the DB-pool/concurrency sentence were verified correct and are
left untouched.

Uncertain — needs human review

• Nothing was deleted that I did not understand. The one removed clause is the single
  factual error above; no instruction was dropped for being unclear.
• The two Helm sections are now redundant, and I deliberately did not consolidate them.
  "Helm Operations" and "Helm Health Probes" both discuss probes and, after this fix, agree.
  Merging them into one section would be tidier but is an editorial call beyond
  "high-confidence fix", so I left it. Reviewer: fold them together if you prefer — the
  unique content in "Helm Operations" is the liveness endpoints plus the DB-pool/concurrency
  caveat.
• Branch name deviates from the runbook. The runbook specifies
  docs/claude-weekly-refresh-20260907, which is unpushable in this repo: a branch named
  docs already exists, and git stores refs as paths, so refs/heads/docs cannot
  simultaneously be a file and a directory (! [remote rejected] (directory file conflict)).
  I used staff-engineer/docs-claude-weekly-refresh-20260907, matching the existing
  staff-engineer/docs-claude-weekly-refresh-20260727 branch from a prior run. Worth fixing
  in the dispatcher runbook so future weeks do not rediscover it.

Verification

• gh pr view <this> --json files → CLAUDE.md only; 2 insertions, 1 deletion.
• Nothing committed to main; branch-only.
• No senior-engineer system-prompt block, Architectural-Principles, or Anti-Patterns section
  was touched.

🤖 Generated with Claude Code

[allyblockcast]

🔗 Paperclip issue: BLO-32585
🔗 Paperclip issue: BLO-32603

[allyblockcast]

🔗 Paperclip issue: BLO-32585
🔗 Paperclip issue: BLO-32603

[allyblockcast]

Ally — Consolidated PR Review

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

Docs-only change to CLAUDE.md (+2/-1). I verified every factual claim in the diff against the tree at this exact head rather than against the PR description, and they all hold. The removed clause was genuinely false.

Critical Issues (0)

Important Issues (0)

Suggestions (2)

• [native-codex] CLAUDE.md:129 — The cross-reference fixes this instance, but leaves two adjacent sections (### Helm Operations, ### Helm Health Probes) both narrating probe policy. That duplication is the mechanism of the regression this PR is repairing: #16 appended overlapping prose above an existing section without reconciling it, and nothing tests prose. Folding the probe sentence into ### Helm Health Probes and leaving ### Helm Operations to the DB-pool/concurrency guidance would give each fact one authoritative home and remove the surface that let the two drift apart. Deliberately narrow scope here is defensible for a docs fix — flagging it as the durable follow-up, not as a change request.
• [pr-review-toolkit/comments] CLAUDE.md:129 — The sentence names the liveness endpoints inline but defers readiness to the section below, which reads as though the two probe types use different paths. They do not: liveness and readiness are the same endpoint on both workloads — API /version at values.yaml:42 and :53, worker /metrics at :145 and :156. One clause ("both probe types use the same process-local endpoint") would close that inference.

Strengths

• The correction is accurate, and I confirmed it independently at this head: API readiness is /version (helm/hindsight/values.yaml:53), worker readiness is /metrics (:156), and all four /health probes in the chart (:398, :406, :435, :443) belong to the optional TEI reranker/embeddings sidecars on ports 8090/8091 — none of them gate API or worker readiness. The readiness remains DB-backed on /health clause was false against the chart and contradicted the section directly beneath it.
• values.yaml:49-50 states the intent in as many words ("Keep readiness on the cheap process/version endpoint so DB pressure cannot cascade into kube probe failures"), so the doc now matches both the config and its stated rationale.
• The diff also inserts the missing blank line before ### Helm Health Probes, which previously abutted the preceding paragraph — a real Markdown structure fix carried quietly alongside the content change.
• The PR body does the thing that makes a docs PR reviewable: it cites git blame provenance (#16 8df7368f regressing what #21 ead5161c established), states the concrete failure mode a reader would hit, and is explicit that the finding is not traceable to a this-week merge. Reporting a no-drift week honestly and still shipping the one real defect found is the right call.
• Correctly scoped — it removes the false clause and points at the accurate section rather than rewriting prose that was already right.

Recommended Action

1. No Critical or Important issues — nothing blocks merge on review grounds.
2. Consider the section-consolidation suggestion as a follow-up; it addresses the recurrence class, not just this instance.
3. Note the author's own "do not merge on my account" request in the PR body — this is posted as a review, not an approval, and the merge decision remains with the repo's humans.