@zh-xx/antu 0.9.0

package/spec/agent/justification/guide.md

@@ -0,0 +1,100 @@
+# Mechanism notes for an agent
+
+> This is an **operating note**, not the specification. The field list is served by
+> `antu_schema`, examples by `antu_examples`, and the design rationale lives in
+> `spec/justification/schema-draft.md` (you do not need it to write JSON).
+>
+> **This file is English on purpose.** It goes into a model's context, the same as
+> the field table and the validation errors. See the header of `src/core/i18n.js`.
+
+## In one sentence
+
+A justification JSON describes **one side's reasoning: how norms and facts lead, step by step, to a
+conclusion**. The engine draws a tree: the conclusion first, what supports it below, and at the
+bottom the facts and the norms.
+
+## Three things, three places
+
+```
+nodes    the statements   conclusion, norm, element, fact, inference, judgement
+links    who supports whom  from (the support) -> to (the supported), with a stance
+groups   the issues         "Issue 1: was it defensive?" (optional, one box each)
+```
+
+Draw **one side's** reasoning (say, the court's reasons). Do not put the other side's tree in the same
+diagram.
+
+## The six kinds of node
+
+```
+conclusion  what is decided; the end of the diagram, or the summing-up of one issue
+norm        a statute, interpretation or precedent (a leaf); sourceIds -> a statute / case source
+element     one constituent requirement a norm breaks into ("time: the attack is under way")
+fact        what the court found happened (a leaf); date, sourceIds
+inference   a statement drawn from facts ("the lights were visible, so he should have known")
+judgement   a value call on a body of facts ("the attack was not urgent")
+```
+
+Keep **fact, inference and judgement apart**; they are questioned differently (evidence, logic, value
+call). A fact says what happened, with a time. An inference says what may therefore be taken to be so.
+When unsure: does the sentence say what happened, or what follows from it?
+
+## Links and their stance
+
+A link runs from the supporting node to the supported one: fact -> element, element -> conclusion.
+
+```
+for      (default) from supports to
+against  from opposes to        (a judgement saying an element is not met)
+basis    from is the norm to rests on     (only from a norm)
+```
+
+## holds: upheld, or rejected
+
+`holds: "yes"` on an element, inference, judgement or conclusion says the reasoning upholds it;
+`holds: "no"` says the reasoning rejects it. **Draw the rejected side too**: a conclusion "it was
+special defence" with `holds: "no"`, and the reasons it fails pointing `against` it. A fact and a norm
+have no `holds`. Leave it out when the reasoning does not say.
+
+## and / or: `combine`
+
+When a node rests on several things, say whether all are needed or one is enough: `combine: "all"` (every
+`for` link into it is needed: the five conditions of lawful defence) or `combine: "any"` (one is enough).
+Leave it out when the reasoning does not say. Only `for` links count, and it belongs only on a conclusion,
+element, inference or judgement. Keep it consistent with `holds`: an `"all"` node that holds cannot rest on a
+rejected node.
+
+## Issues
+
+`groups` is one box per issue. A node is in at most one group. Put a norm in the issue it settles (a
+norm used in two issues is two `norm` nodes with the same `sourceIds`). Nodes in no group (the end
+conclusion) stand above the issues. **A fact that supports things in several issues is written once**: link it to each
+element it supports, and the engine draws it in each of those issues (a copy says "same as"). Do not write
+it twice.
+
+## Big diagrams
+
+A reader can fold each issue up to its conclusion (its box title is a button; the dock has "Fold issues"), so a
+diagram of several issues can be read at a glance. Nothing to write for it: it is not in the JSON. Still split a
+diagram that grows past about 60 nodes.
+
+## After writing
+
+```
+antu_validate   each problem with its path and id: links[3] (f-9 -> e-9): `to` refers to ...
+                on a pass it can still add notes (a fact with no source, nothing supports a conclusion)
+antu_layout     counts, layers, size per orientation; no rendering
+antu_preview    a screenshot: is each issue clear, do the lines cross badly, is anything cut off
+antu_render     the self-contained HTML
+```
+
+**Passing validation is only the pass mark.** Always look with `antu_preview` before delivering. A big diagram
+(past about 40 nodes) is small on one screen: split it, one diagram per issue.
+
+## Also easy to get wrong
+
+- **Referenced ids must exist**: `from` / `to`, `groupId`, `sourceIds`.
+- **A fact or a norm is a leaf**: nothing supports it (an evidence layer is not part of v0).
+- **`holds` is not for facts and norms; `date` is only for facts** (`2032-04-14` or `2032-04-14T22:22`).
+- **At least one conclusion has no outgoing link**: the conclusion the whole reasoning leads to.
+- **Do not invent a date**: leave `date` out when the source does not give one.

package/spec/agent/procedure/guide.md

@@ -0,0 +1,109 @@
+# Mechanism notes for an agent
+
+> This is an **operating note**, not the specification. The field list is served by
+> `antu_schema`, examples by `antu_examples`, and the design rationale lives in the
+> human-facing documents under `spec/` (you do not need them to write JSON).
+>
+> **This file is English on purpose.** It goes into a model's context, the same as
+> the field table and the validation errors. See the header of `src/core/i18n.js`.
+
+## In one sentence
+
+A procedure JSON describes: **what happens in what order, where the path splits, and what
+may happen at any time along the way**. The engine draws a flowchart: steps are nodes,
+the order is edges, contingent clauses are a table under the flow.
+
+## Three things, three places
+
+```
+nodes   steps, decisions, outcomes         "Seller delivers", "Goods pass inspection?"
+edges   the order between them             n-2 -> n-3, with a condition on a branch
+rules   what may happen at any time        "if the seller is late: 0.1% per day"
+```
+
+**The most common mistake is writing a rule as nodes and edges.** A breach, a delay
+penalty, a right to terminate is not a step after another step: it can fire at any moment
+of a stage. As a branch off one step it claims a moment it does not have, and has to be
+repeated per stage. Write it once in `rules`:
+
+```json
+{ "id": "r-1", "when": "Seller delivers late",
+  "then": "Seller pays 0.1% of the price per day, capped at 5%",
+  "outcome": "negative", "stageIds": ["st-1"], "sourceIds": ["s-1"] }
+```
+
+- `when`: one trigger, or an array of them (any one fires the rule);
+- `stageIds`: the stages it applies in; omit for "throughout";
+- `endId`: only when the rule ends the procedure (termination). It must be a node of kind
+  `end`, and that node may have no incoming edge.
+
+Rule of thumb: **if the same branch would leave several steps, or it leads nowhere, it is
+a rule.**
+
+## A node's look: two fields, never mixed
+
+```
+kind     shape:   start     pill, where the flow begins
+                  step      box, something someone does
+                  decision  diamond, a question the path splits on
+                  end       double-bordered pill, where the flow stops
+                  document  box with a wavy bottom, a paper produced
+                  note      folded sheet, an explanation outside the flow
+outcome  paint:   positive (heavier line) / negative (dashed line) / neutral (plain, default); the theme adds colour
+```
+
+`outcome` is what the result means ("contract performed" positive, "terminated" negative).
+
+## Edges
+
+- **The main line** is the path when everything goes as agreed. Mark its edges
+  `"main": true`, one chain from the start to an end. Unmarked, the engine guesses (the
+  first unconditional edge out of each node): mark it.
+- **A decision** needs two or more outgoing edges, **each with a `condition`**. One way
+  out means it is a `step`. On the main line, mark which answer continues it.
+- **A loop is an ordinary edge back** ("rectify" -> "inspect again"). Do not copy nodes
+  to avoid it; it is drawn dashed.
+- Edges may rejoin one node; two edges between the same pair need different conditions.
+
+**Every node must lead somewhere**: all but `end` and `note` need an outgoing edge, and all
+must be reachable from the start. A step that leads nowhere is almost always a
+consequence that belongs in `rules` (the error says so). Only a `start` may have no
+incoming edge (a `note`, and a rule's `endId`, aside): any other node without one is an
+error, since nothing leads to it. Several `start` nodes are allowed, with a hint.
+
+## Stages
+
+`stages` is an ordered list; a node joins one with `stageId`. Each stage is drawn as a
+framed box holding its nodes; the stages stand side by side as columns, the flow running down
+each (a stage much taller than the rest is folded into two columns). Keep a stage's nodes
+consecutive along the flow: an edge into an earlier stage draws backwards (fine for a loop, a
+hint otherwise). Put every node in a stage, or none: with stages on only some nodes, the whole
+diagram falls back to one long column.
+
+Orientation and link style (curved / straight) are the reader's choice in the interface;
+they are not in the data.
+
+## After writing
+
+```
+antu_validate   each problem with its path and node id: nodes (n-4): kind is "decision" but ...
+antu_layout     counts, layers, loops, rules, size per orientation; no rendering
+antu_preview    a screenshot: is the main line obvious, are the branches readable
+antu_render     the self-contained HTML
+```
+
+**Passing validation is only the pass mark.** Always look with `antu_preview` before
+delivering.
+
+## Also easy to get wrong
+
+- **Referenced ids must exist**: `stageId`, `actorIds`, `sourceIds`, an edge's `from` /
+  `to`, a rule's `stageIds` / `endId`.
+- **Keep labels short.** A node shows about three lines of `label`; put the rest in
+  `detail` (its first line shows under the label, all of it on click).
+
+## Another way to look at it
+
+The reader can switch to the **route map**: the main line as one line, with rework loops and early endings
+hanging below it. It needs a clear main line, so **mark `main` along the whole line from start to end**
+(or on none, and the engine infers it). `kind: "route"` on antu_layout / antu_preview / antu_render shows it.

package/spec/agent/relationship/guide.md

@@ -0,0 +1,92 @@
+# Mechanism notes for an agent
+
+> This is an **operating note**, not the specification. The field list is served by
+> `antu_schema`, examples by `antu_examples`, and the design rationale lives in
+> `spec/relationship/schema-draft.md` (you do not need it to write JSON).
+>
+> **This file is English on purpose.** It goes into a model's context, the same as
+> the field table and the validation errors. See the header of `src/core/i18n.js`.
+
+## In one sentence
+
+A relationship JSON describes **who stands in what relation to whom, at one point in time**.
+The engine draws a graph: parties are boxes, relations are lines between them, and camps are
+boxes around parties.
+
+The reader can also switch to a **focus view**: one party in the middle (by default the one with most
+relations; the reader clicks another), the parties tied to it around it, the others further out. It
+suits a case with many parties, where the graph is too busy. The **guarantee chain** shows one block per
+claim (a `debt`) with its guarantors beside it and what stands behind each; for a loan or guarantee
+dispute. **Write `secures` on every guarantee**: without it the chain ties a guarantee to a claim only when
+its creditor has exactly one, and puts it apart otherwise. The **matrix** puts the parties down and across and names the relations in each cell: for "is there any
+relation between A and B". The **equity tree** draws the `equity` relations in levels with the `share` on each
+line, so **write `share` on every equity relation**. The **authority chart** draws `control`, `employment` and `agency` as an organisation chart; the **related-party
+list** is a table of one party's relations (to paste into a brief); the **path** draws the shortest chains between
+two parties; the **summary** draws each camp (`groupId`) as one block. The same JSON draws in all nine;
+`kind: "focus"`, `"chain"`, `"matrix"`, `"equity"`, `"authority"`, `"related"`, `"path"` or `"summary"` on antu_layout / antu_preview / antu_render shows it.
+
+## Three things, three places
+
+```
+entities    the parties          "Zhang San", "Xinghe Trading Co."
+relations   what is between them from -> to, with a kind: debt, equity, guarantee ...
+groups      the camps            "creditor side", "debtor side" (optional)
+```
+
+It is a cross-section: write the relations as they stand on one date (`asOf`, optional). Do not
+write a history. If the relations changed, write two diagrams.
+
+## The kind of a relation, and its direction
+
+The direction runs from `from` to `to`. Write it the way the kind says:
+
+```
+equity       holder -> the entity held             share: 60
+control      controller -> controlled              (control without a shareholding)
+debt         creditor -> debtor                    amount: "CNY 500,000"
+guarantee    guarantor -> creditor                 secures: "r-1"
+contract     either way, no arrowhead              amount: "CNY 80,000"
+kinship      either way, no arrowhead              spouses, parents and children
+employment   employer -> employee
+agency       principal -> agent
+other        anything else
+```
+
+`directed: true/false` overrides the kind's default arrowhead. A loan usually needs **two**
+relations on the same pair: the `contract` (what was agreed) and the `debt` (who owes whom).
+
+## A guarantee says which claim it secures
+
+A guarantee secures **one particular claim**, not the debtor in general. Put the id of the `debt`
+(or `contract`) relation in `secures`. Without it the validator gives a hint, and a reader cannot
+tell which of two loans the guarantee is for.
+
+## Entities
+
+`kind` is `person` / `company` / `organization` / `government` / `other` and fixes the shape only.
+`label` is the name; `role` is the role **in this case** on one short line ("Lender", "Guarantor").
+Keep labels short; put registered capital and the like in `detail` (its full text shows on click).
+
+## Groups
+
+`groups` boxes together the parties a reader should see as one camp. An entity is in at most one
+group (`groupId`); groups do not nest. Leave a party out of every group and it stands outside the boxes.
+
+## After writing
+
+```
+antu_validate   each problem with its path and id: relations (r-2): `secures` points at ...
+                on a pass it can still add notes (an entity nothing relates to, shares over 100%)
+antu_layout     counts, layers, size per orientation; no rendering
+antu_preview    a screenshot: are the camps clear, do the lines cross badly
+antu_render     the self-contained HTML
+```
+
+**Passing validation is only the pass mark.** Always look with `antu_preview` before delivering.
+
+## Also easy to get wrong
+
+- **Referenced ids must exist**: `from` / `to`, `groupId`, `sourceIds`, `secures`.
+- **`share` is only for `equity`, `amount` only for `debt` and `contract`, `secures` only for `guarantee`.**
+- **An entity nothing relates to floats beside the diagram** (a hint): relate it or leave it out.
+- **`amount` is a string**, written the way it should be read, with the currency.