diff --git a/roadmap/prompt-dependency-resolution/RunManifestSchema.md b/roadmap/prompt-dependency-resolution/RunManifestSchema.md new file mode 100644 index 00000000..d492fed9 --- /dev/null +++ b/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: 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