Deterministic templating and generation support

docs/template-generation.md

@@ -0,0 +1,89 @@
+# Templates and Generation Hooks
+
+`markitect-tool` keeps generation deterministic in core. LLM-assisted
+generation is represented as an external hook boundary, not as a provider
+dependency.
+
+## Template Variables
+
+Templates use simple double-brace variables:
+
+```markdown
+# {{title}}
+
+Owner: {{owner.name}}
+
+{{body}}
+```
+
+Variables can use dot paths into JSON/YAML data.
+
+```bash
+mkt template inspect template.md
+mkt template render template.md --data data.yaml --output rendered.md
+mkt template render template.md --set title="Draft" --set owner.name=Ada
+```
+
+Strict rendering is the default. Use `--lenient` to keep unresolved
+placeholders in place.
+
+## Contract Stubs
+
+Contracts can generate first-draft Markdown stubs:
+
+```bash
+mkt generate stub --contract examples/contracts/adr.contract.md --set status=proposed
+```
+
+The stub generator creates frontmatter from contract fields and emits required
+and recommended sections. Forbidden sections are skipped.
+
+## Rule-Based Generation
+
+A generation plan is a Markdown file with a fenced YAML block:
+
+````markdown
+# Letter Generation
+
+```yaml generation
+template: templates/letter.md
+data_file: data/letter.yaml
+output: out/letter.md
+```
+````
+
+Run it with:
+
+```bash
+mkt generate rules rules.md --output-dir .
+```
+
+The `documents` key can render multiple outputs:
+
+```yaml
+documents:
+  - template: templates/letter.md
+    data:
+      title: First
+    output: out/first.md
+  - template: templates/letter.md
+    data_file: data/second.yaml
+    output: out/second.md
+```
+
+## Assisted Generation Hook
+
+FR-042 is supported as a protocol boundary. External packages can implement a
+hook with:
+
+```python
+from markitect_tool.generation import GenerationHookRequest, GenerationHookResult
+
+class MyHook:
+    def generate(self, request: GenerationHookRequest) -> GenerationHookResult:
+        ...
+```
+
+Core does not call an LLM provider by itself. Higher layers can pass a hook into
+`generate_with_hook(...)` after handling credentials, policy, and provider
+selection.

docs/workplan-planning-map.md

@@ -30,9 +30,9 @@ and descriptions mirror the operational view.
 | `MKTT-WP-0001` | complete | done | none | Repository foundation is complete. |
 | `MKTT-WP-0002` | complete | done | `MKTT-WP-0001` | Legacy scope extraction is complete. |
 | `MKTT-WP-0004` | complete | done | `MKTT-WP-0001`, `MKTT-WP-0002` | Contract framework is complete and informs later validation/generation work. |
-| `MKTT-WP-0003` | P0 | active | `MKTT-WP-0001`, `MKTT-WP-0002`, `MKTT-WP-0004` | Mainline implementation. P3.5 is complete; continue with P3.6 templating/generation hooks. |
+| `MKTT-WP-0003` | P0 | active | `MKTT-WP-0001`, `MKTT-WP-0002`, `MKTT-WP-0004` | Mainline implementation. P3.6 is complete; P3.7 caching remains. |
 | `MKTT-WP-0006` | P1 | todo | `MKTT-WP-0004`; task-level trigger: `MKTT-WP-0003-T005` | Ready after transform/composition shape is clear; should account for future reference/provenance needs. |
-| `MKTT-WP-0010` | P1 | todo | `MKTT-WP-0004`; task-level trigger: `MKTT-WP-0003-T006` | Preserve richer content-reference, processor, explode/implode, and weave/tangle architecture after P3.6. |
+| `MKTT-WP-0010` | P1 | todo | `MKTT-WP-0004`; task-level trigger: `MKTT-WP-0003-T006` | Trigger is satisfied; keep as the richer content-reference, processor, explode/implode, and weave/tangle track. |
 | `MKTT-WP-0007` | P2 | todo | `MKTT-WP-0006` | First practical cache backend use case: AST/JSONPath/SQLite/FTS. |
 | `MKTT-WP-0005` | P2 | todo | `MKTT-WP-0003`, `MKTT-WP-0004` | Pick up when generation/form/context or semantic assessment pressure appears. |
 | `MKTT-WP-0009` | P2 | todo | `MKTT-WP-0006` | Establish access-control gateway before security-sensitive cache/context use. |
@@ -46,10 +46,9 @@ It should wait until `MKTT-WP-0003-T005` gives transform/composition enough
 shape to know what cached identities and invalidation rules must preserve.
 
 The second important nuance is `MKTT-WP-0010`: it captures richer content
-reference, processor, explode/implode, and weave/tangle work. It should wait
-until `MKTT-WP-0003-T006` defines the deterministic templating/generation hook
-surface, but it should inform backend, index, context-memory, and access-control
-architecture before those become rigid.
+reference, processor, explode/implode, and weave/tangle work. Its task-level
+trigger `MKTT-WP-0003-T006` is now satisfied. It should inform backend, index,
+context-memory, and access-control architecture before those become rigid.
 
 These are mixed task/workstream dependencies. State Hub does not currently model
 them natively.