Contract robustness and bottleneck test

docs/markitect-tool-integration-usecases.md

@@ -14,7 +14,11 @@ Instead, it should wrap them as adapters and persist engine-owned assets,
 lineage, policy decisions, audit events, and service contracts around them.
 
 The executable companion for this document is
-`tests/test_markitect_tool_contract.py`.
+`tests/test_markitect_tool_contract.py`. The reusable fixture corpus lives in
+`examples/markitect-tool-contract/`.
+Opt-in bottleneck sentinels are described in
+`docs/markitect-tool-capacity-risks.md` and implemented in
+`tests/test_markitect_tool_capacity.py`.
 
 ## Expected Dependency Shape
 
@@ -26,6 +30,22 @@ The executable companion for this document is
 - Persistence posture: store serializable Markitect results and provenance as
   adapter metadata, not as canonical domain objects.
 
+Run the examples against the sibling source checkout during integration
+development with:
+
+```bash
+PYTHONPATH=/home/worsch/kontextual-engine/src:/home/worsch/markitect-tool/src \
+  python3 -m pytest tests/test_markitect_tool_contract.py -q
+```
+
+Run the larger capacity sentinels with:
+
+```bash
+KONTEXTUAL_RUN_CAPACITY=1 \
+PYTHONPATH=/home/worsch/kontextual-engine/src:/home/worsch/markitect-tool/src \
+  python3 -m pytest tests/test_markitect_tool_capacity.py -q
+```
+
 ## Use Case 1: Markdown Normalization
 
 Intent: convert Markdown source content into structured frontmatter, headings,
@@ -207,7 +227,10 @@ Engine expectation:
 | Transform and include provenance | Markdown ops retain Markitect provenance. |
 | Snapshot identity | Engine stores Markitect snapshot metadata without owning the algorithm. |
 | Context package policy filtering | Agent context can reuse Markitect packages and local label policy. |
+| Document contracts | Markdown validation can call Markitect contracts without moving contract semantics into the engine. |
+| Capacity sentinels | Larger generated examples expose likely parser, selector, include, context-package, and snapshot bottlenecks. |
 
-These tests are intentionally small. They are not a replacement for
-`markitect-tool`'s own test suite; they assert only the behaviors this engine
-depends on.
+These tests are intentionally small but example-backed. They are not a
+replacement for `markitect-tool`'s own test suite; they assert only the
+behaviors this engine depends on and provide concrete data for diagnosing
+interface drift.