[codex] Fix slide deck MCP export provenance

README.md

@@ -101,6 +101,8 @@ npm run mcp:smoke
 judgmentkit review --input examples/refund-triage.brief.txt
 ```
 
+For JudgmentKit slide deck planning and local PPTX export from Codex Desktop, use the receipt-backed MCP workflow in `docs/slide-deck-mcp.md`.
+
 For a hosted MCP install:
 
 ```bash

docs/slide-deck-mcp.md

@@ -0,0 +1,149 @@
+# JudgmentKit Slide Deck MCP Export
+
+Use `create_slide_deck` only when the user explicitly asks JudgmentKit to create or plan a deck. Primary slide content should use domain language. Do not put prompts, schemas, MCP tool names, resource ids, traces, or model configuration into slide copy unless the deck is explicitly for setup, debugging, auditing, or integration work.
+
+## Path Contract
+
+`output.path` is always repo-relative and must stay under:
+
+```text
+outputs/judgmentkit-slide-decks/
+```
+
+For local PPTX export from Codex Desktop, pass the active workspace root separately:
+
+```json
+{
+  "output": {
+    "path": "outputs/judgmentkit-slide-decks/repro-minimal.pptx"
+  },
+  "runtime": {
+    "workspace_root": "/absolute/path/to/active/workspace",
+    "artifact_tool_package": "/absolute/path/to/@oai/artifact-tool"
+  }
+}
+```
+
+If `workspace_root` is missing and the MCP runtime cannot determine a safe active workspace, export fails with `workspace_root_missing`. The tool must not silently write under `/var/task`, `.codex`, or the bundled Codex runtime cache.
+
+## Minimal Codex Desktop Example
+
+First plan the deck without writing a file:
+
+```json
+{
+  "deck": {
+    "deck_id": "quarterly-review",
+    "title": "Quarterly review"
+  },
+  "slides": [
+    {
+      "template_id": "slide-21",
+      "content": {
+        "title": "Quarterly review",
+        "subtitle": "Evidence and decisions for the product team."
+      }
+    }
+  ],
+  "dry_run": true
+}
+```
+
+Then export from a local runtime:
+
+```json
+{
+  "deck": {
+    "deck_id": "quarterly-review",
+    "title": "Quarterly review"
+  },
+  "output": {
+    "path": "outputs/judgmentkit-slide-decks/quarterly-review.pptx"
+  },
+  "runtime": {
+    "workspace_root": "/Users/mike/example-workspace",
+    "artifact_tool_package": "/Users/mike/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/node_modules/@oai/artifact-tool"
+  },
+  "dry_run": false,
+  "slides": [
+    {
+      "template_id": "slide-21",
+      "content": {
+        "title": "Quarterly review",
+        "subtitle": "Evidence and decisions for the product team."
+      }
+    }
+  ]
+}
+```
+
+A successful export returns `deck_creation_status: "exported"`, `artifact_ref`, and `provenance_receipt`. The tool also writes a sidecar receipt next to the PPTX, for example:
+
+```text
+outputs/judgmentkit-slide-decks/quarterly-review.pptx.receipt.json
+```
+
+Treat dry-run planning as JudgmentKit guidance when the MCP response uses `schema: "judgmentkit.mcp.slide-deck/v1"` and `deck_creation_status: "planned"`.
+
+Treat a deck as JudgmentKit-generated only when the MCP response or sidecar receipt confirms:
+
+```json
+{
+  "tool_name": "mcp__judgmentkit.create_slide_deck",
+  "deck_creation_status": "exported",
+  "sha256": "<matching PPTX SHA-256>",
+  "bytes": 12345,
+  "mime_type": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  "adapter_manifest_id": "judgmentkit.presentation-theme.adapter-v1",
+  "template_registry_version": "0.1.0"
+}
+```
+
+## Portfolio Or Case-Study Example
+
+For portfolio, pitch, and case-study decks, pass explicit `template_id` values or strong `selection` metadata. Do not rely on broad defaults when layout variety matters.
+
+```json
+{
+  "deck": {
+    "deck_id": "case-study-review",
+    "title": "Case study review"
+  },
+  "output": {
+    "path": "outputs/judgmentkit-slide-decks/case-study-review.pptx"
+  },
+  "runtime": {
+    "workspace_root": "/Users/mike/example-workspace",
+    "artifact_tool_package": "/Users/mike/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/node_modules/@oai/artifact-tool"
+  },
+  "dry_run": false,
+  "slides": [
+    {
+      "template_id": "slide-21",
+      "content": { "title": "Case study review", "subtitle": "Decision context and outcomes." }
+    },
+    {
+      "template_id": "slide-06",
+      "content": { "title": "Problem and solution", "body": "Compare the starting constraint with the repaired workflow." }
+    },
+    {
+      "template_id": "slide-08",
+      "content": { "title": "Evidence table", "rows": [{ "signal": "Review debt", "value": "Rising" }] }
+    },
+    {
+      "template_id": "slide-64",
+      "content": { "title": "Trend evidence", "chart": { "type": "line" } }
+    },
+    {
+      "template_id": "slide-62",
+      "content": { "title": "Outcome metrics", "metrics": [{ "label": "Saved time", "value": "32%" }] }
+    },
+    {
+      "template_id": "slide-80",
+      "content": { "title": "Recommendation", "body": "Name the next decision and owner." }
+    }
+  ]
+}
+```
+
+For decks with at least four slides, if more than half the deck uses the same layout or layout family, the response includes a repetition warning with suggested template families.

packages/codex-plugin/skills/judgmentkit-hosted-mcp/SKILL.md

@@ -25,7 +25,9 @@ Before calling a deck creation MCP tool, establish:
 - required output format and delivery path
 - confidentiality boundary for hosted processing
 
-When the active JudgmentKit MCP server exposes a deck creation tool, call it with the reviewed activity context and allowed source material. Keep primary slide copy in domain language and do not expose prompts, schemas, resource ids, MCP server names, tool names, traces, or model configuration in slide content.
+When the active JudgmentKit MCP server exposes a deck creation tool, call it with the reviewed activity context and allowed source material. Keep primary slide copy in domain language and do not expose prompts, schemas, resource ids, MCP server names, tool names, traces, or model configuration in slide content. For local PPTX export, use a repo-relative `output.path` and pass the active workspace root separately through the tool runtime when required.
+
+Treat dry-run deck planning as JudgmentKit guidance when the MCP response uses `schema: "judgmentkit.mcp.slide-deck/v1"` and `deck_creation_status: "planned"`. Treat an exported PPTX as JudgmentKit output only when the MCP response or sidecar receipt confirms `tool_name: "mcp__judgmentkit.create_slide_deck"`, `deck_creation_status: "exported"`, and matching `sha256`, `bytes`, and `mime_type` artifact fields. A folder named `outputs/judgmentkit-slide-decks` is not provenance by itself.
 
 If no deck creation tool is listed by the active endpoint, state that the current JudgmentKit endpoint cannot create the deck yet. Do not fabricate a JudgmentKit packet, deck, or MCP result. Continue only with a deterministic outline or requirements summary if the user wants that fallback.
 
@@ -85,8 +87,9 @@ For slide deck requests:
 1. Confirm the deck audience, purpose, source material, confidentiality boundary, and target format from the brief or local context.
 2. Use the activity contract to keep the deck focused on the participant decision and outcome, not implementation machinery.
 3. Call the deck creation MCP tool when it is available from the active endpoint.
-4. Treat returned deck guidance or artifacts as JudgmentKit output only when they came from the MCP tool.
-5. Review slide copy for disclosure discipline before handoff: primary slides should use domain language, while prompts, schemas, resource ids, MCP details, traces, and model configuration stay out of the deck unless the deck is explicitly for setup, debugging, auditing, or integration.
+4. Treat dry-run deck planning as JudgmentKit guidance when the MCP response uses `schema: "judgmentkit.mcp.slide-deck/v1"` and `deck_creation_status: "planned"`; treat exported PPTX artifacts as JudgmentKit output only when the MCP response or sidecar receipt confirms `tool_name: "mcp__judgmentkit.create_slide_deck"`, `deck_creation_status: "exported"`, and matching `sha256`, `bytes`, and `mime_type` artifact fields.
+5. For portfolio or case-study decks, pass explicit `template_id` values or strong selection metadata when layout variety matters; heed layout repetition warnings.
+6. Review slide copy for disclosure discipline before handoff: primary slides should use domain language, while prompts, schemas, resource ids, MCP details, traces, and model configuration stay out of the deck unless the deck is explicitly for setup, debugging, auditing, or integration.
 
 ## Activity Contract