Define data comparison contract v0

TODO.md

@@ -22,6 +22,16 @@ No functional implementation is authorized in Phase 0.
 No implementation or changes to external repositories are authorized by this
 ticket.
 
+## Phase 1B: comparison contract v0
+
+- [x] Define the local experimental query/observation/result contract in
+  [`ticket-004`](project/ticket-004/README.md).
+- [x] Pin and compose the existing `wellmanifest/dsl` reusable profiles.
+- [x] Validate golden conflict/match fixtures and negative invariants.
+
+All writes remain inside `data2dsl`; neighboring repositories are read-only
+contract sources and validation tools.
+
 ## Project communication
 
 - [x] Explain the concrete data2dsl product vision, boundaries, golden case and

project/TICKETS.md

@@ -9,4 +9,5 @@ analysis-generated `project/README.md`.
 | **ticket-001** | [`README.md`](./ticket-001/README.md) | [`preprompt.md`](./ticket-001/preprompt.md) | - |  [`ai-codex.md`](./ticket-001/ai-codex.md) |  [`ai-codex-logs.txt`](./ticket-001/ai-codex-logs.txt) | [`changelog.md`](./ticket-001/changelog.md) |
 | **ticket-002** | [`README.md`](./ticket-002/README.md) | [`preprompt.md`](./ticket-002/preprompt.md) | - |  [`ai-codex.md`](./ticket-002/ai-codex.md) |  [`ai-codex-logs.txt`](./ticket-002/ai-codex-logs.txt) | [`changelog.md`](./ticket-002/changelog.md) |
 | **ticket-003** | [`README.md`](./ticket-003/README.md) | [`preprompt.md`](./ticket-003/preprompt.md) | - |  [`ai-codex.md`](./ticket-003/ai-codex.md) |  [`ai-codex-logs.txt`](./ticket-003/ai-codex-logs.txt) | [`changelog.md`](./ticket-003/changelog.md) |
+| **ticket-004** | [`README.md`](./ticket-004/README.md) | [`preprompt.md`](./ticket-004/preprompt.md) | - |  [`ai-codex.md`](./ticket-004/ai-codex.md) |  [`ai-codex-logs.txt`](./ticket-004/ai-codex-logs.txt) | [`changelog.md`](./ticket-004/changelog.md) |
 <!-- AUTO:TICKET_INDEX:END -->

project/ticket-004/README.md

@@ -0,0 +1,52 @@
+# Ticket 004: Define data comparison contract v0
+
+- **ID**: ticket-004
+- **Owner**: unresolved:human
+- **Status**: IN_PROGRESS
+- **Workflow state**: EDIT
+- **Created**: 2026-08-17
+
+## Goal and scope
+
+Define the smallest local, experimental `data2dsl` comparison contract v0 for
+the golden case: compare a `work-summary.md` claim with GitHub activity for the
+same repository, actor, metric and half-open UTC time window.
+
+The contract must compose the existing `wellmanifest/dsl` query, observation
+and result profiles by immutable reference. It adds only data2dsl-owned domain
+semantics: canonical scalar/set values, evidence locators, comparability,
+outcomes and typed deltas. It remains descriptive and effect-free.
+
+Out of scope: changing `subactor/twin`, `wellmanifest/dsl` or another
+repository; implementing source adapters, GitHub acquisition, an LLM layer or
+an enforcing runtime; adding a runtime dependency; publishing a stable API.
+
+## Acceptance criteria
+
+- [x] AC-01: A closed JSON Schema defines query, observation and comparison
+  result documents for scalar and string-set values.
+- [x] AC-02: The contract pins and maps to the current immutable
+  `wellmanifest/dsl` reusable profiles instead of copying their schema.
+- [x] AC-03: Outcomes cover `MATCH`, `CONFLICT`, `MISSING_LEFT`,
+  `MISSING_RIGHT` and `UNEVALUABLE`, separately from observation state.
+- [x] AC-04: Evidence preserves locator, immutable source revision, media
+  type, SHA-256, extractor identity/version and optional location.
+- [x] AC-05: Golden conflict and match fixtures use identical subject, metric
+  and window keys and pass deterministic validation.
+- [x] AC-06: Invalid cross-key, ordering, digest and outcome/delta combinations
+  are rejected by self-tests.
+- [x] AC-07: The pinned `wellmanifest/dsl` checker accepts the local DSL
+  manifest and the data2dsl governance gate passes.
+
+## Result
+
+The experimental contract lives in `src/data2dsl_contract_v0`. It composes
+the immutable Wellmanifest query, observation and result profiles, defines a
+closed data2dsl comparison bundle, and proves all five outcomes plus five
+negative invariants without accessing a source network or changing another
+repository.
+
+## Participants
+
+- Human participant: unresolved; no user-* file was created by this script.
+- Agent participant: [ai-codex.md](ai-codex.md)

project/ticket-004/ai-codex-logs.txt

@@ -0,0 +1,28 @@
+2026-08-17 contract-v0 evidence log
+
+External contract source (read-only):
+- repository: wellmanifest/dsl
+- revision: 0e088f9efa06a903d1674f42b8ac6afaa0fdf071
+- profile schema blob: 1875866bca7753f885fe81f42af5ebc913fa5294
+- normative profile digest: sha256:85010d33a3a1a5a311ad73591b0676b184f475d2aa5323bd2e32ef6d7aca3bd1
+- reused profiles: query/v1, observation/v1, result/v1
+- external worktree remained unmodified
+
+Implemented component:
+- src/data2dsl_contract_v0/comparison.schema.json
+- src/data2dsl_contract_v0/dsl-manifest.json
+- src/data2dsl_contract_v0/validate.py
+- two work-summary/GitHub golden fixtures
+
+Validation:
+- jsonschema conformance version: 4.26.0 (validation only; no runtime dependency)
+- python src/data2dsl_contract_v0/validate.py --self-test
+  CONTRACT-V0-PASS: 5 positive outcomes, 5 negative invariants
+- pinned dsl_check.py validate: DSL-PASS, 0 errors
+- pinned dsl_check.py standards: DSL-PASS, 0 errors
+- project/governance-check.bat --actor agent: GOV-PASS, 0 errors, 0 warnings
+
+Scope:
+- no subactor/twin, wellmanifest/dsl or other external repository was modified
+- no source adapter, network access, reasoning or enforcing behavior was added
+- contract status remains experimental

project/ticket-004/ai-codex.md

@@ -0,0 +1,44 @@
+---
+participant-id: agent:codex
+participant: codex
+role: agent
+ticket: ticket-004
+---
+# Participant: codex (AI agent)
+
+## Understanding
+
+The user authorized the next planned step while restricting all writes to this
+`data2dsl` repository. Other repositories are read-only evidence and tools.
+The current Wellmanifest DSL already owns reusable query, result and
+observation profiles, so data2dsl must compose them and add only its missing
+comparison semantics.
+
+## Execution plan
+
+1. Pin the current clean `wellmanifest/dsl` revision and reusable profile.
+2. Define a closed experimental JSON contract for the golden case.
+3. Add conflict and match fixtures with complete evidence.
+4. Add deterministic positive and negative conformance checks.
+5. Run the pinned external DSL checker and local governance gate.
+
+## Actual changes
+
+- Initialized the bounded ticket and recorded SESSION_EXECUTION_AUTHORIZATION
+  from the request to execute this work.
+- Confirmed that no external-repository modification is authorized or needed.
+- Pinned `wellmanifest/dsl@0e088f9e` and its reusable profile contract digest;
+  no external schema was copied.
+- Added a closed JSON Schema, effect-free Wellmanifest DSL manifest,
+  dependency-free semantic rules apart from the conformance-only pinned
+  `jsonschema` validator, and golden `MATCH`/`CONFLICT` fixtures.
+- Covered all five comparison outcomes and negative cross-key, digest, delta,
+  missing-evidence and set-canonicalization invariants.
+- Passed the local self-test, both pinned Wellmanifest checker modes and the
+  repository governance gate.
+
+## Blockers
+
+- None inside the recorded intent; proceed without a second confirmation.
+- New authority remains required for destructive action, secret access, new
+  external coordination, material objective expansion and trusted merge.

project/ticket-004/changelog.md

@@ -0,0 +1,12 @@
+# Ticket Changelog (ticket-004)
+
+## [0.1.0] - 2026-08-17
+
+- Initial governance scaffold created.
+- No human participant identity or content was generated.
+- Bounded the ticket to one experimental, effect-free local contract component
+  and immutable reuse of the existing Wellmanifest profiles.
+- Added the closed comparison-bundle schema, Wellmanifest DSL manifest,
+  deterministic conformance validator and two golden fixtures.
+- Proved all comparison outcomes and negative invariants without adding a
+  runtime dependency or changing another repository.

project/ticket-004/intent.json

@@ -0,0 +1,66 @@
+{
+  "schema": "new-project.intent/v3",
+  "ticket": "ticket-004",
+  "summary": "Define data comparison contract v0",
+  "workstream": "application",
+  "classification": {
+    "kind": "FEATURE",
+    "priority": "P2",
+    "origin": "requested"
+  },
+  "delivery": {
+    "acceptedBaseSha": "5ce62ce3e85e4381239e4345110f4a2c5ebfb9c5",
+    "targetBranch": "main",
+    "outcome": "Publish an experimental, deterministic data comparison contract v0 with golden-case fixtures and conformance evidence.",
+    "nonGoals": [
+      "Modify subactor/twin, wellmanifest/dsl, or any repository other than data2dsl.",
+      "Implement acquisition adapters, GitHub access, reasoning, enforcement, or a stable public API."
+    ],
+    "complexity": "S",
+    "estimatedMinutes": 30,
+    "budgets": {
+      "maxImplementationFiles": 5,
+      "maxAffectedComponents": 1,
+      "maxPublicInterfaceChanges": 0,
+      "maxRuntimeDependencies": 0
+    },
+    "architecture": {
+      "status": "accepted",
+      "decision": "Own only a local effect-free comparison profile and compose immutable Wellmanifest profile contracts by reference; do not copy or change external contracts.",
+      "components": [
+        {
+          "name": "comparison-contract-v0",
+          "paths": ["src/data2dsl_contract_v0/**"]
+        }
+      ],
+      "responsibilityChanges": false,
+      "interfaceChanges": [],
+      "dataChanges": [],
+      "ui": {
+        "impact": "none",
+        "states": [],
+        "evidence": []
+      },
+      "rollback": "Remove the experimental contract directory and return Phase 1B to planning; no runtime data migration is required."
+    },
+    "runtimeDependencies": [],
+    "validation": [
+      {
+        "criterion": "AC-05",
+        "commands": ["python src/data2dsl_contract_v0/validate.py --self-test"],
+        "evidence": "Both golden fixtures and embedded negative cases are checked deterministically."
+      },
+      {
+        "criterion": "AC-07",
+        "commands": ["python <pinned-wellmanifest-dsl>/src/dsl_check.py validate src/data2dsl_contract_v0/dsl-manifest.json", "project\\governance-check.bat --actor agent"],
+        "evidence": "The external pinned checker accepts the local manifest and governance remains green."
+      }
+    ]
+  },
+  "allowedPaths": ["project/ticket-004/**", "TODO.md", "project/TICKETS.md", "src/data2dsl_contract_v0/**"],
+  "forbiddenPaths": ["project/ticket-*/user-*.md"],
+  "stacks": [],
+  "dependsOn": ["ticket-002"],
+  "conflictsWith": [],
+  "integrationTicket": null
+}

project/ticket-004/preprompt.md

@@ -0,0 +1,12 @@
+# Ticket preprompt
+
+- **Task ID**: ticket-004
+- **Task title**: Define data comparison contract v0
+- **Created**: 2026-08-17T09:48:41Z
+
+Keep executable implementation outside this governance/evidence directory.
+Read a human-owned user-*.md file only when one exists.
+The request to execute this work creates SESSION_EXECUTION_AUTHORIZATION;
+proceed within the recorded intent without a redundant confirmation prompt.
+Require new authority for destructive action, secrets, external coordination,
+material objective expansion and trusted merge approval.