diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..6a203ec --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,137 @@ +# SCOPE + +> This file helps humans and agents understand when this repository is useful, +> what it owns, and where its boundaries stop. + +--- + +## One-liner + +markitect-quarkdown provides the concrete Quarkdown render/export adapter for +Markitect while keeping Quarkdown runtime behavior outside the core toolkit. + +--- + +## Core Idea + +This repo bridges Markitect render/export requests to Quarkdown execution. It +maps Markitect profiles to Quarkdown profiles, builds controlled execution +plans, models runtime permissions, validates generated artifacts, and exposes +the adapter through the Markitect render/export entry point. + +--- + +## In Scope + +- `render.quarkdown` adapter descriptor and package entry point. +- Markitect profile to Quarkdown profile mapping. +- Controlled Quarkdown CLI execution plan construction. +- Permission and runtime dependency documentation. +- Generated artifact validation, checksums, examples, and integration metadata. + +--- + +## Out of Scope + +- Forking, reimplementing, or vendoring Quarkdown. +- Markitect core render/export contract ownership. +- Source extraction from EPUB3, PDF, or other input formats. +- Public rendering services, hosting, or remote job orchestration. +- Making `markitect-tool` depend directly on Quarkdown. + +--- + +## Relevant When + +- You need Markitect render/export behavior backed by Quarkdown. +- You are testing adapter-boundary behavior with fake or real Quarkdown runtime + execution. +- You need profile, permission, runtime, or generated artifact handling for + Quarkdown outputs. +- You are maintaining the `render.quarkdown` adapter entry point. + +--- + +## Not Relevant When + +- The work changes the generic Markitect render/export contract. +- The task is source normalization before a Markitect document exists. +- The desired renderer is not Quarkdown. +- You only need core Markdown parsing, querying, or validation. + +--- + +## Current State + +- Status: active. +- Implementation: Python 3.12 package with adapter code, docs, examples, + integration metadata, and tests. +- Stability: fake-execution adapter tests are covered; real runtime smoke tests + skip when `quarkdown` is unavailable. +- Integration: registered in the Custodian State Hub as + `markitect-quarkdown`. + +--- + +## How It Fits + +- Upstream contract: `markitect-tool` owns render/export adapter interfaces. +- Runtime dependency: Quarkdown CLI provides concrete rendering behavior when + installed. +- Adjacent repo: `markitect-filter` owns source adapters on the input side. + +--- + +## Terminology + +- Preferred terms: render/export adapter, Quarkdown profile, execution plan, + permission mapping, generated artifact. +- Also known as: Quarkdown Markitect adapter. +- Potentially confusing terms: "profile" here is a render/export configuration + profile, not a user profile. + +--- + +## Related / Overlapping + +- `markitect-tool` - owns core render/export adapter contracts. +- `markitect-filter` - owns concrete source-format adapters. +- `the-custodian` - State Hub registration, workplan tracking, and consistency + sync. + +--- + +## Getting Oriented + +- Start with: `README.md`, `docs/adapter-boundary.md`, and + `docs/profile-matrix.md`. +- Key directories: `src/markitect_quarkdown/`, `tests/`, `docs/`, + `integration/`, and `workplans/`. +- Entry point: + `markitect_quarkdown.adapter:quarkdown_adapter_descriptor`. + +--- + +## Provided Capabilities + +```capability +type: render_export_adapter +title: render.quarkdown +description: Produce Quarkdown-backed render/export execution plans and artifact metadata for Markitect requests. +keywords: [quarkdown, render, export, adapter, artifacts] +``` + +```capability +type: integration +title: quarkdown_runtime_boundary +description: Document and validate Quarkdown runtime permissions, profile mapping, and generated artifact checksums. +keywords: [quarkdown, runtime, permissions, profiles, checksums] +``` + +--- + +## Notes + +Run tests with `PYTHONPATH=src:/home/worsch/markitect-tool/src python3 -m +pytest` from this checkout. Real Quarkdown smoke coverage depends on a local +`quarkdown` command being available.