cairn-pack-hello 0.2.0__py3-none-any.whl

cairn_pack_hello/__init__.py

@@ -0,0 +1,11 @@
+"""hello-cairn — the example domain pack (#2423, ADR-0127 D2). Data plus glue; this
+shim builds the Pack from the ``pack.toml`` beside it. The glue (``hooks.py``,
+``tools/calc_server.py``) is reached through an entry point and a profile, never
+imported here."""
+from __future__ import annotations
+
+from cairn.core.pack import Pack
+
+pack = Pack.from_manifest(__file__)
+
+__all__ = ["pack"]

cairn_pack_hello/data/sample.jsonl

@@ -0,0 +1,20 @@
+{"id": 1, "text": "The soup arrived hot and the bread was fresh.", "label": "positive"}
+{"id": 2, "text": "Delivery took two hours longer than promised.", "label": "negative"}
+{"id": 3, "text": "The packaging was fine, nothing special.", "label": "neutral"}
+{"id": 4, "text": "Best noodles I have had in months.", "label": "positive"}
+{"id": 5, "text": "The order was missing the side salad.", "label": "negative"}
+{"id": 6, "text": "Portion size was about what I expected.", "label": "neutral"}
+{"id": 7, "text": "The courier was polite and quick.", "label": "positive"}
+{"id": 8, "text": "My drink had spilled inside the bag.", "label": "negative"}
+{"id": 9, "text": "I ordered the same dish as last week.", "label": "neutral"}
+{"id": 10, "text": "The dessert was a lovely surprise.", "label": "positive"}
+{"id": 11, "text": "The curry was far too salty to finish.", "label": "negative"}
+{"id": 12, "text": "Paid with the app, it worked as usual.", "label": "neutral"}
+{"id": 13, "text": "Everything was still warm when it came.", "label": "positive"}
+{"id": 14, "text": "The tracking map never updated.", "label": "negative"}
+{"id": 15, "text": "The menu has not changed since spring.", "label": "neutral"}
+{"id": 16, "text": "Great value for a weeknight dinner.", "label": "positive"}
+{"id": 17, "text": "The rice was undercooked again.", "label": "negative"}
+{"id": 18, "text": "Arrived at the time the app estimated.", "label": "neutral"}
+{"id": 19, "text": "The new vegetarian option is excellent.", "label": "positive"}
+{"id": 20, "text": "Support never answered my refund request.", "label": "negative"}

cairn_pack_hello/data/train.jsonl

@@ -0,0 +1,48 @@
+{"text": "The tea works well on cold mornings."}
+{"text": "A paper map needed a second try."}
+{"text": "The bicycle bell fits in a coat pocket."}
+{"text": "This notebook looks better in person."}
+{"text": "The garden hose is lighter than it looks."}
+{"text": "A wool scarf smells faintly of cedar."}
+{"text": "The desk lamp made less noise than expected."}
+{"text": "That umbrella arrived a day early."}
+{"text": "The bread knife lasted the whole season."}
+{"text": "A clay mug was easy to set up."}
+{"text": "The tea works well on cold mornings."}
+{"text": "A paper map needed a second try."}
+{"text": "The bicycle bell fits in a coat pocket."}
+{"text": "This notebook looks better in person."}
+{"text": "The garden hose is lighter than it looks."}
+{"text": "A wool scarf smells faintly of cedar."}
+{"text": "The desk lamp made less noise than expected."}
+{"text": "That umbrella arrived a day early."}
+{"text": "The bread knife lasted the whole season."}
+{"text": "A clay mug was easy to set up."}
+{"text": "The tea works well on cold mornings."}
+{"text": "A paper map needed a second try."}
+{"text": "The bicycle bell fits in a coat pocket."}
+{"text": "This notebook looks better in person."}
+{"text": "The garden hose is lighter than it looks."}
+{"text": "A wool scarf smells faintly of cedar."}
+{"text": "The desk lamp made less noise than expected."}
+{"text": "That umbrella arrived a day early."}
+{"text": "The bread knife lasted the whole season."}
+{"text": "A clay mug was easy to set up."}
+{"text": "The tea works well on cold mornings."}
+{"text": "A paper map needed a second try."}
+{"text": "The bicycle bell fits in a coat pocket."}
+{"text": "This notebook looks better in person."}
+{"text": "The garden hose is lighter than it looks."}
+{"text": "A wool scarf smells faintly of cedar."}
+{"text": "The desk lamp made less noise than expected."}
+{"text": "That umbrella arrived a day early."}
+{"text": "The bread knife lasted the whole season."}
+{"text": "A clay mug was easy to set up."}
+{"text": "The tea works well on cold mornings."}
+{"text": "A paper map needed a second try."}
+{"text": "The bicycle bell fits in a coat pocket."}
+{"text": "This notebook looks better in person."}
+{"text": "The garden hose is lighter than it looks."}
+{"text": "A wool scarf smells faintly of cedar."}
+{"text": "The desk lamp made less noise than expected."}
+{"text": "That umbrella arrived a day early."}

cairn_pack_hello/flows/assistant.md

@@ -0,0 +1,97 @@
+---
+name: assistant
+version: 0.1.0
+module: ask
+tags:
+  - flow:state_machine
+  - domain:example
+description: |
+  Answer a question from the pack's own docs: retrieve from the `docs` corpus,
+  re-rank, ask a model, measure the answer with a tool on the example's MCP server,
+  and remember the exchange. The agentic leg of `ask-the-docs`.
+
+flow:
+  type: state_machine
+  source: behavior_tree
+  root:
+    type: sequence
+    children:
+      # Retrieval: the builtin rag/search over the corpus pack.toml declares as
+      # [requires.rag.docs] (sqlite-vec by default; pgvector when RAG_VECTOR_STORE
+      # says so). Read-only.
+      - type: operation
+        operator: rag/search
+        id: search
+        input:
+          corpus: docs
+          query: $input.question
+          top_k: 5
+        output:
+          hits: $state.findings.hits
+          ok: $state.findings.search_ok
+          error: $state.findings.search_error
+      # Re-rank the hits (identity unless a cross-encoder or Cohere is installed).
+      - type: operation
+        operator: rag/rerank
+        id: rerank
+        input:
+          query: $input.question
+          hits: $default($state.findings.hits, [])
+          top_k: 3
+        output:
+          hits: $state.findings.context
+          reranker_used: $state.findings.reranker
+      # The model call. The compiler builds it through core's build_chat_model, so
+      # the call is redacted (when a redact.text binding is active) and costed.
+      - type: action
+        ref: answer
+      # A tool call on the example's own stdio MCP server (tools/calc_server.py),
+      # through the builtin mcp/call operator: governed and audited like any tool call.
+      - type: operation
+        operator: mcp/call
+        id: measure
+        input:
+          server: hello-calc
+          tool: word_count
+          args:
+            text: $state.findings.answer
+        output:
+          result: $state.findings.answer_stats
+          ok: $state.findings.measure_ok
+          error: $state.findings.measure_error
+      # Remember the exchange in a local memory store (memory/write, sqlite-vec). A
+      # store name is a collection name: letters, digits and underscores only.
+      - type: operation
+        operator: memory/write
+        id: remember
+        input:
+          store: hello_answers
+          record:
+            question: $input.question
+            answer: $state.findings.answer
+          embed_text: $input.question
+        output:
+          ok: $state.findings.remembered
+          id: $state.findings.memory_id
+          error: $state.findings.memory_error
+
+  nodes:
+    answer:
+      type: prompt
+      model: gpt-4o-mini
+      capabilities: []
+      prompt_section: answer
+
+tools:
+  required: []
+---
+
+# Ask the docs
+
+## answer
+
+You answer a question about the hello-cairn example pack. The retrieved passages
+are in `state.findings.context` (each hit's `payload.content` is the text, and
+`payload.source` names the file). Answer in at most three sentences, using only
+what the passages say, and name the file you used. When the passages do not cover
+the question, say that the docs do not cover it. Do not invent features.

cairn_pack_hello/flows/engine-check.yaml

@@ -0,0 +1,23 @@
+# flows/engine-check.yaml — a data flow on the builtin engine (#2423).
+#
+# A flow is a list of stages the dataflow engine runs as ONE governed leg. The
+# public core installs exactly one stage provider, cairn-operator-dataflow, and it
+# ships only the conformance stages `noop` and `noop.slow` (the real kernels:
+# dedup, PII redaction, export, live in official operator packs). So this flow
+# is honest about what it is: it proves the flow-leg path end to end (engine
+# selection, the flow gate on aggregate stage risk, a leg Run in the record)
+# and transforms nothing. Swap the stage for a real kernel once one is installed.
+name: engine-check
+kind: data
+description: >
+  One `noop` stage on the builtin dataflow engine: shows a flow leg in the
+  record without touching data, and registers the checked file's content as a
+  version of the dataset the leg names (#2632).
+stages:
+  - stage: noop
+    config:
+      # Bound by the pipeline leg's `with:`; unbound keys are dropped. With both set,
+      # the control plane registers `register` at `source`'s content hash: a changed
+      # file is a new version, which is what a `dataset` watch sees.
+      register: $config.register
+      source: $config.source

cairn_pack_hello/flows/lora.yaml

@@ -0,0 +1,25 @@
+# flows/lora.yaml — a LoRA fine-tune as an ml flow (hello-cairn WP6, ADR-0127 D4).
+#
+# One stage, `train.lora`, from the builtin train-local operator pack
+# (cairn-operator-train-local, contract train.finetune/1.0.0). The stage takes the
+# contract's input keys as its config; every `$config.<key>` the leg does not bind is
+# dropped, so the stage's own defaults apply (Qwen/Qwen2.5-0.5B, 8 steps, 64 rows).
+# `mock: true` runs the torch-free stand-in: no training stack, deterministic numbers.
+#
+# The real fine-tune needs the `[train]` extra of cairn-operator-train-local (torch,
+# transformers, peft, datasets) on the box the ml engine runs on; CPU is enough. The
+# stage writes the adapter under the leg's workdir and reports `kind: model`, so the
+# leg registers a model artifact the pipeline can promote.
+name: lora
+kind: ml
+description: >
+  LoRA fine-tune a small causal LM on a JSONL of {"text": ...} rows (CPU).
+stages:
+  - stage: train.lora
+    config:
+      dataset: $config.dataset
+      base_model: $config.base_model
+      lora_rank: $config.lora_rank
+      steps: $config.steps
+      max_samples: $config.max_samples
+      mock: $config.mock

cairn_pack_hello/flows/nightly-job.md

@@ -0,0 +1,59 @@
+---
+name: nightly-job
+version: 0.1.0
+module: ops
+tags:
+  - flow:state_machine
+  - flow:operation-driven
+  - domain:example
+description: |
+  The nightly job: check that the job's secret is present, then run a report
+  command on an SSH box and fetch what it wrote. The first leg of `nightly-ops`.
+
+flow:
+  type: state_machine
+  source: behavior_tree
+  root:
+    type: sequence
+    children:
+      # A capability node, not an operator: the active profile's
+      # [profile.bindings] "secrets.store" picks the implementation
+      # (secrets/env in profiles/hello.toml, secrets/infisical in
+      # profiles/hello-infisical.toml). A presence check: the value never
+      # enters the run's state.
+      - type: operation
+        capability: contract://secrets.store/1.0.0
+        id: secret
+        input:
+          name: $input.secret_name
+        output:
+          present: $state.findings.secret_present
+      # The SSH job (builtin remote/exec). The box comes from a `compute.ssh`
+      # connection named by the run input, never from the template.
+      - type: operation
+        operator: remote/exec
+        id: report
+        execution:
+          compute_target: $input.compute_target
+        input:
+          command: $input.command
+          env:
+            HELLO_SECRET_PRESENT: $state.findings.secret_present
+        output:
+          status: $state.findings.job_status
+          exit_code: $state.findings.job_exit_code
+          host: $state.findings.job_host
+          metrics: $state.findings.report
+          error: $state.findings.job_error
+  nodes: {}
+
+tools:
+  required: []
+---
+
+# Nightly job
+
+Two operation nodes and no model: the secret check runs through whichever
+`secrets.store` implementation the profile binds, and the report runs over SSH on
+the box the `compute_target` input names. The command writes `metrics.json` in its
+working directory; `remote/exec` reads it back as `report`.

cairn_pack_hello/flows/summarise.yaml

@@ -0,0 +1,18 @@
+# flows/summarise.yaml — the nightly report's data flow (hello-cairn WP6).
+#
+# Two builtin stages on the builtin dataflow engine. The public core ships only the
+# conformance stages (`noop`, `noop.slow`), so this flow carries the report through
+# the engine without transforming it: what it proves is the flow leg itself (engine
+# selection, the flow gate on aggregate stage risk, a leg Run and a registered
+# artifact in the record). `noop.slow` with a short `seconds` shows a leg that takes
+# time and reports progress. Swap in a real kernel once an operator pack provides one.
+name: summarise
+kind: data
+description: >
+  Carry the nightly report through the builtin dataflow engine: two conformance
+  stages, nothing transformed.
+stages:
+  - stage: noop
+  - stage: noop.slow
+    config:
+      seconds: 1

cairn_pack_hello/hooks.py

@@ -0,0 +1,51 @@
+"""hello-cairn's run-hook listener: a receipt line per settled leg and finished run.
+
+Glue, not an operator (ADR-0127 D2). The engine fires run hooks through the
+`cairn.run_hooks` entry-point group (cairn/core/pack/run_hooks.py); this pack's
+pyproject declares
+
+    [project.entry-points."cairn.run_hooks"]
+    hello-receipts = "cairn_pack_hello.hooks:receipts"
+
+so installing the wheel is what turns it on. A dev pack loaded through
+`CAIRN_PACK_PATH` declares no entry points, so nothing fires there.
+
+Every `leg.finished`, `run.finished` and `run.failed` appends one JSON line to
+`$CAIRN_HOME/hello-cairn/receipts.jsonl` (`CAIRN_HOME` defaults to `~/.cairn`). The
+hook sees every run on the engine, not only this pack's, which is what a receipt log
+is for. Only JSON scalars from the payload are written: `run.finished` also carries
+the dispatcher's run store, which is an object, not data.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+#: The events a receipt is written for; the others pass through untouched.
+EVENTS = ("leg.finished", "run.finished", "run.failed")
+
+
+def receipts_path() -> Path:
+    home = os.environ.get("CAIRN_HOME") or str(Path.home() / ".cairn")
+    return Path(home).expanduser() / "hello-cairn" / "receipts.jsonl"
+
+
+async def receipts(event: str, payload: dict[str, Any]) -> None:
+    """``(event, payload) -> None``, the run-hook signature."""
+    if event not in EVENTS:
+        return
+    line = {k: v for k, v in payload.items() if isinstance(v, (str, int, float, bool)) or v is None}
+    line["at"] = datetime.now(timezone.utc).isoformat(timespec="seconds")
+    # Hooks run on the engine's event loop; the file write goes to a worker thread so a
+    # slow disk never stalls the dispatcher.
+    await asyncio.to_thread(_append, receipts_path(), json.dumps(line, sort_keys=True))
+
+
+def _append(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as fh:
+        fh.write(text + "\n")

cairn_pack_hello/pack.toml

@@ -0,0 +1,50 @@
+# hello-cairn — the example domain pack (#2423, ADR-0120 D1; the feature proof,
+# ADR-0127 D1/D2).
+#
+# The one pack the public core ships so a fresh install has something governed
+# to run. It needs the engine and the builtin operator packs, and nothing from the
+# platform: four pipelines, one per kind of work (data, agentic, ml, operations).
+#
+# A domain pack is DATA plus glue, never operators (ADR-0127 D2): this manifest,
+# `pipelines/*.yaml` (the runnable surface), `flows/` (the components the
+# pipelines' flow and template legs name), `rag/docs` (a corpus), `data/`,
+# `policies/`, `profiles/`, the one-line `__init__.py`, a run-hook listener
+# (`hooks.py`, declared through the `cairn.run_hooks` entry point in pyproject.toml)
+# and a stdio MCP tool server (`tools/calc_server.py`). Neither piece of glue
+# registers an operation. Assets are found by convention (`pipelines/`, `flows/`,
+# `rag/`, `data/`, `policies/`), so there is no `[assets]` block.
+
+[pack]
+name        = "hello-cairn"
+version     = "0.2.0"
+description = "Example pack: check a dataset, ask its docs, fine-tune a small model and run a nightly job, each behind gates a person or the data answers."
+tags = [
+    "domain:example",
+    "data:jsonl",
+]
+kind        = "domain"
+publisher   = "cairn"
+trust_level = "builtin"
+
+[compat]
+cairn_engine = ">=0.1.0"
+
+# No `[requires] capabilities`: that table is satisfied by other DOMAIN packs'
+# `[provides]`, not by operator packs, so naming `data.profile` / `storage.put`
+# here would be a composition conflict on every deployment. The pipeline's
+# task legs are checked against the operator registry at plan time instead
+# (`cairn pipeline explain` names the operator class each leg resolves to).
+
+# The corpus ask-the-docs retrieves from. Indexed by the engine, not by a leg:
+# with CAIRN_RAG_AUTOINDEX=1 the server indexes every declared corpus at boot into
+# the collection rag/search reads (cairn/services/rag/lifecycle.py).
+[requires.rag.docs]
+corpus = "rag/docs"
+access = "vector_search"
+
+# The MCP server ask-the-docs' assistant template calls (tools/calc_server.py).
+# The profile names it under [profile.mcp_servers]; `cairn doctor` reports a
+# profile that does not.
+[requires.mcp]
+servers = ["hello-calc"]
+tools   = ["hello-calc:word_count", "hello-calc:add"]

cairn_pack_hello/pipelines/ask-the-docs.yaml

@@ -0,0 +1,85 @@
+# pipelines/ask-the-docs.yaml — the agentic pipeline (hello-cairn WP6, ADR-0127 D1).
+#
+#   assistant (template: search → rerank → model → MCP tool → memory)
+#     → length (monitor/threshold) → review ⏸
+#
+# The work happens in ONE template leg, flows/assistant.md: retrieval over the
+# `docs` corpus this pack ships (pack.toml [requires.rag.docs] → rag/docs/*.txt), a
+# re-rank, one model call built by core's build_chat_model, a tool call on the
+# example's own stdio MCP server (tools/calc_server.py, through the builtin mcp/call)
+# and a memory write. Then a threshold check on how long the answer is, and a person
+# reads it before anyone relies on it.
+#
+# What this needs from the engine (README "ask-the-docs"):
+#   * a model: OPENAI_API_KEY (or LLM_GATEWAY=proxy + LLM_GATEWAY_URL for any
+#     OpenAI-compatible gateway). The engine has no built-in mock model.
+#   * an embedder for retrieval and memory: RAG_EMBED_PROVIDER=openai (or gemini).
+#   * the corpus indexed: CAIRN_RAG_AUTOINDEX=1 on the server indexes every declared
+#     corpus at boot (needs the `rag` extra). There is no indexing operator; an
+#     un-indexed corpus answers with zero hits, and the model says the docs do not
+#     cover the question.
+#   * the MCP server named in the engine's environment, CAIRN_MCP_SERVERS (README).
+#
+# Starts on an event (ADR-0131 D4): when `profile-and-publish` publishes, its
+# `publish` leg emits `dataset.ready`; the `kind: event` trigger below starts this
+# pipeline once per message, paused until someone turns it on (README "Events").
+name: ask-the-docs
+kind: pipeline
+visibility: public
+description: >
+  Answer a question from the example's own docs with retrieval, a model call and
+  an MCP tool, check the answer's length, and have a person read it.
+outcome: Ask a question of a small document set
+suite: operate
+
+inputs:
+  question: {type: str, default: "What is the difference between a data gate and a person gate?", description: "The question to answer from rag/docs."}
+  max_words: {type: int, default: 120, description: "Answers longer than this many words are flagged by the length check."}
+
+triggers:
+  - kind: event
+    topic: dataset.ready
+    enabled: false
+    description: Ask the docs again whenever the sample dataset is published.
+
+governance:
+  # One small model call; the reservation is the ceiling, not the expected spend.
+  budget: {usd: 0.5}
+  series: hello
+  approvers: data-owners
+
+steps:
+  # ── the agentic leg ───────────────────────────────────────────────────────
+  - id: assistant
+    label: Answer from the docs
+    template: assistant
+    with:
+      question: $input.question
+
+  # ── a threshold on the answer (read-only) ─────────────────────────────────
+  # `crossed` is true when the answer runs longer than max_words. The word count
+  # comes from the MCP tool the template called.
+  - id: length
+    label: Check the answer's length
+    task: monitor/threshold
+    depends_on: [assistant]
+    with:
+      metric: answer words
+      value: $steps.assistant.answer_stats.words
+      threshold: $input.max_words
+      comparator: gt
+
+  # ── the PERSON gate ───────────────────────────────────────────────────────
+  - gate: review
+    depends_on: [length]
+    approvers: data-owners
+    show:
+      - assistant.answer
+      - assistant.reranker
+      - length.value
+      - length.crossed
+
+outputs:
+  answer: assistant.answer
+  words: length.value
+  too_long: length.crossed

cairn_pack_hello/pipelines/nightly-ops.yaml

@@ -0,0 +1,108 @@
+# pipelines/nightly-ops.yaml — the operations pipeline (hello-cairn WP6, ADR-0127 D1).
+#
+#   job (template: secret check → SSH report) → summarise (flow)
+#     → propose ⏸ → audit
+#
+# A job that runs every night without a person starting it, and still asks one
+# before anything follows from it:
+#
+#   * `job` (flows/nightly-job.md) checks the job's secret through whatever the
+#     profile binds to `secrets.store` (secrets/env by default, Infisical with
+#     profiles/hello-infisical.toml), then runs `command` on an SSH box through the
+#     builtin remote/exec. The box is a `compute.ssh` connection (`cairn connect add
+#     ssh`) the `compute_target` input names; a template node is where remote/exec
+#     gets one (a `task:` leg has no `execution.compute_target`).
+#   * `summarise` carries the report through the builtin dataflow engine.
+#   * `propose` files the follow-up for a person: monitor/propose declares
+#     `requires_approval`, so this leg waits on the approval queue.
+#   * `audit` writes a hash-chained audit row.
+#
+# Every leg that settles fires the `leg.finished` run hook; this pack's
+# `hello-receipts` listener (hooks.py) appends a receipt line for it.
+name: nightly-ops
+kind: pipeline
+visibility: public
+description: >
+  Check a secret, run a report on an SSH box, carry it through a flow, propose
+  the follow-up to a person, and audit it. Runs nightly once enabled.
+outcome: Run a nightly job on a box you own
+suite: operate
+
+inputs:
+  compute_target: {type: str, default: "hello-ssh", description: "The compute.ssh connection to run the report on (cairn connect add ssh --name hello-ssh …)."}
+  secret_name: {type: str, default: "HELLO_REPORT_TOKEN", description: "The secret the job needs; checked for presence, never read into the run."}
+  command:
+    type: str
+    default: "printf '{\"lines\": %s, \"host\": \"%s\"}' \"$(ls / | wc -l | tr -d ' ')\" \"$(hostname)\" > metrics.json && cat metrics.json"
+    description: "The report command. It writes metrics.json in its working directory; remote/exec reads it back."
+  max_lines: {type: int, default: 100, description: "The proposal's threshold, shown on the approval card."}
+
+governance:
+  budget: {usd: 0.1}
+  series: hello
+  approvers: ops
+
+triggers:
+  # The nightly run. `enabled: true` arms it when the pipeline is enabled in a
+  # workspace; until then it is a declaration.
+  - kind: schedule
+    cron: "30 2 * * *"
+    misfire: skip
+    enabled: true
+    description: "Every night at 02:30 (engine time)."
+  # Rows past the watermark in a Postgres table start a proposal. A `table` source
+  # needs a database the engine can reach: here the DSN is read from the env var
+  # HELLO_EVENTS_DSN at fire time, never written in this file. Declared, NOT armed on a
+  # pipeline: a `table` watch needs the platform's governed import, so core names it
+  # unarmed (ADR-0131 D3) — it shows in the console as declared, not armed here.
+  - kind: watch
+    source: {kind: table, dsn_env: HELLO_EVENTS_DSN, table: hello_events, cursor: id}
+    every: "*/10 * * * *"
+    register_as: hello-events
+    on_change: propose
+    enabled: false
+    description: "Propose a run when hello_events gains rows (needs Postgres)."
+
+steps:
+  # ── the job: secret check + SSH report (template leg) ─────────────────────
+  - id: job
+    label: Run the nightly report
+    template: nightly-job
+    with:
+      compute_target: $input.compute_target
+      secret_name: $input.secret_name
+      command: $input.command
+
+  # ── carry the report through a flow ───────────────────────────────────────
+  - id: summarise
+    label: Summarise the report
+    flow: summarise
+    depends_on: [job]
+
+  # ── propose the follow-up (waits for a person) ────────────────────────────
+  - id: propose
+    label: Propose the follow-up
+    task: monitor/propose
+    depends_on: [summarise]
+    with:
+      metric: report lines
+      value: $default($steps.job.report.lines, 0)
+      threshold: $input.max_lines
+      proposed_workflow: "pipeline:hello-cairn/profile-and-publish"
+
+  # ── the audit record ──────────────────────────────────────────────────────
+  - id: audit
+    label: Record the nightly run
+    task: audit/store
+    depends_on: [propose]
+    with:
+      action: hello.nightly.reported
+      outcome: ok
+      actor: ops
+      target: $steps.job.job_host
+
+outputs:
+  host: job.job_host
+  report: job.report
+  approved: propose.approved
+  audit_hash: audit.hash