Add PROV schema foundation specification (Phase 0) #206
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Defines the foundational schemas for Epic E02 (PROV Logging Implementation): - LinkML Log Entry schema matching SRD Annex A.3 - Expanded ToolResult model with structured change tracking - Provenance format unification (remove duplicate STAC module) - System record schema for snapshot/branch metadata - 15 functional requirements, 7 success criteria, 5 user stories https://claude.ai/code/session_01DiCtXrCN6naDB37AQVKqTm
Links to specs/070-prov-schema-foundation/spec.md https://claude.ai/code/session_01DiCtXrCN6naDB37AQVKqTm
Phase 0: research.md — 10 technical decisions with rationale Phase 1: data-model.md — entity definitions, state transitions Phase 1: contracts/ — JSON Schema for Log Entry, system record, expanded ToolResult Phase 1: quickstart.md — verification guide with before/after examples Phase 2: media/ — planning post and LinkedIn summary Constitution check: all gates pass https://claude.ai/code/session_01DiCtXrCN6naDB37AQVKqTm
68 tasks across 8 phases: - Phase 1: Setup (10 golden fixtures) - Phase 2: Foundation (8 tasks: LinkML schemas + model classes) - Phase 3: US1 MVP — unified provenance (12 tasks) - Phase 4: US2 — expanded ToolResult (6 tasks) - Phase 5: US3 — format unification (7 tasks) - Phase 6: US4 — system record schema (4 tasks) - Phase 7: US5 — schema generation (8 tasks) - Phase 8: Polish (13 tasks: evidence, media, PR) https://claude.ai/code/session_01DiCtXrCN6naDB37AQVKqTm
Create 7 fixture files defining the target PROV-aligned format: - 3 valid log-entry fixtures (tool-invocation, property-edit, artifact-producing) - 2 invalid log-entry fixtures (missing-activity-id, bad-duration-format) - 2 valid system-record fixtures (empty, populated with snapshots/branches) https://claude.ai/code/session_01DiCtXrCN6naDB37AQVKqTm
- Create log-entry.yaml: LogEntry, WasGeneratedBy, ParameterValue, TuneAnnotation - Create system-record.yaml: SystemRecordProperties, SnapshotLinks, BranchRecord, FileProvEntry - Add imports to debrief.yaml root schema - Add ParameterValue, PropertyDelta, ModifiedFeature, CreatedAsset to models.py - Mark existing Provenance class as deprecated - Add 24 unit tests for new model classes (all pass) https://claude.ai/code/session_01DiCtXrCN6naDB37AQVKqTm
- Add LogEntry, WasGeneratedBy, TuneAnnotation models with camelCase aliases - Add create_log_entry() and attach_log_entry() provenance functions - Provenance is now an append-only array on features, not a single dict - attach_log_entry wraps legacy single-object provenance in array - Update executor to use new log entry functions - Update validation to check array-format provenance with PROV fields - Fix duration formatter to avoid scientific notation for small values - 294 tests pass (0 failures), including 20+ new log entry tests https://claude.ai/code/session_01DiCtXrCN6naDB37AQVKqTm
Add optional fields to ToolResult for the PROV Log Service contract: - tool_version: semantic version string - modified_features: list of ModifiedFeature (ID + property deltas) - created_features: list of new feature IDs - created_assets: list of CreatedAsset (result_id + path + mime_type) - parameters: dict of ParameterValue with default/tunable flags All new fields default to None for backward compatibility (SC-006). Includes serialization round-trip test. https://claude.ai/code/session_01DiCtXrCN6naDB37AQVKqTm
- Delete services/stac/src/debrief_stac/provenance.py (wrote to properties.prov) - Update STAC tests to use shared debrief_calc.provenance module - All provenance now uses unified PROV-aligned format (properties.provenance array) - Verified zero occurrences of properties.prov in codebase (SC-003) https://claude.ai/code/session_01DiCtXrCN6naDB37AQVKqTm
- Add SystemRecordProperties, SnapshotLinks, SnapshotRef, BranchRecord, FileProvEntry models - Add LogEntry and WasGeneratedBy model tests with camelCase serialization - Validate all golden fixtures (3 valid log-entry, 2 invalid, 2 system-record) - Round-trip test: Python LogEntry → JSON → Python (SC-007) - 70 model tests pass https://claude.ai/code/session_01DiCtXrCN6naDB37AQVKqTm
- Add test-summary.md: 318 tests pass, 0 failures (SC-001) - Add usage-example.md with Python code snippets - Mark all tasks complete in tasks.md - Update BACKLOG.md status to implementing https://claude.ai/code/session_01DiCtXrCN6naDB37AQVKqTm
- Replace timezone.utc with datetime.UTC alias (UP017) - Remove unused imports: TuneAnnotation, LogEntry, timezone (F401) - Move import above module-level constant (E402) - Apply ruff format to models.py and test_models.py https://claude.ai/code/session_01DiCtXrCN6naDB37AQVKqTm
IanMayo
pushed a commit
that referenced
this pull request
Feb 11, 2026
Cross-referenced 20 merged PRs from the last 72 hours with backlog items. Verified completion via task checklists and evidence artifacts. Newly completed (all tasks done, evidence present, PRs merged): - #70 PROV schema foundation (PR #205/#206) - #71 Log Recording service (PR #207) - #72 Log Panel (PR #211) - #73 Undo/redo split (PR #210) - #74 Snapshots (PR #209) - #75 Branching (PR #215) - #77 Fix VS Code extension bugs (PR #217) - #77 STAC File Tree Component (PR #217) Also: reordered active items by status priority (implementing > specified > approved > proposed), then by total score descending. Removed 7 duplicate completed entries at bottom of table. https://claude.ai/code/session_013y5hsr6RyeCaAFbegJG2W9
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR introduces the formal specification for the PROV Schema Foundation feature (item #70), marking the transition from the backlog to the specification phase. The specification defines the schema contracts, data models, and migration strategy for unifying provenance tracking across the codebase before implementing the Log Service in Phase 1.
Key Changes
Updated BACKLOG.md: Changed item Add specification for VS Code hide default activities feature #70 status from "approved" to "specified" and updated the documentation link from
docs/ideas/tospecs/070-prov-schema-foundation/spec.mdAdded specification document (
specs/070-prov-schema-foundation/spec.md):properties.provreferences, schema round-trip validation)Added requirements checklist (
specs/070-prov-schema-foundation/checklists/requirements.md):Notable Details
Nonedefaults to ensure backward compatibility with existing toolsproperties.provdata by simply not reading it, allowing future saves to use the unifiedproperties.provenanceformathttps://claude.ai/code/session_01DiCtXrCN6naDB37AQVKqTm