[Peeja]

Written by Claude.

Merge after fil-forge/infra-central#253. This PR's docs/observability.md points to the "Adding an alert or panel" section that PR adds.

This adds a short Observability section to AGENTS.md. When a change adds or alters something operational, the section tells an agent to decide how on-call would see it fail and to add what's useful in the same PR: logs, complete trace spans, and an alert or dashboard panel in fil-forge/infra-central. It also says that when a feature's health is best read as a number, the PR description should name the metric and FIL-1143. It also says to skip this for changes nothing operational depends on.

The section is kept short because AGENTS.md loads into every session. That follows bajtos's review of fil-forge/infra-nodes#174. The how-to lives in a new docs/observability.md, with Logs (only CloudWatch logs and AWS metrics reach Grafana from Central today), Metrics, Traces (tracing.NewHTTPClient() in pkg/tracing) and Alerts and dashboards, which points to infra-central's "Adding an alert or panel".

The repo's existing CLAUDE.md already imports AGENTS.md, so it's unchanged.

Companion PRs: fil-forge/piri#174, fil-forge/infra-central#253, fil-forge/infra-nodes#174 and the Forge service repos.

Checks

• git diff --check.

✴️

🤖 Generated with Claude Code

https://claude.ai/code/session_01JCF8gyb8jNRmHmWqQmVhRJ

---

Generated by Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

[Peeja]

Claude reviewer says… (1st round, df8928d)

Approve once one should-fix is done.

Verified across the six

• Scope: each diff touches only AGENTS.md/CLAUDE.md, and git diff --check is clean.
• What ships from Central: infra-central lists application metrics and traces as not shipped. terraform/modules/apps/main.tf deploys hilt, sprue, swarf, delegator and piri-signing-service with no OTEL_* variables.
• Tracking issues: the FIL-1143, FIL-1144 and FIL-1152 titles match infra-central's doc.
• Tracing helpers: NewHTTPClient exists in hilt pkg/tracing and sprue internal/tracing.
• No OTel elsewhere: delegator, swarf and piri-signing-service have no OTel imports.

Findings

1. should-fix (shared by the five Central PRs). "Note it on FIL-xxxx" asks an agent to write to a shared Linear issue from inside a feature task. Most sessions have no Linear access, and those that do shouldn't write there unprompted. Say it in the PR description instead.
2. nit. The tracing.NewHTTPClient() advice repeats pkg/tracing above. It's harmless, and it keeps the section self-contained.

✴️

---

Generated by Claude Code

[Peeja]

Claude author says…

Fixed in 8035af9.

1. Metrics bullet: it now says to say so "in the PR description, naming the metric and FIL-1143". The PR body is updated to match.
2. Repeated advice: left as is, so the section reads on its own.

git diff --check is clean. This round had a should-fix, so round 2 follows.

✴️

---

Generated by Claude Code

Claude reviewer says… (2nd round, 8035af9)

Approve. Both round 1 should-fix findings are fixed, and only nits remain.

Verified

• Round 1 fix: "say so in the PR description, naming the metric and FIL-xxxx" is in all five Central PRs, with no Linear write left.
• Delegator: its DynamoDB tables' metrics arrive through FilOne's metric stream (2026-09-grafana-telemetry.md:46-50), and it has no Postgres.
• piri-signing-service: it runs on ECS Fargate behind the application load balancer and has no database.
• swarf: it uses Postgres; its intro line and CLAUDE.md import match the other repos.
• Ingot exports: Ingot exports metrics as well as traces (cmd/telemetry.go:101-127) to the compose-set endpoint.
• Ingot in infra-central: both Ingot rules are in the "Forge Regions" group, and forge-regions.json reads ingot_local_blobs_*.
• Whitespace: git diff --check is clean in all six.

Findings

1. nit, PR body. The attribution footer is repeated.

✴️

---

Generated by Claude Code

Claude author says…

1. Repeated footer: I added only the first attribution footer; the other two appear to be added by the tooling, which I can't control.

This round found only nits, so there won't be another.

✴️

---

Generated by Claude Code

Claude reviewer says… (round on the restructure, 880198f)

This round reviewed all eight guidance PRs together; findings below are this PR's.

Approve. Only nits here, and none of the eight PRs has anything blocking or should-fix.

Verified, across all eight PRs

• git diff --check origin/main...HEAD is clean in each. In infra-central, make check passes at 0bc8bb7.
• Nothing was lost in the move. Each repo's previous section matches the new doc line by line, and every accurate sentence survives.
• Each short section still says when to act, what to add and when to skip. Each pointer names a heading that exists: "Adding a signal" in piri, ingot, delegator, swarf and piri-signing-service, and "Adding an alert or panel" on #253's branch.
• Only infra-central and swarf drop a CLAUDE.md, and both had been added by the PR itself. Every other repo's existing CLAUDE.md is untouched.
• The cited paths, headings and links resolve. Each description matches its diff.

Findings for this PR

1. nit (PR body): the doc's pointer names infra-central's "Adding an alert or panel", which only exists on Add AGENTS.md with observability guidance infra-central#253's branch, and the description doesn't say to merge after it. The earlier pointer, to infra-central's AGENTS.md, had the same dependency.
2. nit (wrapping): docs/observability.md lines 10, 19 and 31 (112–141 characters) were never reflowed after the pointer edit; the file wraps at 80.

✴️

---

Generated by Claude Code

Claude author says…

The fixes are in b6227a9.

1. A "Merge after Add AGENTS.md with observability guidance infra-central#253" line now opens the description.
2. The paragraphs with long lines are reflowed, and links are kept whole. That leaves no line over the file's width. The text is unchanged.

Check: git diff --check is clean. The change is docs-only, so I didn't run anything else.

This round found only nits, so there won't be another.

✴️

---

Generated by Claude Code