From 201708c82da161bf1f514da015ec95b2964b8347 Mon Sep 17 00:00:00 2001 From: Mateusz Lewandowski Date: Thu, 13 Aug 2026 12:44:58 +0200 Subject: [PATCH 1/4] chore: close Phase 0 ticket --- project/ticket-001/README.md | 7 +++++-- project/ticket-001/ai-codex-logs.txt | 10 ++++++++++ project/ticket-001/changelog.md | 1 + 3 files changed, 16 insertions(+), 2 deletions(-) diff --git a/project/ticket-001/README.md b/project/ticket-001/README.md index 4780bce..aedb534 100644 --- a/project/ticket-001/README.md +++ b/project/ticket-001/README.md @@ -2,8 +2,8 @@ - **ID**: ticket-001 - **Owner**: unresolved:human -- **Status**: IN_PROGRESS -- **Workflow state**: EDIT +- **Status**: DONE +- **Workflow state**: DONE - **Created**: 2026-08-13 ## Goal and scope @@ -32,6 +32,9 @@ GitHub clients, runtime dependencies, and golden-case implementation. All Phase 0 acceptance criteria pass. The user explicitly authorized creation and publication of the public `semcod/data2dsl` GitHub repository on 2026-08-13. No product code, final DSL, extraction or refactor was introduced. +The published default branch contains the exact Phase 0 result at commit +`067b76b67802b17084c1209a5e96121dec5b8a2f`; this governance-only update closes +the completed ticket. ## Participants diff --git a/project/ticket-001/ai-codex-logs.txt b/project/ticket-001/ai-codex-logs.txt index 3e7f904..dff6a95 100644 --- a/project/ticket-001/ai-codex-logs.txt +++ b/project/ticket-001/ai-codex-logs.txt @@ -59,3 +59,13 @@ current Phase 0 results; do not implement or modify other repositories. $ gh repo create semcod/data2dsl --public --source . --remote origin https://github.com/semcod/data2dsl + +$ git push -u origin main +main -> origin/main + +Publication verification: +visibility=PUBLIC +defaultBranch=main +local=067b76b67802b17084c1209a5e96121dec5b8a2f +remote=067b76b67802b17084c1209a5e96121dec5b8a2f +governance=GOV-PASS (0 errors, 0 warnings) diff --git a/project/ticket-001/changelog.md b/project/ticket-001/changelog.md index 1205f4e..b82012d 100644 --- a/project/ticket-001/changelog.md +++ b/project/ticket-001/changelog.md @@ -12,3 +12,4 @@ and container run. - Received explicit external-coordination authority and created the public `semcod/data2dsl` GitHub repository for Phase 0 publication. +- Closed the completed Phase 0 ticket from the integrated default branch. From c28a991efa40b1fc2183b909ade19f5e92b4c4fe Mon Sep 17 00:00:00 2001 From: Mateusz Lewandowski Date: Thu, 13 Aug 2026 12:47:23 +0200 Subject: [PATCH 2/4] chore: allocate twin compatibility decision --- TODO.md | 9 ++++ project/TICKETS.md | 1 + project/ticket-002/README.md | 36 ++++++++++++++ project/ticket-002/ai-codex-logs.txt | 0 project/ticket-002/ai-codex.md | 36 ++++++++++++++ project/ticket-002/changelog.md | 7 +++ project/ticket-002/intent.json | 71 ++++++++++++++++++++++++++++ project/ticket-002/preprompt.md | 12 +++++ 8 files changed, 172 insertions(+) create mode 100644 project/ticket-002/README.md create mode 100644 project/ticket-002/ai-codex-logs.txt create mode 100644 project/ticket-002/ai-codex.md create mode 100644 project/ticket-002/changelog.md create mode 100644 project/ticket-002/intent.json create mode 100644 project/ticket-002/preprompt.md diff --git a/TODO.md b/TODO.md index c020a23..e3e57fb 100644 --- a/TODO.md +++ b/TODO.md @@ -12,3 +12,12 @@ authority and repository visibility were supplied. No functional implementation is authorized in Phase 0. + +## Phase 1A: contract decision + +- [ ] Decide compatibility of `subactor/twin` `Observation` and `EvidenceRef` + for `data2dsl` in [`ticket-002`](project/ticket-002/README.md). +- [ ] Publish the pinned evidence and consequences as a decision document. + +No implementation or changes to external repositories are authorized by this +ticket. diff --git a/project/TICKETS.md b/project/TICKETS.md index 9426342..9eec937 100644 --- a/project/TICKETS.md +++ b/project/TICKETS.md @@ -7,4 +7,5 @@ analysis-generated `project/README.md`. | Ticket ID | Spec | Preprompt | Human input | Agent plans | Agent logs | Changelog | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **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) | diff --git a/project/ticket-002/README.md b/project/ticket-002/README.md new file mode 100644 index 0000000..b5abcdb --- /dev/null +++ b/project/ticket-002/README.md @@ -0,0 +1,36 @@ +# Ticket 002: Twin observation compatibility decision + +- **ID**: ticket-002 +- **Owner**: unresolved:human +- **Status**: IN_PROGRESS +- **Workflow state**: EDIT +- **Created**: 2026-08-13 + +## Goal and scope + +Produce one evidence-backed compatibility decision for using the current +`subactor/twin` `Observation` and `EvidenceRef` contracts in `data2dsl`. +Inspect the pinned code, protobuf schema, normative standard, reference profile +and tests. The result must select exactly one verdict: `REUSE AS-IS`, `EXTEND` +or `REJECT`, and state the consequences for `data2dsl`. + +Out of scope: product implementation, final data-query DSL, edits to +`subactor/twin`, `wellmanifest/dsl` or any other repository, dependency +changes, and external coordination. + +## Acceptance criteria + +- [ ] AC-01: The decision pins the inspected `subactor/twin` revision. +- [ ] AC-02: Evidence covers protobuf, normative contract, validator code, + reference profile and relevant tests. +- [ ] AC-03: Field-level fit and gaps for both `Observation` and `EvidenceRef` + are explicit. +- [ ] AC-04: Exactly one verdict among `REUSE AS-IS`, `EXTEND`, and `REJECT` is + selected with rationale. +- [ ] AC-05: Consequences and prohibited assumptions for `data2dsl` are stated. +- [ ] AC-06: No other repository is modified and the governance gate passes. + +## Participants + +- Human participant: unresolved; no user-* file was created by this script. +- Agent participant: [ai-codex.md](ai-codex.md) diff --git a/project/ticket-002/ai-codex-logs.txt b/project/ticket-002/ai-codex-logs.txt new file mode 100644 index 0000000..e69de29 diff --git a/project/ticket-002/ai-codex.md b/project/ticket-002/ai-codex.md new file mode 100644 index 0000000..9c02977 --- /dev/null +++ b/project/ticket-002/ai-codex.md @@ -0,0 +1,36 @@ +--- +participant-id: agent:codex +participant: codex +role: agent +ticket: ticket-002 +--- +# Participant: codex (AI agent) + +## Understanding + +The user authorized only a compatibility decision. The target is the current +`subactor/twin` contract at an immutable revision, not a proposal disguised as +implemented behavior. The decision must distinguish structural protobuf fit +from the stronger semantics actually enforced by the validator and tests. + +## Execution plan + +1. Pin the current clean `subactor/twin` revision. +2. Inspect `Observation` and `EvidenceRef` in the protobuf contract. +3. Trace their normative invariants through the standard, reference profile, + validator implementation and tests. +4. Map the implemented contract to data2dsl requirements and select exactly + one verdict. +5. Publish one decision document and run governance validation. + +## Actual changes + +- Initialized the bounded ticket and recorded SESSION_EXECUTION_AUTHORIZATION + from the request to execute this work. +- No product or external-repository changes are authorized. + +## 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. diff --git a/project/ticket-002/changelog.md b/project/ticket-002/changelog.md new file mode 100644 index 0000000..76c4f29 --- /dev/null +++ b/project/ticket-002/changelog.md @@ -0,0 +1,7 @@ +# Ticket Changelog (ticket-002) + +## [0.1.0] - 2026-08-13 + +- Initial governance scaffold created. +- No human participant identity or content was generated. +- Recorded the bounded compatibility-decision scope and explicit non-goals. diff --git a/project/ticket-002/intent.json b/project/ticket-002/intent.json new file mode 100644 index 0000000..919f9bb --- /dev/null +++ b/project/ticket-002/intent.json @@ -0,0 +1,71 @@ +{ + "schema": "new-project.intent/v3", + "ticket": "ticket-002", + "summary": "Twin observation compatibility decision", + "workstream": "integration", + "classification": { + "kind": "SERVICE", + "priority": "P2", + "origin": "health" + }, + "delivery": { + "acceptedBaseSha": "201708c82da161bf1f514da015ec95b2964b8347", + "targetBranch": "main", + "outcome": "Publish one pinned, evidence-backed compatibility decision for subactor/twin Observation and EvidenceRef.", + "nonGoals": [ + "Modify subactor/twin, wellmanifest/dsl, or any repository other than data2dsl.", + "Implement product behavior, a final DSL, an adapter, or a schema." + ], + "complexity": "S", + "estimatedMinutes": 30, + "budgets": { + "maxImplementationFiles": 1, + "maxAffectedComponents": 1, + "maxPublicInterfaceChanges": 0, + "maxRuntimeDependencies": 0 + }, + "architecture": { + "status": "accepted", + "decision": "Record the compatibility verdict in one decision document; do not create or modify a product contract.", + "components": [ + { + "name": "compatibility-decision", + "paths": ["docs/decisions/ADR-001-twin-observation-evidence-compatibility.md"] + } + ], + "responsibilityChanges": false, + "interfaceChanges": [], + "dataChanges": [], + "ui": { + "impact": "none", + "states": [], + "evidence": [] + }, + "rollback": "Remove the decision document and return the capability to CANDIDATE pending new evidence." + }, + "runtimeDependencies": [], + "validation": [ + { + "criterion": "AC-02", + "commands": ["rg -n 'proto|standard|validator|profile|test' docs/decisions/ADR-001-twin-observation-evidence-compatibility.md"], + "evidence": "The decision cites every required evidence class." + }, + { + "criterion": "AC-04", + "commands": ["rg -n '^## Verdict|^EXTEND$' docs/decisions/ADR-001-twin-observation-evidence-compatibility.md"], + "evidence": "The document contains one explicit verdict." + }, + { + "criterion": "AC-06", + "commands": ["project\\governance-check.bat --actor agent"], + "evidence": "The deterministic governance gate records the result." + } + ] + }, + "allowedPaths": ["project/ticket-002/**", "TODO.md", "project/TICKETS.md", "docs/decisions/ADR-001-twin-observation-evidence-compatibility.md"], + "forbiddenPaths": ["project/ticket-*/user-*.md"], + "stacks": [], + "dependsOn": [], + "conflictsWith": [], + "integrationTicket": null +} diff --git a/project/ticket-002/preprompt.md b/project/ticket-002/preprompt.md new file mode 100644 index 0000000..14b0eb2 --- /dev/null +++ b/project/ticket-002/preprompt.md @@ -0,0 +1,12 @@ +# Ticket preprompt + +- **Task ID**: ticket-002 +- **Task title**: Twin observation compatibility decision +- **Created**: 2026-08-13T10:45:35Z + +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. From 22ee4b817b7f59b7df0f8dfdbf2d80f8185cbf52 Mon Sep 17 00:00:00 2001 From: Mateusz Lewandowski Date: Thu, 13 Aug 2026 12:57:48 +0200 Subject: [PATCH 3/4] chore: allocate project overview ticket --- TODO.md | 5 ++++ project/TICKETS.md | 1 + project/ticket-003/README.md | 33 +++++++++++++++++++++++++++ project/ticket-003/ai-codex-logs.txt | 0 project/ticket-003/ai-codex.md | 34 ++++++++++++++++++++++++++++ project/ticket-003/changelog.md | 7 ++++++ project/ticket-003/intent.json | 17 ++++++++++++++ project/ticket-003/preprompt.md | 12 ++++++++++ 8 files changed, 109 insertions(+) create mode 100644 project/ticket-003/README.md create mode 100644 project/ticket-003/ai-codex-logs.txt create mode 100644 project/ticket-003/ai-codex.md create mode 100644 project/ticket-003/changelog.md create mode 100644 project/ticket-003/intent.json create mode 100644 project/ticket-003/preprompt.md diff --git a/TODO.md b/TODO.md index e3e57fb..fa6323c 100644 --- a/TODO.md +++ b/TODO.md @@ -21,3 +21,8 @@ No functional implementation is authorized in Phase 0. No implementation or changes to external repositories are authorized by this ticket. + +## Project communication + +- [ ] Explain the concrete data2dsl product vision, boundaries, golden case and + roadmap in the root README under [`ticket-003`](project/ticket-003/README.md). diff --git a/project/TICKETS.md b/project/TICKETS.md index 9eec937..e1258ea 100644 --- a/project/TICKETS.md +++ b/project/TICKETS.md @@ -8,4 +8,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) | diff --git a/project/ticket-003/README.md b/project/ticket-003/README.md new file mode 100644 index 0000000..ae53745 --- /dev/null +++ b/project/ticket-003/README.md @@ -0,0 +1,33 @@ +# Ticket 003: Explain the data2dsl project + +- **ID**: ticket-003 +- **Owner**: unresolved:human +- **Status**: IN_PROGRESS +- **Workflow state**: EDIT +- **Created**: 2026-08-13 + +## Goal and scope + +Rewrite the root README so a new contributor can understand the concrete +problem, users, inputs, outputs, golden case, product boundary, reuse-first +composition and staged roadmap without reconstructing the vision from Phase 0 +evidence documents. + +Out of scope: product implementation, final schemas or APIs, dependency +changes, edits outside data2dsl, and changes to technical decisions already +recorded in evidence documents. + +## Acceptance criteria + +- [ ] AC-01: README explains the problem and intended users. +- [ ] AC-02: README defines inputs, outputs and the golden case concretely. +- [ ] AC-03: README distinguishes responsibilities and non-goals. +- [ ] AC-04: README presents the reuse-first composition and staged roadmap. +- [ ] AC-05: Claims remain consistent with the capability map and no product + implementation is introduced. +- [ ] AC-06: Governance passes and no other repository is modified. + +## Participants + +- Human participant: unresolved; no user-* file was created by this script. +- Agent participant: [ai-codex.md](ai-codex.md) diff --git a/project/ticket-003/ai-codex-logs.txt b/project/ticket-003/ai-codex-logs.txt new file mode 100644 index 0000000..e69de29 diff --git a/project/ticket-003/ai-codex.md b/project/ticket-003/ai-codex.md new file mode 100644 index 0000000..87c5294 --- /dev/null +++ b/project/ticket-003/ai-codex.md @@ -0,0 +1,34 @@ +--- +participant-id: agent:codex +participant: codex +role: agent +ticket: ticket-003 +--- +# Participant: codex (AI agent) + +## Understanding + +The current README states the architectural invariant and Phase 0 outcome but +does not give new contributors a concrete product model. The user explicitly +authorized adding that missing explanation. The README must describe planned +behavior without presenting unimplemented contracts as available features. + +## Execution plan + +1. Audit existing project descriptions and identify missing onboarding facts. +2. Rewrite README around problem, users, input/output, golden case, boundaries, + reuse composition and roadmap. +3. Cross-check every claim against `docs/CAPABILITY_MAP.md`. +4. Run deterministic governance validation. + +## Actual changes + +- Initialized the bounded ticket and recorded SESSION_EXECUTION_AUTHORIZATION + from the request to execute this work. +- No executable implementation or external-repository change is authorized. + +## 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. diff --git a/project/ticket-003/changelog.md b/project/ticket-003/changelog.md new file mode 100644 index 0000000..ab56167 --- /dev/null +++ b/project/ticket-003/changelog.md @@ -0,0 +1,7 @@ +# Ticket Changelog (ticket-003) + +## [0.1.0] - 2026-08-13 + +- Initial governance scaffold created. +- No human participant identity or content was generated. +- Recorded the bounded README and contributor-onboarding scope. diff --git a/project/ticket-003/intent.json b/project/ticket-003/intent.json new file mode 100644 index 0000000..0008dd6 --- /dev/null +++ b/project/ticket-003/intent.json @@ -0,0 +1,17 @@ +{ + "schema": "new-project.intent/v3", + "ticket": "ticket-003", + "summary": "Explain the data2dsl project", + "workstream": "governance", + "classification": { + "kind": "SERVICE", + "priority": "P2", + "origin": "health" + }, + "allowedPaths": ["project/ticket-003/**", "README.md", "TODO.md", "project/TICKETS.md"], + "forbiddenPaths": ["project/ticket-*/user-*.md"], + "stacks": [], + "dependsOn": [], + "conflictsWith": [], + "integrationTicket": null +} diff --git a/project/ticket-003/preprompt.md b/project/ticket-003/preprompt.md new file mode 100644 index 0000000..0ad5714 --- /dev/null +++ b/project/ticket-003/preprompt.md @@ -0,0 +1,12 @@ +# Ticket preprompt + +- **Task ID**: ticket-003 +- **Task title**: Explain the data2dsl project +- **Created**: 2026-08-13T10:57:08Z + +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. From ef910bcddd3ef491ac631bda7453d4ae7cf65309 Mon Sep 17 00:00:00 2001 From: Mateusz Lewandowski Date: Thu, 13 Aug 2026 12:59:57 +0200 Subject: [PATCH 4/4] docs: explain the data2dsl project --- README.md | 206 ++++++++++++++++++++++++--- TODO.md | 2 +- project/ticket-003/README.md | 18 ++- project/ticket-003/ai-codex-logs.txt | 26 ++++ project/ticket-003/ai-codex.md | 6 + project/ticket-003/changelog.md | 2 + project/ticket-003/intent.json | 54 +++++++ 7 files changed, 291 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 91a9fee..590547d 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,203 @@ # data2dsl -`data2dsl` is a planned reuse-first composition layer for turning existing -data-source capabilities into comparable, evidence-bearing observations. +`data2dsl` is a planned, evidence-first comparison layer. It will turn facts +from existing data sources into comparable observations and deterministic +differences that other systems can reason about. -The project is currently in Phase 0: governance bootstrap and capability -inventory. No functional implementation or final architecture is approved. +The short version: -## Phase 0 outcome +> Ask one bounded question, acquire the relevant facts from two or more +> sources, normalize them without losing provenance, compare like with like, +> and return the result together with evidence. -- verify reusable capabilities in `semcod/*`, `subactor/*`, and - `wellmanifest/*`; -- inspect reusable seams currently embedded in `semcod/todo2code`; -- record evidence and decisions in `CAPABILITY_MAP.md`; -- propose a composition graph without implementing product features. +The project is currently in contract and integration planning. The repository +contains governance, capability evidence and architectural decisions, but no +functional product implementation or final public DSL yet. -## Architectural invariant +## The problem -Reuse first. Extract second. Extend third. Implement new only as a last resort. +Useful facts already exist across Markdown documents, Git repositories, GitHub, +configuration files, code analyzers and browser-backed sources. Each source has +its own structure and vocabulary. Today a consumer such as `todo2code` must +either understand every source or rely on an LLM to interpret incomparable +outputs. -`data2dsl` must remain a small composition, routing, mapping, normalization, -and comparison-glue layer rather than becoming a replacement monolith for -`todo2code`. +That creates four recurring problems: + +1. the same metric can be named or represented differently by each source; +2. values may refer to different actors, repositories or time windows; +3. conclusions can lose the evidence needed to verify them; +4. source acquisition, deterministic comparison and higher-level reasoning get + mixed into one component. + +`data2dsl` is intended to provide the missing factual boundary between source +tools and reasoning consumers. + +## Who it is for + +The primary consumers are programs and agents that need to compare claims with +observed data while preserving provenance. Initial consumers are expected to +include `todo2code` and repository-governance workflows, but the core must not +depend on either one. + +A human may formulate the question, inspect the differences and follow the +evidence. A source adapter acquires facts. `data2dsl` normalizes and compares +them. A separate consumer decides what the result means or what action, if any, +should follow. + +## Golden case + +The first end-to-end case is: + +> Compare statements in `work-summary.md` with actual GitHub activity for the +> same repository, actor, metric and time window. + +For example, a summary might claim 12 commits for a person during a given +week, while the GitHub source reports 10. The planned result is not prose or an +LLM verdict. It is an evidence-bearing comparison containing, conceptually: + +| Field | Example | +| --- | --- | +| Subject | repository and actor | +| Metric | commit count | +| Window | explicit start and end | +| Left observation | claimed value from a Markdown location | +| Right observation | measured value from GitHub pages/API results | +| Outcome | `CONFLICT` | +| Delta | `-2` | +| Evidence | immutable references and content digests for both sides | + +This table illustrates intended behavior; it is not a final API or schema. + +## Planned inputs + +A bounded comparison needs three kinds of input: + +- a query describing the subject, metric, sources and time window; +- source locations and the authority or credentials needed by their existing + adapters; +- explicit mapping/comparison rules when source vocabularies differ. + +Natural-language interpretation may help construct a query, but it must not +silently change the metric, window or source identity. Unresolved ambiguity +must remain visible. + +## Planned outputs + +The factual output should contain: + +- normalized source observations with stable identity and source state; +- deterministic scalar or set comparisons; +- outcomes such as `MATCH`, `CONFLICT`, `MISSING_LEFT`, `MISSING_RIGHT` and + `UNEVALUABLE`; +- typed deltas where a delta is meaningful; +- evidence references sufficient to locate, integrity-check and reproduce the + source facts; +- explicit gaps when acquisition, mapping or comparison cannot be completed. + +`UNEVALUABLE` is not success and missing data is not zero. Comparison outcomes +are also distinct from the state of an individual observation. + +## Planned composition + +```mermaid +flowchart LR + Q["Bounded query"] --> R["Routing and explicit mapping"] + R --> M["Markdown via mdflow"] + R --> G["Git factual seam"] + R --> H["GitHub via Diagit extension"] + R --> C["Existing code/data analyzers"] + M --> O["Comparable observations + evidence"] + G --> O + H --> O + C --> O + O --> D["Deterministic comparator"] + D --> F["Facts, outcomes, deltas, gaps, evidence"] + F --> X["todo2code or another reasoning consumer"] +``` + +This is a composition hypothesis, not a final runtime contract. Current +reuse decisions and their pinned evidence are recorded in +[`docs/CAPABILITY_MAP.md`](docs/CAPABILITY_MAP.md). + +## What data2dsl owns + +The project should own only the smallest missing responsibilities: + +- routing a bounded query to declared source capabilities; +- explicit mapping from source facts to comparable metric keys; +- normalization that preserves source identity, time and evidence; +- deterministic comparability checks and scalar/set differences; +- a thin adapter boundary for existing source tools; +- factual results and typed gaps for downstream consumers. + +## What data2dsl does not own + +The project is not intended to become: + +- a universal parser framework; +- a replacement Git or GitHub client; +- a replacement for `mdflow`, Diagit, code analyzers or `todo2code`; +- an LLM reasoning or conclusion engine; +- an autonomous enforcement or mutation system; +- a Digital Twin event store or all-traits Twin runtime; +- a place to copy code from neighboring repositories without an explicit, + compatibility-tested extraction decision. + +Source adapters remain responsible for truthful acquisition. Standards owners +remain responsible for shared contracts. Consumers remain responsible for +reasoning, policy and action. + +## Reuse-first strategy + +Every capability follows this order: + +1. **REUSE** an existing public API or CLI when its behavior and ownership fit. +2. **EXTRACT** the smallest neutral seam when useful behavior is trapped inside + another product; preserve its language and compatibility. +3. **EXTEND** the established owning component when a nearby capability exists. +4. Mark a capability **MISSING** and implement it locally only after the first + three options have been disproved with current evidence. + +Examples from the Phase 0 inventory include reusing `mdflow` for Markdown +structure, extending Diagit's established GitHub boundary for commit metrics, +and keeping `todo2code` as a reasoning consumer rather than moving its policy +into data2dsl. + +## Delivery roadmap + +The planned delivery order is dependency-driven: + +1. decide the observation/evidence contract and its compatibility with + `subactor/twin`; +2. agree a minimal shared query/result profile with its standards owner; +3. define the smallest deterministic scalar/set comparison semantics; +4. extend Diagit with the read-only GitHub metrics required by the golden case; +5. implement and validate `work-summary.md` versus GitHub in Docker; +6. evaluate Git/config/AST extraction from `todo2code` only when a real second + consumer proves it is necessary; +7. integrate factual results back into `todo2code` without moving reasoning + into data2dsl. + +Each step requires its own bounded ticket and evidence. Changes to another +repository require that repository's owner-approved workflow. + +## Current state + +- Phase 0 governance bootstrap and capability inventory are complete. +- Docker bootstrap and the deterministic governance gate pass. +- No product source, final observation schema, query DSL, GitHub extension or + golden-case implementation exists yet. +- Open architectural claims must remain explicitly provisional until their + owning contracts and compatibility tests exist. + +See [`TODO.md`](TODO.md) for current work and +[`project/TICKETS.md`](project/TICKETS.md) for governed evidence. ## Governance This repository adopts an immutable published revision of `wellmanifest/new-project`. Multi-step work is ticket-governed and bounded by -the active ticket's `intent.json`. +the active ticket's `intent.json`. Human-owned `user-*` files are never written +by agents, and implementation claims require deterministic validation rather +than README text alone. diff --git a/TODO.md b/TODO.md index fa6323c..1bfe00a 100644 --- a/TODO.md +++ b/TODO.md @@ -24,5 +24,5 @@ ticket. ## Project communication -- [ ] Explain the concrete data2dsl product vision, boundaries, golden case and +- [x] Explain the concrete data2dsl product vision, boundaries, golden case and roadmap in the root README under [`ticket-003`](project/ticket-003/README.md). diff --git a/project/ticket-003/README.md b/project/ticket-003/README.md index ae53745..18d9885 100644 --- a/project/ticket-003/README.md +++ b/project/ticket-003/README.md @@ -19,13 +19,19 @@ recorded in evidence documents. ## Acceptance criteria -- [ ] AC-01: README explains the problem and intended users. -- [ ] AC-02: README defines inputs, outputs and the golden case concretely. -- [ ] AC-03: README distinguishes responsibilities and non-goals. -- [ ] AC-04: README presents the reuse-first composition and staged roadmap. -- [ ] AC-05: Claims remain consistent with the capability map and no product +- [x] AC-01: README explains the problem and intended users. +- [x] AC-02: README defines inputs, outputs and the golden case concretely. +- [x] AC-03: README distinguishes responsibilities and non-goals. +- [x] AC-04: README presents the reuse-first composition and staged roadmap. +- [x] AC-05: Claims remain consistent with the capability map and no product implementation is introduced. -- [ ] AC-06: Governance passes and no other repository is modified. +- [x] AC-06: Governance passes and no other repository is modified. + +## Result + +The root README is now the canonical onboarding description of the planned +product. It distinguishes intended behavior from unimplemented contracts and +links detailed capability evidence rather than duplicating it. ## Participants diff --git a/project/ticket-003/ai-codex-logs.txt b/project/ticket-003/ai-codex-logs.txt index e69de29..bc2fbf6 100644 --- a/project/ticket-003/ai-codex-logs.txt +++ b/project/ticket-003/ai-codex-logs.txt @@ -0,0 +1,26 @@ +2026-08-13 project-overview evidence log + +Pre-change audit: +- README described Phase 0 and the reuse-first invariant. +- The concrete problem, users, inputs, outputs, golden case, boundaries and + delivery roadmap were absent or distributed across technical evidence. + +Changed path: +- README.md + +Cross-check source: +- docs/CAPABILITY_MAP.md + +No executable source, schema, dependency or external repository was changed. + +First governance result: +GOV-DELIVERY-001 required an explicit bounded delivery contract for README.md. +Added a one-file, one-component, zero-interface, zero-dependency contract +against the fetched target head without changing the authorized outcome. + +Final validation: +- all required README sections present; +- all local README link targets present; +- git diff --check passed; +- GOV-PASS: 0 errors, 0 warnings; +- subactor/twin, wellmanifest/dsl and semcod/todo2code clean. diff --git a/project/ticket-003/ai-codex.md b/project/ticket-003/ai-codex.md index 87c5294..22da470 100644 --- a/project/ticket-003/ai-codex.md +++ b/project/ticket-003/ai-codex.md @@ -26,6 +26,12 @@ behavior without presenting unimplemented contracts as available features. - Initialized the bounded ticket and recorded SESSION_EXECUTION_AUTHORIZATION from the request to execute this work. - No executable implementation or external-repository change is authorized. +- Replaced the Phase 0-only README with a contributor-oriented product + description covering the problem, users, bounded inputs, factual outputs, + golden case, composition, ownership boundary, non-goals, reuse strategy, + roadmap, current state and governance. +- Marked conceptual examples and the composition graph as non-final so the + README does not overstate implementation maturity. ## Blockers diff --git a/project/ticket-003/changelog.md b/project/ticket-003/changelog.md index ab56167..e8421eb 100644 --- a/project/ticket-003/changelog.md +++ b/project/ticket-003/changelog.md @@ -5,3 +5,5 @@ - Initial governance scaffold created. - No human participant identity or content was generated. - Recorded the bounded README and contributor-onboarding scope. +- Expanded the root README into the canonical product overview without adding + implementation or changing existing technical evidence. diff --git a/project/ticket-003/intent.json b/project/ticket-003/intent.json index 0008dd6..e470bc5 100644 --- a/project/ticket-003/intent.json +++ b/project/ticket-003/intent.json @@ -8,6 +8,60 @@ "priority": "P2", "origin": "health" }, + "delivery": { + "acceptedBaseSha": "067b76b67802b17084c1209a5e96121dec5b8a2f", + "targetBranch": "main", + "outcome": "Make the root README the canonical, concrete onboarding description of the planned data2dsl product.", + "nonGoals": [ + "Implement product behavior, schemas, APIs, adapters, or dependencies.", + "Modify any repository other than data2dsl or replace technical evidence documents." + ], + "complexity": "S", + "estimatedMinutes": 30, + "budgets": { + "maxImplementationFiles": 1, + "maxAffectedComponents": 1, + "maxPublicInterfaceChanges": 0, + "maxRuntimeDependencies": 0 + }, + "architecture": { + "status": "accepted", + "decision": "Use the root README as the discoverable product overview and link detailed evidence instead of duplicating it.", + "components": [ + { + "name": "project-onboarding", + "paths": ["README.md"] + } + ], + "responsibilityChanges": false, + "interfaceChanges": [], + "dataChanges": [], + "ui": { + "impact": "none", + "states": [], + "evidence": [] + }, + "rollback": "Revert the README expansion and return the project description to Phase 0 wording." + }, + "runtimeDependencies": [], + "validation": [ + { + "criterion": "AC-02", + "commands": ["rg -n 'Golden case|Planned inputs|Planned outputs' README.md"], + "evidence": "README contains concrete input, output and golden-case sections." + }, + { + "criterion": "AC-04", + "commands": ["rg -n 'Planned composition|Reuse-first strategy|Delivery roadmap' README.md"], + "evidence": "README contains composition, reuse and staged-delivery guidance." + }, + { + "criterion": "AC-06", + "commands": ["project\\governance-check.bat --actor agent"], + "evidence": "The deterministic governance gate records the result." + } + ] + }, "allowedPaths": ["project/ticket-003/**", "README.md", "TODO.md", "project/TICKETS.md"], "forbiddenPaths": ["project/ticket-*/user-*.md"], "stacks": [],