infospace-bench/docs/markitect-tool-adapter.md

Markitect Tool Adapter

Date: 2026-05-14

Purpose

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

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:

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

python3 -m infospace_bench validate infospaces/bootstrap-pilot

The command emits 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.