The capstone turns one Telegram-style request into a controlled content job. It does not send a message to Telegram or write to WordPress. Instead, it makes every boundary visible in local state: sender authorization, specialist dependencies, retry, review, human approval, Git commit, and delivery output.
- Duplicate updates resolve to the same job.
- Research fails once and succeeds on its second bounded attempt.
- Publication cannot begin without explicit human approval.
- The final artifact is committed to a local Git repository.
- Delivery is a JSON record marked
simulated.
1. Treat Telegram as an input boundary
A production Telegram gateway should allowlist numeric user IDs and keep the bot token in the Hermes profile’s secret store. Usernames are not stable authorization identifiers. The fixture reads a saved update, checks the numeric sender, and accepts only /article TOPIC; a blank topic is rejected.
The update ID becomes an idempotency key. Replaying the same update returns the original job instead of creating duplicate cards.
2. Build the specialist graph
The orchestrator creates researcher, code verifier, Korean writer, English localizer, and reviewer roles. Dependencies delay each role until its inputs are done. The English draft cannot start before the Korean draft, and review cannot start before localization.
This fixture records roles in one SQLite database. A deployed Hermes setup maps them to named profiles and lets the dispatcher spawn each profile. Workers update the board through kanban_* tools.
3. Retry without losing context
The simulated researcher records a temporary source timeout on attempt one, then succeeds on attempt two. Downstream roles start only after that success. A permanent failure should reach its configured limit and stop in blocked rather than spin forever.
The operation runbook explains how to inspect this state and recover. It also keeps normal review feedback separate from external blockers.
4. Put approval before side effects
Review completion moves the job to awaiting_approval. Calling publish() at that point raises ApprovalRequired. Only approve() changes the job to approved, and the approver’s identity is included in the artifact.
This ordering matters. Git creation and delivery happen after approval, so a reviewer cannot accidentally turn a candidate into a delivered result. Re-running preparation cannot move an approved or delivered job backward. The local commit also ignores ambient system and global Git configuration, starts without user templates, and disables hooks.
5. Run the complete simulation
cd examples/chapter-12-telegram-kanban-capstone
python3 pipeline.py --workspace demo-output --input telegram-update.json
python3 pipeline.py --workspace demo-approved --input telegram-update.json --approve
python3 -m unittest discover -s tests -vThe first command stops at the approval gate. The second uses a separate workspace, applies a demo human approval, commits the Markdown artifact, and writes a delivery record. The tests cover authorization, duplicate input, the approval barrier, two research attempts, a 40-character commit ID, and the destination chat ID.
6. Operate the real system carefully
In production, Telegram reaches Hermes through the gateway. The orchestrator creates and links Kanban tasks, specialists work from structured handoffs, and the reviewer requests changes or approves. A human then authorizes publication. Delivery should use the gateway and be read back before the job is marked successful.
The included runbook covers startup, inspection, recovery, and cleanup. Keep real credentials and authenticated platform responses outside the repository.
7. Understand what completion proves
The fixture proves the local workflow contract. It does not prove a live Telegram connection, provider availability, WordPress permissions, or public rendering. Those checks need real credentials supplied outside Git and separate readback from each target service.
The practical boundary is simple: local tests can approve the orchestration logic, but only target-system readback can approve an external write.
Leave a Reply