docs(install): write down the release-name convention, and guard it (backend#2621)

[LukasWodka]

Closes tracebloc/backend#2621

What was actually wrong

The installer has always named the release after the namespace:

# scripts/lib/install-client-helm.sh:2272
helm upgrade --install "$TB_NAMESPACE""$chart_ref" --namespace "$TB_NAMESPACE" --create-namespace

…defaulting both to tracebloc, and it explains itself at the point of decision (line 1862):

"The on-prem client is one-per-machine and is identified to the backend by its credentials (clientId), not by this name — so we don't ask the user to invent one."

So the self-service path is consistent by construction. The defect was that this was written down nowhere. docs/INSTALL.md's only example was helm install my-tracebloc …, and docs/migration-tools/tenant-config.example.env records the consequence as a fact to work around rather than a defect to fix:

"The Helm release name (NOT always the namespace name; tenant-a's release is tracebloc)"

Hand-installed edges diverged accordingly — and because Helm cannot rename a release, every divergence is permanent. Fifteen resource names are prefixed with whatever was typed once; correcting it means uninstall + reinstall, with downtime and PV re-binding.

The case that prompted it: an engineer's given name ends up in <name>-jobs-manager, <name>-auto-upgrade, <name>-resource-monitor on a customer's production cluster, visible to anyone running kubectl there.

The change

A short docs/INSTALL.md section stating the convention, including the case the installer doesn't cover — a multi-tenant cluster, where one namespace per tenant means release == namespace still holds — plus what not to do: not a person's name; not a bare environment on a shared cluster; keep it short, because Kubernetes truncates at 63 characters and the chart appends ~30 of component suffix.

The claim is a machine check, not prose

The new section asserts something about code in the document an operator reads first. That is the shape that decays into advice for behaviour the code no longer has, so scripts/tests/release-name-equals-namespace.sh:

• reads both arguments out of the installer's own invocation and asserts they are the same expression, whatever that expression is — so renaming the variable keeps it green, and passing a different value does not. It holds no copy of the expected name;
• fails if the doc section is deleted, because a guard defending nothing is not a guard;
• fails closed — an unreadable installer, a missing invocation, or an unparseable argument are findings, not agreement.

Wired into DRIFT_GUARDS (21 entries; the target counts its iterations and refuses to report green on fewer).

Worth recording: the first version of this guard matched a comment mentioning helm upgrade --install on line 1025 rather than the real invocation on line 2272 — the same "prose satisfies a structural guard" class the file exists to prevent, hit while writing it. It is now anchored to the start of a line, and the comment says why.

Mutation evidence

mutation	result
installer passes a different release name	FAIL — prints both values
the doc drops the convention section	FAIL — "protecting nothing"
the invocation disappears entirely	FAIL — refuses to report agreement
baseline, restored	PASS

make drift: all 21 guards green, with the new one verified to have executed. shellcheck clean.

Deliberately not included: fullnameOverride

I built it, proved the default render byte-identical, and reverted it. Filed as tracebloc/backend#2626 with the measurement:

• 153.Release.Name sites across the templates, in five classes — only two of which may follow an override.
• One of the others feeds RELEASE_NAME into helm status / helm rollback in the auto-upgrade script. A blanket substitution catches that env var on the first pass — mine did — and breaks the auto-upgrade, which is the exact failure backend#2620 is about.
• Half-routed, the chart renders prod-auto-upgrade beside myrel-jobs-manager. A partial rename is worse than no rename.

It needs a completeness guard, not a helper. That is a separate change with a separate risk profile.

Note

Trivially conflicts with #860 on the DRIFT_GUARDS line — both append a guard. Whichever merges second takes the other's entry.

Ticket: tracebloc/backend#2621

---

Note

Low Risk
Documentation and a read-only CI drift check; no chart or installer behavior changes.

Overview
Documents the Helm release name must match the namespace convention in docs/INSTALL.md (aligned with the bundled installer’s helm upgrade --install "$TB_NAMESPACE" … --namespace "$TB_NAMESPACE"), with examples for default and multi-tenant installs and practical naming guidance (avoid personal names, avoid bare env names on shared clusters, stay DNS-1123-short).

Adds scripts/tests/release-name-equals-namespace.sh as a drift guard: it parses the installer’s real helm upgrade --install block (line-anchored so comments don’t fake a match), asserts the release and --namespace arguments are the same expression, and fails if the doc section is removed. The guard is wired into DRIFT_GUARDS in the Makefile (21 guards).

^{Reviewed by Cursor Bugbot for commit 4576e58. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 2f98d4a. Configure here.}

[aptracebloc]

Approving. The "release name == namespace" convention is accurate (the installer defaults TB_NAMESPACE and passes one string for both the release arg and --namespace), and the new release-name-equals-namespace.sh drift-guard is genuinely derived-not-restated, fails closed, and is mutation-proof — I verified all three: release≠namespace fails, doc section deleted fails, real invocation removed fails. It's shellcheck-clean and the DRIFT_GUARDS count self-derives, so no hardcoded-count hazard. Green on make drift.

Two low docs-precision nits only (non-blocking): "Every resource … is prefixed" is slightly overbroad (resource-monitor RBAC uses the release as a suffix), and "Kubernetes truncates names at 63" is imprecise (the API server generally rejects >63; Helm caps release names at 53). Neither affects the operator takeaway.

Operational note for whoever merges after client#860: both touch the DRIFT_GUARDS line, so the second to merge must re-append the other's guard entry (and, given the self-count, confirm exp == ran).

— drafted with Claude Code

[LukasWodka]

Closes tracebloc/backend#2621

What was actually wrong

The installer has always named the release after the namespace:

# scripts/lib/install-client-helm.sh:2272
helm upgrade --install "$TB_NAMESPACE""$chart_ref" --namespace "$TB_NAMESPACE" --create-namespace

…defaulting both to tracebloc, and it explains itself at the point of decision (line 1862):

"The on-prem client is one-per-machine and is identified to the backend by its credentials (clientId), not by this name — so we don't ask the user to invent one."

So the self-service path is consistent by construction. The defect was that this was written down nowhere. docs/INSTALL.md's only example was helm install my-tracebloc …, and docs/migration-tools/tenant-config.example.env records the consequence as a fact to work around rather than a defect to fix:

"The Helm release name (NOT always the namespace name; tenant-a's release is tracebloc)"

Hand-installed edges diverged accordingly — and because Helm cannot rename a release, every divergence is permanent. Fifteen resource names are prefixed with whatever was typed once; correcting it means uninstall + reinstall, with downtime and PV re-binding.

The case that prompted it: an engineer's given name ends up in <name>-jobs-manager, <name>-auto-upgrade, <name>-resource-monitor on a customer's production cluster, visible to anyone running kubectl there.

The change

A short docs/INSTALL.md section stating the convention, including the case the installer doesn't cover — a multi-tenant cluster, where one namespace per tenant means release == namespace still holds — plus what not to do: not a person's name; not a bare environment on a shared cluster; keep it short, because Kubernetes truncates at 63 characters and the chart appends ~30 of component suffix.

The claim is a machine check, not prose

The new section asserts something about code in the document an operator reads first. That is the shape that decays into advice for behaviour the code no longer has, so scripts/tests/release-name-equals-namespace.sh:

• reads both arguments out of the installer's own invocation and asserts they are the same expression, whatever that expression is — so renaming the variable keeps it green, and passing a different value does not. It holds no copy of the expected name;
• fails if the doc section is deleted, because a guard defending nothing is not a guard;
• fails closed — an unreadable installer, a missing invocation, or an unparseable argument are findings, not agreement.

Wired into DRIFT_GUARDS (21 entries; the target counts its iterations and refuses to report green on fewer).

Worth recording: the first version of this guard matched a comment mentioning helm upgrade --install on line 1025 rather than the real invocation on line 2272 — the same "prose satisfies a structural guard" class the file exists to prevent, hit while writing it. It is now anchored to the start of a line, and the comment says why.

Mutation evidence

mutation	result
installer passes a different release name	FAIL — prints both values
the doc drops the convention section	FAIL — "protecting nothing"
the invocation disappears entirely	FAIL — refuses to report agreement
baseline, restored	PASS

make drift: all 21 guards green, with the new one verified to have executed. shellcheck clean.

Deliberately not included: fullnameOverride

I built it, proved the default render byte-identical, and reverted it. Filed as tracebloc/backend#2626 with the measurement:

• 153.Release.Name sites across the templates, in five classes — only two of which may follow an override.
• One of the others feeds RELEASE_NAME into helm status / helm rollback in the auto-upgrade script. A blanket substitution catches that env var on the first pass — mine did — and breaks the auto-upgrade, which is the exact failure backend#2620 is about.
• Half-routed, the chart renders prod-auto-upgrade beside myrel-jobs-manager. A partial rename is worse than no rename.

It needs a completeness guard, not a helper. That is a separate change with a separate risk profile.

Note

Trivially conflicts with #860 on the DRIFT_GUARDS line — both append a guard. Whichever merges second takes the other's entry.

Ticket: tracebloc/backend#2621

---

Note

Low Risk
Documentation and a read-only CI drift check; no chart or installer behavior changes.

Overview
Documents the Helm release name must match the namespace convention in docs/INSTALL.md (aligned with the bundled installer’s helm upgrade --install "$TB_NAMESPACE" … --namespace "$TB_NAMESPACE"), with examples for default and multi-tenant installs and practical naming guidance (avoid personal names, avoid bare env names on shared clusters, stay DNS-1123-short).

Adds scripts/tests/release-name-equals-namespace.sh as a drift guard: it parses the installer’s real helm upgrade --install block (line-anchored so comments don’t fake a match), asserts the release and --namespace arguments are the same expression, and fails if the doc section is removed. The guard is wired into DRIFT_GUARDS in the Makefile (21 guards).

^{Reviewed by Cursor Bugbot for commit 4576e58. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 2f98d4a. Configure here.}

[aptracebloc]

Approving. The "release name == namespace" convention is accurate (the installer defaults TB_NAMESPACE and passes one string for both the release arg and --namespace), and the new release-name-equals-namespace.sh drift-guard is genuinely derived-not-restated, fails closed, and is mutation-proof — I verified all three: release≠namespace fails, doc section deleted fails, real invocation removed fails. It's shellcheck-clean and the DRIFT_GUARDS count self-derives, so no hardcoded-count hazard. Green on make drift.

Two low docs-precision nits only (non-blocking): "Every resource … is prefixed" is slightly overbroad (resource-monitor RBAC uses the release as a suffix), and "Kubernetes truncates names at 63" is imprecise (the API server generally rejects >63; Helm caps release names at 53). Neither affects the operator takeaway.

Operational note for whoever merges after client#860: both touch the DRIFT_GUARDS line, so the second to merge must re-append the other's guard entry (and, given the self-count, confirm exp == ran).

— drafted with Claude Code

[LukasWodka]

Closes tracebloc/backend#2621

What was actually wrong

The installer has always named the release after the namespace:

# scripts/lib/install-client-helm.sh:2272
helm upgrade --install "$TB_NAMESPACE""$chart_ref" --namespace "$TB_NAMESPACE" --create-namespace

…defaulting both to tracebloc, and it explains itself at the point of decision (line 1862):

"The on-prem client is one-per-machine and is identified to the backend by its credentials (clientId), not by this name — so we don't ask the user to invent one."

So the self-service path is consistent by construction. The defect was that this was written down nowhere. docs/INSTALL.md's only example was helm install my-tracebloc …, and docs/migration-tools/tenant-config.example.env records the consequence as a fact to work around rather than a defect to fix:

"The Helm release name (NOT always the namespace name; tenant-a's release is tracebloc)"

Hand-installed edges diverged accordingly — and because Helm cannot rename a release, every divergence is permanent. Fifteen resource names are prefixed with whatever was typed once; correcting it means uninstall + reinstall, with downtime and PV re-binding.

The case that prompted it: an engineer's given name ends up in <name>-jobs-manager, <name>-auto-upgrade, <name>-resource-monitor on a customer's production cluster, visible to anyone running kubectl there.

The change

A short docs/INSTALL.md section stating the convention, including the case the installer doesn't cover — a multi-tenant cluster, where one namespace per tenant means release == namespace still holds — plus what not to do: not a person's name; not a bare environment on a shared cluster; keep it short, because Kubernetes truncates at 63 characters and the chart appends ~30 of component suffix.

The claim is a machine check, not prose

The new section asserts something about code in the document an operator reads first. That is the shape that decays into advice for behaviour the code no longer has, so scripts/tests/release-name-equals-namespace.sh:

• reads both arguments out of the installer's own invocation and asserts they are the same expression, whatever that expression is — so renaming the variable keeps it green, and passing a different value does not. It holds no copy of the expected name;
• fails if the doc section is deleted, because a guard defending nothing is not a guard;
• fails closed — an unreadable installer, a missing invocation, or an unparseable argument are findings, not agreement.

Wired into DRIFT_GUARDS (21 entries; the target counts its iterations and refuses to report green on fewer).

Worth recording: the first version of this guard matched a comment mentioning helm upgrade --install on line 1025 rather than the real invocation on line 2272 — the same "prose satisfies a structural guard" class the file exists to prevent, hit while writing it. It is now anchored to the start of a line, and the comment says why.

Mutation evidence

mutation	result
installer passes a different release name	FAIL — prints both values
the doc drops the convention section	FAIL — "protecting nothing"
the invocation disappears entirely	FAIL — refuses to report agreement
baseline, restored	PASS

make drift: all 21 guards green, with the new one verified to have executed. shellcheck clean.

Deliberately not included: fullnameOverride

I built it, proved the default render byte-identical, and reverted it. Filed as tracebloc/backend#2626 with the measurement:

• 153.Release.Name sites across the templates, in five classes — only two of which may follow an override.
• One of the others feeds RELEASE_NAME into helm status / helm rollback in the auto-upgrade script. A blanket substitution catches that env var on the first pass — mine did — and breaks the auto-upgrade, which is the exact failure backend#2620 is about.
• Half-routed, the chart renders prod-auto-upgrade beside myrel-jobs-manager. A partial rename is worse than no rename.

It needs a completeness guard, not a helper. That is a separate change with a separate risk profile.

Note

Trivially conflicts with #860 on the DRIFT_GUARDS line — both append a guard. Whichever merges second takes the other's entry.

Ticket: tracebloc/backend#2621

---

Note

Low Risk
Documentation and a read-only CI drift check; no chart or installer behavior changes.

Overview
Documents the Helm release name must match the namespace convention in docs/INSTALL.md (aligned with the bundled installer’s helm upgrade --install "$TB_NAMESPACE" … --namespace "$TB_NAMESPACE"), with examples for default and multi-tenant installs and practical naming guidance (avoid personal names, avoid bare env names on shared clusters, stay DNS-1123-short).

Adds scripts/tests/release-name-equals-namespace.sh as a drift guard: it parses the installer’s real helm upgrade --install block (line-anchored so comments don’t fake a match), asserts the release and --namespace arguments are the same expression, and fails if the doc section is removed. The guard is wired into DRIFT_GUARDS in the Makefile (21 guards).

^{Reviewed by Cursor Bugbot for commit 4576e58. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 2f98d4a. Configure here.}

[aptracebloc]

Approving. The "release name == namespace" convention is accurate (the installer defaults TB_NAMESPACE and passes one string for both the release arg and --namespace), and the new release-name-equals-namespace.sh drift-guard is genuinely derived-not-restated, fails closed, and is mutation-proof — I verified all three: release≠namespace fails, doc section deleted fails, real invocation removed fails. It's shellcheck-clean and the DRIFT_GUARDS count self-derives, so no hardcoded-count hazard. Green on make drift.

Two low docs-precision nits only (non-blocking): "Every resource … is prefixed" is slightly overbroad (resource-monitor RBAC uses the release as a suffix), and "Kubernetes truncates names at 63" is imprecise (the API server generally rejects >63; Helm caps release names at 53). Neither affects the operator takeaway.

Operational note for whoever merges after client#860: both touch the DRIFT_GUARDS line, so the second to merge must re-append the other's guard entry (and, given the self-count, confirm exp == ran).

— drafted with Claude Code

[LukasWodka]

Closes tracebloc/backend#2621

What was actually wrong

The installer has always named the release after the namespace:

# scripts/lib/install-client-helm.sh:2272
helm upgrade --install "$TB_NAMESPACE""$chart_ref" --namespace "$TB_NAMESPACE" --create-namespace

…defaulting both to tracebloc, and it explains itself at the point of decision (line 1862):

"The on-prem client is one-per-machine and is identified to the backend by its credentials (clientId), not by this name — so we don't ask the user to invent one."

So the self-service path is consistent by construction. The defect was that this was written down nowhere. docs/INSTALL.md's only example was helm install my-tracebloc …, and docs/migration-tools/tenant-config.example.env records the consequence as a fact to work around rather than a defect to fix:

"The Helm release name (NOT always the namespace name; tenant-a's release is tracebloc)"

Hand-installed edges diverged accordingly — and because Helm cannot rename a release, every divergence is permanent. Fifteen resource names are prefixed with whatever was typed once; correcting it means uninstall + reinstall, with downtime and PV re-binding.

The case that prompted it: an engineer's given name ends up in <name>-jobs-manager, <name>-auto-upgrade, <name>-resource-monitor on a customer's production cluster, visible to anyone running kubectl there.

The change

A short docs/INSTALL.md section stating the convention, including the case the installer doesn't cover — a multi-tenant cluster, where one namespace per tenant means release == namespace still holds — plus what not to do: not a person's name; not a bare environment on a shared cluster; keep it short, because Kubernetes truncates at 63 characters and the chart appends ~30 of component suffix.

The claim is a machine check, not prose

The new section asserts something about code in the document an operator reads first. That is the shape that decays into advice for behaviour the code no longer has, so scripts/tests/release-name-equals-namespace.sh:

• reads both arguments out of the installer's own invocation and asserts they are the same expression, whatever that expression is — so renaming the variable keeps it green, and passing a different value does not. It holds no copy of the expected name;
• fails if the doc section is deleted, because a guard defending nothing is not a guard;
• fails closed — an unreadable installer, a missing invocation, or an unparseable argument are findings, not agreement.

Wired into DRIFT_GUARDS (21 entries; the target counts its iterations and refuses to report green on fewer).

Worth recording: the first version of this guard matched a comment mentioning helm upgrade --install on line 1025 rather than the real invocation on line 2272 — the same "prose satisfies a structural guard" class the file exists to prevent, hit while writing it. It is now anchored to the start of a line, and the comment says why.

Mutation evidence

mutation	result
installer passes a different release name	FAIL — prints both values
the doc drops the convention section	FAIL — "protecting nothing"
the invocation disappears entirely	FAIL — refuses to report agreement
baseline, restored	PASS

make drift: all 21 guards green, with the new one verified to have executed. shellcheck clean.

Deliberately not included: fullnameOverride

I built it, proved the default render byte-identical, and reverted it. Filed as tracebloc/backend#2626 with the measurement:

• 153.Release.Name sites across the templates, in five classes — only two of which may follow an override.
• One of the others feeds RELEASE_NAME into helm status / helm rollback in the auto-upgrade script. A blanket substitution catches that env var on the first pass — mine did — and breaks the auto-upgrade, which is the exact failure backend#2620 is about.
• Half-routed, the chart renders prod-auto-upgrade beside myrel-jobs-manager. A partial rename is worse than no rename.

It needs a completeness guard, not a helper. That is a separate change with a separate risk profile.

Note

Trivially conflicts with #860 on the DRIFT_GUARDS line — both append a guard. Whichever merges second takes the other's entry.

Ticket: tracebloc/backend#2621

---

Note

Low Risk
Documentation and a read-only CI drift check; no chart or installer behavior changes.

Overview
Documents the Helm release name must match the namespace convention in docs/INSTALL.md (aligned with the bundled installer’s helm upgrade --install "$TB_NAMESPACE" … --namespace "$TB_NAMESPACE"), with examples for default and multi-tenant installs and practical naming guidance (avoid personal names, avoid bare env names on shared clusters, stay DNS-1123-short).

Adds scripts/tests/release-name-equals-namespace.sh as a drift guard: it parses the installer’s real helm upgrade --install block (line-anchored so comments don’t fake a match), asserts the release and --namespace arguments are the same expression, and fails if the doc section is removed. The guard is wired into DRIFT_GUARDS in the Makefile (21 guards).

^{Reviewed by Cursor Bugbot for commit 4576e58. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 2f98d4a. Configure here.}

[aptracebloc]

Approving. The "release name == namespace" convention is accurate (the installer defaults TB_NAMESPACE and passes one string for both the release arg and --namespace), and the new release-name-equals-namespace.sh drift-guard is genuinely derived-not-restated, fails closed, and is mutation-proof — I verified all three: release≠namespace fails, doc section deleted fails, real invocation removed fails. It's shellcheck-clean and the DRIFT_GUARDS count self-derives, so no hardcoded-count hazard. Green on make drift.

Two low docs-precision nits only (non-blocking): "Every resource … is prefixed" is slightly overbroad (resource-monitor RBAC uses the release as a suffix), and "Kubernetes truncates names at 63" is imprecise (the API server generally rejects >63; Helm caps release names at 53). Neither affects the operator takeaway.

Operational note for whoever merges after client#860: both touch the DRIFT_GUARDS line, so the second to merge must re-append the other's guard entry (and, given the self-count, confirm exp == ran).

— drafted with Claude Code

[LukasWodka]

Closes tracebloc/backend#2621

What was actually wrong

The installer has always named the release after the namespace:

# scripts/lib/install-client-helm.sh:2272
helm upgrade --install "$TB_NAMESPACE""$chart_ref" --namespace "$TB_NAMESPACE" --create-namespace

…defaulting both to tracebloc, and it explains itself at the point of decision (line 1862):

"The on-prem client is one-per-machine and is identified to the backend by its credentials (clientId), not by this name — so we don't ask the user to invent one."

So the self-service path is consistent by construction. The defect was that this was written down nowhere. docs/INSTALL.md's only example was helm install my-tracebloc …, and docs/migration-tools/tenant-config.example.env records the consequence as a fact to work around rather than a defect to fix:

"The Helm release name (NOT always the namespace name; tenant-a's release is tracebloc)"

Hand-installed edges diverged accordingly — and because Helm cannot rename a release, every divergence is permanent. Fifteen resource names are prefixed with whatever was typed once; correcting it means uninstall + reinstall, with downtime and PV re-binding.

The case that prompted it: an engineer's given name ends up in <name>-jobs-manager, <name>-auto-upgrade, <name>-resource-monitor on a customer's production cluster, visible to anyone running kubectl there.

The change

A short docs/INSTALL.md section stating the convention, including the case the installer doesn't cover — a multi-tenant cluster, where one namespace per tenant means release == namespace still holds — plus what not to do: not a person's name; not a bare environment on a shared cluster; keep it short, because Kubernetes truncates at 63 characters and the chart appends ~30 of component suffix.

The claim is a machine check, not prose

The new section asserts something about code in the document an operator reads first. That is the shape that decays into advice for behaviour the code no longer has, so scripts/tests/release-name-equals-namespace.sh:

• reads both arguments out of the installer's own invocation and asserts they are the same expression, whatever that expression is — so renaming the variable keeps it green, and passing a different value does not. It holds no copy of the expected name;
• fails if the doc section is deleted, because a guard defending nothing is not a guard;
• fails closed — an unreadable installer, a missing invocation, or an unparseable argument are findings, not agreement.

Wired into DRIFT_GUARDS (21 entries; the target counts its iterations and refuses to report green on fewer).

Worth recording: the first version of this guard matched a comment mentioning helm upgrade --install on line 1025 rather than the real invocation on line 2272 — the same "prose satisfies a structural guard" class the file exists to prevent, hit while writing it. It is now anchored to the start of a line, and the comment says why.

Mutation evidence

mutation	result
installer passes a different release name	FAIL — prints both values
the doc drops the convention section	FAIL — "protecting nothing"
the invocation disappears entirely	FAIL — refuses to report agreement
baseline, restored	PASS

make drift: all 21 guards green, with the new one verified to have executed. shellcheck clean.

Deliberately not included: fullnameOverride

I built it, proved the default render byte-identical, and reverted it. Filed as tracebloc/backend#2626 with the measurement:

• 153.Release.Name sites across the templates, in five classes — only two of which may follow an override.
• One of the others feeds RELEASE_NAME into helm status / helm rollback in the auto-upgrade script. A blanket substitution catches that env var on the first pass — mine did — and breaks the auto-upgrade, which is the exact failure backend#2620 is about.
• Half-routed, the chart renders prod-auto-upgrade beside myrel-jobs-manager. A partial rename is worse than no rename.

It needs a completeness guard, not a helper. That is a separate change with a separate risk profile.

Note

Trivially conflicts with #860 on the DRIFT_GUARDS line — both append a guard. Whichever merges second takes the other's entry.

Ticket: tracebloc/backend#2621

---

Note

Low Risk
Documentation and a read-only CI drift check; no chart or installer behavior changes.

Overview
Documents the Helm release name must match the namespace convention in docs/INSTALL.md (aligned with the bundled installer’s helm upgrade --install "$TB_NAMESPACE" … --namespace "$TB_NAMESPACE"), with examples for default and multi-tenant installs and practical naming guidance (avoid personal names, avoid bare env names on shared clusters, stay DNS-1123-short).

Adds scripts/tests/release-name-equals-namespace.sh as a drift guard: it parses the installer’s real helm upgrade --install block (line-anchored so comments don’t fake a match), asserts the release and --namespace arguments are the same expression, and fails if the doc section is removed. The guard is wired into DRIFT_GUARDS in the Makefile (21 guards).

^{Reviewed by Cursor Bugbot for commit 4576e58. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 2f98d4a. Configure here.}

[aptracebloc]

Approving. The "release name == namespace" convention is accurate (the installer defaults TB_NAMESPACE and passes one string for both the release arg and --namespace), and the new release-name-equals-namespace.sh drift-guard is genuinely derived-not-restated, fails closed, and is mutation-proof — I verified all three: release≠namespace fails, doc section deleted fails, real invocation removed fails. It's shellcheck-clean and the DRIFT_GUARDS count self-derives, so no hardcoded-count hazard. Green on make drift.

Two low docs-precision nits only (non-blocking): "Every resource … is prefixed" is slightly overbroad (resource-monitor RBAC uses the release as a suffix), and "Kubernetes truncates names at 63" is imprecise (the API server generally rejects >63; Helm caps release names at 53). Neither affects the operator takeaway.

Operational note for whoever merges after client#860: both touch the DRIFT_GUARDS line, so the second to merge must re-append the other's guard entry (and, given the self-count, confirm exp == ran).

— drafted with Claude Code

[LukasWodka]

Closes tracebloc/backend#2621

What was actually wrong

The installer has always named the release after the namespace:

# scripts/lib/install-client-helm.sh:2272
helm upgrade --install "$TB_NAMESPACE""$chart_ref" --namespace "$TB_NAMESPACE" --create-namespace

…defaulting both to tracebloc, and it explains itself at the point of decision (line 1862):

"The on-prem client is one-per-machine and is identified to the backend by its credentials (clientId), not by this name — so we don't ask the user to invent one."

So the self-service path is consistent by construction. The defect was that this was written down nowhere. docs/INSTALL.md's only example was helm install my-tracebloc …, and docs/migration-tools/tenant-config.example.env records the consequence as a fact to work around rather than a defect to fix:

"The Helm release name (NOT always the namespace name; tenant-a's release is tracebloc)"

Hand-installed edges diverged accordingly — and because Helm cannot rename a release, every divergence is permanent. Fifteen resource names are prefixed with whatever was typed once; correcting it means uninstall + reinstall, with downtime and PV re-binding.

The case that prompted it: an engineer's given name ends up in <name>-jobs-manager, <name>-auto-upgrade, <name>-resource-monitor on a customer's production cluster, visible to anyone running kubectl there.

The change

A short docs/INSTALL.md section stating the convention, including the case the installer doesn't cover — a multi-tenant cluster, where one namespace per tenant means release == namespace still holds — plus what not to do: not a person's name; not a bare environment on a shared cluster; keep it short, because Kubernetes truncates at 63 characters and the chart appends ~30 of component suffix.

The claim is a machine check, not prose

The new section asserts something about code in the document an operator reads first. That is the shape that decays into advice for behaviour the code no longer has, so scripts/tests/release-name-equals-namespace.sh:

• reads both arguments out of the installer's own invocation and asserts they are the same expression, whatever that expression is — so renaming the variable keeps it green, and passing a different value does not. It holds no copy of the expected name;
• fails if the doc section is deleted, because a guard defending nothing is not a guard;
• fails closed — an unreadable installer, a missing invocation, or an unparseable argument are findings, not agreement.

Wired into DRIFT_GUARDS (21 entries; the target counts its iterations and refuses to report green on fewer).

Worth recording: the first version of this guard matched a comment mentioning helm upgrade --install on line 1025 rather than the real invocation on line 2272 — the same "prose satisfies a structural guard" class the file exists to prevent, hit while writing it. It is now anchored to the start of a line, and the comment says why.

Mutation evidence

mutation	result
installer passes a different release name	FAIL — prints both values
the doc drops the convention section	FAIL — "protecting nothing"
the invocation disappears entirely	FAIL — refuses to report agreement
baseline, restored	PASS

make drift: all 21 guards green, with the new one verified to have executed. shellcheck clean.

Deliberately not included: fullnameOverride

I built it, proved the default render byte-identical, and reverted it. Filed as tracebloc/backend#2626 with the measurement:

• 153.Release.Name sites across the templates, in five classes — only two of which may follow an override.
• One of the others feeds RELEASE_NAME into helm status / helm rollback in the auto-upgrade script. A blanket substitution catches that env var on the first pass — mine did — and breaks the auto-upgrade, which is the exact failure backend#2620 is about.
• Half-routed, the chart renders prod-auto-upgrade beside myrel-jobs-manager. A partial rename is worse than no rename.

It needs a completeness guard, not a helper. That is a separate change with a separate risk profile.

Note

Trivially conflicts with #860 on the DRIFT_GUARDS line — both append a guard. Whichever merges second takes the other's entry.

Ticket: tracebloc/backend#2621

---

Note

Low Risk
Documentation and a read-only CI drift check; no chart or installer behavior changes.

Overview
Documents the Helm release name must match the namespace convention in docs/INSTALL.md (aligned with the bundled installer’s helm upgrade --install "$TB_NAMESPACE" … --namespace "$TB_NAMESPACE"), with examples for default and multi-tenant installs and practical naming guidance (avoid personal names, avoid bare env names on shared clusters, stay DNS-1123-short).

Adds scripts/tests/release-name-equals-namespace.sh as a drift guard: it parses the installer’s real helm upgrade --install block (line-anchored so comments don’t fake a match), asserts the release and --namespace arguments are the same expression, and fails if the doc section is removed. The guard is wired into DRIFT_GUARDS in the Makefile (21 guards).

^{Reviewed by Cursor Bugbot for commit 4576e58. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 2f98d4a. Configure here.}

[aptracebloc]

Approving. The "release name == namespace" convention is accurate (the installer defaults TB_NAMESPACE and passes one string for both the release arg and --namespace), and the new release-name-equals-namespace.sh drift-guard is genuinely derived-not-restated, fails closed, and is mutation-proof — I verified all three: release≠namespace fails, doc section deleted fails, real invocation removed fails. It's shellcheck-clean and the DRIFT_GUARDS count self-derives, so no hardcoded-count hazard. Green on make drift.

Two low docs-precision nits only (non-blocking): "Every resource … is prefixed" is slightly overbroad (resource-monitor RBAC uses the release as a suffix), and "Kubernetes truncates names at 63" is imprecise (the API server generally rejects >63; Helm caps release names at 53). Neither affects the operator takeaway.

Operational note for whoever merges after client#860: both touch the DRIFT_GUARDS line, so the second to merge must re-append the other's guard entry (and, given the self-count, confirm exp == ran).

— drafted with Claude Code

[LukasWodka]

Closes tracebloc/backend#2621

What was actually wrong

The installer has always named the release after the namespace:

# scripts/lib/install-client-helm.sh:2272
helm upgrade --install "$TB_NAMESPACE""$chart_ref" --namespace "$TB_NAMESPACE" --create-namespace

…defaulting both to tracebloc, and it explains itself at the point of decision (line 1862):

"The on-prem client is one-per-machine and is identified to the backend by its credentials (clientId), not by this name — so we don't ask the user to invent one."

So the self-service path is consistent by construction. The defect was that this was written down nowhere. docs/INSTALL.md's only example was helm install my-tracebloc …, and docs/migration-tools/tenant-config.example.env records the consequence as a fact to work around rather than a defect to fix:

"The Helm release name (NOT always the namespace name; tenant-a's release is tracebloc)"

Hand-installed edges diverged accordingly — and because Helm cannot rename a release, every divergence is permanent. Fifteen resource names are prefixed with whatever was typed once; correcting it means uninstall + reinstall, with downtime and PV re-binding.

The case that prompted it: an engineer's given name ends up in <name>-jobs-manager, <name>-auto-upgrade, <name>-resource-monitor on a customer's production cluster, visible to anyone running kubectl there.

The change

A short docs/INSTALL.md section stating the convention, including the case the installer doesn't cover — a multi-tenant cluster, where one namespace per tenant means release == namespace still holds — plus what not to do: not a person's name; not a bare environment on a shared cluster; keep it short, because Kubernetes truncates at 63 characters and the chart appends ~30 of component suffix.

The claim is a machine check, not prose

The new section asserts something about code in the document an operator reads first. That is the shape that decays into advice for behaviour the code no longer has, so scripts/tests/release-name-equals-namespace.sh:

• reads both arguments out of the installer's own invocation and asserts they are the same expression, whatever that expression is — so renaming the variable keeps it green, and passing a different value does not. It holds no copy of the expected name;
• fails if the doc section is deleted, because a guard defending nothing is not a guard;
• fails closed — an unreadable installer, a missing invocation, or an unparseable argument are findings, not agreement.

Wired into DRIFT_GUARDS (21 entries; the target counts its iterations and refuses to report green on fewer).

Worth recording: the first version of this guard matched a comment mentioning helm upgrade --install on line 1025 rather than the real invocation on line 2272 — the same "prose satisfies a structural guard" class the file exists to prevent, hit while writing it. It is now anchored to the start of a line, and the comment says why.

Mutation evidence

mutation	result
installer passes a different release name	FAIL — prints both values
the doc drops the convention section	FAIL — "protecting nothing"
the invocation disappears entirely	FAIL — refuses to report agreement
baseline, restored	PASS

make drift: all 21 guards green, with the new one verified to have executed. shellcheck clean.

Deliberately not included: fullnameOverride

I built it, proved the default render byte-identical, and reverted it. Filed as tracebloc/backend#2626 with the measurement:

• 153.Release.Name sites across the templates, in five classes — only two of which may follow an override.
• One of the others feeds RELEASE_NAME into helm status / helm rollback in the auto-upgrade script. A blanket substitution catches that env var on the first pass — mine did — and breaks the auto-upgrade, which is the exact failure backend#2620 is about.
• Half-routed, the chart renders prod-auto-upgrade beside myrel-jobs-manager. A partial rename is worse than no rename.

It needs a completeness guard, not a helper. That is a separate change with a separate risk profile.

Note

Trivially conflicts with #860 on the DRIFT_GUARDS line — both append a guard. Whichever merges second takes the other's entry.

Ticket: tracebloc/backend#2621

---

Note

Low Risk
Documentation and a read-only CI drift check; no chart or installer behavior changes.

Overview
Documents the Helm release name must match the namespace convention in docs/INSTALL.md (aligned with the bundled installer’s helm upgrade --install "$TB_NAMESPACE" … --namespace "$TB_NAMESPACE"), with examples for default and multi-tenant installs and practical naming guidance (avoid personal names, avoid bare env names on shared clusters, stay DNS-1123-short).

Adds scripts/tests/release-name-equals-namespace.sh as a drift guard: it parses the installer’s real helm upgrade --install block (line-anchored so comments don’t fake a match), asserts the release and --namespace arguments are the same expression, and fails if the doc section is removed. The guard is wired into DRIFT_GUARDS in the Makefile (21 guards).

^{Reviewed by Cursor Bugbot for commit 4576e58. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 2f98d4a. Configure here.}

[aptracebloc]

Approving. The "release name == namespace" convention is accurate (the installer defaults TB_NAMESPACE and passes one string for both the release arg and --namespace), and the new release-name-equals-namespace.sh drift-guard is genuinely derived-not-restated, fails closed, and is mutation-proof — I verified all three: release≠namespace fails, doc section deleted fails, real invocation removed fails. It's shellcheck-clean and the DRIFT_GUARDS count self-derives, so no hardcoded-count hazard. Green on make drift.

Two low docs-precision nits only (non-blocking): "Every resource … is prefixed" is slightly overbroad (resource-monitor RBAC uses the release as a suffix), and "Kubernetes truncates names at 63" is imprecise (the API server generally rejects >63; Helm caps release names at 53). Neither affects the operator takeaway.

Operational note for whoever merges after client#860: both touch the DRIFT_GUARDS line, so the second to merge must re-append the other's guard entry (and, given the self-count, confirm exp == ran).

— drafted with Claude Code

[LukasWodka]

Closes tracebloc/backend#2621

What was actually wrong

The installer has always named the release after the namespace:

# scripts/lib/install-client-helm.sh:2272
helm upgrade --install "$TB_NAMESPACE""$chart_ref" --namespace "$TB_NAMESPACE" --create-namespace

…defaulting both to tracebloc, and it explains itself at the point of decision (line 1862):

"The on-prem client is one-per-machine and is identified to the backend by its credentials (clientId), not by this name — so we don't ask the user to invent one."

So the self-service path is consistent by construction. The defect was that this was written down nowhere. docs/INSTALL.md's only example was helm install my-tracebloc …, and docs/migration-tools/tenant-config.example.env records the consequence as a fact to work around rather than a defect to fix:

"The Helm release name (NOT always the namespace name; tenant-a's release is tracebloc)"

Hand-installed edges diverged accordingly — and because Helm cannot rename a release, every divergence is permanent. Fifteen resource names are prefixed with whatever was typed once; correcting it means uninstall + reinstall, with downtime and PV re-binding.

The case that prompted it: an engineer's given name ends up in <name>-jobs-manager, <name>-auto-upgrade, <name>-resource-monitor on a customer's production cluster, visible to anyone running kubectl there.

The change

A short docs/INSTALL.md section stating the convention, including the case the installer doesn't cover — a multi-tenant cluster, where one namespace per tenant means release == namespace still holds — plus what not to do: not a person's name; not a bare environment on a shared cluster; keep it short, because Kubernetes truncates at 63 characters and the chart appends ~30 of component suffix.

The claim is a machine check, not prose

The new section asserts something about code in the document an operator reads first. That is the shape that decays into advice for behaviour the code no longer has, so scripts/tests/release-name-equals-namespace.sh:

• reads both arguments out of the installer's own invocation and asserts they are the same expression, whatever that expression is — so renaming the variable keeps it green, and passing a different value does not. It holds no copy of the expected name;
• fails if the doc section is deleted, because a guard defending nothing is not a guard;
• fails closed — an unreadable installer, a missing invocation, or an unparseable argument are findings, not agreement.

Wired into DRIFT_GUARDS (21 entries; the target counts its iterations and refuses to report green on fewer).

Worth recording: the first version of this guard matched a comment mentioning helm upgrade --install on line 1025 rather than the real invocation on line 2272 — the same "prose satisfies a structural guard" class the file exists to prevent, hit while writing it. It is now anchored to the start of a line, and the comment says why.

Mutation evidence

mutation	result
installer passes a different release name	FAIL — prints both values
the doc drops the convention section	FAIL — "protecting nothing"
the invocation disappears entirely	FAIL — refuses to report agreement
baseline, restored	PASS

make drift: all 21 guards green, with the new one verified to have executed. shellcheck clean.

Deliberately not included: fullnameOverride

I built it, proved the default render byte-identical, and reverted it. Filed as tracebloc/backend#2626 with the measurement:

• 153.Release.Name sites across the templates, in five classes — only two of which may follow an override.
• One of the others feeds RELEASE_NAME into helm status / helm rollback in the auto-upgrade script. A blanket substitution catches that env var on the first pass — mine did — and breaks the auto-upgrade, which is the exact failure backend#2620 is about.
• Half-routed, the chart renders prod-auto-upgrade beside myrel-jobs-manager. A partial rename is worse than no rename.

It needs a completeness guard, not a helper. That is a separate change with a separate risk profile.

Note

Trivially conflicts with #860 on the DRIFT_GUARDS line — both append a guard. Whichever merges second takes the other's entry.

Ticket: tracebloc/backend#2621

---

Note

Low Risk
Documentation and a read-only CI drift check; no chart or installer behavior changes.

Overview
Documents the Helm release name must match the namespace convention in docs/INSTALL.md (aligned with the bundled installer’s helm upgrade --install "$TB_NAMESPACE" … --namespace "$TB_NAMESPACE"), with examples for default and multi-tenant installs and practical naming guidance (avoid personal names, avoid bare env names on shared clusters, stay DNS-1123-short).

Adds scripts/tests/release-name-equals-namespace.sh as a drift guard: it parses the installer’s real helm upgrade --install block (line-anchored so comments don’t fake a match), asserts the release and --namespace arguments are the same expression, and fails if the doc section is removed. The guard is wired into DRIFT_GUARDS in the Makefile (21 guards).

^{Reviewed by Cursor Bugbot for commit 4576e58. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 2f98d4a. Configure here.}

[aptracebloc]

Approving. The "release name == namespace" convention is accurate (the installer defaults TB_NAMESPACE and passes one string for both the release arg and --namespace), and the new release-name-equals-namespace.sh drift-guard is genuinely derived-not-restated, fails closed, and is mutation-proof — I verified all three: release≠namespace fails, doc section deleted fails, real invocation removed fails. It's shellcheck-clean and the DRIFT_GUARDS count self-derives, so no hardcoded-count hazard. Green on make drift.

Two low docs-precision nits only (non-blocking): "Every resource … is prefixed" is slightly overbroad (resource-monitor RBAC uses the release as a suffix), and "Kubernetes truncates names at 63" is imprecise (the API server generally rejects >63; Helm caps release names at 53). Neither affects the operator takeaway.

Operational note for whoever merges after client#860: both touch the DRIFT_GUARDS line, so the second to merge must re-append the other's guard entry (and, given the self-count, confirm exp == ran).

— drafted with Claude Code