@workflow-cannon/workspace-kit 0.18.0 → 0.24.0

package/dist/modules/task-engine/task-type-validation.js

@@ -1,11 +1,51 @@
+import { LEGACY_WISHLIST_ID_METADATA_KEY, WISHLIST_INTAKE_TASK_TYPE } from "./wishlist-intake.js";
+import { WISHLIST_ID_RE } from "./wishlist-validation.js";
 function nonEmptyStringArray(value) {
     return Array.isArray(value) && value.some((entry) => typeof entry === "string" && entry.trim().length > 0);
 }
+function nonEmptyMetaString(metadata, key) {
+    const v = metadata?.[key];
+    return typeof v === "string" && v.trim().length > 0;
+}
 /**
  * Optional strictness for known task types.
  * Unknown/custom task types remain passthrough for compatibility.
  */
 export function validateKnownTaskTypeRequirements(task) {
+    if (task.type === WISHLIST_INTAKE_TASK_TYPE) {
+        const meta = task.metadata;
+        if (!meta || typeof meta !== "object" || Array.isArray(meta)) {
+            return {
+                code: "invalid-task-type-requirements",
+                message: `Type '${task.type}' requires a metadata object with intake fields`
+            };
+        }
+        const m = meta;
+        const need = [
+            "problemStatement",
+            "expectedOutcome",
+            "impact",
+            "constraints",
+            "successSignals",
+            "requestor",
+            "evidenceRef"
+        ];
+        const missing = need.filter((k) => !nonEmptyMetaString(m, k));
+        if (missing.length > 0) {
+            return {
+                code: "invalid-task-type-requirements",
+                message: `Type '${task.type}' requires non-empty metadata fields: ${missing.join(", ")}`
+            };
+        }
+        const legacy = m[LEGACY_WISHLIST_ID_METADATA_KEY];
+        if (legacy !== undefined && (typeof legacy !== "string" || !WISHLIST_ID_RE.test(legacy))) {
+            return {
+                code: "invalid-task-type-requirements",
+                message: `metadata.${LEGACY_WISHLIST_ID_METADATA_KEY} must match W<number> when present`
+            };
+        }
+        return null;
+    }
     if (task.type !== "improvement") {
         return null;
     }

package/dist/modules/task-engine/wishlist-intake.d.ts

@@ -0,0 +1,22 @@
+import type { TaskEntity } from "./types.js";
+import type { WishlistItem } from "./wishlist-types.js";
+/** Task type for ideation items formerly stored as wishlist `W###` rows (Phase 24). */
+export declare const WISHLIST_INTAKE_TASK_TYPE = "wishlist_intake";
+/** Provenance when migrated from legacy wishlist id (`W1`, …). Omitted for net-new intake tasks. */
+export declare const LEGACY_WISHLIST_ID_METADATA_KEY = "legacyWishlistId";
+declare const INTAKE_META_KEYS: readonly ["problemStatement", "expectedOutcome", "impact", "constraints", "successSignals", "requestor", "evidenceRef"];
+export declare function isWishlistIntakeTask(task: TaskEntity): boolean;
+export declare function allocateNextTaskNumericId(tasks: TaskEntity[]): string;
+/**
+ * Build a `wishlist_intake` task from a legacy `WishlistItem`. Caller supplies the new `T###` id.
+ */
+export declare function taskEntityFromWishlistItem(item: WishlistItem, newTaskId: string, now: string): TaskEntity;
+/**
+ * Create a new open wishlist-intake task (no legacy wishlist id). `intake` must pass `validateWishlistIntakePayload` shape except `id` may be omitted.
+ */
+export declare function taskEntityFromNewIntake(intake: Record<string, unknown>, newTaskId: string, now: string, extraMetadata?: Record<string, unknown>): TaskEntity;
+/** Map a `wishlist_intake` task to the wire shape consumers expect from list/get-wishlist. */
+export declare function wishlistIntakeTaskToItem(task: TaskEntity): WishlistItem | null;
+export declare function listWishlistIntakeTasksAsItems(tasks: TaskEntity[]): WishlistItem[];
+export declare function findWishlistIntakeTaskByLegacyOrTaskId(tasks: TaskEntity[], wishlistIdOrTaskId: string): TaskEntity | undefined;
+export { INTAKE_META_KEYS };

package/dist/modules/task-engine/wishlist-intake.js

@@ -0,0 +1,180 @@
+import { WISHLIST_ID_RE } from "./wishlist-validation.js";
+const TASK_ID_RE = /^T\d+$/;
+/** Task type for ideation items formerly stored as wishlist `W###` rows (Phase 24). */
+export const WISHLIST_INTAKE_TASK_TYPE = "wishlist_intake";
+/** Provenance when migrated from legacy wishlist id (`W1`, …). Omitted for net-new intake tasks. */
+export const LEGACY_WISHLIST_ID_METADATA_KEY = "legacyWishlistId";
+const INTAKE_META_KEYS = [
+    "problemStatement",
+    "expectedOutcome",
+    "impact",
+    "constraints",
+    "successSignals",
+    "requestor",
+    "evidenceRef"
+];
+export function isWishlistIntakeTask(task) {
+    return task.type === WISHLIST_INTAKE_TASK_TYPE;
+}
+export function allocateNextTaskNumericId(tasks) {
+    let max = 0;
+    for (const task of tasks) {
+        const m = /^T(\d+)$/.exec(task.id);
+        if (m) {
+            const n = Number(m[1]);
+            if (Number.isFinite(n)) {
+                max = Math.max(max, n);
+            }
+        }
+    }
+    return `T${max + 1}`;
+}
+function wishlistStatusToTaskStatus(status) {
+    if (status === "open") {
+        return "proposed";
+    }
+    if (status === "cancelled") {
+        return "cancelled";
+    }
+    return "completed";
+}
+/**
+ * Build a `wishlist_intake` task from a legacy `WishlistItem`. Caller supplies the new `T###` id.
+ */
+export function taskEntityFromWishlistItem(item, newTaskId, now) {
+    const metadata = {
+        [LEGACY_WISHLIST_ID_METADATA_KEY]: item.id,
+        problemStatement: item.problemStatement,
+        expectedOutcome: item.expectedOutcome,
+        impact: item.impact,
+        constraints: item.constraints,
+        successSignals: item.successSignals,
+        requestor: item.requestor,
+        evidenceRef: item.evidenceRef
+    };
+    if (item.convertedToTaskIds?.length) {
+        metadata.wishlistConvertedToTaskIds = [...item.convertedToTaskIds];
+    }
+    if (item.conversionDecomposition) {
+        metadata.wishlistConversionDecomposition = item.conversionDecomposition;
+    }
+    if (item.convertedAt) {
+        metadata.wishlistConvertedAt = item.convertedAt;
+    }
+    const task = {
+        id: newTaskId,
+        title: item.title,
+        type: WISHLIST_INTAKE_TASK_TYPE,
+        status: wishlistStatusToTaskStatus(item.status),
+        createdAt: item.createdAt,
+        updatedAt: now,
+        metadata
+    };
+    return task;
+}
+/**
+ * Create a new open wishlist-intake task (no legacy wishlist id). `intake` must pass `validateWishlistIntakePayload` shape except `id` may be omitted.
+ */
+export function taskEntityFromNewIntake(intake, newTaskId, now, extraMetadata) {
+    const metadata = {
+        problemStatement: String(intake.problemStatement ?? "").trim(),
+        expectedOutcome: String(intake.expectedOutcome ?? "").trim(),
+        impact: String(intake.impact ?? "").trim(),
+        constraints: String(intake.constraints ?? "").trim(),
+        successSignals: String(intake.successSignals ?? "").trim(),
+        requestor: String(intake.requestor ?? "").trim(),
+        evidenceRef: String(intake.evidenceRef ?? "").trim(),
+        ...(extraMetadata ?? {})
+    };
+    return {
+        id: newTaskId,
+        title: String(intake.title ?? "").trim(),
+        type: WISHLIST_INTAKE_TASK_TYPE,
+        status: "proposed",
+        createdAt: now,
+        updatedAt: now,
+        metadata
+    };
+}
+/** Map a `wishlist_intake` task to the wire shape consumers expect from list/get-wishlist. */
+export function wishlistIntakeTaskToItem(task) {
+    if (!isWishlistIntakeTask(task) || !task.metadata) {
+        return null;
+    }
+    const m = task.metadata;
+    const legacy = m[LEGACY_WISHLIST_ID_METADATA_KEY];
+    const id = typeof legacy === "string" && WISHLIST_ID_RE.test(legacy)
+        ? legacy
+        : task.id;
+    let status = "open";
+    if (task.status === "cancelled") {
+        status = "cancelled";
+    }
+    else if (task.status === "completed") {
+        status = "converted";
+    }
+    const str = (k) => (typeof m[k] === "string" ? m[k] : String(m[k] ?? ""));
+    const item = {
+        id,
+        status,
+        title: task.title,
+        problemStatement: str("problemStatement"),
+        expectedOutcome: str("expectedOutcome"),
+        impact: str("impact"),
+        constraints: str("constraints"),
+        successSignals: str("successSignals"),
+        requestor: str("requestor"),
+        evidenceRef: str("evidenceRef"),
+        createdAt: task.createdAt,
+        updatedAt: task.updatedAt
+    };
+    const convIds = m.wishlistConvertedToTaskIds;
+    if (Array.isArray(convIds) && convIds.every((x) => typeof x === "string")) {
+        item.convertedToTaskIds = convIds;
+    }
+    const dec = m.wishlistConversionDecomposition;
+    if (dec && typeof dec === "object" && !Array.isArray(dec)) {
+        const o = dec;
+        if (typeof o.rationale === "string" &&
+            typeof o.boundaries === "string" &&
+            typeof o.dependencyIntent === "string") {
+            item.conversionDecomposition = {
+                rationale: o.rationale,
+                boundaries: o.boundaries,
+                dependencyIntent: o.dependencyIntent
+            };
+        }
+    }
+    const cat = m.wishlistConvertedAt;
+    if (typeof cat === "string") {
+        item.convertedAt = cat;
+    }
+    return item;
+}
+export function listWishlistIntakeTasksAsItems(tasks) {
+    const out = [];
+    for (const t of tasks) {
+        const row = wishlistIntakeTaskToItem(t);
+        if (row) {
+            out.push(row);
+        }
+    }
+    return out;
+}
+export function findWishlistIntakeTaskByLegacyOrTaskId(tasks, wishlistIdOrTaskId) {
+    const q = wishlistIdOrTaskId.trim();
+    if (!q) {
+        return undefined;
+    }
+    if (TASK_ID_RE.test(q)) {
+        const t = tasks.find((x) => x.id === q);
+        return t && isWishlistIntakeTask(t) ? t : undefined;
+    }
+    if (WISHLIST_ID_RE.test(q)) {
+        return tasks.find((t) => isWishlistIntakeTask(t) &&
+            t.metadata &&
+            t.metadata[LEGACY_WISHLIST_ID_METADATA_KEY] === q);
+    }
+    return undefined;
+}
+export { INTAKE_META_KEYS };

package/dist/modules/task-engine/wishlist-validation.d.ts

@@ -11,6 +11,10 @@ export type WishlistValidationResult = {
  * Validates intake fields for creating or replacing content on an open wishlist item.
  * Wishlist items never carry a Task Engine `phase`; reject if present.
  */
+/**
+ * Validates required wishlist intake strings without requiring a `W###` id (Phase 24 task-backed intake).
+ */
+export declare function validateWishlistContentFields(args: Record<string, unknown>): WishlistValidationResult;
 export declare function validateWishlistIntakePayload(args: Record<string, unknown>): WishlistValidationResult;
 export declare function buildWishlistItemFromIntake(args: Record<string, unknown>, timestamp: string): Omit<WishlistItem, "convertedAt" | "convertedToTaskIds" | "conversionDecomposition">;
 export declare function validateWishlistUpdatePayload(updates: Record<string, unknown>): WishlistValidationResult;

package/dist/modules/task-engine/wishlist-validation.js

@@ -20,6 +20,25 @@ function nonEmptyString(v, label) {
  * Validates intake fields for creating or replacing content on an open wishlist item.
  * Wishlist items never carry a Task Engine `phase`; reject if present.
  */
+/**
+ * Validates required wishlist intake strings without requiring a `W###` id (Phase 24 task-backed intake).
+ */
+export function validateWishlistContentFields(args) {
+    const errors = [];
+    if ("phase" in args && args.phase !== undefined) {
+        errors.push("Wishlist intake must not include 'phase'; only canonical phased tasks use phase.");
+    }
+    for (const key of REQUIRED_STRING_FIELDS) {
+        const s = nonEmptyString(args[key], key);
+        if (s === null) {
+            errors.push(`Wishlist '${key}' is required and must be a non-empty string.`);
+        }
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true };
+}
 export function validateWishlistIntakePayload(args) {
     const errors = [];
     if ("phase" in args && args.phase !== undefined) {

package/dist/modules/workspace-config/index.js

@@ -46,19 +46,16 @@ export const workspaceConfigModule = {
         id: "workspace-config",
         version: "0.4.0",
         contractVersion: "1",
+        stateSchema: 1,
         capabilities: ["diagnostics"],
         dependsOn: [],
+        optionalPeers: [],
         enabledByDefault: true,
         config: {
             path: "src/modules/workspace-config/config.md",
             format: "md",
             description: "Workspace config registry and explain surface."
         },
-        state: {
-            path: "src/modules/workspace-config/state.md",
-            format: "md",
-            description: "Workspace config module runtime state (none)."
-        },
         instructions: {
             directory: "src/modules/workspace-config/instructions",
             entries: [
@@ -85,12 +82,13 @@ export const workspaceConfigModule = {
             };
         }
         const baseCtx = { workspacePath: ctx.workspacePath, registry: reg };
-        if (command.name === "explain-config") {
-            return handleExplainConfig(command.args ?? {}, baseCtx);
-        }
-        if (command.name === "resolve-config") {
-            return handleResolveConfig(command.args ?? {}, baseCtx);
-        }
+        const handlers = {
+            "explain-config": () => handleExplainConfig(command.args ?? {}, baseCtx),
+            "resolve-config": () => handleResolveConfig(command.args ?? {}, baseCtx)
+        };
+        const handler = handlers[command.name];
+        if (handler)
+            return handler();
         return {
             ok: false,
             code: "unknown-command",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow-cannon/workspace-kit",
-  "version": "0.18.0",
+  "version": "0.24.0",
   "private": false,
   "packageManager": "pnpm@10.0.0",
   "license": "MIT",
@@ -19,7 +19,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "check": "tsc -p tsconfig.json --noEmit && node scripts/check-task-engine-run-contracts.mjs",
+    "check": "tsc -p tsconfig.json --noEmit && node scripts/check-task-engine-run-contracts.mjs && node scripts/check-agent-cli-map-coverage.mjs && node scripts/check-orphan-instructions.mjs",
     "clean": "rm -rf dist",
     "test": "pnpm run build && node --test test/**/*.test.mjs",
     "pack:dry-run": "pnpm run build && pnpm pack --pack-destination ./artifacts/workspace-kit-pack",

package/schemas/agent-behavior-profile.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workflow-cannon.dev/schemas/agent-behavior-profile.schema.json",
+  "title": "Agent behavior profile",
+  "description": "Advisory interaction posture for AI agents; subordinate to PRINCIPLES and policy.",
+  "type": "object",
+  "required": ["schemaVersion", "id", "label", "summary", "dimensions"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "id": {
+      "type": "string",
+      "pattern": "^(builtin|custom):[a-z0-9-]+$"
+    },
+    "extends": {
+      "type": "string",
+      "pattern": "^(builtin|custom):[a-z0-9-]+$"
+    },
+    "label": { "type": "string", "minLength": 1, "maxLength": 120 },
+    "summary": { "type": "string", "minLength": 1, "maxLength": 500 },
+    "dimensions": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "deliberationDepth",
+        "changeAppetite",
+        "checkInFrequency",
+        "explanationVerbosity",
+        "explorationStyle",
+        "ambiguityHandling"
+      ],
+      "properties": {
+        "deliberationDepth": { "type": "string", "enum": ["low", "medium", "high"] },
+        "changeAppetite": { "type": "string", "enum": ["conservative", "balanced", "bold"] },
+        "checkInFrequency": { "type": "string", "enum": ["rare", "normal", "often"] },
+        "explanationVerbosity": { "type": "string", "enum": ["terse", "normal", "verbose"] },
+        "explorationStyle": { "type": "string", "enum": ["linear", "parallel"] },
+        "ambiguityHandling": { "type": "string", "enum": ["decide", "ask"] }
+      }
+    },
+    "interactionNotes": { "type": "string", "maxLength": 2000 },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "source": { "type": "string" },
+        "updatedAt": { "type": "string" },
+        "createdAt": { "type": "string" }
+      }
+    }
+  }
+}

package/schemas/task-engine-run-contracts.schema.json

@@ -6,13 +6,13 @@
   "type": "object",
   "required": ["schemaVersion", "packageVersion", "moduleId", "commands"],
   "additionalProperties": false,
-  "packageVersion": "0.18.0",
+  "packageVersion": "0.24.0",
   "properties": {
     "schemaVersion": {
       "const": 1
     },
     "packageVersion": {
-      "const": "0.18.0",
+      "const": "0.24.0",
       "description": "Must match package.json version."
     },
     "moduleId": {
@@ -44,7 +44,10 @@
         "get-next-actions",
         "explain-task-engine-model",
         "migrate-task-persistence",
-        "dashboard-summary"
+        "migrate-wishlist-intake",
+        "dashboard-summary",
+        "get-module-state",
+        "list-module-states"
       ],
       "additionalProperties": false,
       "properties": {
@@ -71,7 +74,10 @@
         "get-next-actions": { "$ref": "#/$defs/contractNextActions" },
         "explain-task-engine-model": { "$ref": "#/$defs/contractExplainTaskEngineModel" },
         "migrate-task-persistence": { "$ref": "#/$defs/contractMigrateTaskPersistence" },
-        "dashboard-summary": { "$ref": "#/$defs/contractDashboardSummary" }
+        "migrate-wishlist-intake": { "$ref": "#/$defs/contractMigrateWishlistIntake" },
+        "dashboard-summary": { "$ref": "#/$defs/contractDashboardSummary" },
+        "get-module-state": { "$ref": "#/$defs/contractGetModuleState" },
+        "list-module-states": { "$ref": "#/$defs/contractListModuleStates" }
       }
     }
   },
@@ -358,7 +364,7 @@
           "properties": {
             "args": {
               "type": "object",
-              "required": ["wishlistId", "decomposition"],
+              "required": ["decomposition", "tasks"],
               "additionalProperties": true
             },
             "responseData": {
@@ -526,6 +532,23 @@
         }
       ]
     },
+    "contractMigrateWishlistIntake": {
+      "allOf": [
+        { "$ref": "#/$defs/contractBase" },
+        {
+          "properties": {
+            "args": {
+              "type": "object",
+              "additionalProperties": true
+            },
+            "responseData": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          }
+        }
+      ]
+    },
     "contractDashboardSummary": {
       "allOf": [
         { "$ref": "#/$defs/contractBase" },
@@ -541,6 +564,7 @@
                 "schemaVersion",
                 "taskStoreLastUpdated",
                 "workspaceStatus",
+                "planningSession",
                 "stateSummary",
                 "readyQueueTop",
                 "readyQueueCount",
@@ -550,6 +574,57 @@
                 "suggestedNext",
                 "blockingAnalysis"
               ],
+              "additionalProperties": true,
+              "properties": {
+                "planningSession": {
+                  "type": ["object", "null"],
+                  "required": [
+                    "schemaVersion",
+                    "updatedAt",
+                    "planningType",
+                    "outputMode",
+                    "status",
+                    "completionPct",
+                    "answeredCritical",
+                    "totalCritical",
+                    "resumeCli"
+                  ],
+                  "additionalProperties": true
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "contractGetModuleState": {
+      "allOf": [
+        { "$ref": "#/$defs/contractBase" },
+        {
+          "properties": {
+            "args": {
+              "type": "object",
+              "additionalProperties": true
+            },
+            "responseData": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          }
+        }
+      ]
+    },
+    "contractListModuleStates": {
+      "allOf": [
+        { "$ref": "#/$defs/contractBase" },
+        {
+          "properties": {
+            "args": {
+              "type": "object",
+              "additionalProperties": true
+            },
+            "responseData": {
+              "type": "object",
               "additionalProperties": true
             }
           }

package/src/modules/documentation/README.md

@@ -1,12 +1,13 @@
 # Documentation Module
 
-Translates between canonical AI-optimized documentation and human-readable maintainership docs.
+Translates between canonical AI-optimized documentation and human-readable maintainership docs using a v2 keyed record pipeline.
 
 Primary responsibilities:
 
 - maintain parity between `/.ai` and configured human docs roots (default: `docs/maintainers`)
 - execute instruction-file driven documentation generation
 - record deterministic documentation generation state and evidence
+- render human docs via view models and named deterministic renderers
 
 See `src/modules/documentation/RULES.md` for the canonical usage order and validation rules.
 
@@ -14,27 +15,17 @@ See `src/modules/documentation/RULES.md` for the canonical usage order and valid
 
 Registered on the documentation module and dispatched through `src/core/module-command-router.ts`:
 
-- `document-project` — batch: generate **all** project docs from the template library. Outputs AI docs to `.ai/` (preserving existing) and human docs to `docs/maintainers/` (overwriting). Continues through failures; reports batch summary. See `instructions/document-project.md`.
-- `generate-document` — single: generate **one** document by `documentType`. See `instructions/generate-document.md`.
-
-## Shipped templates
-
-Files under `templates/`; `documentType` is the filename (basename). Keep this list aligned with `instructions/document-project.md` **Inputs**:
-
-- `AGENTS.md`
-- `ARCHITECTURE.md`
-- `PRINCIPLES.md`
-- `README.md`
-- `RELEASING.md`
-- `ROADMAP.md`
-- `SECURITY.md`
-- `SUPPORT.md`
-- `TERMS.md`
-- `runbooks/parity-validation-flow.md`
-- `runbooks/consumer-cadence.md`
-- `runbooks/release-channels.md`
-- `workbooks/transcript-automation-baseline.md`
-- `workbooks/phase2-config-policy-workbook.md`
-- `workbooks/task-engine-workbook.md`
-
-Adding a new template: add `templates/<Name>.md`, extend the **Inputs** list in `instructions/document-project.md`, and add the same line here.
+- `document-project` — batch: generate all docs from `views/*.view.yaml` (with template fallback for fixture workspaces). See `instructions/document-project.md`.
+- `generate-document` — single: generate one document by `documentType` and render through parser -> validator -> normalizer -> renderer. See `instructions/generate-document.md`.
+
+## File layout
+
+- `parser.ts` - keyed record parsing from AI docs
+- `validator.ts` - schema/rule validation and auto-resolution
+- `normalizer.ts` - typed normalized model + record indexes
+- `renderer.ts` - deterministic named markdown renderers
+- `view-models.ts` - view model loader and listing
+- `views/*.view.yaml` - rendering section contracts per document target
+- `runtime.ts` - orchestration and IO only
+
+Adding a new document target: add/adjust `.ai/<doc>.md` source, create/update matching `views/*.view.yaml`, and ensure a matching template exists if section-coverage checks require it.

package/src/modules/documentation/RULES.md

@@ -12,7 +12,7 @@ When guidance conflicts, apply this order:
 4. `src/modules/documentation/instructions/document-project.md` (document generation workflow)
 5. `src/modules/documentation/instructions/documentation-maintainer.md` (AI-doc generation policy)
 6. `src/modules/documentation/schemas/documentation-schema.md` (record schema contract)
-7. `src/modules/documentation/templates/*.md` (document-type generation templates)
+7. `src/modules/documentation/views/*.view.yaml` (document-type rendering contracts)
 8. `docs/maintainers/module-build-guide.md` (human-readable companion guidance)
 
 ## Usage Model
@@ -20,15 +20,15 @@ When guidance conflicts, apply this order:
 - Choose an instruction entry from `instructions/` for the operation you want.
 - Discover available callable module operations through `src/core/module-command-router.ts` command listing.
 - Load module config first and restrict writes to configured document paths.
-- If a matching template exists, use it as the structure contract.
-- For templates with `{{{ ... }}}` blocks, treat block content as generation instructions, not output text.
-- Generate AI-surface content first, then generate human-surface content from that result plus project context.
+- Resolve view model definitions first and treat them as the section/renderer contract.
+- Generate AI-surface content first, then parse/validate/normalize records before human rendering.
+- Human rendering must use named deterministic renderers only.
 
 ## Command Contracts
 
 ### `document-project(options)` — batch
 
-Generates all project docs by iterating every `.md` template in `sources.templatesRoot`.
+Generates all project docs by iterating every `.view.yaml` in `src/modules/documentation/views` (falls back to template discovery in fixture workspaces without views).
 
 - Default behavior: **preserve AI docs** (`overwriteAi: false`), **overwrite human docs** (`overwriteHuman: true`), continue on individual failure.
 - Returns batch summary with total/succeeded/failed/skipped counts plus per-document results.
@@ -37,7 +37,7 @@ Generates all project docs by iterating every `.md` template in `sources.templat
 
 Generates one document pair (AI + human) for the given `documentType`.
 
-- `documentType`: required string basename resolving to `<templatesRoot>/<documentType>`.
+- `documentType`: required string basename resolving to both AI and human output targets.
 - `options`:
   - `dryRun?: boolean` (default `false`) - compute outputs/validations without writing files
   - `overwrite?: boolean` (default `true`) - allow replacing existing files (both surfaces)
@@ -46,19 +46,19 @@ Generates one document pair (AI + human) for the given `documentType`.
   - `strict?: boolean` (default `true`) - fail on unresolved warnings (validation/conflict/coverage)
   - `maxValidationAttempts?: number` (default from config) - override retry limit
   - `allowWithoutTemplate?: boolean` (default `false`) - continue without template only when explicitly confirmed
-- Shipped template basenames are listed in `instructions/generate-document.md` and `instructions/document-project.md`.
+- Shipped view model files are listed by `listViewModels()` in `view-models.ts`.
 
 ### Shared semantics
 
 - Both commands read paths from module config (`sources.aiRoot`, `sources.humanRoot`, `sources.templatesRoot`, `sources.instructionsRoot`, `sources.schemasRoot`).
 - Both enforce write boundaries to configured output roots only.
-- Both execute AI generation first, then human generation from AI output plus project context.
+- Both execute AI generation first, then human generation from parsed+normalized AI output plus view-model renderers.
 - Both return evidence objects containing files read/written, validations, retries, warnings/conflicts, and timestamp.
 
 ## Required Validation
 
 - Validate AI output against `schemas/documentation-schema.md`.
-- Verify section coverage for templated documents and ensure no unresolved `{{{` blocks remain.
+- Verify section coverage for template-backed content and ensure no unresolved `{{{` blocks remain.
 - Detect conflicts against higher-precedence sources and stop/prompt when required.
 - Emit run evidence (inputs, outputs, validation results, timestamp).