# Arxo package task guides 0.1

Authoring input for the task-guide catalog: declarative guides for applying a canon (or a composition of canons) to a document — pinning of the worlds, collection of case facts, questions through the question-catalog cards, the uniform reading of statuses, the deontic review, the assembly of document sections, boundaries and witnesses. A guide is metadata, not semantics: it is not lowered into CLIR, it is not part of the package hash, it answers nothing and carries no norm — no formula, rate, deadline, threshold, applicability condition, default value or script. The schema is closed; the substantive links (addresses resolve in the pinned worlds, collected predicates are not derivable, a result of one world is never bound into another, every path to completion assembles every required section, every named witness executes the named card with the named status) are held by a repository gate.

## Versions

Accepted `format`: `law.package-task-guides/0.1`.

## Top-level fields

| name | type-or-$ref | required | description |
|---|---|---|---|
| `format` | `"law.package-task-guides/0.1"` | yes | — |
| `package` | [`#/$defs/PackageName`](#packagename) | yes | Name of the owner package from law.toml [package].name: the canon or bridge whose lock closes the world of the task. |
| `language` | enum (2) | no | Language of the TASK-GUIDES.md wrapper and the localization every Localized text must carry: ru by default. |
| `guides` | `array` | yes | — |

## Enumerations

| location | values |
|---|---|
| `properties/format` | `"law.package-task-guides/0.1"` |
| `properties/language` | `"ru"`, `"en"` |
| `$defs/Pinning/properties/facets/items` | `"reference"`, `"execution"`, `"drafting"`, `"editing"`, `"argumentation"`, `"adversarial"`, `"process"`, `"editions"`, `"feedback"` |
| `$defs/PinnedResource/properties/kind` | `"calendar-dataset"` |
| `$defs/Flow/oneOf/1/properties/complete` | `true` |
| `$defs/CaseStep/properties/kind` | `"case"` |
| `$defs/CaseStep/properties/context/contains` | `"legal_time"` |
| `$defs/CaseStep/properties/context/items` | `"legal_time"`, `"decision_time"`, `"knowledge_time"`, `"timezone"` |
| `$defs/CollectStep/properties/kind` | `"collect"` |
| `$defs/Fact/properties/from` | `"human"`, `"document"` |
| `$defs/Fact/properties/origin` | `"case_input"`, `"external_snapshot"`, `"adjudicated"` |
| `$defs/AskStep/properties/kind` | `"ask"` |
| `$defs/Stop/properties/reason` | `"other_route"`, `"both_supports"`, `"negative_answer"`, `"multiple_results"`, `"out_of_scope"`, `"awaiting_judgment"` |
| `$defs/PositionsStep/properties/kind` | `"positions"` |
| `$defs/DecisionStep/properties/kind` | `"decision"` |
| `$defs/DecisionStep/properties/decision` | `"free_parameter"`, `"judgment"`, `"reading"` |
| `$defs/DecisionStep/allOf/0/if/properties/decision` | `"free_parameter"` |
| `$defs/DecisionStep/allOf/1/if/properties/decision` | `"judgment"` |
| `$defs/DecisionStep/allOf/2/if/properties/decision` | `"reading"` |
| `$defs/SectionStep/properties/kind` | `"section"` |
| `$defs/Section/properties/kind` | `"case"`, `"presented"`, `"computed"`, `"open_questions"`, `"deontic"`, `"boundaries"`, `"free"` |
| `$defs/FieldSource/oneOf/0/properties/human` | `true` |
| `$defs/FieldSource/oneOf/2/properties/context` | `"legal_time"`, `"decision_time"`, `"knowledge_time"`, `"timezone"`, `"deadline_policy"`, `"calendar"` |
| `$defs/FieldSource/oneOf/8/properties/boundaries` | `true` |
| `$defs/CompositionBoundary/properties/reason_kind` | `"source_delegates"`, `"not_formalized"`, `"engine_limit"`, `"case_data"`, `"open_reading"` |
| `$defs/WitnessStep/properties/status` | `"TRUE_ONLY"`, `"FALSE_ONLY"`, `"BOTH"`, `"NEITHER"`, `"empty"`, `"single"`, `"multiple"`, `"selected"`, `"declined"`, `"affirmed"`, `"denied"`, `"pending"` |

## Raw schema

[`https://law.arxo.io/schema/package-task-guides.schema.json`](https://law.arxo.io/schema/package-task-guides.schema.json)

## `Id`

Type: `string`.

## `Name`

Type: `string`.

## `PackageName`

Type: `string`.

## `SemVer`

Type: `string`.

## `Sha256`

Type: `string`.

## `SymbolRef`

A package-qualified symbol of a pinned world, written as in .law: `package::name`.

Type: `string`.

## `TypeRef`

A package-qualified entity type (`package::Type`) or a standard type (`Text`, `Money`, `Date` …).

Type: `string`.

## `WorldRef`

`main` — the owner's world (the owner and its dependencies); otherwise the name of an external world from pinning.external.

Type: `string`.

## `FieldRef`

A document field addressed as `<section id>/<field id>`.

Type: `string`.

## `Localized`

Text by language code; the catalog language is mandatory (checked by the gate). Prose passes the secondary scanner of numbers with units, rates, deadlines, conditionals and dates.

Type: `object`.

## `Guide`

Type: `object`.
Required: `id`, `version`, `title`, `purpose`, `pinning`, `inputs`, `start`, `steps`, `document`, `boundaries`, `witnesses`.

| name | type-or-$ref | description |
|---|---|---|
| `id` | [`#/$defs/Id`](#id) | — |
| `version` | [`#/$defs/SemVer`](#semver) | — |
| `title` | [`#/$defs/Localized`](#localized) | — |
| `purpose` | [`#/$defs/Localized`](#localized) | — |
| `pinning` | [`#/$defs/Pinning`](#pinning) | — |
| `inputs` | `array` | — |
| `start` | [`#/$defs/Id`](#id) | Id of the first step. |
| `steps` | `array` | — |
| `document` | [`#/$defs/Document`](#document) | — |
| `boundaries` | [`#/$defs/Boundaries`](#boundaries) | — |
| `witnesses` | `array` | — |
| `quotations` | `array` | Deliberate quotations: exact substrings of the guide's prose on which the secondary prose scanner is silenced, each with a reason. |

## `Pinning`

Type: `object`.
Required: `semantics`, `world`, `facets`.

| name | type-or-$ref | description |
|---|---|---|
| `semantics` | [`#/$defs/SemVer`](#semver) | Semantic revision (`semanticVersion` of the owner's CLIR) under which the guide and its witnesses were checked. |
| `profile` | `object` | Canon profile, when the world is pinned through one. |
| `world` | `array` | Packages of the main world the guide relies on: the owner and its [dependencies], each with its exact version. |
| `external` | `array` | External worlds: separately pinned queries to other canons. Their answers are shown next to the main ones and are never merged into its proof or supplied to it as facts. |
| `resources` | `array` | Resources of the owner's law.lock the guide relies on (the official business-day calendar): id, kind and contentHash exactly as the lock pins them. Declaring a resource names what the passage uses; it never substitutes the lock. |
| `facets` | `array` | MCP facets the executor must offer, as named by the MCP profile. Declaring a facet requires it; it never grants it. |

## `PinnedPackage`

Type: `object`.
Required: `package`, `version`.

| name | type-or-$ref | description |
|---|---|---|
| `package` | [`#/$defs/PackageName`](#packagename) | — |
| `version` | [`#/$defs/SemVer`](#semver) | — |

## `ExternalWorld`

Type: `object`.
Required: `name`, `package`, `version`, `semantics`, `questions`.

| name | type-or-$ref | description |
|---|---|---|
| `name` | [`#/$defs/Id`](#id) | — |
| `package` | [`#/$defs/PackageName`](#packagename) | — |
| `version` | [`#/$defs/SemVer`](#semver) | — |
| `semantics` | [`#/$defs/SemVer`](#semver) | — |
| `questions` | [`#/$defs/Sha256`](#sha256) | sha256 of the exact bytes of the external package's question catalog — the same digest form as questionCatalogHash. |

## `PinnedResource`

Type: `object`.
Required: `id`, `kind`, `hash`.

| name | type-or-$ref | description |
|---|---|---|
| `id` | `string` | Resource id of the owner's law.lock `resources[]` (for a calendar — the dataset URN, e.g. `urn:…#snapshot-2026`). |
| `kind` | enum (1) | Resource kind as the lock names it; only calendars are admitted so far. |
| `hash` | [`#/$defs/Sha256`](#sha256) | contentHash of the resource in the owner's law.lock. |

## `Input`

A named slot of the case: an entity or a value fixed with the person (case_input), never computed.

Type: `object`.
Required: `id`, `world`, `type`, `title`.

| name | type-or-$ref | description |
|---|---|---|
| `id` | [`#/$defs/Id`](#id) | — |
| `world` | [`#/$defs/WorldRef`](#worldref) | — |
| `type` | [`#/$defs/TypeRef`](#typeref) | — |
| `title` | [`#/$defs/Localized`](#localized) | — |
| `many` | `boolean` | The slot holds several values fixed with the person (the inputs of a measurement model, the lines of a shipment). A many slot is bound only by an ask step with `each` over it; the card is then asked once per value. |
| `optional` | `boolean` | The case may lack this input; an unknown input stays unknown — it is not invented, and questions that need it wait for it. |

## `Step`

Definition `Step`.

## `Flow`

Continuation of a step that does not branch: the next step or the completion of the passage.


## `CaseStep`

Type: `object`.
Required: `id`, `kind`, `title`, `world`, `inputs`, `context`, `then`.

| name | type-or-$ref | description |
|---|---|---|
| `id` | [`#/$defs/Id`](#id) | — |
| `kind` | `"case"` | — |
| `title` | [`#/$defs/Localized`](#localized) | — |
| `world` | [`#/$defs/WorldRef`](#worldref) | — |
| `inputs` | `array` | — |
| `context` | `array` | Temporal context fixed with the person; a missing legal time is asked for, never replaced by today. |
| `deadline_policy` | [`#/$defs/SymbolRef`](#symbolref) | Deadline policy fixed for the case: a `deadline policy` declared in a package of the step's world (public when it is not the owner's). The guide names it; the counting itself belongs to the canon. |
| `calendar` | `string` | Official calendar of the case: the id of a resource from pinning.resources (main world only). |
| `then` | [`#/$defs/Flow`](#flow) | — |

## `CollectStep`

Type: `object`.
Required: `id`, `kind`, `title`, `world`, `facts`, `then`.

| name | type-or-$ref | description |
|---|---|---|
| `id` | [`#/$defs/Id`](#id) | — |
| `kind` | `"collect"` | — |
| `title` | [`#/$defs/Localized`](#localized) | — |
| `world` | [`#/$defs/WorldRef`](#worldref) | — |
| `inputs` | `array` | Case slots fixed with the person at this step. |
| `facts` | `array` | — |
| `then` | [`#/$defs/Flow`](#flow) | — |

## `Fact`

Type: `object`.
Required: `predicate`, `arguments`, `from`, `origin`.

| name | type-or-$ref | description |
|---|---|---|
| `predicate` | [`#/$defs/SymbolRef`](#symbolref) | — |
| `arguments` | `array` | Every argument of the declaration in its order: bound to a case slot or supplied with the fact. |
| `from` | enum (2) | — |
| `origin` | enum (3) | Required origin of the presented assertion; `derived` is not collectable. |

## `Argument`

Definition `Argument`.

## `AskStep`

Type: `object`.
Required: `id`, `kind`, `title`, `world`, `card`, `bind`.

| name | type-or-$ref | description |
|---|---|---|
| `id` | [`#/$defs/Id`](#id) | — |
| `kind` | `"ask"` | — |
| `title` | [`#/$defs/Localized`](#localized) | — |
| `world` | [`#/$defs/WorldRef`](#worldref) | — |
| `card` | [`#/$defs/CardRef`](#cardref) | — |
| `bind` | `object` | Every bound parameter of the card: from a case slot or from the collected parameter of an earlier collect card of the same world. |
| `under` | `object` | The question runs with the reading the person selected at the named decision step (selectedInterpretations); without the selection the reading is silent and the question is not asked. |
| `each` | [`#/$defs/Id`](#id) | Id of a many input slot: the card is asked once for every value of the slot (the parameter bound to `{input: <slot>}` takes each value in turn). A step with `each` does not branch on outcomes: every answer is recorded per value and the passage continues by `then`; stops on BOTH or several values are the business of the document fields, which show every value. |
| `on` | oneOf (2) | Handlers of every outcome of the card's form: four truth statuses for truth cards, three cardinalities for collect cards. |
| `then` | [`#/$defs/Flow`](#flow) | `each` steps only: continuation after the card was asked for every value. |

## `CardRef`

Type: `object`.
Required: `package`, `id`.

| name | type-or-$ref | description |
|---|---|---|
| `package` | [`#/$defs/PackageName`](#packagename) | — |
| `id` | [`#/$defs/Id`](#id) | — |

## `Binding`

Definition `Binding`.

## `TruthHandlers`

Type: `object`.
Required: `TRUE_ONLY`, `FALSE_ONLY`, `BOTH`, `NEITHER`.

| name | type-or-$ref | description |
|---|---|---|
| `TRUE_ONLY` | [`#/$defs/Handler`](#handler) | — |
| `FALSE_ONLY` | [`#/$defs/Handler`](#handler) | — |
| `BOTH` | [`#/$defs/Handler`](#handler) | — |
| `NEITHER` | [`#/$defs/Handler`](#handler) | — |

## `CollectHandlers`

Type: `object`.
Required: `empty`, `single`, `multiple`.

| name | type-or-$ref | description |
|---|---|---|
| `empty` | [`#/$defs/Handler`](#handler) | — |
| `single` | [`#/$defs/Handler`](#handler) | — |
| `multiple` | [`#/$defs/Handler`](#handler) | — |

## `Handler`

Definition `Handler`.

## `Stop`

Type: `object`.
Required: `reason`.

| name | type-or-$ref | description |
|---|---|---|
| `reason` | enum (6) | The passage is stopped, not answered negatively: other_route — the case belongs to another route; both_supports — BOTH, both lines are shown; negative_answer — FALSE_ONLY where the guide has no continuation; multiple_results — several collected values, none is chosen; out_of_scope — outside the promise of the guide; awaiting_judgment — the authority has not answered the judgment the guide waits for. |
| `boundary` | [`#/$defs/Id`](#id) | Id of a boundary of this guide (an owner reference or a composition boundary). |

## `PositionsStep`

Type: `object`.
Required: `id`, `kind`, `title`, `world`, `cards`, `then`.

| name | type-or-$ref | description |
|---|---|---|
| `id` | [`#/$defs/Id`](#id) | — |
| `kind` | `"positions"` | — |
| `title` | [`#/$defs/Localized`](#localized) | — |
| `world` | [`#/$defs/WorldRef`](#worldref) | — |
| `cards` | `array` | positions cards whose norms form the deontic surface reviewed; every returned position and status is shown, the absence of a position is not the absence of a duty. |
| `then` | [`#/$defs/Flow`](#flow) | — |

## `DecisionStep`

Type: `object`.
Required: `id`, `kind`, `title`, `decision`.

| name | type-or-$ref | description |
|---|---|---|
| `id` | [`#/$defs/Id`](#id) | — |
| `kind` | `"decision"` | — |
| `title` | [`#/$defs/Localized`](#localized) | — |
| `world` | [`#/$defs/WorldRef`](#worldref) | — |
| `decision` | enum (3) | free_parameter — the person fills free document fields; judgment — the answer of the authority through the judgment channel; reading — the interpretation chosen by the person. The guide never takes the decision itself. |
| `fields` | `array` | — |
| `predicate` | [`#/$defs/SymbolRef`](#symbolref) | — |
| `bind` | `object` | judgment only: parameters of the judgment relation bound to case inputs — the authority's answer counts only when it is about these values. |
| `interpretation` | [`#/$defs/SymbolRef`](#symbolref) | — |
| `then` | [`#/$defs/Flow`](#flow) | — |
| `on` | oneOf (2) | reading: where the passage goes when the person selects the reading and when the person declines it (the guide never selects it); judgment: where it goes once the authority has answered and while the answer is pending (the guide never answers for the authority). |

## `ReadingHandlers`

Outcomes of a reading decision: `selected` — the person chose the reading, the following questions marked `under` run with it; `declined` — the accepted reading only.

Type: `object`.
Required: `selected`, `declined`.

| name | type-or-$ref | description |
|---|---|---|
| `selected` | [`#/$defs/Handler`](#handler) | — |
| `declined` | [`#/$defs/Handler`](#handler) | — |

## `JudgmentHandlers`

Outcomes of a judgment decision. The graph branches only on whether the authority has answered, never on the answer's polarity: `answered` — the authority's adjudicated assertion (affirmed or denied) is in the case and the canon derives its consequences; `pending` — no answer yet: continue (the canon itself says whether the judge is needed) or stop with `awaiting_judgment`.

Type: `object`.
Required: `answered`, `pending`.

| name | type-or-$ref | description |
|---|---|---|
| `answered` | [`#/$defs/Handler`](#handler) | — |
| `pending` | [`#/$defs/Handler`](#handler) | — |

## `SectionStep`

Type: `object`.
Required: `id`, `kind`, `title`, `section`, `then`.

| name | type-or-$ref | description |
|---|---|---|
| `id` | [`#/$defs/Id`](#id) | — |
| `kind` | `"section"` | — |
| `title` | [`#/$defs/Localized`](#localized) | — |
| `section` | [`#/$defs/Id`](#id) | Id of the document section assembled at this step. |
| `then` | [`#/$defs/Flow`](#flow) | — |

## `Document`

Type: `object`.
Required: `title`, `sections`.

| name | type-or-$ref | description |
|---|---|---|
| `title` | [`#/$defs/Localized`](#localized) | — |
| `notice` | [`#/$defs/Localized`](#localized) | What the document is not (for example, not a declaration ready for filing). |
| `sections` | `array` | — |

## `Section`

Type: `object`.
Required: `id`, `title`, `kind`, `required`, `fields`.

| name | type-or-$ref | description |
|---|---|---|
| `id` | [`#/$defs/Id`](#id) | — |
| `title` | [`#/$defs/Localized`](#localized) | — |
| `kind` | enum (7) | The kind fixes which field sources the section admits: a computed field always comes from a query, a free field always from the person. |
| `required` | `boolean` | A required section is assembled on every path to completion; otherwise completion is false. |
| `fields` | `array` | — |
| `gaps` | `array` | deontic sections only: named gaps of the deontic coverage. |

## `Field`

Type: `object`.
Required: `id`, `title`, `source`.

| name | type-or-$ref | description |
|---|---|---|
| `id` | [`#/$defs/Id`](#id) | — |
| `title` | [`#/$defs/Localized`](#localized) | — |
| `source` | [`#/$defs/FieldSource`](#fieldsource) | — |

## `FieldSource`

Where the value of a field comes from; there is no constant or default.


## `Gap`

Type: `object`.
Required: `id`, `title`.

| name | type-or-$ref | description |
|---|---|---|
| `id` | [`#/$defs/Id`](#id) | — |
| `title` | [`#/$defs/Localized`](#localized) | — |
| `boundary` | [`#/$defs/Id`](#id) | — |

## `Boundaries`

Type: `object`.
Required: `owner`, `composition`.

| name | type-or-$ref | description |
|---|---|---|
| `owner` | `array` | References by id to boundaries of the question catalogs of pinned packages: the limitation text lives once, in package-info.json. |
| `composition` | `array` | Limitations of the composition itself, which no single package owns. |

## `BoundaryRef`

Type: `object`.
Required: `package`, `id`.

| name | type-or-$ref | description |
|---|---|---|
| `package` | [`#/$defs/PackageName`](#packagename) | — |
| `id` | [`#/$defs/Id`](#id) | Id of a boundary in the package's question catalog. |

## `CompositionBoundary`

Type: `object`.
Required: `id`, `title`, `reason_kind`.

| name | type-or-$ref | description |
|---|---|---|
| `id` | [`#/$defs/Id`](#id) | — |
| `title` | [`#/$defs/Localized`](#localized) | — |
| `reason_kind` | enum (5) | The five reason kinds: a classification by the author, not an algorithm diagnosing a particular case. |

## `WitnessPath`

Type: `object`.
Required: `id`, `title`, `path`.

| name | type-or-$ref | description |
|---|---|---|
| `id` | [`#/$defs/Id`](#id) | — |
| `title` | [`#/$defs/Localized`](#localized) | — |
| `collection` | `string` | Nested case collection of the owner package (`examples/<name>/`, a case package with its own law.toml, law.lock, registered cases, saved queries and expectations.json). When present, every element of the path names a registered case and a saved query of this collection instead of a scenario: the collection is the end-to-end witness of the walkthrough. |
| `path` | `array` | A walk through consecutive question steps; every element is witnessed either by a scenario of the card's package that executes the card and expects the status (`test`) or, on a path with `collection`, by a registered case of the collection and its saved query whose expectation in expectations.json is the status (`case`, `query`). |

## `WitnessStep`

One element of a witness path: either `test` (a scenario of the card's package) or `case` with `query` (a case of the path's collection); the gate requires exactly one of the two forms. An element naming a reading decision step carries only `step` and `status` (`selected` or `declined`): it is the person's act, not an answer, and it fixes the branch the path takes. An element naming an `each` step witnesses the card for one value of the slot: its status is the outcome for that value. An element naming a judgment decision step with `on` carries only `step` and `status` (`affirmed`, `denied` — the authority answered, the path follows `answered`; `pending` — no answer, the path follows `pending`); the following scenarios of the path carry the adjudicated assertion of that polarity, or none while pending.

Type: `object`.
Required: `step`, `status`.

| name | type-or-$ref | description |
|---|---|---|
| `step` | [`#/$defs/Id`](#id) | — |
| `status` | enum (12) | — |
| `test` | `string` | Title of `test "…"` in tests/**/*.lawtest of the card's package (paths without `collection`). |
| `case` | [`#/$defs/Name`](#name) | Name of a case registered in `[[cases]]` of the path's collection. |
| `query` | [`#/$defs/Id`](#id) | queryId of a saved query `queries/<query>.json` of the path's collection that executes the step's card. |
| `value` | `string` | `each` steps only: the value of the many slot (an entity id or a literal) this element witnesses. Consecutive elements of the same `each` step witness different values; the scenario or saved query must name this value. |

## `Quotation`

Type: `object`.
Required: `text`, `reason`.

| name | type-or-$ref | description |
|---|---|---|
| `text` | `string` | — |
| `reason` | `string` | — |