task-pipeline-skill 1.93.3 → 1.94.1

package/plugins/task-pipeline/skills/task-pipeline/templates/canvas.md

@@ -0,0 +1,97 @@
+# Canvas — <topic> (YYYY-MM-DD)
+
+The target state of the next version, laid over today's logic: wave mode's committed
+target-state spec (`references/waves.md` → *The canvas*), written at step 3 of an iteration
+(`references/iteration.md` → *Integration, until it converges*). The machine-readable plan
+is `<topic>-plan.json` (or the work graph), the inventory is `<topic>-inventory.json`
+(inventory/1), and the question queue is `<topic>-questions.md`. This page cites the
+dossiers by section and does not repeat them.
+
+**Read at:** <repository @ commit, one per repository the canvas touches — the state this
+design was laid over>.
+
+**Decisions applied without re-opening:** <each recorded decision this canvas rests on, with
+its citation>.
+
+## Contents
+
+- 1. As-is → to-be
+- 2. The integration seams
+- 3. Item → module → node → wave
+- 4. Deleted or superseded
+- 5. Remaining conflicts → questions
+- The waves
+
+## 1. As-is → to-be
+
+### Per module
+
+| Module | As-is (the facts that matter) | To-be | Dossier |
+|---|---|---|---|
+| A <name> | <today, with file:line> | <the next version> | <dossier § sections> |
+
+### Per contract
+
+| Contract | Owner | Change | Nodes |
+|---|---|---|---|
+| <schema, wire format, doc of record, register> | <owning repository or Project on the board> | <additive / breaking / new> | <node ids> |
+
+## 2. The integration seams
+
+How each integration happens, who owns each side, and what crosses it. Two dossiers that
+change one seam were designed together; a ★ marks a seam that re-designed a dossier.
+
+| Seam | What | Sides | Rule | Nodes |
+|---|---|---|---|---|
+| S1 | <seam> | <module ↔ module> | <the one rule both sides follow> | <node ids> |
+
+## 3. Item → module → node → wave
+
+Generated, not hand-written: `scripts/waves.py assign --modules <modules.json> --plan
+<plan.json> --write`, then `waves.py count`. Every inventory item is a row. An item on no
+node is closed with its receipt, carried (`release: program`, with the reason), or a gap in
+this canvas — `waves.py validate` exits 1 on the last.
+
+| Item | Module | Node(s) | Wave(s) | Status |
+|---|---|---|---|---|
+| <ID-001> | <A> | <A-1> | <1> | <holds / changed / fixed: receipt / carried: reason> |
+
+## 4. Deleted or superseded
+
+What the next version removes — code, screens, contracts, docs, rows — and which node
+removes it. A removal nobody wrote down survives the release.
+
+| Node | Removes |
+|---|---|
+| <A-1> | <the old path, the doc sentence, the register row> |
+
+## 5. Remaining conflicts → questions
+
+What integration could not settle, each a row in `<topic>-questions.md` with both designs
+attached.
+
+1. <conflict> → <question id>
+
+---
+
+## The waves
+
+Cut per `references/waves.md` → *Cutting the waves*: a wave holds only items closable in one
+pass; wave 1 is the walking skeleton; lanes run in parallel inside a wave and respect file
+ownership. Each node carries its own risk class (`references/iteration.md` → *Verification
+starts when a node lands*): R1 one passing round, R2 two, R3 three, one of them recorded adversarial.
+
+**Counts:** <from `waves.py count` and the graph: nodes by risk, by wave, out of waves>.
+
+### Wave 1: <name>
+
+**Exit criteria, written before the wave starts:**
+- <the tests, the live walk, the gates and the documents that will prove it closed>
+
+**Nodes by lane:**
+
+| Lane | Nodes |
+|---|---|
+| <lane> | <A-1 R2 → A-2 R1> |
+
+**Seam checks:** <{node, node} the seam group checked once its last node lands>.

package/plugins/task-pipeline/skills/task-pipeline/templates/dossier.md

@@ -0,0 +1,82 @@
+# Dossier <letter> — <module name>
+
+One dossier per cluster of inventory items (`references/iteration.md` → *Module dossiers*),
+written in parallel with the others, read-only on every repository: the dossier is the only
+write. **A dossier is a design, not a plan** — it does not cut waves. Evidence for every
+claim: `file:line @commit`, or a command and its output. No secret values, ever.
+
+Written <date> against: <repository @ commit, one per repository read>.
+
+## Contents
+
+- 1. Items
+- 2. As-is
+- 3. To-be
+- 4. Options considered
+- 5. Contracts touched
+- 6. Nodes
+- 7. Deletes
+- 8. Questions
+- 9. Out of scope / program
+
+## 1. Items
+
+Every inventory item the module table assigns here, verified against the code before it is
+trusted. An item that does not reproduce is marked so, with the evidence, and closed in its
+owning register.
+
+| id | title (short) | still holds? (yes / no + evidence / changed) | severity |
+|---|---|---|---|
+| <ID-001> | <…> | <…> | <…> |
+
+## 2. As-is
+
+How the module works today, in the few facts that matter, each with `file:line`.
+
+## 3. To-be
+
+The design of the next version: contracts, data, behaviour, failure handling and logs. One
+coherent design that answers every item; say which items each part answers.
+
+## 4. Options considered
+
+| Choice | Options | Chosen | Why |
+|---|---|---|---|
+| <the real choice> | (a) … (b) … | <…> | <the reason, with the measurement where there is one> |
+
+## 5. Contracts touched
+
+| Contract | Owner (repository / session) | Change | Owner must agree first? |
+|---|---|---|---|
+| <interface, schema, wire format, doc of record, register> | <…> | <additive / breaking / new> | <yes / no> |
+
+## 6. Nodes
+
+The design cut into build nodes. **The risk class is per node**, never one class for the
+whole dossier: one R3 node beside four R1 nodes is five classes, and a dossier-wide class
+either over-checks the four or under-checks the one (`references/iteration.md` →
+*Verification starts when a node lands*). Files owned by one node only, where possible.
+
+| id | repo | owns (files) | does | tests (★ = fails today) | risk | deps | one pass? |
+|---|---|---|---|---|---|---|---|
+| <X-1> | <…> | <paths> | <…> | ★ <the test that fails today>; <…> | <R1 / R2 / R3> | <node ids> | <yes / no> |
+
+Count by risk: <R1 n · R2 n · R3 n>.
+
+## 7. Deletes
+
+What the new version removes — code, docs, rows, files — by node.
+
+## 8. Questions
+
+Only what the sources cannot answer: the operator's recorded decisions, ADRs and
+principles, the code and the neighbours' contracts were tried first.
+
+| id | question | options → consequence | recommendation | whose (operator / peer: name it) | blocks |
+|---|---|---|---|---|---|
+| Q1 | <…> | (a) … → … (b) … → … | <…> | <…> | <node ids> |
+
+## 9. Out of scope / program
+
+Items recommended for a later release, each with its reason (`release: program` in the
+inventory).

package/plugins/task-pipeline/skills/task-pipeline/templates/inventory.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/templates/inventory.schema.json",
+  "title": "inventory/1 — <artifacts>/specs/YYYY-MM-DD-<topic>-inventory.json",
+  "description": "Wave 0's single machine-readable inventory: one item per open item of the board, every survey and every harvested source (references/waves.md, Wave 0). scripts/waves.py merges audit outputs into it (`merge`), writes `module`, `node`, `wave` and `release` from two short tables (`assign`), counts it (`count`) and refuses an item that lands nowhere (`validate`). The document is an object carrying `schema` and `items`; a bare array of items is read as the items of one. Fields a project needs beyond these go under an `x-` prefix.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "items"],
+  "properties": {
+    "schema": {"const": "inventory/1"},
+    "topic": {"type": "string"},
+    "items": {"type": "array", "items": {"$ref": "#/$defs/item"}}
+  },
+  "$defs": {
+    "item": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {"^x-[a-z0-9-]+$": {}},
+      "required": ["id", "title", "area", "kind", "severity", "evidence", "proposed_fix"],
+      "properties": {
+        "id": {
+          "description": "The item's id in its owning register. An item without one gets one there, in the same change. Unique across the inventory.",
+          "type": "string",
+          "pattern": "^[A-Za-z][A-Za-z0-9._-]{0,63}$"
+        },
+        "title": {"type": "string", "minLength": 3},
+        "area": {"description": "The part of the system it touches.", "type": "string", "minLength": 1},
+        "kind": {
+          "description": "What sort of item: e.g. bug, gap, weak-impl, contradiction, doc-wrong, doc-missing, plan.",
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "severity": {"enum": ["critical", "high", "medium", "low", "info"]},
+        "evidence": {
+          "description": "The receipt: file:line at a commit, or a command and its output. A finding is a fact with a receipt, never an impression.",
+          "oneOf": [
+            {"type": "string", "minLength": 3},
+            {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 3}}
+          ]
+        },
+        "proposed_fix": {"type": "string", "minLength": 1},
+        "status": {
+          "description": "As measured, not as the register last said. Absent means open. Every value but open and changed is terminal; carried means release program with a reason.",
+          "enum": ["open", "changed", "closed", "fixed", "fixed-elsewhere", "duplicate", "moved", "stale", "not-reproduced", "carried"],
+          "default": "open"
+        },
+        "source": {"description": "Where it was found, when that differs from the evidence: a register row as file:line, or the command that surfaced it.", "type": "string"},
+        "source_file": {"description": "The survey output it was merged from (written by `waves.py merge`).", "type": "string"},
+        "repo": {"type": "string"},
+        "module": {"description": "The dossier cluster it belongs to (written by `waves.py assign` from the module table).", "type": "string"},
+        "node": {
+          "description": "The canvas nodes that close it, in wave order (written by `waves.py assign` from the plan's `closes`).",
+          "type": "array",
+          "items": {"type": "string"},
+          "uniqueItems": true
+        },
+        "wave": {"description": "The wave that closes it: the last wave among its nodes. Null when it is carried to a later release.", "type": ["integer", "null"], "minimum": 1},
+        "release": {"enum": ["this", "program"]},
+        "register_id": {"type": ["string", "null"]},
+        "blocked_by": {"type": "array", "items": {"type": "string"}},
+        "closable_in_one_pass": {"type": "boolean"},
+        "needs_operator": {"type": "boolean"},
+        "notes": {"type": "string"}
+      }
+    },
+    "modules": {
+      "description": "The module table `assign --modules` reads: module name -> the item ids it holds. An id in two modules is refused. Edited as the canvas is cut; a re-cut is a diff to this table.",
+      "type": "object",
+      "additionalProperties": {"type": "array", "items": {"type": "string"}, "uniqueItems": true}
+    },
+    "plan": {
+      "description": "The wave plan `assign --plan` and `sync-graph` read: any JSON whose `nodes` lists {id, wave, closes}. A work graph that carries `closes` on its nodes is one. A node whose wave is not an integer is carried (`release: program`).",
+      "type": "object",
+      "required": ["nodes"],
+      "properties": {
+        "nodes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id"],
+            "properties": {
+              "id": {"type": "string"},
+              "graph_id": {"type": "string", "pattern": "^N-[0-9]{3,}$", "description": "The work-graph node this canvas node is built as, where the two ids differ; `sync-graph` moves that node."},
+              "wave": {"type": ["integer", "null"], "minimum": 1},
+              "closes": {"type": "array", "items": {"type": "string"}},
+              "release": {"enum": ["this", "program"]},
+              "risk": {"enum": ["R1", "R2", "R3"], "description": "The node's risk class; `sync-graph` writes it onto the work-graph node (a lowering needs --lower-why), and `graph.py close` enforces the rounds it owes."}
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/plugins/task-pipeline/skills/task-pipeline/templates/lesson.schema.json

@@ -0,0 +1,221 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/templates/lesson.schema.json",
+  "title": "lesson/1",
+  "description": "One lesson: a retro entry's class, stated so another project's agent can use it at stage 0. The project retro is canonical; a lesson is its projection (references/iteration.md, The learning loop). scripts/lessons.py builds one from a retro entry that carries a `**Lesson:**` line and refuses anything this schema does not allow. It never carries a transcript, a value, a path outside the repository, a URL, a person's or a customer's name, or code. The origin carries the project's pseudonymous key and the evidence commit: both stay on this machine or estate, and retro.publish strips the whole origin before anything leaves (references/retrospective.md, What may leave the project).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "classKey",
+    "title",
+    "trigger",
+    "check",
+    "grade",
+    "stages",
+    "nouns",
+    "origin"
+  ],
+  "properties": {
+    "schema": {
+      "const": "lesson/1"
+    },
+    "classKey": {
+      "description": "The class as a slug. The identity across projects: two projects with one classKey hold one lesson, seen twice.",
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "maxLength": 64
+    },
+    "title": {
+      "description": "The class in one sentence. States the class, never the incident (redaction rule 5).",
+      "type": "string",
+      "minLength": 8,
+      "maxLength": 160
+    },
+    "trigger": {
+      "description": "When it applies.",
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 200
+    },
+    "check": {
+      "description": "The check that now catches it, by name.",
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 200
+    },
+    "grade": {
+      "description": "The fix grade, 1-3 (references/retrospective.md, Three grades of fix).",
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 3
+    },
+    "stages": {
+      "description": "The stage that owned the failure and the stage that surfaced it. A profile's stage ids need not be numbers.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "owned",
+        "surfaced"
+      ],
+      "properties": {
+        "owned": {
+          "type": [
+            "integer",
+            "string"
+          ]
+        },
+        "surfaced": {
+          "type": [
+            "integer",
+            "string"
+          ]
+        }
+      }
+    },
+    "nouns": {
+      "description": "3-8 search keys: what stage 0 matches the task's nouns against.",
+      "type": "array",
+      "minItems": 3,
+      "maxItems": 8,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 2,
+        "maxLength": 32
+      }
+    },
+    "origin": {
+      "description": "Where the lesson was learned. Local and estate only: retro.publish strips it.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "project",
+        "commit",
+        "retro"
+      ],
+      "properties": {
+        "project": {
+          "description": "The project's pseudonymous key: `p-` and the first 12 hex digits of the repository's root commit. Never its name: a repository name can be a customer's or a product's (redaction rule 4). The shared store receives the same key, never a `project:<slug>` id.",
+          "type": "string",
+          "pattern": "^p-[0-9a-f]{12}$"
+        },
+        "commit": {
+          "description": "The evidence commit, which resolves in the project's own clone.",
+          "type": "string",
+          "pattern": "^[0-9a-f]{7,40}$"
+        },
+        "retro": {
+          "description": "The retro file, relative to the repository, and the entry's anchor: the heading's letters and digits in any script, lowercased, every other run one hyphen. The pattern is the script's RETRO_REF, read with Unicode word characters as Python's `re` reads it.",
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_][A-Za-z0-9_./-]*\\.md#[^\\W_]+(?:-[^\\W_]+)*$",
+          "maxLength": 200
+        }
+      }
+    }
+  },
+  "$defs": {
+    "indexEntry": {
+      "description": "One line of the local index (lesson-index/1): one entry per classKey, a pure function of its origins, so a rebuild from the retros equals the incremental index byte for byte.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema",
+        "id",
+        "classKey",
+        "title",
+        "trigger",
+        "check",
+        "grade",
+        "stages",
+        "nouns",
+        "seen",
+        "projects",
+        "status",
+        "origins"
+      ],
+      "properties": {
+        "schema": {
+          "const": "lesson-index/1"
+        },
+        "id": {
+          "type": "string",
+          "pattern": "^L-[0-9a-f]{12}$",
+          "description": "`L-` and the first 12 hex digits of sha256(classKey)."
+        },
+        "classKey": {
+          "type": "string"
+        },
+        "title": {
+          "type": "string"
+        },
+        "trigger": {
+          "type": "string"
+        },
+        "check": {
+          "type": "string"
+        },
+        "grade": {
+          "type": "integer"
+        },
+        "stages": {
+          "type": "object"
+        },
+        "nouns": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "seen": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "How many origins hold the class."
+        },
+        "projects": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "How many distinct projects hold it."
+        },
+        "status": {
+          "enum": [
+            "local",
+            "candidate"
+          ],
+          "description": "`candidate` when two or more projects hold it: the retro.publish queue for learned.md."
+        },
+        "origins": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "description": "Each origin's own lesson fields, its origin, and the shared-store memory id once recorded (`mem:<id>@<revision>`).",
+            "required": [
+              "project",
+              "commit",
+              "retro",
+              "lesson"
+            ],
+            "properties": {
+              "project": {
+                "type": "string"
+              },
+              "commit": {
+                "type": "string"
+              },
+              "retro": {
+                "type": "string"
+              },
+              "memory": {
+                "type": "string",
+                "pattern": "^mem:[^@\\s]+@[0-9]+$"
+              },
+              "lesson": {
+                "type": "object"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/plugins/task-pipeline/skills/task-pipeline/templates/questions.md

@@ -0,0 +1,45 @@
+# Questions — <topic> (YYYY-MM-DD)
+
+The single question queue of an iteration (`references/iteration.md` → *Question rounds —
+asked in batches, never blocking*; `references/waves.md` → *The questions*). Every question
+is first tried against the sources. One the sources answer is recorded under **Closed**, with
+its citation, and never asked. The rest fall into three groups:
+- **Operator** — ordered so prerequisite decisions come first;
+- **Peers** — grouped by the repository or session that owns the answer;
+- **Assumed** — taken on the recommendation because the answer is internal and reversible;
+  the nodes resting on each are named, so a different answer re-plans exactly those.
+
+An outward or irreversible act is never assumed. A round is called on the first of three
+triggers: the whole frontier is blocked, five questions are open, a wave boundary.
+
+**Counts:** <N closed from sources · N operator · N peers · N assumed>.
+
+## Closed from the sources (not asked)
+
+| # | Question (raised by) | Answer | Citation |
+|---|---|---|---|
+| C1 | <question> (<dossier or node>) | <answer> | <decision record, ADR, code at file:line, a peer's message> |
+
+## Operator
+
+| # | Blocks | Question | Recommended | Consequence of each answer | Reversible? |
+|---|---|---|---|---|---|
+| O1 | <node ids> | <question, answerable without context> | **<answer>** | (a) <…> (b) <…> | <yes / no> |
+
+## Peers
+
+| # | Blocks | Peer (repository / session) | Question | Recommended |
+|---|---|---|---|---|
+| P1 | <node ids> | <owner> | <question> | <answer> |
+
+## Assumed
+
+| # | Assumption | Taken from | Nodes resting on it |
+|---|---|---|---|
+| A1 | <the recommendation, as taken> | <O1 / P1> | <node ids> |
+
+## Answers received
+
+| # | From, when | Answer | Applied to |
+|---|---|---|---|
+| <O1> | <who, date> | <answer as given> | <nodes re-planned, or none> |

package/plugins/task-pipeline/skills/task-pipeline/templates/retro.md

@@ -49,6 +49,10 @@ stays short precisely so that reading it in full at stage 0 stays cheap.
 - **Fix:** grade 1 (mechanical) — … / grade 2 → `R-00N` / grade 3, expires in
   2 runs
 - **The check:** … (what catches this the first time, from now on)
+- **Lesson:** `<class-key>` — <the class, one sentence> · **When:** <trigger> · **Nouns:** <a>, <b>, <c>
+  (optional, and on ONE line: write it only when the class would be true in another
+  project — it makes the entry a lesson for `scripts/lessons.py add`, lesson/1. Without
+  it the entry stays private to this project)
 - **Commit:** `<sha>` — the change that fixed it
 - **Upstream?** … (a lesson true in any repo belongs in the skill's own
   `references/learned.md` — open an issue and say so here)

package/plugins/task-pipeline/skills/task-pipeline/templates/run.md

@@ -20,7 +20,7 @@ Run: `<topic>` · started `<YYYY-MM-DD>` · module map: `<path or "none">`
 
 ## `read:` — which doctrine this run actually opened
 
-The bundle is 40 reference files and nothing recorded which of them a run read, so **a
+The bundle is 41 reference files and nothing recorded which of them a run read, so **a
 skipped file and a read one were indistinguishable** — the class every guard in this
 pipeline exists to catch, left standing over the doctrine itself.
 
@@ -48,7 +48,7 @@ same claim one level down.
 |---|---|---|
 | `unmeasured — no run ledger` | there is no ledger | nothing to read from |
 | `unmeasured — the ledger carries no read: lines` | the hook is absent, **or** the run opened no doctrine | two opposite facts, and the ledger cannot separate them, so neither is claimed |
-| `N of 40 reference files read — unattested`, then each unread one | the hook is installed and fired | the count alone says there is a gap, not where — and `unattested` says the ledger cannot name who wrote the lines |
+| `N of 41 reference files read — unattested`, then each unread one | the hook is installed and fired | the count alone says there is a gap, not where — and `unattested` says the ledger cannot name who wrote the lines |
 
 **It is a disclosure: no floor, no direction, never a target.** A run that needs four files
 and reads four is not worse than one that reads thirty — and the moment the number becomes