fix(whatsapp): complete wa-rs channel behavior and storage correctness

CLAUDE.md

@@ -1,193 +1,474 @@
-# CLAUDE.md
+# CLAUDE.md — ZeroClaw Agent Engineering Protocol
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file defines the default working protocol for Claude agents in this repository.
+Scope: entire repository.
 
-## Project Overview
+## 1) Project Snapshot (Read First)
 
-ZeroClaw is a lightweight autonomous AI assistant infrastructure written entirely in Rust. It is optimized for high performance, efficiency, and security with a trait-based pluggable architecture.
+ZeroClaw is a Rust-first autonomous agent runtime optimized for:
 
-Key stats: ~3.4MB binary, <5MB RAM, <10ms startup, 1,017 tests.
+- high performance
+- high efficiency
+- high stability
+- high extensibility
+- high sustainability
+- high security
 
-## Common Commands
+Core architecture is trait-driven and modular. Most extension work should be done by implementing traits and registering in factory modules.
 
-### Build
-```bash
-cargo build --release          # Optimized release build (~3.4MB)
-CARGO_BUILD_JOBS=1 cargo build --release    # Low-memory fallback (Raspberry Pi 3, 1GB RAM)
-cargo build --release --locked # Build with locked dependencies (fixes OpenSSL errors)
-```
+Key extension points:
 
-### Test
-```bash
-cargo test                     # Run all 1,017 tests
-cargo test telegram --lib      # Test specific module
-cargo test security            # Test security module
-```
+- `src/providers/traits.rs` (`Provider`)
+- `src/channels/traits.rs` (`Channel`)
+- `src/tools/traits.rs` (`Tool`)
+- `src/memory/traits.rs` (`Memory`)
+- `src/observability/traits.rs` (`Observer`)
+- `src/runtime/traits.rs` (`RuntimeAdapter`)
+- `src/peripherals/traits.rs` (`Peripheral`) — hardware boards (STM32, RPi GPIO)
 
-### Format & Lint
-```bash
-cargo fmt --all -- --check     # Check formatting
-cargo fmt                       # Apply formatting
-cargo clippy --all-targets -- -D clippy::correctness  # Baseline (required for CI)
-cargo clippy --all-targets -- -D warnings             # Strict (optional)
-```
+## 2) Deep Architecture Observations (Why This Protocol Exists)
 
-### CI / Pre-push
-```bash
-./dev/ci.sh all                # Full CI in Docker
-git config core.hooksPath .githooks  # Enable pre-push hook
-git push --no-verify           # Skip hook if needed
-```
+These codebase realities should drive every design decision:
 
-## Architecture
+1. **Trait + factory architecture is the stability backbone**
+    - Extension points are intentionally explicit and swappable.
+    - Most features should be added via trait implementation + factory registration, not cross-cutting rewrites.
+2. **Security-critical surfaces are first-class and internet-adjacent**
+    - `src/gateway/`, `src/security/`, `src/tools/`, `src/runtime/` carry high blast radius.
+    - Defaults already lean secure-by-default (pairing, bind safety, limits, secret handling); keep it that way.
+3. **Performance and binary size are product goals, not nice-to-have**
+    - `Cargo.toml` release profile and dependency choices optimize for size and determinism.
+    - Convenience dependencies and broad abstractions can silently regress these goals.
+4. **Config and runtime contracts are user-facing API**
+    - `src/config/schema.rs` and CLI commands are effectively public interfaces.
+    - Backward compatibility and explicit migration matter.
+5. **The project now runs in high-concurrency collaboration mode**
+    - CI + docs governance + label routing are part of the product delivery system.
+    - PR throughput is a design constraint; not just a maintainer inconvenience.
 
-ZeroClaw uses a **trait-based pluggable architecture** where every subsystem is swappable via traits and factory functions.
+## 3) Engineering Principles (Normative)
 
-### Core Extension Points
+These principles are mandatory by default. They are not slogans; they are implementation constraints.
 
-| Trait | Purpose | Location |
-|-------|---------|----------|
-| `Provider` | LLM backends (22+ providers) | `src/providers/traits.rs` |
-| `Channel` | Messaging platforms | `src/channels/traits.rs` |
-| `Tool` | Agent capabilities | `src/tools/traits.rs` |
-| `Memory` | Persistence/backends | `src/memory/traits.rs` |
-| `Observer` | Metrics/logging | `src/observability/traits.rs` |
-| `RuntimeAdapter` | Platform abstraction | `src/runtime/traits.rs` |
-| `Peripheral` | Hardware boards | `src/peripherals/traits.rs` |
+### 3.1 KISS (Keep It Simple, Stupid)
 
-### Key Directory Structure
+**Why here:** Runtime + security behavior must stay auditable under pressure.
 
-```
-src/
-├── main.rs          # CLI entrypoint, command routing
-├── lib.rs           # Module exports, command enums
-├── agent/           # Orchestration loop
-├── channels/        # Telegram, Discord, Slack, WhatsApp, etc.
-├── providers/       # OpenRouter, Anthropic, OpenAI, Ollama, etc.
-├── tools/           # shell, file_read, file_write, memory, browser
-├── memory/          # SQLite, Markdown, Lucid, None backends
-├── gateway/         # Webhook/gateway server (Axum HTTP)
-├── security/        # Policy, pairing, secret store
-├── runtime/         # Native, Docker runtime adapters
-├── peripherals/     # STM32, RPi GPIO hardware support
-├── observability/   # Noop, Log, Multi, OTel observers
-├── tunnel/          # Cloudflare, Tailscale, ngrok, custom
-├── config/          # Schema + config loading/merging
-└── identity/        # AIEOS/OpenClaw identity formats
-```
+Required:
 
-## Memory System
+- Prefer straightforward control flow over clever meta-programming.
+- Prefer explicit match branches and typed structs over hidden dynamic behavior.
+- Keep error paths obvious and localized.
 
-ZeroClaw includes a full-stack search engine with zero external dependencies (no Pinecone, Elasticsearch, or LangChain):
+### 3.2 YAGNI (You Aren't Gonna Need It)
 
-- **Vector DB**: Embeddings stored as BLOB in SQLite, cosine similarity search
-- **Keyword Search**: FTS5 virtual tables with BM25 scoring
-- **Hybrid Merge**: Custom weighted merge function
-- **Embeddings**: `EmbeddingProvider` trait — OpenAI, custom URL, or noop
-- **Chunking**: Line-based markdown chunker with heading preservation
+**Why here:** Premature features increase attack surface and maintenance burden.
 
-## Security Principles
+Required:
 
-ZeroClaw enforces security at every layer. Key patterns:
+- Do not add new config keys, trait methods, feature flags, or workflow branches without a concrete accepted use case.
+- Do not introduce speculative “future-proof” abstractions without at least one current caller.
+- Keep unsupported paths explicit (error out) rather than adding partial fake support.
 
-- **Gateway pairing**: 6-digit one-time code required for webhook access
-- **Workspace-only execution**: Default sandbox scopes file operations
-- **Path traversal blocking**: 14 system dirs + 4 sensitive dotfiles blocked
-- **Command allowlisting**: No blocklists — only explicit allowlists
-- **Secret encryption**: ChaCha20-Poly1305 AEAD for encrypted secrets
-- **No logging of secrets**: Never log tokens, keys, or sensitive payloads
+### 3.3 DRY + Rule of Three
 
-Critical security paths: `src/security/`, `src/runtime/`, `src/gateway/`, `src/tools/`, `.github/workflows/`
+**Why here:** Naive DRY can create brittle shared abstractions across providers/channels/tools.
 
-## Code Naming Conventions
+Required:
 
-- **Rust standard**: modules/files `snake_case`, types/traits `PascalCase`, functions/variables `snake_case`, constants `SCREAMING_SNAKE_CASE`
-- **Domain-first naming**: `DiscordChannel`, `SecurityPolicy`, `SqliteMemory`
-- **Trait implementers**: `*Provider`, `*Channel`, `*Tool`, `*Memory`, `*Observer`, `*RuntimeAdapter`
-- **Factory keys**: lowercase, stable (`"openai"`, `"discord"`, `"shell"`)
-- **Tests**: behavior-oriented (`allowlist_denies_unknown_user`)
-- **Identity-like labels**: Use ZeroClaw-native only (`ZeroClawAgent`, `zeroclaw_user`) — never real names/personal data
+- Duplicate small, local logic when it preserves clarity.
+- Extract shared utilities only after repeated, stable patterns (rule-of-three).
+- When extracting, preserve module boundaries and avoid hidden coupling.
 
-## Architecture Boundary Rules
+### 3.4 SRP + ISP (Single Responsibility + Interface Segregation)
 
-- Extend via trait implementations + factory registration first
-- Keep dependency direction inward: concrete implementations depend on traits/config/util
-- Avoid cross-subsystem coupling (e.g., provider importing channel internals)
-- Keep modules single-purpose
-- Treat config keys as public contract — document migrations
+**Why here:** Trait-driven architecture already encodes subsystem boundaries.
 
-## Engineering Principles
+Required:
 
-From `AGENTS.md` — these are mandatory implementation constraints:
+- Keep each module focused on one concern.
+- Extend behavior by implementing existing narrow traits whenever possible.
+- Avoid fat interfaces and “god modules” that mix policy + transport + storage.
 
-1. **KISS** — Prefer straightforward control flow over clever meta-programming
-2. **YAGNI** — Don't add features/config/flags without a concrete use case
-3. **DRY + Rule of Three** — Extract shared utilities only after repeated stable patterns
-4. **SRP + ISP** — Keep modules focused; extend via narrow traits
-5. **Fail Fast + Explicit Errors** — Prefer explicit `bail!`/errors; never silently broaden permissions
-6. **Secure by Default + Least Privilege** — Deny-by-default for access boundaries
-7. **Determinism + Reproducibility** — Prefer reproducible commands and locked dependencies
-8. **Reversibility + Rollback-First** — Keep changes easy to revert
+### 3.5 Fail Fast + Explicit Errors
 
-## Adding New Components
+**Why here:** Silent fallback in agent runtimes can create unsafe or costly behavior.
 
-### New Provider
-1. Create `src/providers/your_provider.rs`
-2. Implement `Provider` trait
-3. Register factory in `src/providers/mod.rs`
+Required:
 
-### New Channel
-1. Create `src/channels/your_channel.rs`
-2. Implement `Channel` trait
-3. Register in `src/channels/mod.rs`
+- Prefer explicit `bail!`/errors for unsupported or unsafe states.
+- Never silently broaden permissions/capabilities.
+- Document fallback behavior when fallback is intentional and safe.
 
-### New Tool
-1. Create `src/tools/your_tool.rs`
-2. Implement `Tool` trait with strict parameter schema
-3. Register in `src/tools/mod.rs`
+### 3.6 Secure by Default + Least Privilege
 
-### New Peripheral
-1. Create in `src/peripherals/`
-2. Implement `Peripheral` trait (exposes `tools()` method)
-3. See `docs/hardware-peripherals-design.md` for protocol
+**Why here:** Gateway/tools/runtime can execute actions with real-world side effects.
 
-## Validation Matrix
+Required:
+
+- Deny-by-default for access and exposure boundaries.
+- Never log secrets, raw tokens, or sensitive payloads.
+- Keep network/filesystem/shell scope as narrow as possible unless explicitly justified.
+
+### 3.7 Determinism + Reproducibility
+
+**Why here:** Reliable CI and low-latency triage depend on deterministic behavior.
+
+Required:
+
+- Prefer reproducible commands and locked dependency behavior in CI-sensitive paths.
+- Keep tests deterministic (no flaky timing/network dependence without guardrails).
+- Ensure local validation commands map to CI expectations.
+
+### 3.8 Reversibility + Rollback-First Thinking
+
+**Why here:** Fast recovery is mandatory under high PR volume.
+
+Required:
+
+- Keep changes easy to revert (small scope, clear blast radius).
+- For risky changes, define rollback path before merge.
+- Avoid mixed mega-patches that block safe rollback.
+
+## 4) Repository Map (High-Level)
+
+- `src/main.rs` — CLI entrypoint and command routing
+- `src/lib.rs` — module exports and shared command enums
+- `src/config/` — schema + config loading/merging
+- `src/agent/` — orchestration loop
+- `src/gateway/` — webhook/gateway server
+- `src/security/` — policy, pairing, secret store
+- `src/memory/` — markdown/sqlite memory backends + embeddings/vector merge
+- `src/providers/` — model providers and resilient wrapper
+- `src/channels/` — Telegram/Discord/Slack/etc channels
+- `src/tools/` — tool execution surface (shell, file, memory, browser)
+- `src/peripherals/` — hardware peripherals (STM32, RPi GPIO); see `docs/hardware-peripherals-design.md`
+- `src/runtime/` — runtime adapters (currently native)
+- `docs/` — task-oriented documentation system (hubs, unified TOC, references, operations, security proposals, multilingual guides)
+- `.github/` — CI, templates, automation workflows
+
+## 4.1 Documentation System Contract (Required)
+
+Treat documentation as a first-class product surface, not a post-merge artifact.
+
+Canonical entry points:
+
+- root READMEs: `README.md`, `README.zh-CN.md`, `README.ja.md`, `README.ru.md`
+- docs hubs: `docs/README.md`, `docs/README.zh-CN.md`, `docs/README.ja.md`, `docs/README.ru.md`
+- unified TOC: `docs/SUMMARY.md`
+
+Collection indexes (category navigation):
+
+- `docs/getting-started/README.md`
+- `docs/reference/README.md`
+- `docs/operations/README.md`
+- `docs/security/README.md`
+- `docs/hardware/README.md`
+- `docs/contributing/README.md`
+- `docs/project/README.md`
+
+Runtime-contract references (must track behavior changes):
+
+- `docs/commands-reference.md`
+- `docs/providers-reference.md`
+- `docs/channels-reference.md`
+- `docs/config-reference.md`
+- `docs/operations-runbook.md`
+- `docs/troubleshooting.md`
+- `docs/one-click-bootstrap.md`
+
+Required docs governance rules:
+
+- Keep README/hub top navigation and quick routes intuitive and non-duplicative.
+- Keep EN/ZH/JA/RU entry-point parity when changing navigation architecture.
+- Keep proposal/roadmap docs explicitly labeled; avoid mixing proposal text into runtime-contract docs.
+- Keep project snapshots date-stamped and immutable once superseded by a newer date.
+
+## 5) Risk Tiers by Path (Review Depth Contract)
+
+Use these tiers when deciding validation depth and review rigor.
+
+- **Low risk**: docs/chore/tests-only changes
+- **Medium risk**: most `src/**` behavior changes without boundary/security impact
+- **High risk**: `src/security/**`, `src/runtime/**`, `src/gateway/**`, `src/tools/**`, `.github/workflows/**`, access-control boundaries
+
+When uncertain, classify as higher risk.
+
+## 6) Agent Workflow (Required)
+
+1. **Read before write**
+    - Inspect existing module, factory wiring, and adjacent tests before editing.
+2. **Define scope boundary**
+    - One concern per PR; avoid mixed feature+refactor+infra patches.
+3. **Implement minimal patch**
+    - Apply KISS/YAGNI/DRY rule-of-three explicitly.
+4. **Validate by risk tier**
+    - Docs-only: lightweight checks.
+    - Code/risky changes: full relevant checks and focused scenarios.
+5. **Document impact**
+    - Update docs/PR notes for behavior, risk, side effects, and rollback.
+    - If CLI/config/provider/channel behavior changed, update corresponding runtime-contract references.
+    - If docs entry points changed, keep EN/ZH/JA/RU README + docs-hub navigation aligned.
+6. **Respect queue hygiene**
+    - If stacked PR: declare `Depends on #...`.
+    - If replacing old PR: declare `Supersedes #...`.
+
+### 6.1 Branch / Commit / PR Flow (Required)
+
+All contributors (human or agent) must follow the same collaboration flow:
+
+- Create and work from a non-`main` branch.
+- Commit changes to that branch with clear, scoped commit messages.
+- Open a PR to `main`; do not push directly to `main`.
+- Wait for required checks and review outcomes before merging.
+- Merge via PR controls (squash/rebase/merge as repository policy allows).
+- Branch deletion after merge is optional; long-lived branches are allowed when intentionally maintained.
+
+### 6.2 Worktree Workflow (Required for Multi-Track Agent Work)
+
+Use Git worktrees to isolate concurrent agent/human tracks safely and predictably:
+
+- Use one worktree per active branch/PR stream to avoid cross-task contamination.
+- Keep each worktree on a single branch; do not mix unrelated edits in one worktree.
+- Run validation commands inside the corresponding worktree before commit/PR.
+- Name worktrees clearly by scope (for example: `wt/ci-hardening`, `wt/provider-fix`) and remove stale worktrees when no longer needed.
+- PR checkpoint rules from section 6.1 still apply to worktree-based development.
+
+### 6.3 Code Naming Contract (Required)
+
+Apply these naming rules for all code changes unless a subsystem has a stronger existing pattern.
+
+- Use Rust standard casing consistently: modules/files `snake_case`, types/traits/enums `PascalCase`, functions/variables `snake_case`, constants/statics `SCREAMING_SNAKE_CASE`.
+- Name types and modules by domain role, not implementation detail (for example `DiscordChannel`, `SecurityPolicy`, `MemoryStore` over vague names like `Manager`/`Helper`).
+- Keep trait implementer naming explicit and predictable: `<ProviderName>Provider`, `<ChannelName>Channel`, `<ToolName>Tool`, `<BackendName>Memory`.
+- Keep factory registration keys stable, lowercase, and user-facing (for example `"openai"`, `"discord"`, `"shell"`), and avoid alias sprawl without migration need.
+- Name tests by behavior/outcome (`<subject>_<expected_behavior>`) and keep fixture identifiers neutral/project-scoped.
+- If identity-like naming is required in tests/examples, use ZeroClaw-native labels only (`ZeroClawAgent`, `zeroclaw_user`, `zeroclaw_node`).
+
+### 6.4 Architecture Boundary Contract (Required)
+
+Use these rules to keep the trait/factory architecture stable under growth.
+
+- Extend capabilities by adding trait implementations + factory wiring first; avoid cross-module rewrites for isolated features.
+- Keep dependency direction inward to contracts: concrete integrations depend on trait/config/util layers, not on other concrete integrations.
+- Avoid creating cross-subsystem coupling (for example provider code importing channel internals, tool code mutating gateway policy directly).
+- Keep module responsibilities single-purpose: orchestration in `agent/`, transport in `channels/`, model I/O in `providers/`, policy in `security/`, execution in `tools/`.
+- Introduce new shared abstractions only after repeated use (rule-of-three), with at least one real caller in current scope.
+- For config/schema changes, treat keys as public contract: document defaults, compatibility impact, and migration/rollback path.
+
+## 7) Change Playbooks
+
+### 7.1 Adding a Provider
+
+- Implement `Provider` in `src/providers/`.
+- Register in `src/providers/mod.rs` factory.
+- Add focused tests for factory wiring and error paths.
+- Avoid provider-specific behavior leaks into shared orchestration code.
+
+### 7.2 Adding a Channel
+
+- Implement `Channel` in `src/channels/`.
+- Keep `send`, `listen`, `health_check`, typing semantics consistent.
+- Cover auth/allowlist/health behavior with tests.
+
+### 7.3 Adding a Tool
+
+- Implement `Tool` in `src/tools/` with strict parameter schema.
+- Validate and sanitize all inputs.
+- Return structured `ToolResult`; avoid panics in runtime path.
+
+### 7.4 Adding a Peripheral
+
+- Implement `Peripheral` in `src/peripherals/`.
+- Peripherals expose `tools()` — each tool delegates to the hardware (GPIO, sensors, etc.).
+- Register board type in config schema if needed.
+- See `docs/hardware-peripherals-design.md` for protocol and firmware notes.
+
+### 7.5 Security / Runtime / Gateway Changes
+
+- Include threat/risk notes and rollback strategy.
+- Add/update tests or validation evidence for failure modes and boundaries.
+- Keep observability useful but non-sensitive.
+- For `.github/workflows/**` changes, include Actions allowlist impact in PR notes and update `docs/actions-source-policy.md` when sources change.
+
+### 7.6 Docs System / README / IA Changes
+
+- Treat docs navigation as product UX: preserve clear pathing from README -> docs hub -> SUMMARY -> category index.
+- Keep top-level nav concise; avoid duplicative links across adjacent nav blocks.
+- When runtime surfaces change, update related references (`commands/providers/channels/config/runbook/troubleshooting`).
+- Keep multilingual entry-point parity for EN/ZH/JA/RU when nav or key wording changes.
+- For docs snapshots, add new date-stamped files for new sprints rather than rewriting historical context.
+
+
+## 8) Validation Matrix
 
 Default local checks for code changes:
 
 ```bash
 cargo fmt --all -- --check
-cargo clippy --all-targets -- -D clippy::correctness
+cargo clippy --all-targets -- -D warnings
 cargo test
 ```
 
-For Docker CI parity (recommended when available):
+Preferred local pre-PR validation path (recommended, not required):
 
 ```bash
 ./dev/ci.sh all
 ```
 
-## Risk Tiers by Path
+Notes:
 
-- **Low risk**: docs/chore/tests-only
-- **Medium risk**: most `src/**` behavior changes without boundary/security impact
-- **High risk**: `src/security/**`, `src/runtime/**`, `src/gateway/**`, `src/tools/**`, `.github/workflows/**`, access-control boundaries
+- Local Docker-based CI is strongly recommended when Docker is available.
+- Contributors are not blocked from opening a PR if local Docker CI is unavailable; in that case run the most relevant native checks and document what was run.
 
-## Important Documentation
+Additional expectations by change type:
 
-- `AGENTS.md` — Agent engineering protocol (primary guide for AI contributors)
-- `CONTRIBUTING.md` — Contribution guide and architecture rules
-- `docs/pr-workflow.md` — PR workflow and governance
-- `docs/reviewer-playbook.md` — Reviewer operating checklist
-- `docs/ci-map.md` — CI ownership and triage
-- `docs/hardware-peripherals-design.md` — Hardware peripherals protocol
+- **Docs/template-only**:
+    - run markdown lint and link-integrity checks
+    - if touching README/docs-hub/SUMMARY/collection indexes, verify EN/ZH/JA/RU navigation parity
+    - if touching bootstrap docs/scripts, run `bash -n bootstrap.sh scripts/bootstrap.sh scripts/install.sh`
+- **Workflow changes**: validate YAML syntax; run workflow lint/sanity checks when available.
+- **Security/runtime/gateway/tools**: include at least one boundary/failure-mode validation.
 
-## Pre-push Hook
+If full checks are impractical, run the most relevant subset and document what was skipped and why.
 
-The repo includes a pre-push hook that runs `fmt`, `clippy`, and `tests` before every push. Enable once with:
+## 9) Collaboration and PR Discipline
 
-```bash
-git config core.hooksPath .githooks
+- Follow `.github/pull_request_template.md` fully (including side effects / blast radius).
+- Keep PR descriptions concrete: problem, change, non-goals, risk, rollback.
+- Use conventional commit titles.
+- Prefer small PRs (`size: XS/S/M`) when possible.
+- Agent-assisted PRs are welcome, **but contributors remain accountable for understanding what their code will do**.
+
+### 9.1 Privacy/Sensitive Data and Neutral Wording (Required)
+
+Treat privacy and neutrality as merge gates, not best-effort guidelines.
+
+- Never commit personal or sensitive data in code, docs, tests, fixtures, snapshots, logs, examples, or commit messages.
+- Prohibited data includes (non-exhaustive): real names, personal emails, phone numbers, addresses, access tokens, API keys, credentials, IDs, and private URLs.
+- Use neutral project-scoped placeholders (for example: `user_a`, `test_user`, `project_bot`, `example.com`) instead of real identity data.
+- Test names/messages/fixtures must be impersonal and system-focused; avoid first-person or identity-specific language.
+- If identity-like context is unavoidable, use ZeroClaw-scoped roles/labels only (for example: `ZeroClawAgent`, `ZeroClawOperator`, `zeroclaw_user`) and avoid real-world personas.
+- Recommended identity-safe naming palette (use when identity-like context is required):
+    - actor labels: `ZeroClawAgent`, `ZeroClawOperator`, `ZeroClawMaintainer`, `zeroclaw_user`
+    - service/runtime labels: `zeroclaw_bot`, `zeroclaw_service`, `zeroclaw_runtime`, `zeroclaw_node`
+    - environment labels: `zeroclaw_project`, `zeroclaw_workspace`, `zeroclaw_channel`
+- If reproducing external incidents, redact and anonymize all payloads before committing.
+- Before push, review `git diff --cached` specifically for accidental sensitive strings and identity leakage.
+
+### 9.2 Superseded-PR Attribution (Required)
+
+When a PR supersedes another contributor's PR and carries forward substantive code or design decisions, preserve authorship explicitly.
+
+- In the integrating commit message, add one `Co-authored-by: Name <email>` trailer per superseded contributor whose work is materially incorporated.
+- Use a GitHub-recognized email (`<login@users.noreply.github.com>` or the contributor's verified commit email) so attribution is rendered correctly.
+- Keep trailers on their own lines after a blank line at commit-message end; never encode them as escaped `\\n` text.
+- In the PR body, list superseded PR links and briefly state what was incorporated from each.
+- If no actual code/design was incorporated (only inspiration), do not use `Co-authored-by`; give credit in PR notes instead.
+
+### 9.3 Superseded-PR PR Template (Recommended)
+
+When superseding multiple PRs, use a consistent title/body structure to reduce reviewer ambiguity.
+
+- Recommended title format: `feat(<scope>): unify and supersede #<pr_a>, #<pr_b> [and #<pr_n>]`
+- If this is docs/chore/meta only, keep the same supersede suffix and use the appropriate conventional-commit type.
+- In the PR body, include the following template (fill placeholders, remove non-applicable lines):
+
+```md
+## Supersedes
+- #<pr_a> by @<author_a>
+- #<pr_b> by @<author_b>
+- #<pr_n> by @<author_n>
+
+## Integrated Scope
+- From #<pr_a>: <what was materially incorporated>
+- From #<pr_b>: <what was materially incorporated>
+- From #<pr_n>: <what was materially incorporated>
+
+## Attribution
+- Co-authored-by trailers added for materially incorporated contributors: Yes/No
+- If No, explain why (for example: no direct code/design carry-over)
+
+## Non-goals
+- <explicitly list what was not carried over>
+
+## Risk and Rollback
+- Risk: <summary>
+- Rollback: <revert commit/PR strategy>
 ```
 
-Skip with `git push --no-verify` during rapid iteration (CI will catch issues).
+### 9.4 Superseded-PR Commit Template (Recommended)
+
+When a commit unifies or supersedes prior PR work, use a deterministic commit message layout so attribution is machine-parsed and reviewer-friendly.
+
+- Keep one blank line between message sections, and exactly one blank line before trailer lines.
+- Keep each trailer on its own line; do not wrap, indent, or encode as escaped `\n` text.
+- Add one `Co-authored-by` trailer per materially incorporated contributor, using GitHub-recognized email.
+- If no direct code/design is carried over, omit `Co-authored-by` and explain attribution in the PR body instead.
+
+```text
+feat(<scope>): unify and supersede #<pr_a>, #<pr_b> [and #<pr_n>]
+
+<one-paragraph summary of integrated outcome>
+
+Supersedes:
+- #<pr_a> by @<author_a>
+- #<pr_b> by @<author_b>
+- #<pr_n> by @<author_n>
+
+Integrated scope:
+- <subsystem_or_feature_a>: from #<pr_x>
+- <subsystem_or_feature_b>: from #<pr_y>
+
+Co-authored-by: <Name A> <login_a@users.noreply.github.com>
+Co-authored-by: <Name B> <login_b@users.noreply.github.com>
+```
+
+Reference docs:
+
+- `CONTRIBUTING.md`
+- `docs/README.md`
+- `docs/SUMMARY.md`
+- `docs/docs-inventory.md`
+- `docs/commands-reference.md`
+- `docs/providers-reference.md`
+- `docs/channels-reference.md`
+- `docs/config-reference.md`
+- `docs/operations-runbook.md`
+- `docs/troubleshooting.md`
+- `docs/one-click-bootstrap.md`
+- `docs/pr-workflow.md`
+- `docs/reviewer-playbook.md`
+- `docs/ci-map.md`
+- `docs/actions-source-policy.md`
+
+## 10) Anti-Patterns (Do Not)
+
+- Do not add heavy dependencies for minor convenience.
+- Do not silently weaken security policy or access constraints.
+- Do not add speculative config/feature flags “just in case”.
+- Do not mix massive formatting-only changes with functional changes.
+- Do not modify unrelated modules “while here”.
+- Do not bypass failing checks without explicit explanation.
+- Do not hide behavior-changing side effects in refactor commits.
+- Do not include personal identity or sensitive information in test data, examples, docs, or commits.
+
+## 11) Handoff Template (Agent -> Agent / Maintainer)
+
+When handing off work, include:
+
+1. What changed
+2. What did not change
+3. Validation run and results
+4. Remaining risks / unknowns
+5. Next recommended action
+
+## 12) Vibe Coding Guardrails
+
+When working in fast iterative mode:
+
+- Keep each iteration reversible (small commits, clear rollback).
+- Validate assumptions with code search before implementing.
+- Prefer deterministic behavior over clever shortcuts.
+- Do not “ship and hope” on security-sensitive paths.
+- If uncertain, leave a concrete TODO with verification context, not a hidden guess.