INT-D1: publish the typed canonical quickstart

[skylarbpayne]

Summary

• publish HW-20's fully typed ReleaseNoteInput / ReleaseNoteResult workflow as the primary copyable example in the README, authoring guide, setup guide, and packaged creating skill
• switch the documented registry/run path to hermes_workflows.examples.install_smoke:release_note_workflow
• document and regression-test the exact serialized input, running state, typed Review Queue wait, and typed terminal result

Immutable receipts

• base / current framework main: 98370d28c71af8b29e47b2c9260d38da0be37f26
• INT-D1 head: 5194547ad399c343094a3cc5af0dfb154b500b1e
• effective FND-RT repair merge consumed: 1c9bf29fbfcf1aab56fa4a5cfaf83dc2d8c3eaa7
• original FND-RT merge consumed: 583459d3ee36dae63f89dbd87d175f91b53ec39d
• HW-20 reviewed head consumed: d1f7dd198ff8fc6283f833010423388940d355bf
• HW-20 merge consumed: 88d52e315f9a6ab90639711ac5c85d416de6da33
• excluded PR feat: support custom select values in review queue #131 head: fc9eb5ae0797c5cbdfcf51d6b9be551e6ba85331 (git merge-base --is-ancestor ... HEAD exited nonzero; it is not an ancestor)

TDD receipts

Red, before docs edits:

uv run pytest -q tests/test_launch_examples.py::test_primary_copyable_docs_execute_the_canonical_typed_wait_and_result tests/test_public_facade.py::test_primary_docs_publish_exact_typed_quickstart_behavior
2 failed in 0.38s
- README.md did not publish the canonical typed quickstart
- README.md did not contain the exact typed input/state behavior

Green after publication:

same targeted command
2 passed in 0.15s

uv run pytest -q tests/test_typed_quickstart_contract.py tests/test_launch_examples.py tests/test_public_facade.py tests/test_authoring_api.py
59 passed in 1.34s

Python compatibility and full suites:

uv run --isolated --python 3.9 pytest -q tests/test_typed_quickstart_contract.py tests/test_launch_examples.py tests/test_public_facade.py tests/test_authoring_api.py
59 passed in 1.44s

uv run --isolated --python 3.11 pytest -q tests/test_typed_quickstart_contract.py tests/test_launch_examples.py tests/test_public_facade.py tests/test_authoring_api.py
59 passed in 1.17s

uv run --isolated --python 3.9 pytest -q
659 passed, 1 skipped in 40.50s

uv run --isolated --python 3.11 pytest -q
658 passed, 2 skipped in 34.45s

Extracted copyable snippet

The new test extracts this block from every primary copyable surface, requires byte identity with docs/snippets/typed_quickstart.py, imports it, reaches the typed wait, submits a typed response, and asserts the Python result is ReleaseNoteResult.

Canonical extracted Python

from __future__ import annotations

from dataclasses import dataclass
from typing import Literal, Optional

from hermes_workflows import agent, ask, workflow


@dataclass(frozen=True)
class ReleaseNoteInput:
    change: str


@dataclass(frozen=True)
class Draft:
    text: str


@dataclass(frozen=True)
class ReviewDecision:
    action: Literal["approve", "request_changes"]
    feedback: Optional[str] = None


@dataclass(frozen=True)
class SideEffects:
    published: bool = False


@dataclass(frozen=True)
class ReleaseNoteResult:
    draft: Draft
    decision: ReviewDecision
    side_effects: SideEffects


@workflow
async def release_note_workflow(inputs: ReleaseNoteInput) -> ReleaseNoteResult:
    draft = await agent(
        "writer",
        prompt="Draft a release note for the supplied change.",
        input=inputs,
        returns=Draft,
        # The canonical quickstart must reach typed review without credentials.
        mock_output={"text": f"Release note: {inputs.change}"},
    )
    decision = await ask(
        "Review this release note.",
        key="review_release_note",
        input=draft,
        returns=ReviewDecision,
    )
    return ReleaseNoteResult(
        draft=draft,
        decision=decision,
        side_effects=SideEffects(),
    )


if __name__ == "__main__":
    raise SystemExit(release_note_workflow.run())  # type: ignore[attr-defined]

Exact output from executing the README-extracted block:

{"error":null,"result":null,"status":"running","waiting_on":null,"workflow_id":"wf_typed_quickstart"}
{"error":null,"result":null,"status":"waiting","waiting_on":"signal:operator.response:review_release_note","workflow_id":"wf_typed_quickstart"}
{"error":null,"result":{"decision":{"action":"approve","feedback":"Ready to ship."},"draft":{"text":"Release note: Expose typed workflow contracts."},"side_effects":{"published":false}},"status":"completed","waiting_on":null,"workflow_id":"wf_typed_quickstart"}

The documented registry alias was also exercised through the real CLI: run returned the exact running JSON, the foreground runner executed three commands, and status reported ReviewDecision at review_release_note with waiting_on=signal:operator.response:review_release_note.

Exact allowlist diff

• README.md
• docs/index.md
• docs/authoring.md
• docs/setup-for-agents.md
• src/hermes_workflows/plugin_skills/hermes-workflows-creating/SKILL.md
• tests/test_launch_examples.py
• tests/test_public_facade.py

git diff --check 98370d28c71af8b29e47b2c9260d38da0be37f26...HEAD emitted no output. The diff is exactly the seven allowlisted paths. .hermes/showcase-artifacts/** is unchanged.

Mutation statement

No live profile, install, registry, database, service, deployment, cutover, cron, plugin enablement, external send, or external coding-agent mutation was performed. Verification used only isolated Python environments and ephemeral test databases. Do not merge until the planned fresh INT-D1 specification review and separate quality/security review pass at this exact head.

Remote checks

• docs build: pass (20s); PR deploy correctly skipped
• tests pytest (3.11): pass (1m8s)
• tests pytest (3.9): pass (1m14s)