refactor(config): retire the vendor config sections behind a generic compatibility window (WS6)

[BenKurrek]

What this is

CHECKLIST WS6 — the config narrows row (vendor sections) and the reject_legacy_slack_config half of the CLI vendor-shed row. Both rows are re-measured against live main and amended in place with dated notes quoting what they replace.

The measurement that changed the shape of this PR

The row says the vendor sections "move to package-owned admin-config/data". Measured on live main first: SlackSection and TelegramSection had nothing to move.

Their only consumers were reject_legacy_slack_config (which exists to reject them), config list's display expansion, and update_slack_enabled. Zero runtime readers. The enablement gate they fed — [slack].enabled / IRONCLAW_REBORN_SLACK_ENABLED and the Telegram equivalents — was deleted by #6116 (2026-07-21), which removed serve_slack.rs/serve_telegram.rs outright. Nothing replaced it: the ingress route is generic and always mounted, gated only by whether the extension's signing secret is registered (503 until it is, 401 on mismatch).

Two user-visible consequences, live until this PR:

1. ironclaw config set slack.enabled true printed slack.enabled: saved and changed nothing.
2. Five operator-facing docs still taught that flag. docs/reborn/setup-slack-for-reborn-binary.md called it the binary's "one gate", described IRONCLAW_REBORN_SLACK_ENABLED=false as a "deployment kill switch" (it is not — Slack stays mounted), and offered a troubleshooting step that could never fix anything.

So this is a deletion with a compatibility window, not a move.

What landed

• Deleted SlackSection, SlackChannelRouteSection, TelegramSection, their three builders, and update_slack_enabled.
• RebornConfigFile no longer names a vendor. Retired sections are split off the raw document before the typed parse, so the schema keeps deny_unknown_fields without declaring a retired key.
• reject_legacy_slack_config → reject_retired_config_sections: a call into one RETIRED_SECTIONS table in ironclaw_reborn_config. That is PROPOSAL §12.2's "the existing reject_legacy_slack_config shape, relocated" — the two WS6 rows described the same seam from opposite sides.
• CLI shed ConfigKey::SlackEnabled, its shape validator, its write path, and slack_remediation_text (whose only production caller was that key). config set slack.enabled now answers with migration guidance instead of a typo report.
• Corrected the five stale docs + .env.example.

The compatibility window, widened rather than merely preserved

	before	after
existing file with [slack]	parses	parses
retired setup key at serve	fails closed	fails closed, same message
inert section (enabled only)	boots, silently ignored	boots and says so
[telegram]	silently ignored	announced
inline-secret rejection	9 hardcoded Slack keys	every string at any depth, any retired section

Decision under delegated authority

Recorded as a dated amendment at PROPOSAL §6.10.3 — not a new §12.1x slot, because §12.11's D-A…D-J are the last on main and I did not want to collide with an open PR's numbering.

Ruling: a retired config.toml section stays in ironclaw_config as a gravestone, expressed as data in one table. It does not become package-owned. A boot-time migration check runs before any extension exists, and this crate may hold no workspace dependency. The division that holds: a package owns its live admin configuration; the config crate owns the retired keys it once defined itself.

Alternatives rejected:

• Delete outright — breaks every existing operator file against deny_unknown_fields, the exact constraint the row exists for.
• serde(flatten) catch-all — silently disables deny_unknown_fields, trading a live typo-catcher for a gravestone.
• Two-pass parse for every file — rejected on measurement, not taste: routing through toml::Table loses the line/column span on unknown-field errors (TOML parse error at line 5, column 1 + caret becomes a bare unknown field ... in `boot` ). The shipped form re-parses the original text whenever no retired section is present, so every clean file keeps the better diagnostics; the degraded span is confined to files already being told to remove a section. Pinned by unknown_field_errors_keep_their_span_when_no_section_is_retired.

Sabotage testing

Every guard was broken deliberately and confirmed red with the right message, then restored.

sabotage	guard	result
drop slack_user_id from rejected_keys	retired_setup_key_fails_closed_with_migration_guidance	RED
always route through toml::Table	unknown_field_errors_keep_their_span_...	RED
drop the inline-secret walk	retired_section_values_are_still_inline_secret_checked (+ nested)	RED
remove the retired-key check in config set	set.rs unit + smoke.rs binary-tier	RED (both)
no-op the serve-time check	serve_startup_rejects_loaded_config_with_retired_setup_fields	RED
drop the splitter's scalar re-insert	retired_section_name_used_as_a_scalar_...	GREEN — guard was inert

The last row is why this discipline exists. That test only covered slack = 1 alone, which leaves retired_sections empty — so the fast path re-parses the original text and catches it with or without the re-insert. The re-insert is load-bearing only when a genuine retired section forces the slow path (slack = 1 beside [telegram] then silently bypasses deny_unknown_fields). Widened; it now goes red.

Also recorded rather than quietly repaired: every_declared_rejected_key_fails_the_boot_closed builds its input from the table it checks, so it proves reachability, not fidelity — renaming a row keeps it green. Stated in the test doc.

Test accounting (un-masking)

Unfiltered per-crate --list name-by-name, before and after, on a quiescent tree.

• ironclaw_reborn_config: 105 → 112. −2 (update_slack_enabled_writes_new_section, ..._preserves_unrelated_config_and_flips_value — subject deleted), +9 retired-section tests.
• ironclaw (CLI): 627 → 626. Three renamed/repurposed pairs (slack_enabled_round_trips → retired_config_key_is_refused_...; serve_startup_..._legacy_slack_fields → ..._retired_setup_fields, which also gained the [telegram] case; config_set_slack_enabled_prints_restart_exactly_once → config_set_retired_slack_key_is_refused_...). One genuine net removal: slack_enabled_validator_requires_bool_shape, whose subject (ConfigKey::SlackEnabled's bool-shape arm) no longer exists.
• The "restart printed exactly once" invariant the deleted smoke test carried is not lost — config_set_google_client_id_writes_config_toml asserts the same matches("service restart").count() == 1 on a key that still exists. Checked explicitly rather than assumed.
• cargo test -p ironclaw_architecture: green.

Exception / allowlist accounting

Extension-specificity ALLOWLIST: 127 → 125, and WS0_EXTENSION_SPECIFICITY_ALLOWLIST_BASELINE lowered 129 → 125 to lock the new floor (the doc on that const requires lowering it in the same PR that deletes entries).

Method: the length was read back from the compiler, not counted by eye or regex — the baseline was temporarily set to 0 so the ratchet test reported ALLOWLIST grew to 125 entries, then set to that number. Four entries deleted (config_file.rs×{slack,telegram}, lib.rs×{slack,telegram}), two added (retired_sections.rs×{slack,telegram}).

LAYER_MATRIX_EXCEPTIONS is untouched — still 10 on main; none of the survivors are this row's to remove.

Not done, deliberately

• GoogleSection + the Google update pipeline. Genuinely live — read by the CLI's ~200-line OAuth resolution. It is one slice with the CLI row's Google half; doing the config half alone would strand it.
• capability_remediation.rs. The row calls it a Google copy to move. It is not dead: the filename greps to two files, but its five functions have real consumers in four crates (ironclaw_extension_manager, ironclaw_extension_host ×2, ironclaw_reborn_cli ×3). A move is a four-crate change, not a file move.
• The ironclaw_reborn_cli → app/ironclaw_cli dir rename. Renames are parked program-wide; this one would conflict with every open PR touching the CLI. Said so on the row.

Filed, not silently patched

#7115 — docker/reborn/entrypoint.sh:148 gates its legacy-Slack config migration on IRONCLAW_REBORN_SLACK_ENABLED not being truthy. That var has had no Rust reader since #6116, and the docs (until this PR) told operators to set it — so following the documented instruction disabled the auto-migration and left the container failing to boot on the retired setup fields. Docker-image surface, outside this PR's crate scope.

Also corrected in place, since it directly contradicts what this PR builds: docs/reborn/extension-runtime/checklist.md's DEL-3 box cited rejects_retired_slack_section, a test added by 4c8195a3ca and removed when the parse-only shim came back — a phantom citation, same class as #6945. Its claim that a stale [slack] "hard-fails config parse" was also never true of shipped code (the refusal was at serve, setup fields only), and is deliberately still not true: an operator with a stale section must be able to run config list/config set to fix it.

A CI gate this PR had to widen

Tests (Reborn) failed on the first push with unclassified pull-request path: .env.example. The Reborn PR test planner is fail-closed on unknown paths and had a rule for repo-root *.md but not for its non-.md sibling — so any PR correcting an env-var comment aborted the planner and failed the whole roll-up, on a change with no build surface. Nothing reads .env.example: no crate, test, or workflow; only doc comments name it.

Fixed by classifying the path, not by dropping the (correct) doc change and not by loosening the fail-closed arm — following the .claude/ precedent added 2026-08-03, whose comment in that same file states exactly this rule. The regression test asserts four things, because a one-sided version of it would be the inert kind: the path is accepted, it selects no Rust lane (so a future "classification" that turns a comment fix into a full matrix also fails), a real change riding along still selects its lane, and an unknown root file (.env.local) still raises. Sabotage-verified: removing the classification turns it red.

One incidental fix worth naming

The inline-secret test fixtures started as Slack-shaped tokens (xoxb-…) and GitHub push protection rejected the push. They are now OpenAI-shaped (sk-proj-…, the pattern already used elsewhere in this file), which is strictly better as a test: the guard is prefix-based across every known vendor, not keyed to the section a value appears in, so a Slack-shaped fixture inside [slack] was quietly under-specifying what it proved. Noted in the test doc so nobody "fixes" it back.

Guidance travelling with the change

crates/ironclaw_reborn_config/AGENTS.md gains the new module, a "no new per-vendor section" boundary rule pointing at the shrink-only gate, and a "Retiring a config section" recipe — including grep docs/ as well as crates/, which is the lesson this PR paid for.

🤖 Generated with Claude Code

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[railway-app]

🚅 Deployed to the ironclaw-pr-7117 environment in ironclaw-ci-preview

Service	Status	Web	Updated (UTC)
ironclaw	✅ Success (View Logs)	Web	Aug 4, 2026 at 10:23 am

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 2daef030-f604-47c0-ba97-527df28ce543

📥 Commits

Reviewing files that changed from the base of the PR and between f9dc381 and cc9c4df.

📒 Files selected for processing (2)

• scripts/ci/reborn_pr_test_plan.py
• scripts/ci/test_reborn_pr_test_plan.py

---

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Slack and Telegram setup is managed through WebUI extensions and the encrypted secret store.
  • Their routes remain available but return 503 until setup is complete.
  • Slack OAuth redirect URLs are derived from the instance’s public base URL.

• Bug Fixes

  • Legacy configuration keys now provide migration guidance or deprecation notices.
  • Obsolete setup fields correctly prevent startup.
  • Retired configuration sections no longer affect active settings.

• Documentation

  • Updated deployment, setup, troubleshooting, configuration, and CLI guidance.

Walkthrough

Slack and Telegram TOML configuration is retired. The configuration crate preserves legacy sections for migration checks and notices. CLI writes reject retired keys, startup applies generic migration handling, and documentation describes WebUI-managed activation.

Changes

Retired channel configuration

Layer / File(s)	Summary
Retired-section compatibility model crates/ironclaw_reborn_config/src/retired_sections.rs, crates/ironclaw_reborn_config/src/config_file.rs, crates/ironclaw_reborn_config/src/lib.rs, crates/ironclaw_reborn_config/AGENTS.md	Retired Slack and Telegram tables are extracted before typed deserialization. Setup fields fail with migration errors. Inert sections emit notices. Nested strings are scanned for secrets.
CLI and startup retirement handling crates/ironclaw_reborn_cli/src/commands/config/*, crates/ironclaw_reborn_cli/src/commands/serve.rs, crates/ironclaw_reborn_cli/tests/smoke.rs	slack.enabled is no longer classified or written. Retired keys return extension guidance. Startup rejects retired setup fields and allows inert sections with notices.
Documentation and architecture invariants .env.example, README.md, docs/channels/*, docs/reborn/*, docs/capabilities/configuration.mdx, docs/using/cli.mdx, docs/internal/live-canary.md, crates/ironclaw_architecture/tests/reborn_extension_specificity.rs	Documentation removes configuration-based activation and describes WebUI extension setup, always-mounted routes, 503 behavior, and legacy-section handling. Architecture allowlist entries and the baseline are updated.
CI classification and build-support gating scripts/ci/reborn_pr_test_plan.py, scripts/ci/test_reborn_pr_test_plan.py, crates/ironclaw_reborn_composition/src/runtime.rs	.env.example is classified as an ignored root documentation file. Tests cover documentation-only, mixed, and unknown-root-file cases. Test-only imports are conditionally compiled.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Operator
  participant ConfigSetCommand
  participant ConfigFile
  participant Serve
  participant WebUIExtensions
  Operator->>ConfigSetCommand: set slack.enabled
  ConfigSetCommand->>ConfigFile: request retired-key guidance
  ConfigSetCommand-->>Operator: reject write and show /extensions
  Operator->>WebUIExtensions: install and configure extension
  Operator->>Serve: start service
  Serve->>ConfigFile: inspect retired sections
  ConfigFile-->>Serve: migration error or deprecation notice

Loading

Possibly related PRs

• nearai/ironclaw#5152: Introduced the WebUI-based Slack setup path that this PR makes authoritative.
• nearai/ironclaw#5181: Added Slack environment and configuration enablement mechanisms removed here.
• nearai/ironclaw#5646: Added Slack legacy-field rejection later generalized into retired-section handling.

Suggested reviewers: serrrfirat

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is detailed and relevant but does not use the required template or provide several mandatory sections, including security, database, rollback, and review details.	Reformat the description using the repository template and complete all required sections, including change type, linked issue, security, database impact, blast radius, rollback, and review follow-through.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title follows the preferred Conventional Commits format and accurately summarizes retirement of vendor configuration sections.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

⚔️ Resolve merge conflicts 💡

• Resolve merge conflict in branch ws6/config-vendor-narrow

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/capabilities/configuration.mdx`:
- Around line 276-283: Update the Google configuration guidance near the
google.* description to document both supported paths: configuring via the web
interface and using the Google CLI/config set path. Remove the implication that
operators must use only the WebUI, while preserving the existing explanation of
the OAuth client ID, redirect URI, and hosted-domain hint.

In `@docs/channels/telegram.mdx`:
- Around line 95-99: Update docs/channels/telegram.mdx lines 95-99 to retain the
note about inert retired [telegram] sections while adding the exception that
retired setup keys fail during serve with migration guidance. In
docs/reborn/extension-runtime/checklist.md lines 824-839, replace the stale
claim that retired sections fail at parse time with the conditional behavior:
setup keys fail with migration guidance, while inert retired sections load and
emit a deprecation notice.

In `@docs/reborn/setup-slack-for-reborn-binary.md`:
- Around line 318-320: Align the Slack setup guidance across
docs/reborn/setup-slack-for-reborn-binary.md lines 318-320,
docs/channels/slack.mdx lines 230-232, and
docs/reborn/deploy-reborn-cli-docker.md lines 201-204: consistently state that
503 indicates incoming signing-secret credentials are not configured, and direct
users to the same Slack Channels card location for signing-secret/token
configuration rather than /extensions.

In `@docs/using/cli.mdx`:
- Around line 58-59: Update the direct-edit documentation around the
`webui.token --rotate` description so it only applies to supported settings,
removing the implication that retired Slack, Telegram, or setup keys can be
edited directly. Preserve the routing guidance for the configuration file,
encrypted secret store, and web token file, while noting that retired keys
provide migration guidance, retired setup keys are rejected, and inert sections
are ignored.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 362d92c1-93d8-49f2-a111-e2beebe5b4b5

📥 Commits

Reviewing files that changed from the base of the PR and between dfdd02b and 4174f7e.

⛔ Files ignored due to path filters (1)

• docs/zh/channels/telegram.md is excluded by !docs/zh/**

📒 Files selected for processing (22)

• .env.example
• README.md
• crates/ironclaw_architecture/tests/reborn_extension_specificity.rs
• crates/ironclaw_reborn_cli/src/commands/config/capability_config.rs
• crates/ironclaw_reborn_cli/src/commands/config/read.rs
• crates/ironclaw_reborn_cli/src/commands/config/set.rs
• crates/ironclaw_reborn_cli/src/commands/serve.rs
• crates/ironclaw_reborn_cli/tests/smoke.rs
• crates/ironclaw_reborn_config/AGENTS.md
• crates/ironclaw_reborn_config/src/config_file.rs
• crates/ironclaw_reborn_config/src/lib.rs
• crates/ironclaw_reborn_config/src/retired_sections.rs
• docs/capabilities/configuration.mdx
• docs/channels/slack.mdx
• docs/channels/telegram.mdx
• docs/internal/live-canary.md
• docs/reborn/deploy-reborn-cli-docker.md
• docs/reborn/extension-runtime/checklist.md
• docs/reborn/setup-slack-for-reborn-binary.md
• docs/reborn/target-architecture/CHECKLIST.md
• docs/reborn/target-architecture/PROPOSAL.md
• docs/using/cli.mdx

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/ironclaw_reborn_composition/src/runtime.rs`:
- Around line 410-420: Preserve the separate CI build legs covering default,
dependency-as-library, and feature-enabled configurations; do not replace them
with a single --all-features validation. Keep the cfg gates on the
ChannelConnectionNoticePolicy, AdminUserService, and adjacent test-support-only
imports/accessors so each build tree remains checked independently.

In `@docs/reborn/setup-slack-for-reborn-binary.md`:
- Around line 320-330: Update the Slack setup guide’s signing-secret
instructions to consistently identify Extensions → Channels → Slack card as the
credential location, replacing stale Admin Configuration for Slack references or
explicitly stating they refer to the same card. Keep the existing 503 and 401
troubleshooting guidance intact.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 5aea8123-0391-45b1-8fe8-e6ebfb26aebb

📥 Commits

Reviewing files that changed from the base of the PR and between 5474939 and 5b45123.

📒 Files selected for processing (4)

• crates/ironclaw_reborn_composition/src/runtime.rs
• docs/capabilities/configuration.mdx
• docs/reborn/setup-slack-for-reborn-binary.md
• docs/using/cli.mdx

[BenKurrek]

Reconciled with main (merge, not rebase)

main moved three times under this branch (74778bab78 → 79435f4b91 → d289dd8985). Merged twice; no rebase, so the reviewed commits are untouched.

Three files conflicted. Two were mechanical unions, one was a real supersession.

1–2. scripts/ci/reborn_pr_test_plan.py + test_reborn_pr_test_plan.py — union.
#7112 added IGNORED_GUIDANCE_PATHS (tests/CLAUDE.md, tests/integration/CLAUDE.md) in the same two places this PR added IGNORED_ROOT_FILES (.env.example): one new constant after IGNORED_PREFIXES, one new disjunct in the same if, and one new test method at the same insertion point. Both sides kept, main's placement preserved so the delta reads as a pure addition:

if (
    path in IGNORED_GUIDANCE_PATHS      # #7112
    or path.startswith(IGNORED_PREFIXES)
    or path in IGNORED_ROOT_FILES       # this PR
    or (path.endswith(".md") and "/" not in path)
):

Verified by asserting every line each side added is present in the merged file (0 lost on either side) and by running the suite: 44 passed, 24 subtests, including both sides' new tests by name.

3. docs/internal/live-canary.md — took main's version and dropped this PR's note.
This is the one substantive change, and it is a deletion of content this PR added. That PR carried a dated note saying the [slack] block was inert but the live-QA runner still gated on it, left as-is and tracked in #7116. #7123 has since fixed exactly that — _slack_enabled is gone from run_live_qa.py and slack_helpers.py, and #7116 is CLOSED as completed. Every claim in the note was therefore false on the merged tree: the runner no longer keys off the value, the [slack] enabled = true block it referred to no longer exists, and the issue it pointed at is closed. Keeping it would have shipped a stale doc contradicting the code beside it, so the section is now main's text verbatim — which already describes the section as retired, consistent with this PR's work. That file is now byte-identical to main and drops out of this PR's delta (26 files → 25).

The rest of the PR is untouched by the merges. All 23 other files in the original delta are byte-identical to the pre-merge tip f9dc381123, verified by blob hash — the config retirement, retired_sections.rs, the compatibility window, the CLI changes, and both append-only ledgers (CHECKLIST.md / PROPOSAL.md 2026-08-04 amendments, which main never touched).

Recomputed counts. The extension-specificity ALLOWLIST did not conflict (main never touched that file), but main added new files, so the count was re-derived rather than assumed — baseline temporarily set to 0 and the length read back off the ratchet's own failure message: exactly 125, matching WS0_EXTENSION_SPECIFICITY_ALLOWLIST_BASELINE = 125. Restored and re-verified byte-identical. LAYER_MATRIX_EXCEPTIONS and tests/integration/changed-coverage-exemptions.toml were touched by neither side — no recomputation needed.

Verification on the pushed ref: cargo test -p ironclaw_architecture exit 0 (32 binaries, 0 failed) · cargo check --all-targets exit 0 on {ironclaw, ironclaw_reborn_composition, ironclaw_reborn_config, ironclaw_architecture} · the #7119 unblock survived and cargo clippy -p ironclaw -p ironclaw_reborn_config --lib --bins -- -D warnings exits 0 · zero conflict markers repo-wide.

One pre-existing failure, not from this merge: test_live_canary_workflow_shards_cover_non_telegram_qa_suite fails because it asserts a reborn-e2e.yml packaging string that the workflow no longer contains. It reproduces on a clean checkout of main (d289dd8985) and at this PR's original merge-base (dfdd02b9fb), and the implicated files are byte-identical to main here. It sits behind QA_HARNESS_PREFIXES, so it does not run in the PR lane — same class as #7119.

[BenKurrek]

Superseded: this slice's content is on main — the retired-sections compatibility window is on main (ironclaw_reborn_config retired_sections, recorded discharged in PROPOSAL §12 item 2). It merged via the Wave 3–4 trains and batches (#7139/#7141 era and the Waves 0–4 batches #7170/#7181); the branch predates those squashes so ancestry can't show it, but the on-main artifact does. Closing as merged-via-train, not abandoned.