generated from coulomb/repo-seed
172 lines
4.9 KiB
Markdown
172 lines
4.9 KiB
Markdown
---
|
|
id: MKTT-WP-0010
|
|
type: workplan
|
|
title: "Content References, Processors, and Literate Workflows"
|
|
domain: markitect
|
|
status: todo
|
|
owner: markitect-tool
|
|
topic_slug: markitect
|
|
planning_priority: P1
|
|
planning_order: 55
|
|
depends_on_workplans:
|
|
- MKTT-WP-0004
|
|
depends_on_tasks:
|
|
- MKTT-WP-0003-T006
|
|
informs_workplans:
|
|
- MKTT-WP-0006
|
|
- MKTT-WP-0007
|
|
- MKTT-WP-0008
|
|
- MKTT-WP-0009
|
|
- MKTT-WP-0011
|
|
created: "2026-05-04"
|
|
updated: "2026-05-04"
|
|
state_hub_workstream_id: "7863fd01-0be0-4dbc-9941-0151365bb9e1"
|
|
---
|
|
|
|
# MKTT-WP-0010: Content References, Processors, and Literate Workflows
|
|
|
|
## Purpose
|
|
|
|
Build the richer framework layer for namespaced content references,
|
|
processor-driven Markdown blocks, reversible explode/implode, and literate
|
|
weave/tangle workflows.
|
|
|
|
This preserves the important `markitect-main` ideas that were intentionally not
|
|
pulled into the first transform/compose/include slice.
|
|
|
|
## Background
|
|
|
|
The first P3.5 implementation provides a clean deterministic kernel:
|
|
frontmatter/body/heading transforms, file composition, and explicit include
|
|
markers. That is better for the core toolkit than the old platform-heavy
|
|
implementation, but it leaves out several valuable capabilities:
|
|
|
|
- reversible explode/implode variants
|
|
- named chunks and Knuth-style weave/tangle
|
|
- scoped variables and conditional transclusion
|
|
- stable namespaces and content references
|
|
- processor semantics for fenced blocks
|
|
- reference graphs, provenance, and source maps
|
|
- deterministic multi-inheritance for content classes and overlays
|
|
|
|
See `docs/content-reference-literate-workflow-research.md`.
|
|
|
|
## P10.1 - Define reference address model and namespace rules
|
|
|
|
```task
|
|
id: MKTT-WP-0010-T001
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "f70d2b9d-151b-46c6-9613-bd6bdbf164e7"
|
|
```
|
|
|
|
Define stable content-unit identities, namespace mappings, reference syntax,
|
|
resolver inputs/outputs, and error cases.
|
|
|
|
Output: reference model docs, examples, and tests for path, namespace, selector,
|
|
and ID resolution.
|
|
|
|
## P10.2 - Add token-safe transforms and operation provenance
|
|
|
|
```task
|
|
id: MKTT-WP-0010-T002
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "e35639b7-756f-4993-8b3c-2e58b23e0eca"
|
|
```
|
|
|
|
Make transform/include behavior aware of fenced blocks and parser tokens. Add
|
|
structured operation provenance, dependency edges, source spans, and diagnostics.
|
|
|
|
Output: token-safe transform implementation and provenance result envelope.
|
|
|
|
## P10.3 - Implement named regions and addressable block selectors
|
|
|
|
```task
|
|
id: MKTT-WP-0010-T003
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "98cafe28-a364-48f1-ae55-cb47c71d9441"
|
|
```
|
|
|
|
Support named Markdown/source regions, section IDs, fenced block IDs, and region
|
|
selection by ID/tag/line range where appropriate.
|
|
|
|
Output: region parser/resolver, CLI examples, and source-snippet tests.
|
|
|
|
## P10.4 - Reimplement reversible explode/implode variants
|
|
|
|
```task
|
|
id: MKTT-WP-0010-T004
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "67f77aa1-a7ee-485c-891e-6ae7ecc52067"
|
|
```
|
|
|
|
Recreate the useful `markitect-main` explode/implode functionality with a slim
|
|
variant interface and manifest-first reversibility.
|
|
|
|
Initial variants: flat and hierarchical. Semantic variant can follow once the
|
|
reference and processor model is stable.
|
|
|
|
Output: `mkt explode`, `mkt implode`, manifest schema, roundtrip tests.
|
|
|
|
## P10.5 - Define processor registry for fenced blocks
|
|
|
|
```task
|
|
id: MKTT-WP-0010-T005
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "eb7cde08-8a73-4163-ac54-19a2bc7b5f88"
|
|
```
|
|
|
|
Create a deterministic processor API for fenced blocks and directives.
|
|
Processors should receive content units, resolver access, context, and policy,
|
|
and return generated content/files, diagnostics, dependencies, and provenance.
|
|
|
|
Output: processor registry API, deterministic built-in processors, and tests.
|
|
|
|
## P10.6 - Implement literate weave/tangle MVP
|
|
|
|
```task
|
|
id: MKTT-WP-0010-T006
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "090fcc38-758b-4414-b941-40f217eb17ca"
|
|
```
|
|
|
|
Implement Markdown-native literate workflows: named code chunks, chunk
|
|
references, target files, tangling, and woven documentation with chunk
|
|
cross-references.
|
|
|
|
Output: `mkt tangle`, `mkt weave`, chunk-reference diagnostics, examples.
|
|
|
|
## P10.7 - Design content class composition and multi-inheritance
|
|
|
|
```task
|
|
id: MKTT-WP-0010-T007
|
|
status: todo
|
|
priority: medium
|
|
state_hub_task_id: "220e6b27-2d7b-4c22-b5e8-304198ecfea8"
|
|
```
|
|
|
|
Define content classes, slots, merge policies, and deterministic
|
|
multi-inheritance resolution. Use a C3-like linearization with clear conflict
|
|
diagnostics.
|
|
|
|
Output: architecture note, examples, and a small deterministic resolver spike.
|
|
|
|
## P10.8 - Add migration examples from markitect-main
|
|
|
|
```task
|
|
id: MKTT-WP-0010-T008
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "287637d3-1997-43b2-b97d-10587d565cec"
|
|
```
|
|
|
|
Translate the relevant old explode/implode, transclusion, and spaces reference
|
|
graph tests into successor-style fixtures and examples.
|
|
|
|
Output: migration test inventory, example documents, and parity notes.
|