docs: announce F1.2 Robot Mode contract v1 (CHANGELOG + ADR + marketing) #48

New Issue

2026-05-07T04:03:54+02:00

product-owner commented

2026-05-07 04:03:54 +02:00

WIG alignment: WIG-3 (agent orchestration / MCP integration)

Compound-RICE: reach=70 impact=7 confidence=0.9 synergy=2.5 effort=2 maintenance=1.0 -> score=551 (critical)

Problem

Once #35 (wire ExitCode), #44 (regression suite), and #21 (robot meta fields) are merged, the F1.2 Robot Mode contract is technically ready -- but there is no public announcement, no CHANGELOG entry, and no ADR locking the schema. AI orchestrators integrating with terraphim-agent currently have no way to discover that the contract is stable, what guarantees apply, or where to find the canonical exit-code / envelope reference.

A feature is not done until the market hears about it. This issue closes the loop on the F1.2 contract by producing the announcement, doc anchor, and changelog entry that turn engineering completion into an adoption-ready artefact.

Proposed Solution

Add a "Robot Mode F1.2 Contract v1" entry under the next release in CHANGELOG.md
Create an ADR under docs/adr/ capturing the exit-code table and JSON envelope schema as a stable contract
Produce one orchestrator-targeted announcement artefact: README banner, blog post draft, or release-notes excerpt under /docs
Include a runnable example in the announcement showing terraphim-agent robot search "..." | jq with documented exit-code semantics

Acceptance Criteria (mini-UAT)

Given #35, #44, #21 are merged and CI green
When the F1.2 contract is declared v1
Then CHANGELOG.md contains a "Robot Mode F1.2 contract v1" entry under the next release
  And docs/adr/ contains a new ADR locking exit-code + envelope schema
  And one orchestrator-targeted announcement artefact exists in /docs
  And the announcement includes a runnable example demonstrating exit-code propagation
  And the ADR cross-references issues #35, #44, #21 as the implementation evidence

Marketing hint: "Terraphim Agent now ships a stable Robot Mode contract: deterministic exit codes, structured JSON envelope, and matched-concept telemetry. AI orchestrators can integrate it as a deterministic Unix tool."

Suggested agent: technical-writer (with technical-cto review for the announcement copy)

Created by Themis (product-owner) -- Compound-RICE + Essentialism + UAT cycle 2026-05-07
Trade-off this cycle: opening this single doc/announce issue means not opening additional F3.x scope. A feature is not done until announced.

**WIG alignment**: WIG-3 (agent orchestration / MCP integration) **Compound-RICE**: reach=70 impact=7 confidence=0.9 synergy=2.5 effort=2 maintenance=1.0 -> score=551 (critical) ## Problem Once #35 (wire ExitCode), #44 (regression suite), and #21 (robot meta fields) are merged, the F1.2 Robot Mode contract is technically ready -- but there is no public announcement, no CHANGELOG entry, and no ADR locking the schema. AI orchestrators integrating with terraphim-agent currently have no way to discover that the contract is stable, what guarantees apply, or where to find the canonical exit-code / envelope reference. A feature is not done until the market hears about it. This issue closes the loop on the F1.2 contract by producing the announcement, doc anchor, and changelog entry that turn engineering completion into an adoption-ready artefact. ## Proposed Solution - Add a "Robot Mode F1.2 Contract v1" entry under the next release in `CHANGELOG.md` - Create an ADR under `docs/adr/` capturing the exit-code table and JSON envelope schema as a stable contract - Produce one orchestrator-targeted announcement artefact: README banner, blog post draft, or release-notes excerpt under `/docs` - Include a runnable example in the announcement showing `terraphim-agent robot search "..." | jq` with documented exit-code semantics ## Acceptance Criteria (mini-UAT) ```gherkin Given #35, #44, #21 are merged and CI green When the F1.2 contract is declared v1 Then CHANGELOG.md contains a "Robot Mode F1.2 contract v1" entry under the next release And docs/adr/ contains a new ADR locking exit-code + envelope schema And one orchestrator-targeted announcement artefact exists in /docs And the announcement includes a runnable example demonstrating exit-code propagation And the ADR cross-references issues #35, #44, #21 as the implementation evidence ``` **Marketing hint**: "Terraphim Agent now ships a stable Robot Mode contract: deterministic exit codes, structured JSON envelope, and matched-concept telemetry. AI orchestrators can integrate it as a deterministic Unix tool." **Suggested agent**: technical-writer (with technical-cto review for the announcement copy) --- *Created by Themis (product-owner) -- Compound-RICE + Essentialism + UAT cycle 2026-05-07* *Trade-off this cycle: opening this single doc/announce issue means not opening additional F3.x scope. A feature is not done until announced.*

product-owner referenced this issue

2026-05-07 04:04:36 +02:00

feat: wire ExitCode into main() return for f1.2 robot exit code contract #35

product-owner referenced this issue

2026-05-07 07:07:14 +02:00

feat: install SIGTERM/SIGPIPE signal handlers in robot mode and emit JSON envelope before exit #51

product-owner referenced this issue

2026-05-07 07:07:46 +02:00

feat: emit JSON error envelope on robot-mode failures #50

product-owner referenced this issue

2026-05-09 03:03:13 +02:00

ci: enforce F1.2 robot-contract regression job on every PR #49