task-pipeline-skill 1.85.2 → 1.86.3

package/plugins/task-pipeline/skills/task-pipeline/execution-packet.schema.json

@@ -0,0 +1,217 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/ssheleg/task-pipeline/main/plugins/task-pipeline/skills/task-pipeline/execution-packet.schema.json",
+  "title": "task-pipeline execution packet",
+  "description": "The family's versioned task/context contract (CTX-01). One packet is one dispatchable unit of work: what to do, under which module decisions, reading which inputs, inside which budget. Packets are IMMUTABLE once issued — a change is a new packet with a new id, never an edit. What ships is this schema, one example, and `scripts/packet.py`, the dependency-free validator every consumer runs before acting: a packet whose mandatory version major is unknown, whose input lacks a digest, or whose decision ref is unbound must be rejected at the door, because acting on a packet you could not verify is how two agents build different things from one plan.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "id",
+    "module",
+    "intent",
+    "inputs",
+    "decision_refs",
+    "source_scope",
+    "budgets"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "pattern": "^execution-packet/[0-9]+$",
+      "description": "Contract version, `execution-packet/<major>`. A consumer that does not know the major REJECTS the packet — an unknown mandatory version is not a warning."
+    },
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable packet id. Immutable: revising the work issues a new id."
+    },
+    "parent_id": {
+      "type": "string",
+      "description": "The parent outcome or plan node this packet serves, when one exists."
+    },
+    "module": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The owning module/repository the packet's edits belong to."
+    },
+    "intent": {
+      "type": "string",
+      "minLength": 1,
+      "description": "One sentence of what this packet changes and why — the contract, not the diff."
+    },
+    "inputs": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/contextRef"
+      },
+      "description": "Every context document the work READS. Each is content-addressed: an input without a digest cannot be verified fresh, so it does not dispatch."
+    },
+    "decision_refs": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/decisionRef"
+      },
+      "description": "The module decisions this packet is bound by. BOUND means address+digest present — a decision named without its bytes is a rumour, and the packet is rejected."
+    },
+    "source_scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "edit_targets"
+      ],
+      "properties": {
+        "edit_targets": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/editTarget"
+          },
+          "description": "The exact files the packet may change. A baseline digest per Edit target is what makes 'the source moved under the plan' detectable before dispatch."
+        },
+        "claim": {
+          "type": "string",
+          "description": "The coordination scope to claim before editing, where the project has agent-sync on."
+        }
+      }
+    },
+    "budgets": {
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "context_bytes": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "token_note": {
+          "type": "string",
+          "description": "How tokens were measured or estimated — a named tokenizer or the estimate's basis. A bare token count nothing computed is not a budget."
+        }
+      },
+      "description": "At least one bound. Budgets cut appendix material, never the packet's decisions or acceptance."
+    },
+    "acceptance": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "Observable acceptance cases. Never truncated to fit a budget."
+    },
+    "dependencies": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "task_id",
+          "kind",
+          "rationale"
+        ],
+        "properties": {
+          "task_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "data",
+              "control",
+              "resource"
+            ],
+            "description": "data: this packet consumes the other's output; control: ordering only — no payload, and the edge is PRESERVED, never pruned for being payload-less; resource: both touch one thing that tolerates one writer."
+          },
+          "rationale": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Why the edge exists — an edge nobody can explain is an edge nobody dares remove or trust."
+          },
+          "satisfaction": {
+            "type": "string",
+            "description": "What marks it satisfied: an artifact address, a state, a receipt. A control edge may leave this empty — ordering is its whole payload."
+          },
+          "owner": {
+            "type": "string"
+          }
+        }
+      },
+      "description": "Typed edges into the plan's graph. Uniqueness of packet ids, resolution of every task_id and acyclicity are properties of the packet SET — `scripts/packet.py validate-graph` owns them."
+    }
+  },
+  "definitions": {
+    "contextRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "address",
+        "sha256"
+      ],
+      "properties": {
+        "address": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Where the bytes live: a repo-relative path or a portable `scheme://` address."
+        },
+        "sha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "Digest of the exact bytes the plan was made against. Freshness is checked against this before dispatch; a mismatch blocks, it never silently becomes permission to use stale context."
+        },
+        "role": {
+          "type": "string"
+        }
+      }
+    },
+    "decisionRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "address",
+        "sha256"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "address": {
+          "type": "string",
+          "minLength": 1
+        },
+        "sha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        }
+      }
+    },
+    "editTarget": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "address",
+        "mode"
+      ],
+      "properties": {
+        "address": {
+          "type": "string",
+          "minLength": 1
+        },
+        "mode": {
+          "type": "string",
+          "enum": [
+            "Edit",
+            "Create",
+            "Create_or_extend"
+          ]
+        },
+        "baseline_sha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "Required when mode is Edit: the bytes the plan reviewed. Creates have no baseline."
+        }
+      }
+    }
+  }
+}

package/plugins/task-pipeline/skills/task-pipeline/execution-result.example.json

@@ -0,0 +1,49 @@
+{
+  "schema_version": "execution-result/1",
+  "packet_id": "FIX-EX-01.01",
+  "grant": {
+    "grant_id": "g-000042",
+    "packet_id": "FIX-EX-01.01",
+    "revision": 7,
+    "fence": 12,
+    "holder": "r-7f3a91",
+    "issued_at": "2026-09-08T21:14:00Z"
+  },
+  "built_against_revision": 7,
+  "candidate": {
+    "commit": "aabec96",
+    "changed": [
+      {
+        "address": "plugins/example/skills/example/SKILL.md",
+        "sha256": "a0dcc36937f50a8da38261c1c39afe6caeb0f31674cdf3baaac48c4c81defe32"
+      }
+    ]
+  },
+  "checks": [
+    {
+      "name": "focused regression",
+      "command": "python3 test/audit_regressions/fix-ex-01.01.py",
+      "status": "PASS",
+      "observed": "7/7 cases"
+    },
+    {
+      "name": "browser smoke",
+      "command": "npx playwright test smoke",
+      "status": "NOT_RUN",
+      "observed": "no browser on this host — needs playwright installed"
+    }
+  ],
+  "evidence": [
+    {
+      "class": "fact",
+      "statement": "the crash fixture reproduces the loss before the fix and passes after",
+      "source": "test output, this run"
+    },
+    {
+      "class": "unknown_effect",
+      "statement": "behaviour under the provider's real rate limits was not observed",
+      "source": "no live account in this environment"
+    }
+  ],
+  "status": "completed"
+}

package/plugins/task-pipeline/skills/task-pipeline/execution-result.schema.json

@@ -0,0 +1,261 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/ssheleg/task-pipeline/main/plugins/task-pipeline/skills/task-pipeline/execution-result.schema.json",
+  "title": "task-pipeline execution result",
+  "description": "The answer half of the family's task contract (CTX-01, beside execution-packet.schema.json). An attempt starts with an AttemptGrant — a structured object from the single authority, carrying the graph revision it was issued at and the fence that supersedes it; a bare boolean is NOT a grant, because `true` cannot say who granted what, against which revision, or whether it has since been superseded. The attempt answers with this envelope: the candidate change (content-addressed), every check actually run with its honest status (NOT_RUN is never PASS), and the evidence rows in the fact/defect/unknown-effect union. A candidate built against an older revision than the current one is STALE and cannot validate as current — it goes back through re-planning, never quietly forward. `scripts/packet.py validate-result` is the dependency-free runtime half.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "packet_id",
+    "grant",
+    "built_against_revision",
+    "candidate",
+    "checks",
+    "evidence",
+    "status"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "pattern": "^execution-result/[0-9]+$",
+      "description": "Contract version. An unknown major is rejected, never skimmed — same rule as the packet."
+    },
+    "packet_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "grant": {
+      "$ref": "#/definitions/attemptGrant"
+    },
+    "built_against_revision": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "The graph revision the candidate was built against. Compared to the CURRENT revision at validation: older means stale, and stale means re-plan."
+    },
+    "candidate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "changed"
+      ],
+      "properties": {
+        "commit": {
+          "type": "string",
+          "description": "The candidate commit, where one exists."
+        },
+        "changed": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "address",
+              "sha256"
+            ],
+            "properties": {
+              "address": {
+                "type": "string",
+                "minLength": 1
+              },
+              "sha256": {
+                "type": "string",
+                "pattern": "^[0-9a-f]{64}$"
+              }
+            }
+          },
+          "description": "Every path the candidate changed, content-addressed — the receipt a reviewer can verify against the tree."
+        }
+      }
+    },
+    "checks": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/check"
+      },
+      "description": "Every check actually run — and the ones that could not run, as NOT_RUN with what it would take. An empty list is a result nobody verified, which the consumer may refuse."
+    },
+    "evidence": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/evidenceRow"
+      },
+      "description": "Observations in the union evidence-docs and project-audit share: a FACT (observed, with its receipt), a DEFECT (observed wrong), or an UNKNOWN_EFFECT (could not be established) — three different verdicts that never blend."
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "completed",
+        "partial",
+        "blocked",
+        "abandoned"
+      ],
+      "description": "The attempt's own verdict about itself. `completed` with failing checks is a contradiction the validator refuses."
+    },
+    "outputs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "name",
+          "kind",
+          "address",
+          "sha256"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "description": "What the output IS to a consumer. Never a credential — a name that reads as one (token, secret, password, api_key, credential, cookie, private_key) is refused by the validator: a result outlives its session exactly like the packet (FIX-PF-05.03)."
+          },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "artifact",
+              "report",
+              "decision",
+              "metric"
+            ]
+          },
+          "address": {
+            "type": "string",
+            "minLength": 1
+          },
+          "sha256": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          }
+        }
+      },
+      "description": "TYPED outputs the attempt produced, content-addressed. A consumer binds to a named output's digest — which is what makes a changed predecessor output DETECTABLE downstream (see `consumed`)."
+    },
+    "packet_digest": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$",
+      "description": "sha256 of the immutable dispatch packet this attempt ran from (FIX-PF-05.01). Ties the answer to the exact question; a result naming a packet digest the coordinator does not recognise is a result about different work."
+    },
+    "consumed": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "name",
+          "sha256"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1
+          },
+          "producer": {
+            "type": "string"
+          },
+          "sha256": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          }
+        }
+      },
+      "description": "The predecessor outputs this attempt READ, by name + digest. Freshness is a comparison, not a feeling: when a predecessor re-runs and its output digest changes, every result that consumed the old digest is STALE and the node rebuilds at a new revision."
+    }
+  },
+  "definitions": {
+    "attemptGrant": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "grant_id",
+        "packet_id",
+        "revision",
+        "fence",
+        "holder"
+      ],
+      "description": "What the single authority issued. A boolean confirmation is not a grant: it names no issuer, no revision, no fence — nothing a later reader could check.",
+      "properties": {
+        "grant_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "packet_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "revision": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "fence": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Monotonic token from the authority. A newer fence supersedes this grant: a result carrying an old fence lost its exclusivity mid-flight and must not land as current."
+        },
+        "holder": {
+          "type": "string",
+          "minLength": 1
+        },
+        "issued_at": {
+          "type": "string"
+        }
+      }
+    },
+    "check": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "command",
+        "status"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "command": {
+          "type": "string",
+          "minLength": 1
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "PASS",
+            "FAIL",
+            "ERROR",
+            "NOT_RUN"
+          ],
+          "description": "NOT_RUN and ERROR are their own statuses — never upgraded to PASS, never folded into FAIL."
+        },
+        "observed": {
+          "type": "string"
+        }
+      }
+    },
+    "evidenceRow": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "class",
+        "statement"
+      ],
+      "properties": {
+        "class": {
+          "type": "string",
+          "enum": [
+            "fact",
+            "defect",
+            "unknown_effect"
+          ]
+        },
+        "statement": {
+          "type": "string",
+          "minLength": 1
+        },
+        "source": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/plugins/task-pipeline/skills/task-pipeline/graph.example.json

@@ -29,7 +29,16 @@
       ],
       "serves": "REQ-002",
       "check": "python3 test/graph_test.py — the validate fixtures",
-      "evidence": null
+      "evidence": null,
+      "claim": {
+        "owner": "sess-7f3a:attempt-1",
+        "attempt": 1,
+        "revision": 4,
+        "fence": 12,
+        "expiry": "2026-08-14T18:30:00Z",
+        "state": "claimed",
+        "installed_at": "2026-08-14T18:00:00Z"
+      }
     },
     {
       "id": "N-003",