marki-docx/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Repo Is

marki-docx (markidocx) is a Markdown ↔ DOCX round-trip editing system.

• Markdown is the canonical structured source
• Word documents are editorial projections — generated for review, not authoritative
• Conversion must be deterministic, inspectable, and semantically stable across cycles
• Interfaces: CLI, REST service, MCP tools

Key artefacts already in this repo:

• specs/MarkiDocxProductRequirementsDocument_v0.1.md — PRD (implementation-independent)
• specs/MarkiDocxFunctionalRequirementsSpecification_v0.2.md — FRS (binding functional contract)
• specs/MarkiDocxUseCaseCatalog_v0.1.md — use case catalogue

---

Planned Architecture

markidocx is a conversion pipeline with three delivery interfaces over a shared functional core.

Interfaces

Interface	Purpose
CLI	Local document workflows (markidocx build, import, validate, compare)
REST service	Automation / pipeline integration
MCP tools	Agent-accessible operations (same functional surface as CLI/REST)

All three interfaces expose the same functional model — no interface-specific logic should live outside its adapter layer.

Core Functional Domains (from FRS)

FR group	Domain
FR-100	Project & manifest management
FR-200	Build / export (Markdown → DOCX)
FR-300	Import / round-trip (DOCX → Markdown)
FR-400	Multi-file composition & redistribution
FR-500	Feature-level enforcement (LEVEL1 / LEVEL3)
FR-600	Template & style family management
FR-700	Validation & drift analysis
FR-1100	Test & regression
FR-1300	Composite workflow orchestration
FR-1400	Evidence & report assembly

Key Concepts

• Project manifest — declares source files, feature level, and template/style family; drives all operations
• Feature levels — LEVEL1 (headings, lists, tables, footnotes, images, links); LEVEL3 adds cross-refs, numbered figures, auto-diagrams, bibliography
• Document families — three built-in: article, book, website; extensible via registration
• Source mapping — multi-file imports must redistribute content back to origin files; fallback produces a merged single file
• Drift detection — structural diff between original Markdown and re-imported result; reported as inspectable evidence

Round-trip data flow

manifest + Markdown sources
    ↓  FR-100 (resolve project)
    ↓  FR-200 (compose + export → DOCX)
     [Word editorial review]
    ↓  FR-300 (import DOCX → Markdown)
    ↓  FR-400 (redistribute to source files)
    ↓  FR-700 (validate + drift report)
evidence artefacts

Implementation State

Module	Status	FR coverage
cli.py	implemented — all commands wired (build, import, compare, validate, serve, workflow, mcp, template)	all
manifest.py	implemented	FR-100
builder.py	implemented — LEVEL1 + LEVEL3 (xrefs, figures, diagrams, citations)	FR-200, FR-531–539
importer.py	implemented — LEVEL1 + LEVEL3 round-trip	FR-300/400, FR-531–536
differ.py	implemented — LEVEL1 + LEVEL3 drift detection	FR-700, FR-540–542
templates.py	implemented	FR-600
evidence.py	implemented	FR-1400
workflows.py	implemented (single-file-roundtrip, multi-file-roundtrip, release-regression, family-switch-build)	FR-1300
rest.py	implemented — FastAPI app, all endpoints; structured warning records	FR-900, FR-1208
mcp_server.py	implemented — FastMCP server, all tools and resources; structured warnings	FR-1000, FR-1208
errors.py	implemented — WarningRecord, FailureRecord, OutputState	FR-1201–1210
level3.py	implemented — LEVEL3 support detection, capability disclosure	FR-537–539
xref.py	implemented — cross-reference round-trip helpers	FR-531, FR-540
figures.py	implemented — numbered figure round-trip helpers	FR-532, FR-541
diagrams.py	implemented — auto-diagram source-only + renderer path	FR-533, FR-534
bibliography.py	implemented — citation and references section round-trip	FR-535, FR-536, FR-542

tests/conftest.py provides shared fixtures. WP-0001, WP-0002, and WP-0003 complete — 259 tests passing. Full LEVEL1 + LEVEL3 feature coverage. All interfaces (CLI, REST, MCP) implemented and parity-tested.

---

Development Commands

# Install in editable mode
pip install -e ".[dev]"

# Run tests
pytest

# Run a single test file
pytest tests/path/to/test_file.py

# Lint
ruff check .

# Type-check
mypy src/

# Start REST service (dev mode)
markidocx serve --dev

# CLI: build a document project
markidocx build <manifest.yaml>

# CLI: import an edited DOCX
markidocx import <manifest.yaml> <edited.docx>

# CLI: compare baseline vs re-import
markidocx compare <manifest.yaml> <edited.docx>

# CLI: run end-to-end regression
markidocx test

---

Custodian State Hub Integration

This project is tracked as the markitect domain in the Custodian State Hub.

Key	Value
Domain	markitect
Topic ID	5571d954-0d30-4950-980d-7bcaaad8e3e2
Repo ID	75d31180-acf5-4d47-aea8-2a5b1e71e6a9
Repo slug	marki-docx

Hub API: http://127.0.0.1:18001 — if offline: cd ~/the-custodian/state-hub && make api

---

Session Protocol (MANDATORY)

On session start — before writing any response text:

Step 1 — Orient via State Hub

get_domain_summary("markitect")

Note: active workstreams, blocking decisions, recent progress, SBOM status.

Step 2 — Scan local workplans

ls workplans/   # or Glob(pattern="workplans/**/*.md")

For each file with status: active, extract pending todo / in_progress tasks.

Step 3 — Present orientation

Output a concise brief:

1. Active workstreams for markitect domain — title, task counts, blocking decisions
2. Pending tasks — from local workplans/ + state hub tasks with [repo:marki-docx]
3. Goal guidance — if goal_guidance is present in the summary:
   • needs_workplan: surface as top suggested action — create workplan file + workstream
   • alignment_warnings: name the misaligned workstream and flag it
4. Suggested next action — highest-priority open item
5. SBOM status — last_sbom_at set? If not, note it as a gap

If no workstreams exist → follow First Session Protocol below.

During work:

• record_decision() — any decision affecting direction or dependencies
• add_progress_event() — milestones, blockers, insights
• resolve_decision() — once a decision is made

On session end:

add_progress_event(
    summary="<what was accomplished or decided>",
    event_type="note|milestone|blocker",
    topic_id="5571d954-0d30-4950-980d-7bcaaad8e3e2",
    workstream_id="<id if applicable>"
)

Design boundary: The State Hub is a read model. Two write operations are permanently sanctioned: Resolving Decisions and Suggesting Next Steps. Bootstrap tools (create_workstream, create_task) are First Session Protocol only. Work items originate as files in this repo (ADR-001), not in the hub alone.

---

Repo Boundary Rule

This agent is responsible for files in this repo only.

• Do not write files or commit in any other repository
• Work identified for another repo → create a state hub task with [repo:<slug>] in the title
• Work identified for an upstream package → create a contribution artefact in contrib/

---

First Session Protocol

Triggered when get_domain_summary("markitect") shows no workstreams linked to marki-docx.

Step 1 — Read the specs

• specs/MarkiDocxProductRequirementsDocument_v0.1.md
• specs/MarkiDocxFunctionalRequirementsSpecification_v0.2.md
• specs/MarkiDocxUseCaseCatalog_v0.1.md
• Scan the repo root for any existing code or further docs

Step 2 — Survey the canon

• ~/the-custodian/canon/projects/markitect/project_charter_v0.1.md
• ~/the-custodian/canon/projects/markitect/roadmap_v0.1.md

Step 3 — Propose workstreams to Bernd Propose 1–3 workstreams — coherent strands of work lasting weeks to months, anchored to a roadmap phase. Wait for approval before creating anything.

Step 4 — Create workplan file first, then DB record (ADR-001)

workplans/MRKD-WP-0001-<slug>.md   ← write this first

Then register:

create_workstream(
    topic_id="5571d954-0d30-4950-980d-7bcaaad8e3e2",
    title="...", owner="marki-docx", description="..."
)
create_task(workstream_id="<id>", title="...", priority="high|medium|low")

Step 5 — Record the setup

add_progress_event(
    summary="First session: structured marki-docx work into N workstreams, M tasks",
    event_type="milestone",
    topic_id="5571d954-0d30-4950-980d-7bcaaad8e3e2",
    detail={"workstreams": [...], "tasks_created": M}
)

---

Workplan Convention (ADR-001)

Work items MUST originate as files in this repo before being registered in the hub.

File location: workplans/MRKD-WP-NNNN-<slug>.md

Required frontmatter:

---
id: MRKD-WP-NNNN
type: workplan
domain: markitect
repo: marki-docx
status: active|done|paused
state_hub_workstream_id: <uuid>
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

Task blocks (embedded in the workplan file):

## Task Title
​```task
id: MRKD-WP-NNNN-T01
status: todo
priority: high
state_hub_task_id: <uuid>
​```

After writing or modifying workplan files, run:

cd ~/the-custodian/state-hub && make fix-consistency REPO=marki-docx

This syncs task blocks → DB. Without it, the dashboard shows 0 progress.

---

Contribution Tracking

Track upstream contributions in contrib/:

contrib/
  bug-reports/       # br-YYYY-MM-DD--org--repo--slug.md
  feature-requests/  # fr-YYYY-MM-DD--org--repo--slug.md
  extension-points/  # EP-MRKD-NNN--org--repo--slug.md
  upstream-prs/      # upr-YYYY-MM-DD--org--repo--slug.md

Templates: ~/the-custodian/canon/standards/contrib-templates/

---

SBOM

Re-run the SBOM after any dependency change (new package added/removed/upgraded in pyproject.toml).

The ops-bridge ingest_sbom_tool requires the lockfile to be accessible from the bridge machine. Use a requirements.txt generated via:

pip list --format=freeze | grep -E "^(python-docx|PyYAML|typer|rich|mistune|fastapi|uvicorn|mcp|pytest|pytest-cov|ruff|mypy|types-PyYAML|httpx|pydantic|click|starlette|anyio|httpcore|certifi|h11|sniffio|idna)=" | sort > requirements.txt

Then either:

• Run locally if API is accessible: cd ~/the-custodian/state-hub && make ingest-sbom REPO=marki-docx SCAN=1 REPO_PATH=/home/tegwick/marki-docx
• Or via MCP ingest_sbom_tool once host_paths mapping is configured for marki-docx in the custodian

---

Quick Reference

• MCP tool reference: ~/the-custodian/state-hub/mcp_server/TOOLS.md
• ADR-001 (workplan convention): ~/the-custodian/canon/architecture/adr-001-workplans-as-repo-artefacts.md
• Contribution convention: ~/the-custodian/canon/standards/contribution-convention_v0.1.md
• Release process: docs/release-process.md
• Changelog: CHANGELOG.md