[aucontraire]

Summary

• Every wiki page now carries a cumulative provenance: frontmatter block (latest checkpoint, contributing conversations, action, confidence, total edits, exchange count) backed by a permanent per-checkpoint JSON record at <vault>/InsightMesh/.history/checkpoints/<conv-id>/cp-<NNN>.json and a shadow git repository for git log -p style diff history of every page's evolution across edits.
• Designed as a stable read contract (additive forward-compatibility within schema_version=1) for the planned in-Obsidian viewer plugin in a separate repo: aucontraire/insightmesh-obsidian.
• All bookkeeping is orchestrator-side; Editor's contract is unchanged; provenance failures never fail the run (FR-019).

What's new

src/history.py (NEW, ~660 lines): 8 Pydantic v2 models (CheckpointRecord + supporting + ProvenanceFrontmatter), CheckpointRecordRead permissive read-side subclass per FR-002, 4 custom exceptions, 7 pure helpers (compute_checkpoint_payload, write_checkpoint_metadata atomic + immutable per FR-001a, merge_page_provenance cumulative + atomic per FR-011, snapshot_page, init_shadow_repo idempotent three-state per FR-012, commit_checkpoint FR-014 format, is_git_available cached). No new runtime dependencies.

src/orchestrator.py (modified): new _sanitize_conversation_subdir, _normalize_vault_relative_path, _editor_decision_to_record, _build_exchange_records, _write_provenance helpers. _write_provenance is wired into the existing Spec 004 checkpoint loop after Editor success and before the cursor save, per FR-017.

src/exports.py (modified): refactored _to_role_content to share a _message_payload helper; added _to_role_content_with_ids + _provider_from_adapter. extract_conversation now populates ChatTranscript.metadata with provider, models_used, exchange_message_ids.

.claude/agents/editor.md (doc-only): note that orchestrator owns the provenance: frontmatter block per FR-017.

Tests: tests/test_history.py NEW (37 tests) + tests/test_orchestrator.py extended (+25 tests: 14 US1 + 10 US2 + 1 absolute-path regression). tests/fixtures/provenance_cp_001.json NEW for forward-compat fixture.

Docs: docs/index.md admonition refreshed to feature Spec 005; docs/reference/cli.md new "Per-checkpoint provenance record (Spec 005)" section under On-disk artifacts; docs/known-limitations.md gains a "RESOLVED in Spec 005" entry; README.md updated; status tables refreshed across index.md + README.md.

On-disk artifacts (per checkpoint)

<vault>/InsightMesh/
├── <page>.md                                    # now carries `provenance:` frontmatter block
└── .history/                                    # NEW
    ├── .git/                                    # shadow git repo, machine-greppable commits per FR-014
    ├── checkpoints/
    │   └── <conv-id-or-_flat>/
    │       └── cp-<NNN>.json                    # CheckpointRecord (permanent, immutable per FR-001a)
    └── pages/
        └── <sanitized-slug>.md                  # page snapshots, git-tracked

Test plan

• uv run pytest: 302 passing
• uv run mypy --strict src/: clean across 9 source files
• uv run ruff check src/ tests/: all checks passed
• uv run black --check src/ tests/: 19 files clean
• uv run ruff check --select TID: no banned-API violations (constitution v1.1.2 §Project Standards)
• uv run mkdocs build --strict: clean
• insightmesh --version → 0.5.0
• Real-data smoke (T020) on all 3 transcript code paths: Claude.ai conversation (provider="anthropic", models_used=[], real echomine UUIDs), ChatGPT conversation (provider="openai", models_used=["gpt-4o"], real ids), Spec 001 flat-array (provider=null, conv_id=null, _flat/ sentinel subdir, null message ids). Findings memory: project_spec005_findings.md.

Bugs found + fixed during real-data smoke

S1: WikiPageResult.file_path from MCPVault is an absolute filesystem path, not vault-relative. _normalize_vault_relative_path originally only handled bare-filename + already-prefixed inputs, producing garbage like InsightMesh//Users/.../InsightMesh/Page.md in results.pages_created / pages_updated. Fix in commit bdea9df with regression test TestProvenanceAbsolutePathNormalization. Same lesson as Spec 004 findings: mocked tests with synthetic defaults silently mask the failures real Editor output surfaces.

Spec process (followed full speckit cycle)

/speckit-specify → /speckit-clarify (1 question, locked per-conversation subdir naming) → /speckit-plan → /speckit-tasks (21 tasks) → /speckit-checklist (added second durability-and-resilience checklist of 38 items) → /spec-gaps all (15 remediation groups applied) → /speckit-analyze (1 MEDIUM + 4 LOW found) → /reconcile all (all 5 closed) → /speckit-implement → real-data smoke (T020). 21/21 tasks done, both checklists 100% (16+38 items checked).

Constitution compliance

• Anti-Slop: 1 new src/ file (src/history.py) justified in plan.md Complexity Tracking; modifications to src/orchestrator.py and src/exports.py surgical; no new dependencies
• Project Standards: all data shapes are pydantic.BaseModel(ConfigDict(strict=True)) — the one spec-mandated extra="allow" deviation on CheckpointRecordRead is documented inline per FR-002
• Incremental Delivery: US1 ships as an MVP shippable without git on PATH; US2 layers shadow-repo on top

Out of scope (deferred to future specs)

• In-Obsidian viewer plugin — separate repo: aucontraire/insightmesh-obsidian
• CLI insightmesh history <page> subcommand
• Obsidian Dataview / Bases templates (Properties panel doesn't render nested YAML natively — design decision; covered in spec Key Entities)
• Phase B Postgres migration of the checkpoint JSON
• Pruning / compaction of .history/

Full list in specs/005-page-provenance/spec.md § Out of Scope.