Included run manifest schema to check prompt dependency resolution against later

roadmap/prompt-dependency-resolution/RunManifestSchema.md

@@ -0,0 +1,305 @@
+RunManifestSchema
+
+*Prompt run tracking*
+
+# RunManifestSchema v0.1
+# Purpose:
+# - Record a PromptRun end-to-end (TemplateAnalysis → ContextCompilation → PromptProcessing)
+# - Provide deterministic dependency tracking for incremental recompute (spreadsheet/build-system style)
+# - Support Generate-macros via nested PromptRuns
+# - Capture validation/quality outcomes and "impact debt" when recompute is suppressed (cycles/depth)
+
+$schema: "https://markitect.dev/schemas/run-manifest/v0.1"  # optional identifier
+schema_version: "0.1"
+
+# ----------------------------
+# Top-level identity & timing
+# ----------------------------
+run_id: "uuid-or-content-address"         # unique per run (uuid ok; content-addressed optional)
+run_type: "PromptRun"                     # reserved for future (e.g., ValidatorRun)
+created_at: "2026-02-08T19:12:34+01:00"   # ISO8601, Europe/Berlin
+status: "succeeded"                       # enum: succeeded | failed | partial | skipped
+
+# ----------------------------
+# Where this run happened
+# ----------------------------
+execution_context:
+  engine: "MarkiTect"
+  engine_version: "0.0.0"                 # semantic version or git hash
+  workspace_id: "coulomb-social-workspace-id"  # optional
+  information_space_id: "space:my-topic"  # the primary InformationSpace this run targets
+  resolver_config_id: "resolver:default"  # identifies PromptResolver ruleset used
+
+# ----------------------------
+# Stage breakdown (conceptual)
+# ----------------------------
+stages:
+  - name: "TemplateAnalysis"
+    started_at: "2026-02-08T19:12:34+01:00"
+    ended_at: "2026-02-08T19:12:35+01:00"
+    status: "succeeded"
+  - name: "ContextCompilation"
+    started_at: "2026-02-08T19:12:35+01:00"
+    ended_at: "2026-02-08T19:12:38+01:00"
+    status: "succeeded"
+  - name: "PromptProcessing"
+    started_at: "2026-02-08T19:12:38+01:00"
+    ended_at: "2026-02-08T19:12:44+01:00"
+    status: "succeeded"
+
+# ----------------------------
+# Template used (the "formula")
+# ----------------------------
+template:
+  prompt_template_name: "IllustratorPrompt"      # name referenced by user/UI
+  prompt_template_artifact:                      # resolved artifact for the template itself
+    artifact_id: "artifact:IllustratorPrompt.md" # stable ID in MarkiTect
+    information_space_id: "space:my-topic"       # where it was found (local/default/etc)
+    path: "prompts/IllustratorPrompt.md"         # optional
+    content_digest: "sha256:..."                 # digest of template content
+    version_ref: "git:abc123"                    # optional, if versioned
+  template_parameters:                           # runtime overrides (shadow resolver)
+    # only include if used
+    overrides:
+      BrandBook: null                            # example; explicit override to null is allowed
+      Audience: "IT Experts"
+
+# ----------------------------
+# Macro graph extracted by TemplateAnalysis
+# ----------------------------
+content_macros:
+  - name: "Topic"
+    kind: "Required"                             # enum: Required | Optional | Generate
+    expected_artifact_name: "Topic"              # or "TOPIC.md" depending on your naming
+    expected_format: "markdown"
+  - name: "BrandBook"
+    kind: "Generate"
+    expected_artifact_name: "BrandBook"
+    expected_format: "markdown"
+    generator:
+      selection_rule: "by-name"                  # enum: by-name | registry | explicit
+      generator_template_name: "BrandBookGenerator" # convention: <ArtifactName>Generator
+      output_artifacts:
+        - "BrandBook"
+
+# ----------------------------
+# PromptResolver decisions (what resolved from where)
+# ----------------------------
+resolution:
+  resolution_order:
+    - "local"
+    - "explicit_includes"
+    - "default"
+    - "team"
+  explicit_includes:                             # InformationSpaces included for this run (optional)
+    - information_space_id: "space:default"
+      alias: "default"
+    - information_space_id: "space:team"
+      alias: "team"
+
+  resolved_inputs:
+    - macro: "Topic"
+      kind: "Required"
+      resolved:
+        status: "found"                          # enum: found | missing_optional | generated | failed
+        artifact_ref:
+          artifact_id: "artifact:Topic.md"
+          information_space_id: "space:my-topic"
+          path: "Topic.md"
+          content_digest: "sha256:..."
+    - macro: "BrandBook"
+      kind: "Generate"
+      resolved:
+        status: "generated"
+        artifact_ref:
+          artifact_id: "artifact:BrandBook.md"
+          information_space_id: "space:my-topic"
+          path: "BrandBook.md"
+          content_digest: "sha256:..."
+        generated_by_run_id: "run:uuid-of-generator-run"
+
+  missing:
+    # filled when applicable
+    required: []                                  # list of unresolved required macros
+    optional: []                                  # list of unresolved optional macros
+
+# ----------------------------
+# ContextCompilation outputs
+# ----------------------------
+compilation:
+  compiled_prompt:
+    compiled_prompt_id: "compiled:sha256:..."     # optional content-address
+    content_digest: "sha256:..."                  # digest of the compiled prompt text
+    token_estimate: 4200                          # optional
+    assembly_plan:
+      # Optional but useful for debugging: which artifacts got concatenated and how
+      segments:
+        - type: "template"
+          artifact_id: "artifact:IllustratorPrompt.md"
+        - type: "macro_injection"
+          macro: "Topic"
+          artifact_id: "artifact:Topic.md"
+        - type: "macro_injection"
+          macro: "BrandBook"
+          artifact_id: "artifact:BrandBook.md"
+
+  input_bundle_hash:
+    # Deterministic hash used for idempotent skipping/caching:
+    # hash(template_digest + ordered dependency digests + resolver_config + model_settings + compilation_options)
+    algorithm: "sha256"
+    value: "sha256:..."
+
+  idempotency:
+    cache_decision: "executed"                    # enum: executed | skipped_cache_hit | skipped_user
+    cache_hit_run_id: null                        # if skipped_cache_hit, point to prior run
+
+# ----------------------------
+# PromptProcessing (LLM execution)
+# ----------------------------
+llm:
+  provider: "openai"                              # or "local"
+  model: "gpt-5.2"                                # string
+  settings:
+    temperature: 0.4
+    top_p: 1.0
+    max_output_tokens: 1200
+    seed: 12345                                   # optional: if supported
+  request:
+    # optional: do NOT store raw prompt by default if privacy-sensitive; store hashes + refs instead
+    compiled_prompt_digest: "sha256:..."
+  response:
+    output_digest: "sha256:..."                   # digest of raw model output
+    finish_reason: "stop"                         # optional
+
+# ----------------------------
+# Produced artifacts (writes to InformationSpace)
+# ----------------------------
+outputs:
+  written_artifacts:
+    - artifact_name: "IllustrationBrief"
+      artifact_id: "artifact:IllustrationBrief.md"
+      information_space_id: "space:my-topic"
+      path: "IllustrationBrief.md"
+      content_digest: "sha256:..."
+      format: "markdown"
+      role: "primary_output"                      # enum: primary_output | intermediate | log
+  side_effects:
+    # optional: e.g. triggered image generation job, created links, etc.
+    - type: "image_request"
+      ref: "image_gen:request_id"
+      status: "queued"                            # or "completed" if synchronous in your system
+
+# ----------------------------
+# Validation / QualityGates
+# ----------------------------
+validation:
+  quality_gates:
+    - gate_id: "schema:BrandBook.v0.1"
+      target_artifact_id: "artifact:BrandBook.md"
+      status: "passed"                            # enum: passed | failed | skipped
+      details:
+        errors: []
+        warnings:
+          - code: "MISSING_SECTION"
+            message: "Consider adding 'Color Palette' section."
+    - gate_id: "schema:IllustrationBrief.v0.1"
+      target_artifact_id: "artifact:IllustrationBrief.md"
+      status: "passed"
+      details:
+        errors: []
+        warnings: []
+
+  metrics:
+    # soft metrics snapshot used for marginal-gains halting policies
+    - metric_id: "completeness.sections"
+      target_artifact_id: "artifact:BrandBook.md"
+      value: 0.86
+      scale: "0..1"
+    - metric_id: "consistency.internal"
+      target_artifact_id: "artifact:IllustrationBrief.md"
+      value: 0.92
+      scale: "0..1"
+
+  policy:
+    quality_policy_id: "policy:default-satisficing"
+    halt_decision: "halted_quality_met"          # enum: halted_quality_met | continue_refine | halted_budget | unknown
+    iterations:
+      current: 2
+      max: 5
+
+# ----------------------------
+# Dependency recompute support (spreadsheet/build behavior)
+# ----------------------------
+dependencies:
+  # Directed edges: output depends on inputs (resolved artifacts).
+  # Used to build the global dependency graph.
+  edges:
+    - dependent_artifact_id: "artifact:IllustrationBrief.md"
+      depends_on_artifact_id: "artifact:Topic.md"
+      depends_on_digest: "sha256:..."
+      role: "macro:Topic"
+    - dependent_artifact_id: "artifact:IllustrationBrief.md"
+      depends_on_artifact_id: "artifact:BrandBook.md"
+      depends_on_digest: "sha256:..."
+      role: "macro:BrandBook"
+    - dependent_artifact_id: "artifact:BrandBook.md"
+      depends_on_artifact_id: "artifact:Topic.md"
+      depends_on_digest: "sha256:..."
+      role: "generator_input:Topic"
+
+  recompute:
+    default_depth: 1
+    suppressed_recompute:
+      # record when a dependent should be recomputed but was suppressed (cycle/depth)
+      - dependent_artifact_id: "artifact:Topic.md"
+        reason: "cycle_detected"
+        would_trigger_from_artifact_id: "artifact:BrandBook.md"
+
+# ----------------------------
+# Impact debt (changes ignored due to depth/cycle, with "gravity of change")
+# ----------------------------
+impact_debt:
+  items:
+    - dependent_artifact_id: "artifact:IllustrationBrief.md"
+      upstream_artifact_id: "artifact:BrandBook.md"
+      upstream_previous_digest: "sha256:old..."
+      upstream_current_digest: "sha256:new..."
+      suppression_reason: "depth_limit"
+      gravity:
+        method: "diff_ratio"                      # enum: diff_ratio | embedding_distance | llm_assessed
+        score: 0.31                               # normalized 0..1
+        label: "medium"                           # enum: none | low | medium | high
+      recommendation: "recompute"                 # enum: ignore | recompute | recompute_and_revalidate
+      noted_at: "2026-02-08T19:12:45+01:00"
+
+# ----------------------------
+# Nested runs (for Generate macros, validators, fixers)
+# ----------------------------
+subruns:
+  # You can inline summaries here, or store subruns as separate manifests and link by id
+  - run_id: "run:uuid-of-generator-run"
+    relation: "generated_macro:BrandBook"
+    status: "succeeded"
+    produced_artifacts:
+      - "artifact:BrandBook.md"
+
+# ----------------------------
+# Diagnostics
+# ----------------------------
+errors:
+  # present if status failed/partial
+  - code: "MISSING_REQUIRED_MACRO"
+    message: "Required macro 'Topic' could not be resolved."
+    stage: "ContextCompilation"
+    details:
+      macro: "Topic"
+
+warnings:
+  - code: "OPTIONAL_MISSING"
+    message: "Optional macro 'Examples' was not found; continuing with empty."
+    stage: "ContextCompilation"
+    details:
+      macro: "Examples"
+
+
+xxx