docs← Back to article

Markdown for LLMs

A typical task along a canon's route

The source Markdown for this article. Copy it into your assistant or download it as a text file.

Download this articlePlain text ↗
# A typical task along a canon's route

A question to a canon gets one answer. A typical task — a customs dossier
for an import, an insurance payout, a measurement uncertainty report — is
many questions in the right order, facts from a person between them and a
document at the end. The canon's author knows the order and publishes it next
to the package as a **task guide** (`analysis/task-guides.json`):
which case to pin, which facts to collect and from where,
which question cards to ask, where to go on every answer status, and which
answers fill which fields of the document.

A guide carries no formula, rate, deadline or threshold: those live in the
canon's `.law`. It does not choose a disputed reading and does not judge for
an authority — a person decides that at a decision step. The engine still
executes and proves; the agent and the person only walk the graph and copy
answers.

After this page you can take one report from an empty journal to a
finished document and say where every value in it came from. The example is
the GUM measurement uncertainty report, `jcgm.gum/uncertainty-report`; it is
carried through the whole page.

## The report we are building

A measurement result `r` in microvolts has an estimate of 150 µV and two
input quantities, `x1` and `x2`, each entering with sensitivity 1 and
uncorrelated. A calibration certificate quotes 12 µV for `x1`; for `x2` only
the bounds ±15 µV are known. The person compiling the report chooses a
coverage factor k = 2. The identifiers are the ones in the author's
case collection `otchet-neopredelennosti` that ships with the canon, case
`KVybranChelovekom` ("k chosen by a person").

The finished document has these values. Each comes from one step of the
route; the right-hand column names it.

| Section · field | Value | Filled by |
|---|---|---|
| Case · result | `urn:example:gum:r` | `pin-case`: the person binds the result |
| Case · date | 2026-09-06 | the case's legal time, named in `journal new` |
| Case · coverage factor k | 2/1 | `collect-coverage`: the person names k |
| Budget · number of inputs | 2 | `ask-input-count` |
| Budget · u²(xi) | x1: 144/1, x2: 75/1 | `ask-input-variance`, once per input |
| Budget · contributions | x1: 144/1, x2: 75/1 | `ask-input-contribution`, once per input |
| Budget · combined uc(y) | 15 µV (√219, rounded) | `ask-combined` |
| Coverage · degrees of freedom | open: empty collection, not zero | `ask-dof` |
| Result · expanded U | 30 µV | `ask-expanded` |
| Result · U/y | 1/5 | `ask-relative-expanded` |
| Result · level of confidence | about 95 % | `ask-level` |
| Result · complete per 7.2.3 | `TRUE_ONLY` | `ask-report-complete` |
| Free fields · compiled by, instrument | what the person typed | `request-free-fields` |

These are the values the collection expects; they follow from the GUM
formulas, not from a model's arithmetic. No number in the table is typed by
the agent or the person except k and the free fields: every other value is
copied from an answer the engine computed and the journal recorded.

## Find a guide

From an assistant over MCP, guides are the server's prompts. `prompts/list`
names them `<package>/<guide id>`; `prompts/get` with `legal_time` and the
optional `case`, `locale` and `step` returns the task frame, the pinned
packages, a window of the next steps with ready `law_ask` calls and the
uniform template for reading statuses. Getting a prompt executes nothing and
accepts no facts. The GUM uncertainty report (`jcgm.gum/uncertainty-report`)
is visible on the public science slice. The profile's guide catalog is
`law_packages` with `catalog: "task-guides"`.

From a terminal, `law guide <package directory>` lists guides,
`law guide <package directory> <id>` prints the steps, document sections and
boundaries, and `--witnesses` prints only the commands the author uses to
replay their witness paths. In a project with an installed dependency,
`law guide <dependency name>` reads `deps/<name>.task-guides.json` and checks
its bytes against `taskGuideCatalogHash` in `law.lock`; a substitution is
refused with `LDC-E1104`. Outside a project, pass the directory.

## Two modes

By default a guide is an order hint: the agent asks its cards in its order
(`law ask … --format brief`), follows the handlers of each outcome and
copies the `status` and `display` fields into its answer. A small
measurement on 28 September 2026 showed that this keeps a weaker model from
computing a sum itself, while stronger models gain no accuracy from a
journal. The journal and the executor are for a document others will check:
the result is then `law guide journal render --json`, whose fields are
copied, not asked again.

## Walk the report with a journal

The steps below use two shell variables: `P` is the canon, `C` the case
collection.

```bash
P=corpus/laws/org/jcgm/gum
C=$P/examples/otchet-neopredelennosti
law guide $P uncertainty-report
```

The last command prints the 25 steps of the route, the seven document
sections and the boundaries. Start a journal on the case and its legal date:

```bash
law guide journal new $P uncertainty-report --legal-time 2026-09-06 \
  --case KVybranChelovekom --out journal.json
```

The date of law is named by a person; today's date is never filled in. It
must match the case: a journal opened on another date refuses the case's
answers. The journal pins the guide by the sha256 of the catalog bytes, so
a changed catalog refuses new records.

At any point, `law guide journal next journal.json` prints the next step,
the facts the case already holds and a ready command to record it. The
records go strictly in route order; a step out of order is refused with the
step that was expected.

**1. Pin the case and present the facts.** The person binds the result and
its inputs; a many-valued input is bound as a list:

```bash
law guide journal add journal.json --step pin-case --bind result=urn:example:gum:r
law guide journal add journal.json --step collect-model \
  --bind input=urn:example:gum:x1 --bind input=urn:example:gum:x2 \
  --present jcgm.gum::input_of --present jcgm.gum::result_estimate …
```

`--present` records which facts were presented; what the person does not
have is simply not presented. `collect-evaluations` records the
certificate value for `x1` and the bounds for `x2` the same way.

**2. Ask the budget questions.** Each ask step is one question to the
engine, saved with `--out` and attached with `--answer`:

```bash
law ask $C --case KVybranChelovekom --query-json $C/queries/summarnaya.json --out answers/combined
law guide journal add journal.json --step ask-combined --answer answers/combined
```

`law ask … --out` also prints the whole evaluation document; redirect it if
you do not need it. A step that asks once per input takes one answer per
value: `--answer answers/variance-x1 --answer answers/variance-x2`. This is
where uc = 15 µV enters the journal — as an answer with its own hashes, not
as a number someone wrote.

**3. Let the outcome choose the branch.** `ask-dof` returns an empty
collection: no effective degrees of freedom are derived. The guide moves to
`ask-dof-infinite`, which answers `NEITHER` — it is not established that all
components are exactly known. That outcome sends the route to
`collect-coverage` instead of the table-G.2 path: the person must name k.

**4. The person decides.** At `collect-coverage` the person names k and
confirms the conditions the canon asks about:

```bash
law guide journal add journal.json --step collect-coverage --bind coverage-factor=2 \
  --present jcgm.gum::coverage_factor --present jcgm.gum::g66_conditions_hold …
```

Then come the result questions — U = 30 µV, U/y = 1/5, about 95 %, and
`TRUE_ONLY` for completeness per 7.2.3 — and at `request-free-fields` the
person fills what the canon does not decide:

```bash
law guide journal add journal.json --step request-free-fields \
  --set "free/compiled-by=…" --set "free/instrument=…"
```

Other decision steps take `--choice selected|declined` for a reading, or
`--choice affirmed|denied|pending` for an authority's answer to a judgment:
the guide follows whether the authority has answered, and the canon derives
what the answer means.

**5. Assemble and check.** The seven `assemble-*` steps take no flags: each
section is filled by copying from earlier records.

```bash
law guide journal check journal.json --replay
law guide journal render journal.json
```

`check --replay` re-reads every attached answer and repeats it with
`law eval`; `render` prints the document from the table above, with every
value and the journal entry it came from (`--json` gives `value`, `display`
and `from` for each field).

## Reading stops

One template for every canon (see [Reading an answer](/guide/reading-an-answer/)
and [Silence](/guide/silence/)). In this report:

- an empty collection is not zero: when `ask-dof` is empty, the field stays
  open with its reason, and the route continues by its own branch;
- `NEITHER` is not "no" but the absence of support. Here it sends the route
  forward to `collect-coverage`, where the person supplies what the canon
  cannot derive. Guides that declare a return instead show `whyNot` and go
  back to a collect step; if the case has nothing more, that step is passed
  as it is, and the same answer stops the passage (`missing_facts`) — the
  dependent fields stay open;
- when an input has no evaluation, the combined uncertainty comes back
  empty, the route goes to `ask-contribution-count` and on to the free
  fields; the document completes with uc open, not zero;
- several values, or `BOTH` — none is chosen; the passage stops;
- an incomplete evaluation, a required judgment of an authority or a reading
  to choose — a stop or a person's decision step, not a negative answer. A
  stopped journal records the reason, for example
  `walkthrough stopped at step ask-combined: … — this is not a negative answer`.

The journal's state is `open` with the next step, `completed` with the open
fields named, or `stopped` with a reason. "All steps done" means the declared
steps were executed, not that the document is legally sufficient.

## From code and from an agent

Node: `taskGuides`, `taskGuide` and `GuideJournal` from
`@arxo/law/task-guides`; a case package has `pkg.taskGuides()`. Python:
`arxo.task_guides`, `arxo.GuideJournal`. Both facades run the same binary
for the journal.

For an assistant there is a separate skill, `apply-canon` — the companion of
`formalize-act`, which builds canons: it teaches walking a guide, reading
statuses by one template and computing nothing.

The agent side of the same walk — steps, branches, human decisions, open
fields, and what completion does and does not mean — is [Follow a task
guide](/agent-engineering/task-guides/).