Ground the repo docs and move presence provisioning to a declared spec

Align AGENTS.md with the FT-WP- prefix the hub already registered, and
rewrite INTENT.md and SCOPE.md, which were still the generated stubs and
carried none of the composed-post framing the interface is built around.

Fix two artifact inconsistencies: R-1's retry comment still described
POST /v1/hall-entries idempotent on entry_id, from before the reframe to
composed posts; and the seed pressure record listed only one of the two
hypotheses that cite it. Rename it to match its id.

Replace the manual T01-T03 route with FT-WP-0002. The Bot API cannot
create a bot or a channel, so provisioning is an MTProto client acting as
a designated operator account (Canon INT-03), driven from a declared
presence spec owned by the campaign. One bounded human bootstrap remains
and docs/provisioning.md says why it cannot be removed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0172sgCZEEDJcnQmr4SGDvKa

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 1361245@bnt-lap001
Assistant-Session: b3b428ef-f3e6-4688-b091-01f71461d66a
This commit is contained in:
tegwick 2026-09-04 19:21:08 +02:00
parent 3dae4ae74c
commit 5a785b9d9f
11 changed files with 670 additions and 46 deletions

View file

@ -1,32 +1,69 @@
# SCOPE
> This file was generated by `statehub register`. Refine it as the repository
> boundaries become clearer.
## One-liner
Fluid interface for telegram messaging and interaction platform.
The deterministic delivery interface that publishes composed HelixForge posts to
Telegram, under a governed contract with a reconstructible audit trail.
## Core Idea
fluid-telegram exists to provide the capability described in INTENT.md.
A caller submits a **composed post** — already written, already reviewed,
carrying a consent basis and a citation to its source entry. This interface
validates it, renders it into the Telegram form the serving revision calls for,
delivers it through the Bot API, and reports how it performed.
Everything about *what to say and when* lives elsewhere. Everything about *how
it is carried and proven* lives here.
## In Scope
- Maintain the repository's primary implementation.
- Keep docs, tests, and operational metadata current.
- The R-1 contract (`contracts/r1.openapi.yaml`) and its revisions.
- The adapter: rendering, delivery, idempotency on `post_id`, custody of the bot
token for the duration of a call.
- Validation and refusal: no reviewer, no consent basis, or a body that exceeds
the limit for the form being published → refused, never truncated.
- Delivery experiments (`E-tg-delivery`, cohort `telegram-subscribers`) and the
hypotheses behind them.
- Per-variant engagement reporting back to the campaign.
- Observation and redaction policy (`docs/observation.md`).
- Bot and channel configuration, and the provisioning of that configuration from
a declared specification (FT-WP-0002).
- Operational recovery: token rotation, channel administration, revision
rollback (`docs/runbook.md`).
## Out of Scope
- Own unrelated adjacent systems.
- Make irreversible operational decisions without human approval.
- **Composition and editorial voice.** Condensing an entry into a post, choosing
which work is worth publishing, the publishing cadence, variant strategies.
These belong to `pr-hall-of-helix`.
- **Consent records and the review queue.** The campaign obtains and holds them;
this interface only refuses a post that arrives without one.
- **Reading `hall-of-helix`.** The adapter's only knowledge of an entry is the id
and URL a post cites, which it renders as a link.
- **Autonomous administration.** Creating, renaming or deleting channels, groups
or bots, and changing membership or permissions, are forbidden to the Daimon
(IEI-1 §7). Where such acts are automated at all, they run in the separate,
human-approved provisioning plane, never in the request path.
- Owning unrelated adjacent systems.
## Current State
- Status: active; implementation and stability should be verified by the repo agent.
Design-complete, not yet live. Governance, the R-1 contract, the adapter's
connector contract, observation configuration, the seed pressure record and two
competing hypotheses are in place. The bot, the channels and the adapter are
not.
- Work: `workplans/FT-WP-0001-telegram-identity-and-hall-channel.md` (active)
- Provisioning: `workplans/FT-WP-0002-*` (declared-presence provisioning; supersedes
the manual T01T03 route)
- Depends on: `fluid-core` `FLUID-WP-0008` (handover)
- Not yet created: `pr-hall-of-helix`
## Getting Oriented
- Start with: INTENT.md
- Agent instructions: AGENTS.md
- Workplans: workplans/
- Why it exists: `INTENT.md`
- What may change and what may not: `InterfaceEvolutionIntent.md` (IEI-1)
- What the adapter owes: `docs/adapter-contract.md`
- Platform capability reference: `TelegramCapabilityCanon.md`
- Agent instructions: `AGENTS.md`
- Workplans: `workplans/`