pi-outpost 0.32.4 → 0.34.0

package/dist/contract/README.md

@@ -1,7 +1,7 @@
 # Structured exchange — for producers
 
 A tool can return structured data alongside its text, and this application will render
-it natively: a graph, a sequence, or a table, drawn from the data rather than from
+it natively: a graph, a sequence, a table, or a planning timeline, drawn from the data rather than from
 anything the tool wrote for display. When the document names a target it is read as a
 *proposal* to change something an external authority holds, and its rendering becomes
 the approval gate before that change is applied.
@@ -421,6 +421,124 @@ not, and will not:
 - **resolve anything you name.** Profiles, locations and artifact URIs are inert text
   until a person acts on them.
 
+## Version 3: the timeline, `urn:structured-exchange:3`
+
+Version 3 is version 2 with one more kind. Everything version 2 defines keeps its
+meaning — re-declare a version 2 document as version 3 and it reaches the same verdict
+with the same diagnostics — and versions 1 and 2 never accept a timeline. The schema is
+[`shared/schemas/structured-exchange-3.json`](../shared/schemas/structured-exchange-3.json).
+
+A `timeline` carries a schedule: a calendar range, rows of tasks and separators, the
+activities and milestones on each task, and optional Gantt dependencies between them.
+
+```json
+{
+  "schema": "urn:structured-exchange:3",
+  "kind": "timeline",
+  "data": {
+    "title": "Validation campaign",
+    "time": { "start": "2027-01-01", "end": "2027-06-30", "scale": "month" },
+    "rows": [
+      { "type": "separator", "label": "Bench" },
+      { "type": "task", "id": "bench", "label": "Bench tests", "items": [
+        { "type": "activity", "id": "b1", "start": "2027-01-11", "end": "2027-02-26", "label": "Campaign 1" },
+        { "type": "milestone", "id": "trr", "date": "2027-03-01", "kind": "TRR", "label": "Test Readiness Review" },
+        { "type": "activity", "id": "b2", "start": "2027-03-08", "end": "2027-04-30", "label": "Campaign 2" }
+      ] },
+      { "type": "task", "id": "report", "label": "Report", "items": [
+        { "type": "milestone", "id": "final", "date": "2027-06-15", "kind": "QR" }
+      ] }
+    ],
+    "periods": [
+      { "start": "2027-05-03", "end": "2027-05-14", "label": "Bench maintenance", "kind": "closure" }
+    ],
+    "references": [
+      { "date": "2027-06-30", "label": "Contractual end of campaign", "kind": "contract" }
+    ],
+    "dependencies": [
+      { "from": "trr", "to": "b2" },
+      { "from": "b2", "to": "final" }
+    ]
+  }
+}
+```
+
+What a producer has to know:
+
+- **Dates are calendar days**, `YYYY-MM-DD`, never instants, so no reader's time zone
+  moves a bar. An impossible day (`2027-02-30`) is `invalid-date`; a range or an activity
+  that ends before it starts is `inverted-range`; an item outside `time` is
+  `item-outside-range` — refused, never clipped.
+- **Rows and items are dispatched by `type`.** A task needs `id`, `label` and `items`
+  (which may be empty); a separator needs nothing else and may carry a `label`. A refusal
+  points at the property at fault, including one the timeline does not define: positions,
+  colours, shapes and the current date are the renderer's, and the schema refuses them.
+- **Dependencies** name a task or an identified item at each end. A task stands for the
+  span of its items. `type` is one of `finish-to-start` (the default), `start-to-start`,
+  `finish-to-finish`, `start-to-finish`. Unresolved ends, an empty task as an end, a task
+  linked to its own item, duplicates and cycles are refused. A dependency the dates do
+  not honour — the successor's linked day strictly before the predecessor's — is **not**
+  refused: it is drawn marked as not satisfied and reported to the agent, because a slip
+  is exactly what a reader needs to see.
+- **A timeline is not a proposal.** It carries no `target`, `removals` or `viewpoints`;
+  a revision is the whole timeline presented again. No profile constrains it, and
+  `write_structure_table` refuses it.
+- **A timeline can carry its calendar.** `periods` (`start`, `end`, optional `label`, `kind`)
+  are drawn as translucent bands across every row and the header — a closure, holidays; their
+  colour follows their `kind`, neutral and hatched without one. `references` (`date`, `label`,
+  optional `kind`) are named dashed lines — a contractual date, a delivery. Neither constrains
+  any item. A period may straddle the range's edge and is drawn clipped; one wholly outside is
+  `period-outside-range`; a reference outside the range is `item-outside-range`.
+- **A timeline can state what it is compared with.** `comparedTo: { label, date? }` names
+  the previous plan; an activity may carry `previous: { start, end }`, a milestone
+  `previous: { date }`, and a task or item `role: "added" | "removed"`. The reader draws the
+  previous dates dashed beside the current ones with the shift written out, marks what is
+  new and strikes what was dropped, and offers the new version alone. Without `comparedTo`,
+  none of these may appear (`comparison-without-reference`); an added or removed item has no
+  `previous` (`contradictory-change`); nothing may depend on a removed item
+  (`dependency-on-removed`); previous dates fall inside `time`. The agent's
+  `compare_timelines` tool produces such a document from two plan files, pairing by `id`.
+- **A timeline has a scale, and the reader may change it.** `time.scale` is `week`, `month`
+  or `quarter`: the scale the plan opens at, a choice of display that moves no date. The
+  reader switches between them or fits the whole range to the visible width; the header
+  labels the finest unit there is room for — ISO weeks (`W41`) under months, months under
+  years, or quarters (`Q1`) under years — and every year stays named. A comparison opens on
+  its first change, anything else on *Today*.
+- **A timeline leaves as a figure.** `write_structure_figure` writes it as one SVG — labels,
+  calendar, rows, arrows, key — with `scale` to draw it by week, month or quarter, `width` to
+  fit a page (which wins over `scale`), `compact` and `hide_dependencies`
+  for the reader's display options, and a date line labelled with the day it was written
+  (`reference_line: "none"` omits it). The reader's "download SVG" saves the same figure for
+  the options and scale on screen.
+- **Today is never in the document.** The reader draws a *Today* line at their own
+  calendar date when it falls in the range, and says which side of the range it is on
+  when it does not.
+
+A compared timeline, as `compare_timelines` writes it:
+
+```json
+{
+  "schema": "urn:structured-exchange:3",
+  "kind": "timeline",
+  "data": {
+    "title": "Validation campaign",
+    "comparedTo": { "label": "Plan of 1 September", "date": "2026-09-01" },
+    "time": { "start": "2027-01-01", "end": "2027-06-30", "scale": "month" },
+    "rows": [
+      { "type": "task", "id": "bench", "label": "Bench tests", "items": [
+        { "type": "activity", "id": "b1", "start": "2027-01-25", "end": "2027-03-12", "label": "Campaign 1",
+          "previous": { "start": "2027-01-11", "end": "2027-02-26" } },
+        { "type": "milestone", "id": "trr", "date": "2027-03-15", "kind": "TRR", "role": "added" },
+        { "type": "milestone", "id": "dry", "date": "2027-02-01", "label": "Dry run", "role": "removed" }
+      ] }
+    ]
+  }
+}
+```
+
+The scales are `week`, `month` and `quarter`. Version 3 may still grow in place until a
+release publishes it; after that, another scale is a version 4.
+
 ## Holding documents to a project's data model
 
 The core contract treats `profile` as a name. A project can go further: declare its data
@@ -796,6 +914,7 @@ contract ships with the package, under `contract/`:
 node_modules/pi-outpost/dist/contract/
   schemas/structured-exchange-1.json    the normative schema — any validator runs it
   schemas/structured-exchange-2.json    the enriched contract, published beside it
+  schemas/structured-exchange-3.json    version 2 plus the planning timeline
   schemas/structured-exchange-rules-1.json
                                         the rules a project reviews its specifications against
   conformance/                          documents and the verdict each should get

package/dist/contract/conformance/README.md

@@ -17,8 +17,8 @@ whether it conforms does not have a contract, it has a dependency.
 
 ## Two versions in one suite
 
-Cases are named for the version they exercise: `v2-` for the enriched contract,
-everything else for version 1. A conforming implementation dispatches on the
+Cases are named for the version they exercise: `v3-` for the timeline, `v2-` for the
+enriched contract, everything else for version 1. A conforming implementation dispatches on the
 identifier each document declares — `index.json` states the expected verdict, and
 nothing else about a case tells you which contract judges it.
 
@@ -48,6 +48,19 @@ at v0.25.0 — the first release to publish version 2. Until then version 2 grew
 written against it. From that release on, a change to what a version 2 envelope may say is a
 new version, and the two locks together are the floor the suite may not sink below.
 
+## Version 3
+
+Version 3 is version 2 with one more kind, `timeline`. Everything version 2 defines keeps
+its meaning, so a version 2 document re-declared as version 3 reaches the same verdict
+with the same reasons; the `v3-` cases exercise only the timeline. `unknown-version`
+moved to version 4 when version 3 was published, and the version 1 lock records why.
+
+Version 3 may still grow in place until a release publishes it, as version 2 did for
+viewpoints — compared timelines (`comparedTo`, `previous`, `role`), calendar periods and reference dates
+(`periods`, `references`) and the `week` and `quarter` scales were added that way. From that release on it is
+frozen like the other two: another timeline scale (`day`, `year`), another item or row type, or anything else a
+version 3 document could not say before, is a version 4.
+
 ## Rules that are not in the schema
 
 JSON Schema decides shape. These are the relational rules that follow it, and the
@@ -55,12 +68,12 @@ JSON Schema decides shape. These are the relational rules that follow it, and th
 
 | Rule | What it refuses |
 |---|---|
-| `duplicate-identifier` | two elements sharing an envelope-scoped `id` |
+| `duplicate-identifier` | two elements sharing an envelope-scoped `id` — on a timeline, any two tasks or items |
 | `duplicate-container-identifier` | two containers sharing an `id` |
-| `unresolved-endpoint` | a relationship endpoint that no declared element carries |
+| `unresolved-endpoint` | a relationship endpoint that no declared element carries, or a timeline dependency naming no task or item |
 | `unresolved-container` | an element assigned to a container the document never declares |
 | `kind-data-mismatch` | a declared `kind` that disagrees with the data variant present |
-| `kind-not-proposable` | a `table` carrying a `target` or a `removal` |
+| `kind-not-proposable` | a `table` (version 1) or a `timeline` carrying a `target` or a `removal` |
 | `removal-without-target` | a removal in a document that targets nothing |
 | `duplicate-reference` | the same reference addressed twice — changed twice, or changed and removed |
 | `change-without-reference` | a `set` with no `ref` naming what should change |
@@ -71,6 +84,17 @@ JSON Schema decides shape. These are the relational rules that follow it, and th
 | `viewpoints-without-graph` | viewpoints declared on a document that is not a graph |
 | `duplicate-viewpoint-identifier` | two viewpoints of one document sharing an `id` |
 | `empty-viewpoint` | a viewpoint that retains no element kind and no relationship kind |
+| `invalid-date` | a timeline date the pattern admits and the calendar does not, such as `2027-02-30` |
+| `inverted-range` | a timeline, or an activity, that starts after it ends |
+| `item-outside-range` | an activity or milestone outside the timeline's `time` range — refused, never clipped |
+| `empty-task-endpoint` | a dependency naming a task that holds no item, so has no start or finish |
+| `self-dependency` | a dependency from something to itself, or between a task and one of its own items |
+| `duplicate-dependency` | the same `from`, `to` and type declared twice |
+| `comparison-without-reference` | previous dates or a change role in a timeline that declares no `comparedTo` |
+| `contradictory-change` | previous dates on an added or removed item, or an item role contradicting its task's |
+| `dependency-on-removed` | a dependency naming a task or item the plan dropped |
+| `period-outside-range` | a timeline period lying wholly outside the range (one straddling an edge is drawn clipped) |
+| `dependency-cycle` | dependencies that loop, which no dates could honour; the message names the loop |
 | `unresolved-viewpoint-kind` | a viewpoint retaining a kind no element, or no relationship, of the document has — checked per vocabulary, and never corrected to a near miss |
 
 Rules prefixed `schema/` come from the JSON Schema itself; the suffix is the keyword

package/dist/contract/conformance/index.json

@@ -77,6 +77,33 @@
     },
     {
       "file": "valid/v2-graph-with-viewpoints.json"
+    },
+    {
+      "file": "valid/v3-timeline-programme.json"
+    },
+    {
+      "file": "valid/v3-timeline-empty-task-and-anonymous-separator.json"
+    },
+    {
+      "file": "valid/v3-timeline-single-day-activity.json"
+    },
+    {
+      "file": "valid/v3-timeline-week-scale.json"
+    },
+    {
+      "file": "valid/v3-timeline-quarter-scale.json"
+    },
+    {
+      "file": "valid/v3-timeline-four-dependency-types.json"
+    },
+    {
+      "file": "valid/v3-timeline-unsatisfied-dependency.json"
+    },
+    {
+      "file": "valid/v3-timeline-compared.json"
+    },
+    {
+      "file": "valid/v3-timeline-calendar.json"
     }
   ],
   "invalid": [
@@ -255,6 +282,94 @@
     {
       "file": "invalid/viewpoints-under-version-1.json",
       "expectedRule": "schema/additionalProperties"
+    },
+    {
+      "file": "invalid/v3-timeline-impossible-date.json",
+      "expectedRule": "invalid-date"
+    },
+    {
+      "file": "invalid/v3-timeline-inverted-activity.json",
+      "expectedRule": "inverted-range"
+    },
+    {
+      "file": "invalid/v3-timeline-inverted-range.json",
+      "expectedRule": "inverted-range"
+    },
+    {
+      "file": "invalid/v3-timeline-milestone-outside-range.json",
+      "expectedRule": "item-outside-range"
+    },
+    {
+      "file": "invalid/v3-timeline-duplicate-identifier.json",
+      "expectedRule": "duplicate-identifier"
+    },
+    {
+      "file": "invalid/v3-timeline-unresolved-dependency-endpoint.json",
+      "expectedRule": "unresolved-endpoint"
+    },
+    {
+      "file": "invalid/v3-timeline-empty-task-endpoint.json",
+      "expectedRule": "empty-task-endpoint"
+    },
+    {
+      "file": "invalid/v3-timeline-self-dependency.json",
+      "expectedRule": "self-dependency"
+    },
+    {
+      "file": "invalid/v3-timeline-duplicate-dependency.json",
+      "expectedRule": "duplicate-dependency"
+    },
+    {
+      "file": "invalid/v3-timeline-dependency-cycle.json",
+      "expectedRule": "dependency-cycle"
+    },
+    {
+      "file": "invalid/v3-timeline-unsupported-scale.json",
+      "expectedRule": "schema/enum"
+    },
+    {
+      "file": "invalid/v3-timeline-unknown-dependency-type.json",
+      "expectedRule": "schema/enum"
+    },
+    {
+      "file": "invalid/v3-timeline-presentation-property.json",
+      "expectedRule": "schema/additionalProperties"
+    },
+    {
+      "file": "invalid/v3-timeline-with-target.json",
+      "expectedRule": "kind-not-proposable"
+    },
+    {
+      "file": "invalid/v3-timeline-under-version-2.json",
+      "expectedRule": "schema/enum"
+    },
+    {
+      "file": "invalid/v3-timeline-comparison-without-reference.json",
+      "expectedRule": "comparison-without-reference"
+    },
+    {
+      "file": "invalid/v3-timeline-contradictory-change.json",
+      "expectedRule": "contradictory-change"
+    },
+    {
+      "file": "invalid/v3-timeline-previous-outside-range.json",
+      "expectedRule": "item-outside-range"
+    },
+    {
+      "file": "invalid/v3-timeline-dependency-on-removed.json",
+      "expectedRule": "dependency-on-removed"
+    },
+    {
+      "file": "invalid/v3-timeline-previous-wrong-shape.json",
+      "expectedRule": "schema/additionalProperties"
+    },
+    {
+      "file": "invalid/v3-timeline-period-outside-range.json",
+      "expectedRule": "period-outside-range"
+    },
+    {
+      "file": "invalid/v3-timeline-reference-outside-range.json",
+      "expectedRule": "item-outside-range"
     }
   ]
 }

package/dist/contract/conformance/invalid/unknown-version.json

@@ -1,5 +1,5 @@
 {
-  "schema": "urn:structured-exchange:3",
+  "schema": "urn:structured-exchange:4",
   "kind": "graph",
   "data": {
     "nodes": [

package/dist/contract/conformance/invalid/v3-timeline-comparison-without-reference.json

@@ -0,0 +1,123 @@
+{
+  "schema": "urn:structured-exchange:3",
+  "kind": "timeline",
+  "data": {
+    "title": "Programme X",
+    "time": {
+      "start": "2026-10-01",
+      "end": "2028-03-31",
+      "scale": "month"
+    },
+    "rows": [
+      {
+        "type": "separator",
+        "label": "Système A"
+      },
+      {
+        "type": "task",
+        "id": "T1",
+        "label": "Études système",
+        "items": [
+          {
+            "type": "activity",
+            "id": "etude-preliminaire",
+            "start": "2026-11-01",
+            "end": "2027-02-28",
+            "label": "Étude préliminaire"
+          },
+          {
+            "type": "milestone",
+            "id": "srr",
+            "date": "2027-03-01",
+            "kind": "SRR",
+            "label": "System Requirements Review",
+            "previous": {
+              "date": "2027-02-01"
+            }
+          },
+          {
+            "type": "activity",
+            "id": "etude-detaillee",
+            "start": "2027-03-15",
+            "end": "2027-07-31",
+            "label": "Étude détaillée"
+          },
+          {
+            "type": "milestone",
+            "id": "pdr",
+            "date": "2027-05-15",
+            "kind": "PDR",
+            "label": "Preliminary Design Review"
+          },
+          {
+            "type": "milestone",
+            "id": "cdr",
+            "date": "2027-08-01",
+            "kind": "CDR",
+            "label": "Critical Design Review"
+          }
+        ]
+      },
+      {
+        "type": "task",
+        "id": "T2",
+        "label": "Développement",
+        "items": [
+          {
+            "type": "activity",
+            "id": "dev",
+            "start": "2027-03-01",
+            "end": "2027-09-30",
+            "label": "Développement"
+          }
+        ]
+      },
+      {
+        "type": "separator",
+        "label": "Système B"
+      },
+      {
+        "type": "task",
+        "id": "T3",
+        "label": "Études système",
+        "items": [
+          {
+            "type": "activity",
+            "start": "2027-02-01",
+            "end": "2027-06-30",
+            "label": "Étude"
+          }
+        ]
+      },
+      {
+        "type": "separator"
+      },
+      {
+        "type": "task",
+        "id": "T4",
+        "label": "Recette",
+        "items": []
+      }
+    ],
+    "dependencies": [
+      {
+        "from": "etude-preliminaire",
+        "to": "srr"
+      },
+      {
+        "from": "srr",
+        "to": "T2"
+      },
+      {
+        "from": "etude-detaillee",
+        "to": "cdr",
+        "type": "finish-to-finish"
+      },
+      {
+        "from": "T1",
+        "to": "T3",
+        "type": "start-to-start"
+      }
+    ]
+  }
+}

package/dist/contract/conformance/invalid/v3-timeline-contradictory-change.json

@@ -0,0 +1,128 @@
+{
+  "schema": "urn:structured-exchange:3",
+  "kind": "timeline",
+  "data": {
+    "title": "Programme X",
+    "time": {
+      "start": "2026-10-01",
+      "end": "2028-03-31",
+      "scale": "month"
+    },
+    "rows": [
+      {
+        "type": "separator",
+        "label": "Système A"
+      },
+      {
+        "type": "task",
+        "id": "T1",
+        "label": "Études système",
+        "items": [
+          {
+            "type": "activity",
+            "id": "etude-preliminaire",
+            "start": "2026-11-01",
+            "end": "2027-02-28",
+            "label": "Étude préliminaire"
+          },
+          {
+            "type": "milestone",
+            "id": "srr",
+            "date": "2027-03-01",
+            "kind": "SRR",
+            "label": "System Requirements Review"
+          },
+          {
+            "type": "activity",
+            "id": "etude-detaillee",
+            "start": "2027-03-15",
+            "end": "2027-07-31",
+            "label": "Étude détaillée"
+          },
+          {
+            "type": "milestone",
+            "id": "pdr",
+            "date": "2027-05-15",
+            "kind": "PDR",
+            "label": "Preliminary Design Review"
+          },
+          {
+            "type": "milestone",
+            "id": "cdr",
+            "date": "2027-08-01",
+            "kind": "CDR",
+            "label": "Critical Design Review",
+            "role": "added",
+            "previous": {
+              "date": "2027-07-01"
+            }
+          }
+        ]
+      },
+      {
+        "type": "task",
+        "id": "T2",
+        "label": "Développement",
+        "items": [
+          {
+            "type": "activity",
+            "id": "dev",
+            "start": "2027-03-01",
+            "end": "2027-09-30",
+            "label": "Développement"
+          }
+        ]
+      },
+      {
+        "type": "separator",
+        "label": "Système B"
+      },
+      {
+        "type": "task",
+        "id": "T3",
+        "label": "Études système",
+        "items": [
+          {
+            "type": "activity",
+            "start": "2027-02-01",
+            "end": "2027-06-30",
+            "label": "Étude"
+          }
+        ]
+      },
+      {
+        "type": "separator"
+      },
+      {
+        "type": "task",
+        "id": "T4",
+        "label": "Recette",
+        "items": []
+      }
+    ],
+    "dependencies": [
+      {
+        "from": "etude-preliminaire",
+        "to": "srr"
+      },
+      {
+        "from": "srr",
+        "to": "T2"
+      },
+      {
+        "from": "etude-detaillee",
+        "to": "cdr",
+        "type": "finish-to-finish"
+      },
+      {
+        "from": "T1",
+        "to": "T3",
+        "type": "start-to-start"
+      }
+    ],
+    "comparedTo": {
+      "label": "Plan of 1 September",
+      "date": "2026-09-01"
+    }
+  }
+}