Contract robustness and bottleneck test

examples/markitect-tool-contract/README.md

@@ -0,0 +1,21 @@
+# markitect-tool Contract Examples
+
+This directory is a small interface lab for the `kontextual-engine` dependency
+on `markitect-tool`.
+
+The files are intentionally ordinary Markdown/YAML fixtures rather than inline
+test strings. They should help us validate Markitect behavior before engine
+workplans depend on it, and they should be updated whenever the expected
+integration contract changes.
+
+Covered examples:
+
+- Markdown parsing with frontmatter, headings, sections, lists, and source
+  paths.
+- Selector extraction for sections, frontmatter paths, and blocks.
+- Include resolution, heading shifts, composition, and operation provenance.
+- Snapshot identity for Markdown files.
+- Context-package creation from sources and manifests.
+- Local label policy filtering for public versus internal context.
+- Basic document contract validation for decision records.
+

examples/markitect-tool-contract/composition/context-bundle.md

@@ -0,0 +1,10 @@
+# Kontextual Engine Context Bundle
+
+{{include:../corpus/adr-0001-context-packages.md}}
+
+<!-- mkt:include path="../corpus/engineering-policy.md" selector="sections[heading=Controls]" heading_delta="1" -->
+
+```markdown
+{{include:../corpus/internal-risk-note.md}}
+```
+

examples/markitect-tool-contract/contracts/decision-record.contract.md

@@ -0,0 +1,51 @@
+# Decision Record Contract
+
+```yaml contract
+id: kontextual-decision-record-v1
+document:
+  type: adr
+  title: Architecture Decision Record
+fields:
+  status:
+    type: string
+    required: true
+    enum: [proposed, accepted, superseded]
+  owner:
+    type: string
+    required: true
+metrics:
+  document:
+    words:
+      min: 35
+      max: 500
+      severity: warning
+sections:
+  - id: context
+    title: Context
+    presence: required
+    level: 2
+    order:
+      before: decision
+    assertions:
+      - id: context-names-problem
+        contains_any: [problem, motivation, need]
+        severity: warning
+        guidance: Explain why the decision exists.
+  - id: decision
+    title: Decision
+    presence: required
+    level: 2
+    assertions:
+      - id: decision-commits
+        matches: "\\b(use|adopt|choose|will)\\b"
+        severity: error
+        guidance: State the actual decision.
+  - id: consequences
+    title: Consequences
+    presence: recommended
+    level: 2
+  - id: deprecated
+    title: Deprecated Approach
+    presence: forbidden
+```
+

examples/markitect-tool-contract/corpus/adr-0001-context-packages.md

@@ -0,0 +1,33 @@
+---
+document_type: adr
+status: accepted
+owner: Platform Knowledge
+tags:
+  - context
+  - markdown
+  - governance
+policy:
+  labels: [public, engineering]
+source:
+  system: repo
+  path: examples/markitect-tool-contract/corpus/adr-0001-context-packages.md
+---
+
+# Use Markitect Context Packages
+
+## Context
+
+The problem is that the engine needs Markdown-native structure and context
+packages without owning a second Markdown parser or selector language.
+
+## Decision
+
+We will use markitect-tool as the Markdown syntax, selector, deterministic
+operation, snapshot, and context-package layer for Markdown-backed assets.
+
+## Consequences
+
+- Engine assets stay cross-format and durable.
+- Markdown selectors stay Markitect-owned.
+- Adapter provenance can be stored with engine transformation runs.
+

examples/markitect-tool-contract/corpus/adr-invalid-missing-decision.md

@@ -0,0 +1,18 @@
+---
+document_type: adr
+status: accepted
+owner: Platform Knowledge
+policy:
+  labels: [public, engineering]
+---
+
+# Weak Decision Record
+
+## Context
+
+The note mentions a need but does not contain the required decision section.
+
+## Deprecated Approach
+
+This forbidden section should be reported by the Markitect contract checker.
+

examples/markitect-tool-contract/corpus/engineering-policy.md

@@ -0,0 +1,24 @@
+---
+document_type: policy
+status: active
+owner: Platform Knowledge
+policy:
+  labels: [public, governance]
+source:
+  system: repo
+  path: examples/markitect-tool-contract/corpus/engineering-policy.md
+---
+
+# Engineering Knowledge Policy
+
+## Controls
+
+Published context packages must preserve source paths, source spans, policy
+labels, and enough provenance for the engine to audit how the package was
+assembled.
+
+## Review
+
+Sensitive or high-impact generated artifacts must pass through an engine-owned
+review gate before publication or export.
+

examples/markitect-tool-contract/corpus/internal-risk-note.md

@@ -0,0 +1,22 @@
+---
+document_type: risk-note
+status: draft
+owner: Platform Knowledge
+policy:
+  labels: [internal]
+source:
+  system: repo
+  path: examples/markitect-tool-contract/corpus/internal-risk-note.md
+---
+
+# Internal Retrieval Risk
+
+## Risk
+
+This internal note should not appear in a public context activation.
+
+## Mitigation
+
+Permission filtering must happen before snippets, context packages, or derived
+outputs are returned to a caller.
+

examples/markitect-tool-contract/manifests/agent-context.yaml

@@ -0,0 +1,21 @@
+title: Kontextual Engine Markdown Adapter Context
+intent: Provide public Markdown-backed context for adapter boundary testing.
+namespace:
+  project: kontextual-engine
+  task: markitect-tool-contract
+budget:
+  max_items: 4
+retrieval_recipes:
+  - kind: selector
+    engine: selector
+    query: sections[heading=Decision]
+    sources:
+      - corpus/adr-0001-context-packages.md
+  - kind: selector
+    engine: selector
+    query: sections[heading=Controls]
+    sources:
+      - corpus/engineering-policy.md
+metadata:
+  fixture: markitect-tool-contract
+