markitect-tool integration

docs/markitect-tool-adapter.md

@@ -0,0 +1,68 @@
+# 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.