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 | FR-200 |
| `importer.py` | implemented | FR-300/400 |
| `differ.py` | implemented | FR-700 |
| `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 | FR-900 |
| `mcp_server.py` | implemented — FastMCP server, all tools and resources | FR-1000 |

`tests/conftest.py` provides shared fixtures (`tmp_project`, `SIMPLE_MANIFEST_YAML`, `SIMPLE_MARKDOWN`). WP-0001 and WP-0002 complete — 135 tests passing. All interfaces (CLI, REST, MCP) implemented and parity-tested.

---

## Development Commands

```bash
# 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**

```bash
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:
```python
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:
```python
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**
```python
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:**
```yaml
---
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):**
```markdown
## Task Title
​```task
id: MRKD-WP-NNNN-T01
status: todo
priority: high
state_hub_task_id: <uuid>
​```
```

After writing or modifying workplan files, run:
```bash
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

After updating dependencies:
```bash
cd ~/the-custodian/state-hub
make ingest-sbom REPO=marki-docx SCAN=1 REPO_PATH=/home/tegwick/marki-docx
```

---

## 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`