docs(platforms): schema-driven platform facts knowledge base with CI conformance

[luffy-aiagent]

Problem

┌─────────────────────────────────────────────────────────────────────┐
│                     ❌ Without this PR                               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Reviewer A on a LINE PR:                                           │
│  "What is LINE reply token TTL?" → digs through adapter code → 30m │
│                                                                     │
│  Reviewer B on another LINE PR:                                     │
│  "Does LINE support edit?" → digs through code again → 20m          │
│                                                                     │
│  Reviewer C comparing platforms:                                    │
│  "Which platforms support streaming?" → reads 8 adapters → 1 hour  │
│                                                                     │
│  New maintainer joins:                                              │
│  "How does Discord differ from Slack?" → no docs → figure it out   │
│                                                                     │
│  ❌ Same facts re-derived on every review                            │
│  ❌ Knowledge scattered in code + PR comments + people's heads       │
│  ❌ Platform behavior changes silently, nobody updates docs          │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

                              │
                              ▼

┌─────────────────────────────────────────────────────────────────────┐
│                     ✅ With this PR                                   │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌───────────────────────────────────────────────┐                  │
│  │  docs/platforms/schema/line.toml              │                  │
│  │                                               │                  │
│  │  capability.send_model = "hybrid"             │ ← written once   │
│  │  capability.message_length_limit = 5000       │                  │
│  │  streaming = "not_implemented"                │                  │
│  │  edit_message = "n_a"                         │                  │
│  │  source = "line.rs#dispatch_line_reply"       │ ← traceable      │
│  └───────────────────────────────────────────────┘                  │
│         × 8 platforms                                               │
│                                                                     │
│                     │                                               │
│         ┌───────────┼───────────┐                                   │
│         ▼           ▼           ▼                                   │
│  ┌────────────┐ ┌────────┐ ┌──────────┐                            │
│  │ Reviewer   │ │ CI     │ │ New      │                            │
│  │            │ │        │ │ maintainer│                            │
│  │ Check TOML │ │ Auto-  │ │          │                            │
│  │ get answer │ │ detect │ │ Read     │                            │
│  │ in 5 sec   │ │ drift  │ │ schema → │                            │
│  │            │ │        │ │ instant  │                            │
│  └────────────┘ └────────┘ │ grasp    │                            │
│                             └──────────┘                            │
│                                                                     │
│  ✅ Facts written once, shared by everyone                           │
│  ✅ Code changes → CI detects missing symbol → forces doc update    │
│  ✅ Day-1 maintainer sees full capability picture across 8 platforms│
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Summary

Bootstraps docs/platforms/ — a machine-readable platform facts schema for all 8 messaging platforms, with typed Rust conformance tests in CI.

What this adds

Component	Purpose
docs/platforms/schema/*.toml	Machine-readable facts: capabilities, feature status, quirks (8 platforms)
docs/platforms/README.md	Schema reference + update workflow + architecture diagram
docs/platforms/_template.toml	Blank schema for adding new platforms
crates/platform-schema/	Standalone Rust crate — typed structs + conformance tests
.github/workflows/platform-schema-conformance.yml	CI enforcement on schema changes
CONTRIBUTING.md	Added platform schema section

Architecture

• TOML = facts schema for CI/automation/onboarding (machine-readable)
• docs/<platform>.md = operator setup guides (human-readable, unchanged)
• Rust conformance = validates structure, closed feature set, schema version, and code-ref #symbol existence

Three schemas per platform

1. [capability.*] — 18 fixed fields per platform, sourced from official docs
2. [[openab_features]] — closed 17-feature set with status + code-ref source
3. [[quirks]] — freeform dated findings log

Follow-up issues

Issue	Why	Benefit
#1337	CI only triggers on schema file changes — adapter code renames bypass anti-drift entirely	Symbol renames caught at PR time, not weeks later when an unrelated PR breaks
#1338	Builds not reproducible (--locked missing), no cache (30-60s wasted), checkout@v4 inconsistent, no concurrency group	Faster CI, reproducible builds, cleaner CI tab, consistent with repo standards
#1339	No platform page owners, no PR checklist, unclear TOML-vs-Markdown relationship	Clear accountability prevents silent staleness; new maintainers know what to update
#1340	check_code_ref has bypass routes: empty #symbol always passes, ../ paths escape repo	If CI is green, refs are genuinely validated — no silent exceptions

Context

• Proposed in Proposal: docs/platforms/ — schema-driven platform knowledge base (3 versioned schemas, one page per platform) #1294
• Ref: ADR docs(adr): revise identity-trust-none — three-layer architecture #1291 (LINE)
• Design discussion: https://discord.com/channels/1491295327620169908/1491365158868619404/1523034521807618289

[chaodu-agent]

Note

LGTM ✅ — Well-structured, schema-driven platform knowledge base with solid CI enforcement.

What This PR Does

Reviewers and new maintainers repeatedly re-derive the same platform facts (reply token TTL, message limits, threading model) from scattered code and PRs. This PR bootstraps docs/platforms/ — a machine-readable TOML schema for all 8 messaging platforms — validated by typed Rust conformance tests in CI, so platform knowledge is written once and stays current.

How It Works

Three-schema structure per platform:

1. [capability.*] (18 fixed fields) — intrinsic platform facts sourced from official docs
2. [[openab_features]] (closed 17-feature set) — OpenAB implementation status with code-ref source fields
3. [[quirks]] (freeform dated log) — gotchas, design decisions, findings

A standalone Rust crate (crates/platform-schema/) deserializes every schema/*.toml into typed structs with #[serde(deny_unknown_fields)], enforcing structural validity, closed enum sets, schema version currency, and anti-drift (every #symbol code-ref is grep-verified against the tree). CI triggers on schema/crate changes via a dedicated workflow.

Findings

#	Severity	Finding	Location
1	🟢	Excellent schema design — deny_unknown_fields + closed feature set + code-ref verification is a strong anti-drift mechanism	crates/platform-schema/src/lib.rs
2	🟢	Good separation of concerns — TOML (machine facts) vs existing docs/<platform>.md (operator guides)	docs/platforms/README.md
3	🟢	Self-documenting: the template IS the schema reference, and conformance tests verify the template stays in sync	docs/platforms/_template.toml
4	🟢	Thoughtful follow-up issue decomposition (#1337–#1340) acknowledges known gaps without blocking the bootstrap	PR description
5	🟢	CI workflow uses --locked for reproducible builds	.github/workflows/platform-schema-conformance.yml
6	🟢	Platform facts are deeply researched with official-doc sources; adapter notes show genuine code-audit depth	docs/platforms/schema/*.toml

Finding Details

🟢 F1: Strong anti-drift design

The combination of #[serde(deny_unknown_fields)], a closed EXPECTED_FEATURES set, schema version enforcement, and check_code_ref (file existence + symbol grep) creates a robust system where stale docs fail the build.

🟢 F2: Clean architecture separation

TOML captures "what the platform can do + what OpenAB implements" (CI-checkable); Markdown captures "how to deploy" (human-readable). No duplication, clear boundaries.

🟢 F3: Template-as-documentation

The conformance test template_enumerates_every_section_and_feature() ensures the human-facing template can never drift from the Rust structs — the template is forced to stay accurate as a schema reference.

🟢 F4: Honest scope management

The PR explicitly calls out known limitations (#1337: trigger-path gap, #1338: CI hardening, #1339: ownership model, #1340: code-ref bypass routes) as follow-up issues rather than silently shipping them. This makes the review scope clear.

🟢 F5: Reproducible CI

Using --locked ensures the Cargo.lock is committed and builds are deterministic. The crate is workspace-excluded so it builds independently of heavy adapter dependencies.

🟢 F6: Deep platform research

Each platform file shows genuine investigation — e.g., Feishu's 20-edit cap with errcode mapping, LINE's reply-token TTL nuances, Teams' JWT endorsement validation, WeCom's PKCS7 block_size=32 divergence. These facts previously lived only in code comments or PR discussions.

Baseline Check

• PR opened: 2026-07-08
• Main already has: nothing in docs/platforms/ or crates/platform-schema/ — both are entirely net-new
• Net-new value: A complete platform knowledge base (8 platforms × 3 schemas each) + typed conformance CI + contributor workflow documentation
• CI status: All relevant checks pass; one unrelated smoke-test (Dockerfile.antigravity) failure is pre-existing and not caused by this PR

What's Good (🟢)

• Schema is genuinely machine-checkable — not just documentation theater
• The source field discipline (official-doc URLs for intrinsic facts, file.rs#symbol for OpenAB decisions) creates clear provenance
• Status::requires_source() ensures any "implemented"/"partial"/"workaround" claim must cite code evidence
• Quirks log captures valuable tribal knowledge (e.g., Feishu's post→card promotion state machine, Slack's stopStream duplication trap)
• PR description is exemplary — clear problem statement, architecture diagram, component table, follow-up issue decomposition

5️⃣ Three Reasons We Might Not Need This PR

1. Docs rot faster than code — Despite CI enforcement, the anti-drift only catches symbol renames/deletions; semantic drift (a feature's behavior changes but the function name stays the same) won't be caught. Counter: the schema version bump + code-ref system still makes staleness more visible than scattered comments, and follow-up ci(platform-schema): expand conformance workflow path triggers to cover adapter source code #1337 addresses the trigger-path gap.

2. 8 platforms × 3 schemas = maintenance burden — Every new feature added to EXPECTED_FEATURES requires updating all 8 files simultaneously. Counter: this is by design (forces completeness), the template makes it mechanical, and CI prevents partial updates from merging.

3. The quirks log may become a dumping ground — Freeform [[quirks]] sections are already verbose (10-12 entries per platform); without curation they could become noise. Counter: quirks carry date + kind for filtering, and the schema's purpose is to be comprehensive — a reviewer can ctrl+F for what they need rather than hunting through code.

All three concerns are acknowledged in the PR's follow-up issues or mitigated by the schema design. The net value (single source of truth for 8 platforms, CI-enforced freshness, day-1 onboarding) clearly outweighs the maintenance cost.