Quarkdown review and document function extension workplan generation

docs/workplan-planning-map.md

@@ -37,6 +37,7 @@ and descriptions mirror the operational view.
 | `MKTT-WP-0005` | P2 | todo | `MKTT-WP-0003`, `MKTT-WP-0004` | Pick up when generation/form/context or semantic assessment pressure appears. |
 | `MKTT-WP-0011` | P2 | todo | `MKTT-WP-0003`; task-level triggers: `MKTT-WP-0010-T001`, `MKTT-WP-0010-T005` | Declarative Markdown dataflow workflows: source extraction, deterministic/assisted processing, and multi-output generation. |
 | `MKTT-WP-0009` | P2 | todo | `MKTT-WP-0006` | Establish access-control gateway before security-sensitive cache/context use. |
+| `MKTT-WP-0012` | P3 | todo | `MKTT-WP-0004`, `MKTT-WP-0010`, `MKTT-WP-0011` | Future Quarkdown-inspired document function layer: reusable Markdown-native function calls over processors, references, contracts, workflows, and later assisted steps. |
 | `MKTT-WP-0008` | P3 | todo | `MKTT-WP-0006`, `MKTT-WP-0007`, `MKTT-WP-0009` | Agent working-memory cache after backend and policy floor are available. |
 
 ## Dependency Notes
@@ -60,6 +61,12 @@ optional assisted generation hooks, and multiple Markdown outputs. It should not
 block P3.7, but it should follow the first reference model and processor
 registry decisions in `MKTT-WP-0010`.
 
+`MKTT-WP-0012` captures the Quarkdown-inspired document function layer. It
+should follow `MKTT-WP-0011` because the workflow layer will reveal which
+operations deserve author-facing function syntax. It should remain optional and
+capability-gated, especially before assisted, external, file, or network
+functions are allowed.
+
 ## State Hub Mirror
 
 Native State Hub dependency edges should mirror the whole-workstream
@@ -78,6 +85,9 @@ dependencies:
 - `MKTT-WP-0005 -> MKTT-WP-0004`
 - `MKTT-WP-0011 -> MKTT-WP-0003`
 - `MKTT-WP-0009 -> MKTT-WP-0006`
+- `MKTT-WP-0012 -> MKTT-WP-0004`
+- `MKTT-WP-0012 -> MKTT-WP-0010`
+- `MKTT-WP-0012 -> MKTT-WP-0011`
 - `MKTT-WP-0008 -> MKTT-WP-0006`
 - `MKTT-WP-0008 -> MKTT-WP-0007`
 - `MKTT-WP-0008 -> MKTT-WP-0009`

workplans/MKTT-WP-0012-document-function-layer.md

@@ -0,0 +1,256 @@
+---
+id: MKTT-WP-0012
+type: workplan
+title: "Document Function Layer"
+domain: markitect
+status: todo
+owner: markitect-tool
+topic_slug: markitect
+planning_priority: P3
+planning_order: 85
+depends_on_workplans:
+  - MKTT-WP-0004
+  - MKTT-WP-0010
+  - MKTT-WP-0011
+related_workplans:
+  - MKTT-WP-0005
+  - MKTT-WP-0006
+  - MKTT-WP-0007
+  - MKTT-WP-0009
+created: "2026-05-04"
+updated: "2026-05-04"
+state_hub_workstream_id: "f82e74c4-d349-4e9e-80cd-10c0c6d9545d"
+---
+
+# MKTT-WP-0012: Document Function Layer
+
+## Purpose
+
+Design and implement an optional document function layer inspired by
+Quarkdown's rich function language, while keeping Markitect markdown-native,
+contract-aware, provenance-rich, and extension-oriented.
+
+This layer should let authors and agents express reusable document operations
+as named functions over Markdown content, structured data, references,
+processors, contracts, workflows, and eventually assisted generation.
+
+## Background
+
+Quarkdown demonstrates that document authoring can benefit from a compact
+function language with:
+
+- dot-style function calls
+- positional and named arguments
+- block-body arguments that remain readable in Markdown
+- nested and chained calls
+- variables and scoped bindings
+- conditionals, loops, lambdas, and table/data operations
+- rendering-aware helpers for layout, numbering, references, and document setup
+
+For Markitect, the useful idea is not to clone Quarkdown syntax or compiler
+behavior. The useful idea is a disciplined function abstraction:
+
+```text
+document function = named operation + declared inputs + Markdown-friendly body
+                    + output type + capability/policy metadata
+                    + provenance + diagnostics
+```
+
+The layer should sit above existing primitives rather than replace them:
+contracts define expectations, references identify content, processors perform
+deterministic transformations, workflows orchestrate dataflow, backend fabric
+tracks identity/provenance, and access policy gates risky operations.
+
+## Decision
+
+Do not implement this until the deterministic workflow layer has enough shape
+to show real author pressure. Treat it as a future extension track that can
+unify processor ergonomics, workflow steps, contract-aware generation, and
+render/export adapters.
+
+Recommended sequencing:
+
+1. Finish or substantially shape `MKTT-WP-0011`.
+2. Use practical workflow examples to identify recurring author-facing step
+   patterns.
+3. Define the function model as a thin authoring surface over those primitives.
+4. Add assisted and unsafe functions only after capability/policy metadata is
+   enforced.
+
+## P12.1 - Define function model and vocabulary
+
+```task
+id: MKTT-WP-0012-T001
+status: todo
+priority: high
+state_hub_task_id: "13ddfdbb-8fc1-4570-915d-038d40d489e1"
+```
+
+Define a document function descriptor with:
+
+- stable function id and namespace
+- summary and documentation fields
+- positional and named parameters
+- optional/default parameter behavior
+- block-body parameter semantics
+- accepted input types and output type
+- deterministic/assisted/external execution kind
+- capability requirements
+- provenance and diagnostic contract
+
+Output: design note, schema, and small examples.
+
+## P12.2 - Design Markdown-native call syntax
+
+```task
+id: MKTT-WP-0012-T002
+status: todo
+priority: high
+state_hub_task_id: "58166792-457a-4844-96a7-27baf50c1d7e"
+```
+
+Evaluate a conservative syntax that stays close to Markdown and does not break
+CommonMark documents accidentally.
+
+The design should consider:
+
+- inline calls
+- block calls with indented body content
+- named arguments
+- multiline arguments
+- escaping/literal behavior
+- fenced-block alternatives
+- namespace-qualified function names
+- diagnostics for ambiguous parses
+
+Output: syntax proposal with accepted/rejected examples and parser impact.
+
+## P12.3 - Add function registry and adapter boundary
+
+```task
+id: MKTT-WP-0012-T003
+status: todo
+priority: high
+state_hub_task_id: "06196bde-cc10-464e-9d1a-6b8acc616c06"
+```
+
+Create a registry that can expose existing Markitect capabilities as functions
+without moving their core implementation:
+
+- reference resolution
+- selectors and extraction
+- deterministic processors
+- template rendering
+- contract validation
+- workflow steps
+- render/export adapters
+
+Output: registry API, adapter protocol, and tests with fake functions.
+
+## P12.4 - Implement pure deterministic function execution
+
+```task
+id: MKTT-WP-0012-T004
+status: todo
+priority: high
+state_hub_task_id: "986121f0-f824-46eb-af59-65ebf2389f34"
+```
+
+Implement an evaluator for pure deterministic functions only.
+
+It should produce:
+
+- expanded Markdown or structured values
+- source spans and provenance envelopes
+- typed diagnostics
+- cycle/depth limits
+- stable execution traces for caching and test fixtures
+
+Output: minimal evaluator and CLI/library tests.
+
+## P12.5 - Add chaining and data binding semantics
+
+```task
+id: MKTT-WP-0012-T005
+status: todo
+priority: medium
+state_hub_task_id: "94bb131c-cb4e-4391-8453-bb9de4f3834c"
+```
+
+Explore pipeline-style chaining where the previous result becomes the first
+argument of the next function, plus explicit bindings to workflow data products.
+
+This should integrate with `MKTT-WP-0011` expressions rather than create a
+second unrelated expression system.
+
+Output: chaining rules, data binding rules, and diagnostic examples.
+
+## P12.6 - Add contract-aware function validation
+
+```task
+id: MKTT-WP-0012-T006
+status: todo
+priority: medium
+state_hub_task_id: "899d361f-8eaa-4098-97d9-0fd33afc3304"
+```
+
+Allow contracts to declare which functions are permitted, expected, deprecated,
+or forbidden in a document or workflow.
+
+Validation should cover:
+
+- unknown functions
+- wrong arity or argument names
+- wrong input/output type
+- unsafe capability use
+- missing required provenance
+- unstable assisted functions in deterministic contexts
+
+Output: contract integration and actionable diagnostics.
+
+## P12.7 - Define capability and policy gates
+
+```task
+id: MKTT-WP-0012-T007
+status: todo
+priority: medium
+state_hub_task_id: "2a51b42c-b46b-42cd-ba33-ab504100e653"
+```
+
+Integrate with the access-control and backend capability vocabulary before any
+function can read files, access network resources, invoke external processes, or
+call assisted-generation adapters.
+
+Output: permission model, blocked-operation diagnostics, and policy examples.
+
+## P12.8 - Add author-facing examples
+
+```task
+id: MKTT-WP-0012-T008
+status: todo
+priority: medium
+state_hub_task_id: "30358902-5564-48a2-b1e3-e400bfbe7d1a"
+```
+
+Create examples that show practical value:
+
+- reusable document components
+- contract-aware report sections
+- Markdown table filtering/summarization
+- reference-driven transclusion
+- processor pipelines expressed as function chains
+- Quarkdown export preparation without taking a dependency on Quarkdown
+
+Output: examples and comparison notes against Quarkdown-inspired patterns.
+
+## Exit Criteria
+
+- The function layer is optional and does not disturb existing Markdown parsing
+  or deterministic processors.
+- Functions are discoverable, typed enough for diagnostics, and namespace-aware.
+- Pure deterministic functions can be executed and tested without external
+  dependencies.
+- Function calls preserve source provenance and can be explained.
+- Risky capabilities are declared before execution and can be blocked.
+- The model composes naturally with workflows, contracts, references,
+  processors, cache backends, and future assisted steps.