Plan auto capture of provenance metadata (2.2.5 ExecPlan)

[leynos]

Summary

Adds an Execution Plan (ExecPlan) for roadmap item 2.2.5: automatically capture provenance metadata in TEI headers for both ingestion and script-generation flows, aligned with hexagonal architecture principles and ensuring compatibility with existing TEI consumers.

Changes

• New document: docs/execplans/2-2-5-capture-provenance-metadata.md (390+ lines in diff, 391 insertions).
• The ExecPlan details constraints, tolerances, risks, progress, surprises & discoveries, a decision log, outcomes & retrospective, and a staged plan of work from alignment to full validation.
• Provides concrete steps, validation criteria, and interfaces/ports required for implementing provenance capture.

Rationale

• Establishes a single, shared provenance assembly pathway used by both ingestion and script-generation flows to preserve consistent TEI provenance blocks.
• Enforces hexagonal architecture boundaries: domain policies and data structures separate from application orchestration and TEI formatting in outbound adapters.
• Documents acceptance criteria, quality gates, and documentation updates needed to complete roadmap item 2.2.5.

Plan of work (stages A–H)

• Stage A: alignment and baseline (no behavior changes)
• Stage B: domain and port design
• Stage C: shared application service
• Stage D: ingestion flow integration
• Stage E: script generation flow integration
• Stage F: behavioral and regression hardening
• Stage G: documentation and roadmap updates
• Stage H: full validation and evidence capture

Each stage includes concrete validation tasks (unit tests, behavioural tests, fixtures), decisions, and go/no-go criteria as described in the ExecPlan.

Validation and acceptance

• Feature acceptance (behavioral):
  • Ingestion and script-generation TEI headers include provenance metadata with source priorities, timestamps (UTC), and reviewer identity.
  • Operation type differentiates ingestion vs. script_generation in provenance blocks.
  • Deterministic timestamps via a clock port in tests; explicit reviewer fallback semantics.
• Quality gates: make check-fmt, make typecheck, make lint, make test (and behavioural tests) must pass.
• Documentation: design decisions, user guidance, and developer guidance updated; roadmap item 2.2.5 marked as done upon completion.

Interfaces and dependencies (high level)

• CaptureProvenance application service (domain boundary)
• ClockPort, ReviewerIdentityPort, SourcePriorityPort (driven ports)
• TEI header adapter to render provenance into TEI blocks

Review guidance

• Focus on completeness of the planning, feasibility of staged approach, and alignment with existing TEI and provenance policies.
• Confirm the document accurately reflects architectural constraints and the testing/quality gate expectations.

Notes

• This is a planning/doc-only change to establish the execution plan; no code changes are introduced by this PR.
• The ExecPlan serves as the alignment contract for subsequent implementation work and related documentation updates.

◳ Generated by DevBoxer ◰

---

ℹ️ Tag @devboxerhub to ask questions and address PR feedback

📎 Task: https://www.devboxer.com/task/f7d6eac4-b20d-44c8-8bc9-7bf283d97e47

Summary by Sourcery

Documentation:

• Add ExecPlan documentation outlining stages, constraints, risks, interfaces, and acceptance criteria for roadmap item 2.2.5 on automatic TEI provenance capture.

[sourcery-ai]

Reviewer's Guide

Adds a new ExecPlan document that defines the staged implementation plan, architecture boundaries, interfaces, and validation/acceptance criteria for automatically capturing provenance metadata in TEI headers across both ingestion and script-generation flows, without making any code changes.

Sequence diagram for provenance capture in TEI header generation

sequenceDiagram
  actor User
  participant IngestionAdapter
  participant ScriptGenerationAdapter
  participant CaptureProvenance
  participant ClockPort
  participant ReviewerIdentityPort
  participant SourcePriorityPort
  participant TEIHeaderAdapter

  alt Ingestion flow
    User->>IngestionAdapter: submit ingestion request
    IngestionAdapter->>CaptureProvenance: assembleProvenance(ingestion, sources, reviewerContext)
  else Script generation flow
    User->>ScriptGenerationAdapter: request script generation
    ScriptGenerationAdapter->>CaptureProvenance: assembleProvenance(script_generation, sources, reviewerContext)
  end

  CaptureProvenance->>ClockPort: nowUtc()
  ClockPort-->>CaptureProvenance: timestamp

  CaptureProvenance->>ReviewerIdentityPort: resolveReviewer()
  ReviewerIdentityPort-->>CaptureProvenance: reviewerIdentity

  CaptureProvenance->>SourcePriorityPort: resolveSourcePriorities(sources)
  SourcePriorityPort-->>CaptureProvenance: orderedSourcePriorities

  CaptureProvenance-->>IngestionAdapter: ProvenanceRecord
  CaptureProvenance-->>ScriptGenerationAdapter: ProvenanceRecord

  IngestionAdapter->>TEIHeaderAdapter: renderHeader(ProvenanceRecord, existingHeader)
  ScriptGenerationAdapter->>TEIHeaderAdapter: renderHeader(ProvenanceRecord, existingHeader)
  TEIHeaderAdapter-->>User: TEI with provenance header

Loading

Class diagram for provenance capture domain, application service, and ports

classDiagram

class ProvenanceRecord {
  +operationType string
  +sources SourcePriority[]
  +timestamp IngestionTimestamp
  +reviewer ReviewerIdentity
}

class SourcePriority {
  +sourceId string
  +priority int
}

class ReviewerIdentity {
  +id string
  +displayName string
}

class IngestionTimestamp {
  +value datetime
}

class CaptureProvenance {
  +assembleProvenance(operationType string, sources SourcePriority[], reviewerContext ReviewerIdentity) ProvenanceRecord
}

class ClockPort {
  <<interface>>
  +nowUtc() datetime
}

class ReviewerIdentityPort {
  <<interface>>
  +resolveReviewer() ReviewerIdentity
}

class SourcePriorityPort {
  <<interface>>
  +resolveSourcePriorities(sources string[]) SourcePriority[]
}

class IngestionAdapter {
  +handleIngestionRequest(rawSourceMetadata any)
}

class ScriptGenerationAdapter {
  +handleScriptGenerationRequest(generationContext any)
}

class TEIHeaderAdapter {
  +renderHeader(provenance ProvenanceRecord, existingHeader any) string
}

%% Layer groupings (conceptual)
ProvenanceRecord --> SourcePriority
ProvenanceRecord --> IngestionTimestamp
ProvenanceRecord --> ReviewerIdentity

CaptureProvenance --> ProvenanceRecord
CaptureProvenance --> ClockPort
CaptureProvenance --> ReviewerIdentityPort
CaptureProvenance --> SourcePriorityPort

IngestionAdapter --> CaptureProvenance
ScriptGenerationAdapter --> CaptureProvenance

TEIHeaderAdapter --> ProvenanceRecord
IngestionAdapter --> TEIHeaderAdapter
ScriptGenerationAdapter --> TEIHeaderAdapter

Loading

File-Level Changes

Change	Details	Files
Introduce a detailed execution plan document for roadmap item 2.2.5 covering staged delivery, architecture, interfaces, and validation for TEI provenance capture.	Create docs/execplans/2-2-5-capture-provenance-metadata.md as a living ExecPlan with sections for constraints, tolerances, risks, progress tracking, surprises & discoveries, decision log, and outcomes & retrospective. Define domain/application/adapter responsibilities and required ports (CaptureProvenance service, ClockPort, ReviewerIdentityPort, SourcePriorityPort, TEI header adapter) aligned with hexagonal architecture. Specify an 8-stage implementation plan (A–H) with concrete tasks, go/no-go criteria, and validation steps for aligning roadmap/docs, designing the domain model, implementing a shared application service, integrating ingestion and script-generation flows, hardening tests, updating documentation/roadmap, and final validation. Document concrete validation and acceptance criteria including behavioural expectations for TEI headers, quality gates (fmt, typecheck, lint, tests), and documentation updates, plus idempotence/recovery guidance and required implementation artefacts.	docs/execplans/2-2-5-capture-provenance-metadata.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch capture-provenance-metadata-2w5vt3

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}