---
id: MKTT-WP-0003
type: workplan
title: "Core Markdown Toolkit Implementation"
domain: markitect
status: done
owner: markitect-tool
topic_slug: markitect
planning_priority: P0
planning_order: 40
depends_on_workplans:
  - MKTT-WP-0001
  - MKTT-WP-0002
  - MKTT-WP-0004
created: "2026-05-03"
updated: "2026-05-04"
state_hub_workstream_id: "9fefb57d-985e-4125-8daf-03554844f45e"
---

# MKTT-WP-0003: Core Markdown Toolkit Implementation

## Purpose

Build the first usable `markitect-tool` implementation around the PRD/FRS
contract and the `mkt` CLI.

## P3.1 - Bootstrap package and tests

```task
id: MKTT-WP-0003-T001
status: done
priority: high
state_hub_task_id: "9d9501fe-6809-4b4f-bda6-ec5e5952ddc7"
```

Create project metadata, package layout, test structure, and a minimal CLI
entry point that can be installed or run locally.

Output: `pyproject.toml`, `src/markitect_tool/`, `tests/`.

## P3.2 - Implement structured markdown parse contract

```task
id: MKTT-WP-0003-T002
status: done
priority: high
state_hub_task_id: "7dead033-e249-46b0-9eb3-908ae231a987"
```

Implement FR-001 and FR-002: parse markdown files, preserve headings,
frontmatter, sections, and content blocks, and expose structured output via
API and CLI.

Initial implementation complete for Markdown files, YAML frontmatter, headings,
sections, content blocks, parser tokens, API access, and `mkt parse`.

## P3.3 - Implement schema load and validation

```task
id: MKTT-WP-0003-T003
status: done
priority: high
state_hub_task_id: "36a22def-d415-4c08-a793-836ee52e4308"
```

Implement FR-010 through FR-012: define/derive schemas, validate documents,
and report structured violations with file/location context.

Initial implementation complete for Markdown schema loading, JSON Schema
validation, structured violations, `mkt validate`, and `mkt schema validate`.

## P3.4 - Implement query and extraction

```task
id: MKTT-WP-0003-T004
status: done
priority: medium
state_hub_task_id: "e4f72218-601e-488f-a5df-171b91a747d2"
```

Implement FR-030 and FR-031 over the structured representation. Start with a
small query language or JSONPath-like adapter only if it remains simple.

Initial implementation complete for simple selectors over frontmatter,
headings, sections, blocks, and metrics, with API access plus `mkt query` and
`mkt extract`.

## P3.5 - Implement transform, compose, and include primitives

```task
id: MKTT-WP-0003-T005
status: done
priority: medium
state_hub_task_id: "205d69eb-dd34-46a5-af0b-cc2de9d213d0"
```

Implement FR-020 through FR-022 as deterministic document operations. Keep
transclusion syntax and resolution rules explicit and testable.

Initial implementation complete for deterministic frontmatter/body/heading
transforms, file composition, Markdown-native include/transclusion markers,
recursive include resolution, cycle/path safety checks, API access, docs, tests,
and `mkt transform`, `mkt compose`, and `mkt include`.

## P3.6 - Implement templating and generation hooks

```task
id: MKTT-WP-0003-T006
status: done
priority: medium
state_hub_task_id: "307fa072-b1ce-42e8-9309-e2a92e130ae1"
```

Implement FR-040 through FR-042 with deterministic templates first and optional
LLM-assisted hooks supplied by external providers.

Extension point: `EP-MKTT-001`.

Keep this slice focused on deterministic templates and generation hooks. Rich
processors, named chunks, weave/tangle, namespaces, and content-class
inheritance are captured in `MKTT-WP-0010` after this hook surface is clear.

Initial implementation complete for deterministic `{{field.path}}` templates,
template inspection, strict/lenient rendering, JSON/YAML/CSV data loading,
contract-based stub generation, Markdown/YAML generation plans, provider-neutral
generation hook protocols, docs, examples, tests, `mkt template inspect`,
`mkt template render`, `mkt generate stub`, and `mkt generate rules`.

## P3.7 - Add caching and incremental processing

```task
id: MKTT-WP-0003-T007
status: done
priority: low
state_hub_task_id: "236f90e3-1d79-473f-8c57-bcbbde9ece02"
```

Implement FR-070 and FR-071 after the parse/schema contracts are stable.

Initial implementation complete for lightweight file-backed cache manifests,
SHA-256 content fingerprints, parse summaries, new/changed/deleted detection,
CLI access via `mkt cache fingerprint`, `mkt cache build`, and
`mkt cache status`, docs, and tests. Rich AST/query/index caching remains
tracked in `MKTT-WP-0006` and `MKTT-WP-0007`.

## Known Technical Debt

```task
id: MKTT-WP-0003-T008
status: done
priority: medium
state_hub_task_id: "94067c7e-e68b-45be-a1d6-90547eb15422"
```

Resolve `TD-MKTT-001` by adding the implementation scaffold: package metadata,
module layout, test runner, and `mkt` CLI entry point.

Resolved by the initial package scaffold.