feat(contract): add work_item_ref shared schema (#1590) (#1593)

Phase 2.1 of Epic #1565 (work-source dispatch). Adds a draft-07 JSON
schema at internal/contract/schemas/shared/work_item_ref.json so future
WorkSourceService, /work board, and dispatch wiring share a validated
shape for forge issues/PRs, scheduled jobs, and manual triggers.

Schema details:
- $id wave://shared/work_item_ref, title WorkItemRef.
- source enum (github, gitea, gitlab, bitbucket, schedule, manual)
  discriminates forge vs non-forge entries.
- Unconditional required: source, url, title, state, created_at.
- forge_host, owner, repo are required only for forge sources via
  allOf if/then; number stays optional even for forge sources because
  some forges expose numberless work items.
- additionalProperties:false for parity with issue_ref / pr_ref.

Also:
- registry_test.go canonical list includes work_item_ref; sorted-floor
  bumped 7 -> 8.
- New work_item_ref_test.go covers six positive fixtures (one per
  source) and five negatives (missing forge_host, unknown source,
  extra property, invalid state, malformed created_at).
- ADR-010 updated: schema count 8 -> 9 and a Schema additions footer
  table.
- docs/scope/onboarding-as-session-plan.md: Phase 2.1 row ticked,
  inline draft snippet replaced with the canonical-shape diff
  (forge -> source, repo string -> forge_host/owner/repo,
  kind/id -> number + state).

.agents/contracts/ deliberately not mirrored: that registry holds
step-output contracts validated by sync_test.go, not pipeline-I/O
typed schemas (different system).

Author: nextlevelshit

docs/adr/010-pipeline-io-protocol.md

@@ -9,7 +9,7 @@ Accepted (Phase 1 — load-time validation live; pipeline migration ongoing)
 ## Implementation Status
 
 Landed:
-- Eight canonical schemas in `internal/contract/schemas/shared/*.json` (`issue_ref`, `pr_ref`, `scope_result`, `plan_ref`, `findings_report`, `workspace_ref`, `spec_ref`, `branch_ref`).
+- Nine canonical schemas in `internal/contract/schemas/shared/*.json` (`issue_ref`, `pr_ref`, `scope_result`, `plan_ref`, `findings_report`, `workspace_ref`, `spec_ref`, `branch_ref`, `work_item_ref`).
 - Registry: `internal/contract/schemas/registry.go` (+ test).
 - Typed I/O fields: `InputConfig.Type` (`internal/pipeline/types.go:138`) and `PipelineOutput.Type` (`types.go:725`); both expose `EffectiveType()` defaulting to `"string"`.
 - Load-time validation: `ValidatePipelineIOTypes` and `TypedWiringCheck` in `internal/pipeline/iotypes.go` (~216 LOC), wired into the loader at `dag.go:42` and `dag.go:52`.
@@ -63,7 +63,7 @@ Introduce a **typed I/O protocol** with four pieces:
    `internal/contract/schemas/shared/*.json`, embedded into the Wave
    binary via `go:embed`. Each file's basename is the type name
    (`issue_ref`, `pr_ref`, `branch_ref`, `spec_ref`, `findings_report`,
-   `plan_ref`, `workspace_ref`, `scope_result`). A pipeline's type
+   `plan_ref`, `workspace_ref`, `scope_result`, `work_item_ref`). A pipeline's type
    annotation must resolve against this registry or the sentinel
    `string`.
 
@@ -193,7 +193,7 @@ on input/output, load-time validation.
 ## Implementation Notes
 
 Files created:
-- `internal/contract/schemas/shared/*.json` (8 canonical schemas)
+- `internal/contract/schemas/shared/*.json` (9 canonical schemas)
 - `internal/contract/schemas/shared/registry.go` (+ test)
 - `internal/pipeline/iotypes.go` (+ test)
 - `docs/adr/010-pipeline-io-protocol.md` (this file)
@@ -255,3 +255,9 @@ by design — they exercise specific executor paths and need free shape.
   decide whether to wire shared types into the runtime contract path.
 - No deep `field`-extraction on `pipeline_outputs` with type
   narrowing. The existing `field:` hint stays as-is.
+
+## Schema additions
+
+| Date | Type | Issue / PR | Notes |
+|---|---|---|---|
+| 2026-04-30 | `work_item_ref` | #1590 (Epic #1565 Phase 2.1) | Canonical work-source dispatch shape; `source` enum (`github`, `gitea`, `gitlab`, `bitbucket`, `schedule`, `manual`) discriminates forge vs non-forge entries. Forge sources require `forge_host`, `owner`, `repo` via `if/then`; `number` stays optional even for forge sources to accommodate numberless work items. Not mirrored to `.agents/contracts/` — that registry holds step-output contracts, not shared pipeline-I/O types. |

docs/scope/onboarding-as-session-plan.md

@@ -389,20 +389,12 @@ See PRE-5. Five new tables; ~10 new `StateStore` methods. Zero existing column c
 
 New canonical schema (per ADR-010): `internal/contract/schemas/shared/work_item_ref.json` — generalizes `issue_ref` / `pr_ref` for forge-agnostic work items.
 
-```json
-{
-  "type": "object",
-  "required": ["forge", "repo", "kind", "id"],
-  "properties": {
-    "forge": { "enum": ["github", "gitea", "gitlab", "bitbucket"] },
-    "repo": { "type": "string" },        // owner/name
-    "kind": { "enum": ["issue", "pr", "task"] },
-    "id": { "type": "string" },
-    "title": { "type": "string" },
-    "url": { "type": "string", "format": "uri" }
-  }
-}
-```
+The shipped shape is canonicalized in [`internal/contract/schemas/shared/work_item_ref.json`](../../internal/contract/schemas/shared/work_item_ref.json). It diverged from the earlier draft below:
+
+- `source` (not `forge`) discriminates entries — enum extended with `schedule` and `manual` so non-forge work items fit cleanly.
+- `forge_host`, `owner`, `repo` replace the combined `repo: "owner/name"` string and are conditionally required (`if/then` on `source`) only for forge entries.
+- `number` (integer) supersedes the polymorphic `id` and `kind` fields. Issue-vs-PR distinction lives in the `state` enum (`open | closed | merged`) and the URL itself, not a separate type tag.
+- `state` and `created_at` are required; `labels` is an optional array of strings.
 
 ---
 
@@ -432,7 +424,7 @@ New canonical schema (per ADR-010): `internal/contract/schemas/shared/work_item_
 
 | # | Title | Files |
 |---|---|---|
-| 2.1 | `work_item_ref` shared schema | `internal/contract/schemas/shared/work_item_ref.json` + registry |
+| 2.1 ✅ | `work_item_ref` shared schema | `internal/contract/schemas/shared/work_item_ref.json` + registry |
 | 2.2 | WorkSourceService + bindings | `internal/service/worksource.go`, `internal/worksource/`, table CRUD |
 | 2.3 | Webui `/work` board + detail | new templates, handlers; replaces dashboard as default landing |
 | 2.4 | "Run on this issue" button | binding lookup → `ExecutorService.Run` |

internal/contract/schemas/shared/registry_test.go

@@ -14,6 +14,7 @@ func TestRegistryContainsCanonicalTypes(t *testing.T) {
 		"findings_report",
 		"plan_ref",
 		"workspace_ref",
+		"work_item_ref",
 	}
 	for _, name := range expected {
 		data, ok := Lookup(name)
@@ -63,8 +64,8 @@ func TestUnknownType(t *testing.T) {
 
 func TestNamesSorted(t *testing.T) {
 	names := Names()
-	if len(names) < 7 {
-		t.Errorf("Names() returned %d entries, want at least 7", len(names))
+	if len(names) < 8 {
+		t.Errorf("Names() returned %d entries, want at least 8", len(names))
 	}
 	for i := 1; i < len(names); i++ {
 		if names[i-1] >= names[i] {

internal/contract/schemas/shared/work_item_ref.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "wave://shared/work_item_ref",
+  "title": "WorkItemRef",
+  "description": "Canonical reference to a unit of work emitted by a work-source (forge issue/PR, scheduled job, manual trigger) and consumed by pipelines. Forge-specific fields (forge_host, owner, repo, number) are required only when source identifies a git forge; schedule/manual sources omit them.",
+  "type": "object",
+  "required": ["source", "url", "title", "state", "created_at"],
+  "properties": {
+    "source": {
+      "type": "string",
+      "enum": ["github", "gitea", "gitlab", "bitbucket", "schedule", "manual"],
+      "description": "Origin of the work item. Forge values (github, gitea, gitlab, bitbucket) imply forge_host, owner, repo are required."
+    },
+    "forge_host": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Hostname of the forge instance (e.g. github.com, codeberg.org, gitlab.example.com). Required for forge sources."
+    },
+    "owner": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Owner (user or organization). Required for forge sources."
+    },
+    "repo": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Repository name. Required for forge sources."
+    },
+    "number": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Issue or PR number. Optional even for forge sources because some forges expose numberless work items (e.g. Gitea task lists)."
+    },
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Canonical URL identifying the work item. Used as the primary key in the worksource_binding table."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable title of the work item."
+    },
+    "labels": {
+      "type": "array",
+      "description": "Labels or tags attached to the work item. May be empty; absent for sources that have no label concept.",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "state": {
+      "type": "string",
+      "enum": ["open", "closed", "merged"],
+      "description": "Lifecycle state. 'merged' applies only to PR-like work items; consumers may filter per source."
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "RFC 3339 timestamp marking when the work item was created."
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "source": {
+            "enum": ["github", "gitea", "gitlab", "bitbucket"]
+          }
+        },
+        "required": ["source"]
+      },
+      "then": {
+        "required": ["forge_host", "owner", "repo"]
+      }
+    }
+  ],
+  "additionalProperties": false
+}