diff --git a/roadmap/prompt-dependency-resolution/FunctionalRequirementsSpecification.md b/roadmap/prompt-dependency-resolution/FunctionalRequirementsSpecification.md new file mode 100644 index 00000000..301ebaf0 --- /dev/null +++ b/roadmap/prompt-dependency-resolution/FunctionalRequirementsSpecification.md @@ -0,0 +1,288 @@ +FunctionalRequirementSpecification + +*PromptDependencyResolution for MarkiTect* + +# Functional Requirements Specification (FRS) + +## MarkiTect Extension: PromptDependencyResolution Infrastructure + +--- + +## 1. System Definition + +The system shall provide infrastructure within MarkiTect to support structured execution of PromptTemplates using deterministic PromptDependencyResolution across InformationSpaces. + +The system shall enable: + +* Resolution of ContentMacros (Required, Optional, Generate) +* Deterministic context compilation +* Controlled PromptRun execution +* Nested Generator runs +* Idempotent execution via InputBundleHash +* Dependency graph construction +* Incremental recomputation with depth control +* RunManifest persistence and inspection +* QualityGate validation and impact tracking + +--- + +## 2. Functional Scope + +The system shall operate within a MarkiTect workspace and extend existing InformationSpace capabilities to support executable knowledge artifacts. + +The system shall not prescribe: + +* LLM provider implementation +* UI layout specifics +* Storage backend architecture +* Internal algorithm selection + +--- + +# 3. Functional Requirements + +--- + +## FR-1: InformationSpace Addressability + +**FR-1.1** +The system shall allow content artifacts within an InformationSpace to be uniquely addressable by name and persistent identifier. + +**FR-1.2** +The system shall compute and store a content digest for each artifact upon modification. + +**FR-1.3** +The system shall allow referencing artifacts across multiple InformationSpaces. + +--- + +## FR-2: PromptTemplate Definition + +**FR-2.1** +The system shall allow defining a PromptTemplate as a content artifact containing ContentMacros. + +**FR-2.2** +The system shall detect and extract ContentMacros during TemplateAnalysis. + +**FR-2.3** +The system shall support the following ContentMacro kinds: + +* Required +* Optional +* Generate + +--- + +## FR-3: PromptResolver Behavior + +**FR-3.1** +The system shall resolve ContentMacros in a deterministic resolution order: + +1. Local InformationSpace +2. Explicitly included InformationSpaces +3. Default InformationSpace +4. Team/Shared InformationSpace (if configured) + +**FR-3.2** +The system shall mark unresolved Required macros as failure conditions. + +**FR-3.3** +The system shall allow Optional macros to resolve to empty without failure. + +**FR-3.4** +The system shall, for Generate macros: + +* Identify a corresponding Generator PromptTemplate +* Initiate a nested PromptRun +* Persist generated artifact(s) +* Resume original resolution + +**FR-3.5** +The system shall enforce a configurable maximum generation depth. + +--- + +## FR-4: PromptRun Lifecycle + +**FR-4.1** +The system shall support PromptRun execution stages: + +* TemplateAnalysis +* ContextCompilation +* PromptProcessing + +**FR-4.2** +The system shall produce a CompiledPrompt during ContextCompilation. + +**FR-4.3** +The system shall calculate an InputBundleHash consisting of: + +* Template digest +* Ordered dependency digests +* Resolver configuration identifier +* Model settings +* Compilation options + +**FR-4.4** +The system shall skip execution if a prior successful PromptRun with identical InputBundleHash exists, unless explicitly overridden. + +--- + +## FR-5: RunManifest Persistence + +**FR-5.1** +The system shall persist a RunManifest for each PromptRun. + +**FR-5.2** +The RunManifest shall include: + +* Template metadata +* Resolved inputs and their digests +* CompiledPrompt digest +* Model configuration +* Output artifacts and digests +* Dependency edges +* Validation results +* Impact debt records (if applicable) + +**FR-5.3** +The system shall link nested Generator runs to parent PromptRuns. + +--- + +## FR-6: Dependency Graph Construction + +**FR-6.1** +The system shall record directed dependency edges between produced artifacts and their input artifacts. + +**FR-6.2** +The system shall construct a dependency graph across InformationSpaces. + +**FR-6.3** +The system shall detect circular dependencies. + +--- + +## FR-7: Incremental Recompute + +**FR-7.1** +When an artifact is modified, the system shall identify dependent artifacts via the dependency graph. + +**FR-7.2** +By default, the system shall recompute direct dependents only (depth = 1). + +**FR-7.3** +If recomputation would create a circular dependency or exceed depth limits, the system shall suppress further recompute. + +**FR-7.4** +The system shall record suppressed recomputations in the RunManifest. + +--- + +## FR-8: Change Impact Assessment + +**FR-8.1** +The system shall calculate a change magnitude metric when an upstream artifact changes. + +**FR-8.2** +The system shall support configurable methods for change magnitude calculation: + +* Structural diff ratio +* Content diff ratio +* Embedding distance (optional) +* LLM-assessed impact (optional) + +**FR-8.3** +The system shall record impact assessments as ImpactDebt entries in the RunManifest when recomputation is suppressed. + +--- + +## FR-9: QualityGate Validation + +**FR-9.1** +The system shall support schema validation against generated artifacts. + +**FR-9.2** +The system shall allow multiple QualityGates per artifact. + +**FR-9.3** +The system shall record pass/fail results and validation diagnostics in the RunManifest. + +**FR-9.4** +The system shall support halting policies based on QualityGate results. + +--- + +## FR-10: Halting and Refinement Policy + +**FR-10.1** +The system shall support configurable QualityPolicies. + +**FR-10.2** +The system shall evaluate halting decisions based on: + +* QualityGate results +* Marginal improvement metrics +* Iteration limits +* Resource budgets (e.g., number of runs) + +**FR-10.3** +The system shall record halting decisions in the RunManifest. + +--- + +## FR-11: Traceability and Auditability + +**FR-11.1** +The system shall enable traceability from any artifact to: + +* Producing PromptTemplate +* Input artifacts +* Generator runs +* Quality validation results + +**FR-11.2** +The system shall enable recomputation based on changes in any dependency. + +--- + +# 4. Out of Scope + +The following are explicitly excluded from this FRS: + +* User interface design and layout +* Internal storage architecture +* LLM provider selection +* Model training or fine-tuning +* Visualization tooling +* Economic or incentive mechanisms + +--- + +# 5. Acceptance Criteria + +The system shall be considered compliant when: + +1. A PromptTemplate referencing Required, Optional, and Generate macros can be executed. +2. Missing Generate dependencies are automatically generated and persisted. +3. Re-running an unchanged PromptRun with identical InputBundleHash results in a skipped execution. +4. Changing an upstream artifact triggers recomputation of direct dependents. +5. Circular recomputation is suppressed and logged. +6. RunManifest contains complete provenance and dependency information. +7. Schema validation failures are correctly recorded and influence halting policy. + +--- + +# 6. Architectural Positioning + +This infrastructure operates: + +* Above artifact storage +* Below UI interaction layers +* Orthogonal to LLM provider implementation +* As an execution engine inside MarkiTect + +It provides the functional backbone required for executable InformationSpaces within Coulomb Social. + + +xxx