pi-outpost 0.32.4 → 0.34.0

package/dist/skills/structured-exchange/references/enriched-contract.md

@@ -0,0 +1,158 @@
+# The enriched contract: `urn:structured-exchange:2`
+
+<!-- only: pi-outpost -->
+Part of the `structured-exchange` skill. What a project's profile refuses, and what to do about it, is in its `SKILL.md`.
+<!-- end -->
+
+Everything in `SKILL.md` is version 1 and still works exactly as written. Declare version 2
+instead when you need any of what follows. Nothing is removed: change the identifier and
+a version 1 document is a version 2 document, except that `target` becomes an object
+(`"target": { "ref": "architecture-v4" }`), which is what lets it name a revision.
+
+**Emit version 1 unless you need something below.** The reader cannot tell which you
+used and neither contract is better; there is simply no reason to reach for the larger
+vocabulary to say a smaller thing.
+
+## Attributes: the properties your domain owns
+
+Any element, relationship or row may carry `attributes` — bounded, typed properties
+whose names belong to your domain, not to this contract.
+
+```json
+{ "id": "battery", "label": "Battery", "kind": "source",
+  "attributes": { "voltage": 400, "chemistry": "LFP", "serviceable": true,
+                  "suppliedBy": [{ "ref": "ORG-3" }] } }
+```
+
+A value is a string, a finite number, a boolean, `null`, a reference (`{ "ref": "…" }`),
+or one flat list of those. **Lists never nest and no other object shape is allowed.** A
+quantity with a unit is two attributes or one string — `"mass_kg": 3.4`, not
+`{ "value": 3.4, "unit": "kg" }`, which is refused.
+
+Name the vocabulary those names come from with `profile` on the envelope:
+
+```json
+{ "schema": "urn:structured-exchange:2", "kind": "graph", "profile": "acme/electrical", "data": { … } }
+```
+
+The profile is **a name and nothing more**. It is never fetched, resolved or executed,
+and a reader who does not know it still sees every attribute, rendered generically. Do
+not invent one to look official; use the identifier your domain actually uses, or omit
+it.
+
+## Description, expectation, change: three different claims
+
+Version 1 already separates *describing* a referenced thing from *changing* it. Version
+2 adds a third, and confusing them is the mistake that matters:
+
+```json
+{ "id": "r1", "ref": "REQ-1",
+  "label": "Stop within 40 m",
+  "expect": { "revision": "rev-9", "attributes": { "status": "approved" } },
+  "set": { "label": "Stop within 35 m", "attributes": { "status": "in review" },
+           "removeAttributes": ["waiver"] } }
+```
+
+- **beside `ref`** — what it is called *now*. How the reader recognises it. Applied to
+  nothing.
+- **`expect`** — what you believe is currently true, for the receiving authority to check
+  before it applies anything. You are not asserting it is true; you are saying what you
+  assumed. If you did not read the current state, do not write an `expect`.
+- **`set`** — the only thing that changes anything.
+- **`removeAttributes`** — takes properties away. **`null` does not delete.** Writing
+  `"waiver": null` sets the property to null; to unset it, name it here. Naming the same
+  attribute in both `set.attributes` and `removeAttributes` is refused rather than
+  resolved, because there is no precedence worth inventing.
+
+Put the revision you prepared against on the target: `"target": { "ref": "REQ-DOC-1",
+"revision": "rev-9" }`. A revision and an `expect` are only allowed in a proposal —
+there is no authority to check them against otherwise.
+
+## Locations: where it is, never what it is
+
+```json
+"locations": [{ "uri": "file:///src/brakes.ts", "revision": "abc123",
+                "range": { "startLine": 10, "endLine": 42 } }]
+```
+
+A hint for a reader, zero-based. It takes no part in identity: `ref` says what something
+**is**, a location says where a copy of it can be found today. Never encode a path into a
+`ref` to save writing one — moving the file would then change the thing's identity.
+
+Nothing is opened until a reader asks, and only through the application's existing rules
+about what may be opened at all.
+
+## Artifacts: linked, digested, not attached
+
+```json
+"artifacts": [{ "rel": "verifies", "uri": "https://ci.example/report.json",
+                "sha256": "sha256:<64 hex characters>", "mediaType": "application/json" }]
+```
+
+The digest is mandatory, and it is the point: it binds an approval to specific bytes
+even when the URI serves different ones later. If you cannot compute a digest, you do not
+have an artifact link — use a location instead. Never inline the content; the envelope
+carries references, and a payload pasted into it is a document nobody can read and a
+ceiling you will hit.
+
+## Tables that carry a document
+
+A row may declare an identity and a type of its own, which is what makes a requirements
+table more than a grid:
+
+```json
+{ "id": "r1", "ref": "REQ-1", "kind": "requirement",
+  "cells": ["REQ-1", "Stop within 40 m", "approved"] }
+```
+
+Headings organise it, and are rows of their own — not a data row with empty cells:
+
+```json
+{ "heading": "1. Braking", "depth": 1 }
+```
+
+Traceability between rows is declared beside them, with each end stated explicitly:
+
+```json
+"relations": [
+  { "from": { "id": "r1" }, "to": { "id": "r2" }, "kind": "derives" },
+  { "from": { "id": "r1" }, "to": { "ref": "TEST-9" }, "kind": "verifiedBy" }
+]
+```
+
+`{ "id": … }` is a row of this document and must exist — a typo is refused, not quietly
+drawn pointing at nothing. `{ "ref": … }` is something outside it and is accepted as
+leaving the document, which is the normal case for the test that verifies a requirement.
+Relation kinds are opaque, like every other kind: `derives`, `verifiedBy`, `satisfies` —
+whatever your domain says.
+
+**Do not state coverage you have not been told.** A requirement with no relation is a
+requirement with no relation; the application reports what you declared and infers
+nothing about what is missing.
+
+All of it together, as one document you can copy:
+
+```json
+{
+  "schema": "urn:structured-exchange:2",
+  "kind": "table",
+  "profile": "acme/requirements",
+  "data": {
+    "columns": ["id", "requirement", "status"],
+    "rows": [
+      { "heading": "1. Braking", "depth": 1 },
+      { "id": "r1", "ref": "REQ-1", "kind": "requirement",
+        "cells": ["REQ-1", "Stop within 40 m", "approved"],
+        "attributes": { "verification": "test" },
+        "locations": [{ "uri": "file:///specs/brakes.md", "range": { "startLine": 10, "endLine": 12 } }] },
+      { "heading": "1.1 Sensing", "depth": 2 },
+      { "id": "r2", "ref": "REQ-2", "kind": "requirement",
+        "cells": ["REQ-2", "Read wheel speed at 100 Hz", "approved"] }
+    ],
+    "relations": [
+      { "from": { "id": "r1" }, "to": { "id": "r2" }, "kind": "derives" },
+      { "from": { "id": "r1" }, "to": { "ref": "TEST-9" }, "kind": "verifiedBy" }
+    ]
+  }
+}
+```

package/dist/skills/structured-exchange/references/figures.md

@@ -0,0 +1,52 @@
+# Putting a diagram in a document you are writing
+
+Part of the `structured-exchange` skill. A timeline's own figure options are in `references/timelines.md`.
+
+`present_structure` shows a document in the conversation. When you are *writing* a
+file — a report, a design note, a README — a diagram belongs in that file instead,
+and `write_structure_figure` puts it there:
+
+```
+write_structure_figure(
+  path: "models/vehicle.json",
+  output_path: "figures/power-train.svg",
+  hide_relationship_kinds: ["diagnostic"]
+)
+```
+
+It reads a structured-exchange document from the workspace, draws it, and writes one
+`.svg`. Reference it from your Markdown as a relative path — `![Power
+train](figures/power-train.svg)` — and the interface renders it in the preview.
+
+Three things about it are worth knowing before you use it.
+
+**The two hide lists are different vocabularies.** `hide_element_kinds` hides boxes by
+their `kind`; `hide_relationship_kinds` hides arrows by theirs. The same name in both
+means two unrelated things, and naming one where you meant the other hides nothing,
+draws a perfectly valid figure of the whole document, and looks like it worked.
+
+**Write one figure per view worth having.** A narrowed figure is the reason the tool
+takes a narrowing at all: three figures each about one thing beat one figure of
+everything, which is the diagram nobody reads. A figure that shows less than its
+document says so, inside the picture, so a figure separated from its source is never
+mistaken for the whole of it.
+
+**A relationship whose endpoint you hid goes with it.** An arrow to a box that is not
+drawn cannot be drawn. The result tells you how much of the document the figure shows,
+so a narrowing that took more than you meant is visible in the answer rather than in
+the file.
+
+A table has no figure — it is data. To put one in a document you are writing,
+`write_structure_table` writes it as Markdown:
+
+```
+write_structure_table(
+  path: "requirements/braking.json",
+  output_path: "reports/braking-requirements.md"
+)
+```
+
+It reads a table from the workspace and writes a new `.md` file — each chapter a heading
+followed by a Markdown table of its rows — which you can include in the document or hand on.
+It never overwrites an existing file, and a table the project's profile or rules refuse is not
+written. The reader can also export a table they are shown as a spreadsheet or as Markdown.

package/dist/skills/structured-exchange/references/graphs-and-tables.md

@@ -0,0 +1,115 @@
+# Graphs and tables: roles, containers, viewpoints
+
+Part of the `structured-exchange` skill. The envelope and validation are in its `SKILL.md`.
+
+## Roles on a table's rows
+
+A table cannot be proposed, but it can *report* on a change it projects. Any row
+may say what it plays, and the interface colours it the way it colours an added or
+changed element in a graph:
+
+```jsonc
+"data": {
+  "columns": ["id", "requirement", "status"],
+  "rows": [
+    { "role": "added",   "cells": ["REQ-5", "Log every actuation.", "draft"] },
+    { "role": "changed", "cells": ["REQ-2", "Signal a fault within 200 ms.", "in review"] },
+    { "role": "removed", "cells": ["REQ-3", "Read battery voltage at 10 Hz.", "withdrawn"] },
+    { "cells": ["REQ-1", "Stop the vehicle within 40 m.", "approved"] }   // context
+  ]
+}
+```
+
+`role` is one of `added`, `changed`, `context`, `removed`. A row that declares none
+reads as context when any other row declares one. Both row forms are accepted, so
+`["REQ-1", "…"]` and `{ "cells": ["REQ-1", "…"] }` are the same row, and a table
+that declares no role anywhere is rendered exactly as before roles existed.
+
+Declare the role — do not put it in a column and expect the colours. A `status`
+column is your data and is rendered as data; nothing infers a role from it.
+
+## Grouping: containers
+
+A graph or a sequence may declare **containers** — subsystems, layers, teams,
+whatever the domain groups things into — and each element or participant may say
+which one it belongs to.
+
+```jsonc
+"data": {
+  "containers": [{ "id": "electrical", "label": "Electrical system" }],
+  "nodes": [{ "id": "battery", "label": "Battery", "container": "electrical" },
+            { "id": "driver",  "label": "Driver" }],          // in no container
+  "edges": [{ "from": "driver", "to": "battery", "kind": "operates" }]
+}
+```
+
+Four things to know:
+
+- **Membership goes on the member**, never as a list of members on the container.
+  An element belongs to one container or to none.
+- **Relationships ignore grouping entirely.** They connect elements, they cross
+  container boundaries freely, and an endpoint is never a container id. Naming a
+  container as `from` or `to` is refused.
+- **Containers do not nest.** A member names a container, never a chain of them.
+- **A container nobody joins is fine.** Declare the group first and fill it later
+  if that is what you mean; it is drawn as an empty box.
+
+Naming a container the document does not declare is refused rather than quietly
+ungrouped — an element shown outside a group it belongs to would misstate the
+system you are describing.
+
+In a sequence, the view puts a container's columns next to each other so its
+header spans them. If you interleave two containers, the columns are reordered:
+the first member of a container met brings the rest of that container with it,
+and anything belonging to no container keeps its place. Declare participants in
+the order you want them read.
+
+## Viewpoints: the readings a graph is made for
+
+When a graph will be read in more than one way — power, then control, then what is
+safety-relevant — declare those readings as `viewpoints` on the envelope, rather than
+leaving the reader to rebuild each one from the key:
+
+```json
+{
+  "schema": "urn:structured-exchange:2",
+  "kind": "graph",
+  "viewpoints": [
+    {
+      "id": "power",
+      "label": "Power distribution",
+      "concern": "Where energy is stored, converted and consumed",
+      "elementKinds": ["source", "load"],
+      "relationshipKinds": ["power"]
+    }
+  ],
+  "data": {
+    "nodes": [
+      { "id": "battery", "label": "Battery", "kind": "source" },
+      { "id": "motor", "label": "Motor", "kind": "load" },
+      { "id": "ecu", "label": "ECU", "kind": "controller" }
+    ],
+    "edges": [
+      { "from": "battery", "to": "motor", "kind": "power" },
+      { "from": "ecu", "to": "motor", "kind": "signal" }
+    ]
+  }
+}
+```
+
+- **A viewpoint says what it retains.** Name the element kinds, the relationship kinds,
+  or both — at least one list. A list you leave out keeps that whole vocabulary.
+- **Only kinds the document has.** Every kind you retain must be the kind of some
+  element (or, for `relationshipKinds`, some relationship) in this document. A typo is
+  refused, not corrected, and the refusal says when the word exists in the other list.
+- **Always give the concern.** It is printed inside every figure drawn for the
+  viewpoint — write it as the question that reading answers.
+- **Graphs only**, and at most twenty per document.
+- **Something with no kind survives every viewpoint.** If an element must drop out of a
+  reading, give it a kind.
+
+<!-- only: pi-outpost -->
+When you write a report with one chapter per reading, write one figure per viewpoint:
+`write_structure_figure` with `viewpoint: "power"`. Do not rebuild the same selection
+from hide lists — the viewpoint carries both the selection and the reason for it.
+<!-- end -->

package/dist/skills/structured-exchange/references/proposals.md

@@ -0,0 +1,86 @@
+# Proposing a change to something that exists
+
+Part of the `structured-exchange` skill. The envelope, the two identities and validation are in its `SKILL.md`.
+
+> **The one rule that trips everyone up.** When you propose a change to something
+> that already exists, the fields you write beside its `ref` say *what it is called
+> now*. They are not applied. The new value goes in `set`.
+>
+> ```json
+> { "id": "ledger", "ref": "EL-7", "label": "Ledger",
+>   "set": { "label": "General Ledger" } }
+> ```
+>
+> Writing `"label": "General Ledger"` on its own does **not** rename anything — it
+> claims that is already its name, and the proposal silently does nothing. If the
+> tool answers `0 changed`, this is what happened.
+
+Name the artifact in `target`. Then:
+
+- An element you do not mention is left alone. Omission never removes anything.
+- **On anything carrying a `ref`, the fields you declare describe what is already
+  there.** They are how the reader recognises it. They change nothing.
+- **To change something, say so in `set`.** That is the only thing that is applied.
+- To remove something, say so in `removals`, giving both the `ref` and whether it is
+  an `"element"` or a `"relationship"` — a reference alone does not say which.
+
+> **Say what you are removing.** A removal may also carry `label`, `kind`, and for a
+> relationship `from` and `to`. Add them. The reader's application holds your document
+> and nothing else — it cannot look up what `REL-88` stood for, so without them the
+> approval gate reads "relationship: REL-88" and asks someone to approve deleting
+> something they cannot see. These fields describe and never identify: `ref` is still
+> what names the thing.
+
+```json
+{
+  "schema": "urn:structured-exchange:1",
+  "kind": "graph",
+  "target": "architecture-v4",
+  "removals": [
+    { "type": "relationship", "ref": "REL-88",
+      "kind": "calls", "from": "ledger", "to": "billing" }
+  ],
+  "data": {
+    "nodes": [
+      { "id": "billing", "ref": "EL-12", "label": "Billing" },
+      { "id": "ledger", "ref": "EL-7", "label": "Ledger",
+        "set": { "label": "General Ledger" } },
+      { "id": "audit", "label": "Audit" }
+    ],
+    "edges": [{ "from": "audit", "to": "billing", "kind": "calls" }]
+  }
+}
+```
+
+Read that proposal:
+
+- **The removal** names `REL-88` and says what it is: the `calls` from Ledger to
+  Billing. The reader sees what goes, rather than an identifier.
+
+- **`billing`** has a `ref` and a name, no `set` → **context**. It exists, it is shown
+  so you can see where the new thing attaches, and nothing happens to it.
+- **`ledger`** has a `ref`, its current name, and a `set` → **a change**. The reader
+  sees `Ledger → General Ledger`, which is what makes it approvable.
+- **`audit`** has no `ref` → **new**. With nothing to describe, its `label` is simply
+  its value.
+
+**Include as much context as the reader needs.** That is what the default is for: an
+element you include to make the picture legible costs nothing and changes nothing.
+Leaving it out to be safe is the wrong instinct — a proposal nobody can situate is a
+proposal nobody should approve.
+
+## Two rules that catch people out
+
+**Never put a `set` on something with no `ref`.** There is nothing to change; its
+fields are already its values. Refused.
+
+**Never both `set` and remove the same `ref`.** That states two intentions at once and
+is refused rather than resolved — decide which you meant.
+
+**A relationship always declares `from` and `to`**, even when it carries a `ref`. Its
+endpoints are its identity, not something you patch. To re-attach a relationship,
+remove it and declare a new one.
+
+**Moving something between containers is an ordinary change**: `"set": { "container":
+"electrical" }` on an element that carries a `ref`, like any other field you change.
+Containers themselves are not patched — they are declared afresh in every document.

package/dist/skills/structured-exchange/references/timelines.md

@@ -0,0 +1,87 @@
+# Timelines: a schedule as data
+
+Part of the `structured-exchange` skill. The envelope, validation and size limits are in its `SKILL.md`.
+
+A project schedule, a roadmap, a validation campaign: declare it as a version 3
+`timeline` rather than as a Mermaid `gantt` block or a table of dates. The interface
+draws a proportional calendar, bars, star milestones, dependency arrows and a **Today**
+line taken from the reader's own date.
+
+```json
+{
+  "schema": "urn:structured-exchange:3",
+  "kind": "timeline",
+  "data": {
+    "title": "Programme X",
+    "time": { "start": "2026-10-01", "end": "2027-12-31", "scale": "month" },
+    "rows": [
+      { "type": "separator", "label": "System A" },
+      { "type": "task", "id": "T1", "label": "System studies", "items": [
+        { "type": "activity", "id": "study", "start": "2026-11-01", "end": "2027-02-28", "label": "Preliminary study" },
+        { "type": "milestone", "id": "srr", "date": "2027-03-01", "kind": "SRR", "label": "System Requirements Review" },
+        { "type": "activity", "id": "design", "start": "2027-03-15", "end": "2027-07-31", "label": "Detailed design" },
+        { "type": "milestone", "id": "cdr", "date": "2027-08-01", "kind": "CDR" }
+      ] },
+      { "type": "separator" },
+      { "type": "task", "id": "T2", "label": "Development", "items": [
+        { "type": "activity", "id": "dev", "start": "2027-03-01", "end": "2027-09-30" }
+      ] }
+    ],
+    "dependencies": [
+      { "from": "study", "to": "srr" },
+      { "from": "srr", "to": "T2" },
+      { "from": "design", "to": "cdr", "type": "finish-to-finish" }
+    ]
+  }
+}
+```
+
+- **Rows** are drawn in order. A `task` has an `id`, a `label` and any number of
+  `items` — activities and milestones, overlapping or with gaps, in any order. A
+  `separator` divides groups of tasks, with a `label` or without one.
+- **An activity** runs from `start` to `end` inclusive; **a milestone** is a `date`.
+  Dates are calendar days, `YYYY-MM-DD`, and every item must fall inside `time`:
+  one outside is refused, never clipped — widen `time` instead.
+- **`label`** is what a reader sees beside the item; a milestone without one shows its
+  `kind`. **`kind`** is your own vocabulary (`SRR`, `PDR`, `CDR`); every kind gets its
+  own colour and a legend entry. Write no colour, position, shape or "today" — the
+  renderer derives them, and the schema refuses them.
+- **A dependency** says `to` waits on `from`. Each names a task or an item by `id` (give
+  an item an `id` if anything depends on it); a task stands for the span of its items.
+  `type` is `finish-to-start` when omitted, or `start-to-start`, `finish-to-finish`,
+  `start-to-finish`. A dependency the dates break is **drawn and reported to you as
+  not satisfied**, not refused — tell the user, do not move dates to hide it. A cycle
+  is refused.
+- A timeline is not a proposal: it has no `target`. To change one, present the whole
+  revised timeline again.
+  <!-- only: pi-outpost -->
+  `write_structure_table` refuses it.
+  <!-- end -->
+- **Choose `time.scale` for the plan's length**: `week` for a few months (a test campaign),
+  `month` for a year or two, `quarter` beyond (a multi-year programme). It is only the scale
+  the plan opens at — the reader can switch to another or fit it to the screen — and it moves
+  no date.
+- **Closures, holidays and key dates** belong in the plan: `periods` (`start`, `end`, optional
+  `label` and `kind`, e.g. `"fermeture"`) are drawn as bands across every row, and `references`
+  (`date`, `label`, optional `kind`, e.g. a contractual date) as named lines. They constrain
+  nothing. A period may run past the plan's range (drawn clipped); a reference must fall inside it.
+<!-- only: pi-outpost -->
+- **To show what changed between two versions of a plan**, keep each version as its own
+  timeline file and call `compare_timelines` with the previous and the current one — never
+  work out the shifts yourself. It pairs tasks and items by `id`, so give every item an `id`
+  in a plan that will be compared; it tells you how many it could not pair. The reader sees
+  previous dates dashed, shifts like `(+3w)`, new and dropped items marked, and can switch to
+  the new version alone. Give `output_path` to keep the comparison for a report, and draw it
+  with `write_structure_figure` (`comparison: "new"` draws the new version alone). A compared
+  timeline carries `comparedTo`, `previous` dates and `role: "added" | "removed"`; do not write
+  these by hand.
+- **To put a timeline in a report**, write it with `write_structure_figure` and reference
+  the `.svg` from the Markdown. Give `width` (e.g. `900`) for a page — durations stay
+  proportional and rows grow to keep labels apart, and the header switches to months or
+  quarters when weeks would not fit; `scale` (`week`, `month`, `quarter`) to draw it at that
+  scale's natural size instead; `compact: true` for one row per section;
+  `hide_dependencies: true` to leave the arrows out. The figure's date line is labelled
+  with the day it is written (`reference_line: "none"` leaves it out), because the file
+  outlives that day. Graph options (`hide_element_kinds`, `viewpoint`…) are refused for a
+  timeline.
+<!-- end -->