version: "1.0.0" name: hn-digest description: Fetch top Hacker News stories, pause for human editorial approval, and publish a curated Markdown digest using examples/hn_digest/actions.py.

Hacker News Curated Digest (hn_digest)

Executes the 3-stage Hacker News curation workflow using the Python helper functions in examples/hn_digest/actions.py.

Workflow Stages & Rules

1. Stage 1 — Fetch Top Stories (`fetch_top_stories`):

• Call actions.fetch_top_stories(payload) with `{"offline": True,

"limit": 3} (or live API if offline=False`).

• Returns (out_dict, msg) where out_dict contains `{"stories": [...],

"count": int, "top_title": str, "top_score": int, "source": str}`.

• Persist out_dict under payload["outputs"]["fetch_top_stories"] so

fetch_top_stories is not called again in Stage 3.

• Example invocation:

``bash python3 -B -c "import json, sys; sys.path.insert(0, 'examples/hn_digest'); import actions; out, msg = actions.fetch_top_stories({'offline': True, 'limit': 3}); print(json.dumps({'outputs': {'fetch_top_stories': out}, 'message': msg}))" ``

1. Stage 2 — Human Editorial Gate (`editorial_gate`):

• MANDATORY GATE: Stop after Stage 1 and present top_title,

top_score, and count to the human editor.

• Wait for their explicit approval and optional editor_note +

output_path before executing Stage 3. Never auto-approve.

1. Stage 3 — Publish Digest (`publish_digest`):

• Condition: Run only if the editor approved Stage 2. Do not

re-run fetch_top_stories.

• Call actions.publish_digest(payload) where payload contains:
• `"outputs": {"fetch_top_stories": <stage_1_out>, "editorial_gate":

{"editor_note": "<note>", "output_path": "<path>"}}`

• Writes the curated Markdown file atomically to output_path and returns

({"digest_path": str, "story_count": int, "simulated": bool}, msg).