markitect-tool/workplans/MKTT-WP-0010-content-reference-processor-literate-workflows.md

id, type, title, domain, status, owner, topic_slug, planning_priority, planning_order, depends_on_workplans, depends_on_tasks, informs_workplans, created, updated, state_hub_workstream_id

id	type	title	domain	status	owner	topic_slug	planning_priority	planning_order	depends_on_workplans	depends_on_tasks	informs_workplans	created	updated	state_hub_workstream_id
MKTT-WP-0010	workplan	Content References, Processors, and Literate Workflows	markitect	done	markitect-tool	markitect	P1	55	MKTT-WP-0004	MKTT-WP-0003-T006	MKTT-WP-0006 MKTT-WP-0007 MKTT-WP-0008 MKTT-WP-0009 MKTT-WP-0011	2026-05-04	2026-05-04	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

id: MKTT-WP-0010-T001
status: done
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.

Initial implementation completed with a reference extension package, frontmatter namespace loading, root-bounded path resolution, existing query selector reuse, heading/section/block fragment IDs, CLI access via mkt ref resolve, reference docs, examples, and tests. Region/tag/fenced-block addressing continues in P10.3; processor dependency/provenance use continues in P10.2 and P10.5.

P10.2 - Add token-safe transforms and operation provenance

id: MKTT-WP-0010-T002
status: done
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.

Initial implementation completed with token-safe heading shifts, include markers that stay literal inside fenced or indented code blocks, additive OperationProvenance events on transform/include results, dependency edges for resolved includes, docs, and regression tests. Rich structured diagnostics and source maps continue through P10.3, P10.4, and P10.5.

P10.3 - Implement named regions and addressable block selectors

id: MKTT-WP-0010-T003
status: done
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.

Initial implementation completed as reference-layer extensions: named mkt:region comments, region tags, fenced-block IDs and tags from info-string attributes, #line:start-end ranges, convenience ID lookup ordering, docs, examples, and tests. Deeper source maps and processor-owned block semantics continue in P10.5 and P10.6.

P10.4 - Reimplement reversible explode/implode variants

id: MKTT-WP-0010-T004
status: done
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.

Initial implementation completed with a separate explode extension package, manifest-first flat and hierarchical variants, exact roundtrip implode, non-empty output protection, CLI commands, docs, and tests. Semantic variants remain deferred until processor and content-class semantics are stable.

P10.5 - Define processor registry for fenced blocks

id: MKTT-WP-0010-T005
status: done
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.

Initial implementation completed with a deterministic processor extension package, fenced-block discovery, explicit registry, context/policy envelope, result files/diagnostics/dependencies/provenance, built-in identity, uppercase, and reference-backed include processors, CLI mkt process, docs, examples, and tests. Arbitrary code or LLM execution remains intentionally outside this deterministic registry floor.

P10.6 - Implement literate weave/tangle MVP

id: MKTT-WP-0010-T006
status: done
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.

Initial implementation completed with a literate extension package, named fenced code chunks, tangle targets, noweb-style <<chunk-id>> expansion, missing/cyclic chunk diagnostics, deterministic file writing, woven chunk index output, CLI mkt tangle/mkt weave, docs, examples, and tests.

P10.7 - Design content class composition and multi-inheritance

id: MKTT-WP-0010-T007
status: done
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.

Initial implementation completed with a content_class extension package, C3-style deterministic linearization, explicit slot merge policies, conflict diagnostics, CLI mkt class resolve, docs, examples, and tests. Markdown instantiation and snippet injection remain deferred to later integration work.

P10.8 - Add migration examples from markitect-main

id: MKTT-WP-0010-T008
status: done
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.

Initial implementation completed with WP-0010 migration parity notes, successor-style examples for explode/implode, path include, reference-backed transclusion, and literate tangling, plus tests that exercise these examples. Legacy platform, database, infospace, rendering, and provider-specific behaviors remain intentionally out of scope.