# Markitect Tool Adapter

Date: 2026-05-14

## Purpose

`infospace-bench` delegates Markdown syntax work to `markitect-tool` through a
single narrow adapter:

```text
src/infospace_bench/markdown_adapter.py
```

This keeps the repos orthogonal:

- `markitect-tool` parses and validates Markdown.
- `infospace-bench` interprets parsed/validated artifacts as parts of concrete
  infospaces.

## Current Adapter Surface

- `parse_markdown_artifact(path)`
- `extract_section_text(parsed, heading)`
- `validate_markdown_artifact(artifact_id, path, contract_path)`
- `validate_infospace_artifacts(root)`

The adapter normalizes `markitect-tool` diagnostics into
`MarkdownDiagnostic`, preserving severity, code, message, source, contract,
rule, guidance, and details.

## Contract Selection

`validate_infospace_artifacts()` reads `infospace.yaml` and uses the `schemas`
mapping as artifact-kind contract references:

```yaml
schemas:
  source: contracts/source.contract.md
  generated: contracts/generated.contract.md
```

If no contract is configured for an artifact kind, validation skips that
artifact. If a configured contract path is missing, validation raises a
structured `InfospaceError`.

## CLI

```bash
python3 -m infospace_bench validate infospaces/bootstrap-pilot
```

The command emits JSON:

```json
{
  "valid": true,
  "results": []
}
```

It exits with `0` when all checked artifacts are valid and `1` when any checked
artifact fails validation.

## Boundary Rule

Only `src/infospace_bench/markdown_adapter.py` should import `markitect_tool`.
Other modules should consume adapter results so `infospace-bench` remains an
application layer, not a Markdown toolkit.