onto-mcp 0.4.4 → 0.4.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. package/.onto/authority/core-lexicon.yaml +26 -1
  2. package/.onto/processes/reconstruct/ontology-seeding-and-maturation-design.md +2220 -0
  3. package/.onto/processes/reconstruct/{foundry-style-ontology-seed-contract.md → operational-ontology-seed-contract.md} +443 -74
  4. package/.onto/processes/reconstruct/reconstruct-boundary-contract.md +34 -16
  5. package/.onto/processes/reconstruct/reconstruct-contract-registry.yaml +1368 -77
  6. package/.onto/processes/reconstruct/reconstruct-execution-ux-contract.md +2 -2
  7. package/.onto/processes/reconstruct/source-profile-contract.md +103 -2
  8. package/.onto/processes/reconstruct/source-profiles/code.md +26 -0
  9. package/.onto/processes/reconstruct/source-profiles/database.md +27 -0
  10. package/.onto/processes/reconstruct/source-profiles/document.md +29 -0
  11. package/.onto/processes/reconstruct/source-profiles/spreadsheet.md +26 -0
  12. package/AGENTS.md +3 -2
  13. package/README.md +48 -27
  14. package/dist/cli.js +12 -12
  15. package/dist/core-api/reconstruct-api.js +3 -3
  16. package/dist/core-runtime/reconstruct/material-profile-validation.js +13 -2
  17. package/dist/core-runtime/reconstruct/materialize-preparation.js +4 -5
  18. package/dist/core-runtime/reconstruct/{actionable-seed-validation.js → ontology-seed-validation.js} +189 -10
  19. package/dist/core-runtime/reconstruct/post-seed-validation.js +2 -2
  20. package/dist/core-runtime/reconstruct/record.js +1 -1
  21. package/dist/core-runtime/reconstruct/run.js +914 -230
  22. package/dist/core-runtime/reconstruct/seed-claim-projections.js +10 -1
  23. package/dist/core-runtime/reconstruct/terminal-validation.js +2 -9
  24. package/dist/mcp/server.js +281 -37
  25. package/dist/mcp/tool-schemas.js +15 -14
  26. package/package.json +2 -1
  27. package/.onto/processes/reconstruct/actionable-ontology-seed-recomposition-design.md +0 -447
@@ -0,0 +1,2220 @@
1
+ # Reconstruct Ontology Seeding And Maturation Design
2
+
3
+ > Status: active design plan.
4
+ > Purpose: define reconstruct as a two-stage process: first create an
5
+ > `OntologySeed`, then mature that seed into an `ActionableOntology` through
6
+ > evidence-backed question iteration.
7
+
8
+ ## 1. Goal
9
+
10
+ Reconstruct has two named stages:
11
+
12
+ | Stage | Name | Output | Purpose |
13
+ |---|---|---|---|
14
+ | 1 | `Ontology Seeding` | `OntologySeed` / `ontology-seed.yaml` | create an evidence-backed starting ontology seed and frontier for later iteration |
15
+ | 2 | `Ontology Maturation` | `ActionableOntology` | repeatedly ask questions from the current ontology, collect answer support from source material, runtime proof, user authority, or external authority, answer those questions, and expand the ontology across the seven maturity dimensions until static, kinetic, and dynamic actionability are all satisfied |
16
+
17
+ The current runtime target output is `ontology-seed.yaml`, an `OntologySeed`
18
+ that contains:
19
+
20
+ - why the target exists
21
+ - what operational objects exist
22
+ - which actors participate
23
+ - what actions, decisions, records, or obligations matter
24
+ - which material-specific structure is required for the target purpose
25
+ - which rules, constraints, responsibilities, or policies govern that structure
26
+ - which source data or source records back, read, write, or prove the seed
27
+ - which external competency-question artifact tests the seed
28
+ - which limitations must be carried into the next step
29
+
30
+ The seed is complete enough when it can be handed to `Ontology Maturation`
31
+ without pretending that missing actors, actions, permissions, data bindings,
32
+ runtime proofs, or external alignments are known.
33
+
34
+ `OntologySeed` is not action-ready. `ActionableOntology` is reached only after
35
+ the maturation loop has filled the ontology dimensions enough for the declared
36
+ decision or action purpose.
37
+
38
+ The seven maturation dimensions are:
39
+
40
+ | Dimension | What matures |
41
+ |---|---|
42
+ | structure | stable concepts, objects, actors, actions, values, states, and data bindings |
43
+ | relation | links, dependencies, lifecycle paths, ownership, permissions, and interaction paths |
44
+ | intent | why each modeled element matters and which decision or action it supports |
45
+ | principle | rules for classification, permission, validation, change, and exception handling |
46
+ | context | runtime, organizational, material, domain, and usage boundaries |
47
+ | evidence | source observations, answer support, validation evidence, and provenance |
48
+ | external | standards, external systems, integrations, external ontologies, and interoperability boundaries |
49
+
50
+ The seven dimensions are detailed coverage axes. Actionability is judged through
51
+ three higher-level surfaces:
52
+
53
+ | Actionability surface | Question it must answer | Main seed locations |
54
+ |---|---|---|
55
+ | `static_surface` | What exists, what does it mean, and what evidence/source authority grounds it? | `purpose`, `conceptual_frame`, `semantic_layer`, `data_binding_layer`, `source_authority` |
56
+ | `kinetic_surface` | Who can do what, through which action/function/workflow, and what changes or is recorded afterward? | `kinetic_layer`, `dynamic_layer.state_models`, `data_binding_layer.writebacks` |
57
+ | `dynamic_surface` | Under which conditions, permissions, states, exceptions, runtime contexts, external dependencies, or unresolved decisions does the answer change? | `decision_context`, `dynamic_layer`, `purpose_adequacy_frame`, `source_authority`, `handoff_limitations` |
58
+
59
+ An ontology is not actionable if it is only static. Static coverage produces a
60
+ glossary or structure map. Static plus kinetic coverage produces a process
61
+ model. Only static, kinetic, and dynamic coverage together produce a basis for
62
+ decision and action.
63
+
64
+ An actionable ontology kernel is not complete because each dimension appears
65
+ somewhere. It is complete only when the source-derived purpose has a
66
+ material-kind-specific `PurposeAdequacyFrame`: the source-backed set of elements
67
+ that must be represented for the target to fulfill its purpose.
68
+
69
+ The frame is not a universal flow. A code product may need actor, action, state,
70
+ permission, and data facets. A meeting record may need subject, participants,
71
+ decisions, action items, owners, deadlines, rationale, and unresolved topics. A
72
+ spreadsheet may need inputs, formulas, outputs, assumptions, source data, and
73
+ decision cells. The seed must preserve whichever facets are material for the
74
+ classified target material kind.
75
+
76
+ The kernel is scoped by the source-derived target purpose, not by a generic user
77
+ request to reconstruct a service. It does not need to model every possible
78
+ object, action, source, or external standard, but it must not omit a material
79
+ element required by the source-derived `PurposeAdequacyFrame`.
80
+
81
+ ## 2. Non-Negotiable Constraints
82
+
83
+ 1. Runtime validates; the host LLM authors semantic meaning.
84
+ 2. Active reconstruct prompts and contracts load only the active reconstruct
85
+ contract set.
86
+ 3. Source material kind is classified before observation and validation.
87
+ 4. Conceptual orientation is only one layer of the seed.
88
+ 5. Salient candidates must receive explicit disposition.
89
+ 6. Seed validity is separate from process completion.
90
+ 7. Partial results may be useful, but limitations must be explicit.
91
+ 8. Inferred target purpose requires user confirmation before seed readiness can
92
+ be projected as `ready` or `limited`.
93
+ 9. `reconstruct-contract-registry.yaml` is the canonical machine-readable
94
+ authority graph for active runtime artifacts, validation gates, result
95
+ projections, source profile records, and reconstruct lens judgment records.
96
+
97
+ ## 3. Active Concept Model
98
+
99
+ | Concept | Role | Owner |
100
+ |---|---|---|
101
+ | `OntologySeeding` | first reconstruct stage that creates the seed and frontier | host LLM authored, runtime validated |
102
+ | `OntologySeed` | primary reconstruct semantic artifact for stage 1 | host LLM authored, runtime validated |
103
+ | `OntologyMaturation` | second reconstruct stage that expands the seed through question/evidence/answer iteration | host LLM authored, runtime validated |
104
+ | `ActionableOntology` | matured ontology that may support the declared decision or action purpose | host LLM authored, runtime validated |
105
+ | `ActionabilitySurface` | static, kinetic, and dynamic coverage surface used to judge whether the ontology can support decision and action | registry-owned coverage axis, host LLM authored in questions |
106
+ | `MaturationQuestionFrontier` | unanswered questions generated from the current ontology | host LLM authored, runtime validated |
107
+ | `AnswerSupport` | direct authority, runtime proof, user confirmation, or convergent source evidence that can support a maturation answer claim | host LLM authored, runtime validated |
108
+ | `TargetMaterialKind` | source handling axis | shared contract |
109
+ | `SourceProfileDefinition` | material-specific observation guide | reconstruct contract |
110
+ | `SelectedSourceProfile` | runtime selection recorded after material classification | runtime |
111
+ | `SourceObservation` | structural evidence record | runtime |
112
+ | `SourceDerivedPurpose` | target purpose inferred or confirmed from source material | host LLM authored, runtime evidence-validated |
113
+ | `PurposeAdequacyFrame` | material-kind-specific structure required for the source-derived purpose to be adequately represented | host LLM authored, runtime evidence-validated |
114
+ | `PurposeConfirmation` | user confirmation, rejection, or revision of an inferred target purpose | user decision recorded by runtime |
115
+ | `ReconstructLensJudgment` | independent semantic judgment over observed evidence | host LLM |
116
+ | `ExplorationSynthesis` | integrated round result and next-source need | host LLM |
117
+ | `SourceFrontier` | requested next source refs | host LLM authored, runtime validated |
118
+ | `MaturationClosureFrontier` | maturity-question-driven next-authority frontier covering source requests and non-source authority requests | host LLM authored, runtime validated |
119
+ | `CandidateInventory` | salient candidate set found in evidence | host LLM |
120
+ | `CandidateDisposition` | placement decision for every salient candidate | host LLM |
121
+ | `CompetencyQuestion` | question used to test seed usefulness | host LLM |
122
+ | `SeedIterationReadinessValidation` | runtime gate projection proving the seed can honestly enter maturation | runtime |
123
+ | `ReconstructRecord` | structured run record and artifact truth index | runtime |
124
+
125
+ New runtime or MCP fields should reuse these concepts. A new concept is allowed
126
+ only when it changes ownership, lifecycle, validation behavior, public output,
127
+ or artifact authority.
128
+
129
+ ## 4. Extensibility Model
130
+
131
+ The reconstruct seeding structure is intentionally extensible. It should become
132
+ more precise by running against more real sources, but extension must happen
133
+ through profile and registry evolution, not through ad hoc runtime invention.
134
+
135
+ Stable boundary:
136
+
137
+ - `OntologySeed` remains the common artifact shape.
138
+ - `TargetMaterialKind` remains the first dispatch axis.
139
+ - `SourceProfileDefinition` owns material-specific reading guidance.
140
+ - The selected, validated `PurposeAdequacyFrame` owns the
141
+ material-kind-specific requirement authority for a source-derived purpose.
142
+ Seed and maturation artifacts may project it, but they must not redefine it.
143
+ - `SourceFrontier` owns seeding next-source requests.
144
+ `MaturationClosureFrontier` owns maturation next-authority requests; it may
145
+ include source requests, user authority, external authority, domain-standard
146
+ authority, or runtime-capability gaps.
147
+ - Runtime validates ids, evidence refs, seed refs, limitations, source-profile
148
+ snapshots, registry snapshots, and migration mappings.
149
+ - The host LLM authors purpose and semantic seed meaning.
150
+
151
+ Evolving boundary:
152
+
153
+ - Each source profile may add purpose-bearing evidence cues, recommended
154
+ adequacy facets, closure examples, and anti-examples.
155
+ - New facet names start as profile-owned strings, not global enums.
156
+ - A facet is promoted into a shared/global registry only when repeated
157
+ real-source runs show that it is stable across material kinds or when public
158
+ validation behavior depends on it.
159
+ - A new material kind, root candidate kind, readiness value, artifact field, or
160
+ validation gate requires contract, registry, validator, and migration updates
161
+ together.
162
+
163
+ Run behavior for unknown or emerging source patterns:
164
+
165
+ 1. Do not force the source into an existing flow or frame.
166
+ 2. Record the observed signal with source refs.
167
+ 3. Represent the needed element in the selected
168
+ `PurposeAdequacyFrame.required_elements[]` when it is source-backed.
169
+ 4. If closure is incomplete, add a limitation or source frontier.
170
+ 5. After multiple runs, update the source profile and registry if the pattern is
171
+ stable enough to become a reusable rule.
172
+
173
+ This keeps early runs useful without pretending the current profile catalog is
174
+ complete.
175
+
176
+ ## 5. Target Process
177
+
178
+ ```text
179
+ 1. Bind target and reconstruct intent
180
+ 2. Classify material kind
181
+ 3. Build source inventory
182
+ 4. Observe selected source slices once into reusable `source-observations.yaml`
183
+ 5. Project purpose-bearing evidence from observed records
184
+ 6. Derive source purpose and purpose adequacy frame candidates
185
+ 7. Validate purpose and purpose adequacy evidence closure
186
+ 8. Ask the user to confirm inferred purpose when no direct purpose authority exists
187
+ 9. Project semantic-use evidence from the same observed records
188
+ 10. Run reconstruct lens judgments
189
+ 11. Synthesize gaps and next-source frontier
190
+ 12. Repeat observation with round lineage if frontier is valid and useful
191
+ 13. Build candidate inventory
192
+ 14. Record candidate disposition
193
+ 15. Author OntologySeed
194
+ 16. Validate seed-shape gates
195
+ 17. Author claim-realization map
196
+ 18. Validate claim-realization map
197
+ 19. Confirm seed claims or record limitations
198
+ 20. Validate seed confirmation and derive CQ eligibility
199
+ 21. Author competency questions
200
+ 22. Validate competency-question coverage
201
+ 23. Assess competency questions
202
+ 24. Validate competency-question assessment
203
+ 25. Classify failures and propose bounded revision
204
+ 26. Emit metrics and stop decision
205
+ 27. Validate seed iteration readiness from runtime gates and stop decision
206
+ 28. Emit final output and reconstruct record
207
+ ```
208
+
209
+ Each step either writes an artifact or records why it cannot proceed.
210
+
211
+ The second stage, `Ontology Maturation`, begins after a valid seed is available:
212
+
213
+ ```text
214
+ OntologySeed
215
+ -> generate questions from current ontology gaps
216
+ -> answer questions that the ontology can already answer
217
+ -> search source material for unanswered questions
218
+ -> collect answer support from source evidence, runtime proof, user authority, or external authority
219
+ -> author answer claims with evidence refs
220
+ -> expand structure, relation, intent, principle, context, evidence, or external dimensions
221
+ -> validate the expanded ontology and remaining frontier
222
+ -> repeat until the declared maturity threshold is met
223
+ -> ActionableOntology
224
+ ```
225
+
226
+ ### 5.1 Seeding Revision Design
227
+
228
+ The current seeding path already produces `OntologySeed` and validates that the
229
+ seed declares `static_surface`, `kinetic_surface`, and `dynamic_surface` in
230
+ `validation_layer.coverage_axes[]`. The next seeding revision must connect those
231
+ surface names to source-backed seed content. A seed that merely lists the three
232
+ surface ids is not yet sufficient.
233
+
234
+ Seeding revision goal:
235
+
236
+ ```text
237
+ source-observations.yaml
238
+ -> source-purpose-candidates.yaml
239
+ -> purpose-confirmation.yaml when needed
240
+ -> PurposeAdequacyFrame with actionability surface mapping
241
+ -> candidate inventory and disposition with surface/facet mapping
242
+ -> OntologySeed with static, kinetic, and dynamic seed content or limitations
243
+ -> seed validation and seed iteration readiness
244
+ ```
245
+
246
+ Implementation rule: promote seeding changes before maturation runtime changes.
247
+ Seeding is the authority boundary that decides whether maturation has a valid
248
+ kernel to continue from. Maturation implementation may start only after the
249
+ seeding runtime can produce source-purpose candidates, purpose confirmation
250
+ validation, surface-mapped candidate disposition, and surface-closure seed
251
+ validation against a real source.
252
+
253
+ Current active runtime must not require source-purpose or purpose-confirmation
254
+ refs until the corresponding planned artifact authority, validation authority,
255
+ gate, validator, predicate, and activation condition are promoted together.
256
+ Before that promotion, `ontology-seed.yaml` may carry only a seed-local purpose
257
+ projection validated against source observations, target-material profile
258
+ evidence, candidate disposition, and limitations.
259
+
260
+ The first implementation must not create compatibility projections for legacy
261
+ seed names. If an old artifact shape remains in tests or docs, migrate or remove
262
+ the old reference instead of projecting it into the new runtime path.
263
+
264
+ #### Purpose Authority Split
265
+
266
+ Purpose inference and user confirmation must become their own authority
267
+ artifacts. `ontology-seed.yaml` may carry the confirmed purpose projection, but
268
+ it must not be the only place where inferred purpose was selected or confirmed.
269
+
270
+ | Artifact | Owner | Role |
271
+ |---|---|---|
272
+ | `source-purpose-candidates.yaml` | host LLM author | ranked source-derived purpose candidates and candidate `PurposeAdequacyFrame` rows |
273
+ | `source-purpose-candidates-validation.yaml` | runtime | evidence-ref, evidence-kind, contradiction, ranking, and material-kind closure |
274
+ | `purpose-confirmation.yaml` | user-mediated runtime artifact | confirmation, rejection, or revision of an inferred purpose |
275
+ | `purpose-confirmation-validation.yaml` | runtime | confirms that inferred purpose status can be used for seed readiness |
276
+
277
+ Purpose confirmation and seed confirmation are different gates. Purpose
278
+ confirmation validates the selected source-derived purpose before seed authoring
279
+ can honestly project readiness. `seed-confirmation.yaml` validates authored seed
280
+ claims after `ontology-seed.yaml` exists and before competency-question
281
+ assessment and seed-iteration readiness.
282
+
283
+ Direct P1 source-declared purpose may bypass user confirmation, but it still
284
+ needs `source-purpose-candidates.yaml` so the selected purpose, rejected
285
+ alternatives, and evidence policy remain auditable.
286
+
287
+ Implementable `source-purpose-candidates.yaml` shape:
288
+
289
+ ```yaml
290
+ schema_version: "1"
291
+ session_id:
292
+ created_at:
293
+ target_material_kind:
294
+ source_observations_ref: source-observations.yaml
295
+ selected_source_profile_refs:
296
+ - profile_id:
297
+ target_material_kind:
298
+ profile_ref:
299
+ definition_sha256:
300
+ purpose_candidates:
301
+ - purpose_candidate_id:
302
+ statement:
303
+ rank: primary | secondary | candidate | rejected
304
+ purpose_source_status: explicit_source_declared | convergent_inferred | limitation_backed | unresolved
305
+ evidence_kind_refs: [P1 | P2 | P3 | P4 | P5]
306
+ supporting_evidence_refs: []
307
+ contradicting_source_refs: []
308
+ adequacy_frame:
309
+ frame_id:
310
+ frame_kind:
311
+ frame_status: source_declared | evidence_inferred | limitation_backed | unresolved
312
+ adequacy_claim:
313
+ material_kind_requirements:
314
+ target_material_kind:
315
+ required_facets: []
316
+ optional_facets: []
317
+ rationale:
318
+ required_elements:
319
+ - element_id:
320
+ element_kind:
321
+ material_facet_kind:
322
+ description:
323
+ actionability_surface_refs: []
324
+ maturity_dimension_refs: []
325
+ member_scope_refs: []
326
+ member_target_material_kind:
327
+ member_source_refs: []
328
+ cross_material_ref_refs: []
329
+ supporting_evidence_refs: []
330
+ expected_seed_ref_families: []
331
+ closure_expectation: model_or_limit | frontier_required
332
+ ranking_rationale:
333
+ limitation_refs: []
334
+ selection:
335
+ primary_purpose_candidate_id:
336
+ selection_basis:
337
+ confirmation_policy_hint:
338
+ unresolved_reason:
339
+ ```
340
+
341
+ Implementable `source-purpose-candidates-validation.yaml` shape:
342
+
343
+ ```yaml
344
+ schema_version: "1"
345
+ session_id:
346
+ created_at:
347
+ source_purpose_candidates_ref: source-purpose-candidates.yaml
348
+ source_observations_ref: source-observations.yaml
349
+ registry_ref: .onto/processes/reconstruct/reconstruct-contract-registry.yaml
350
+ validation_status: valid | invalid
351
+ selected_purpose_candidate_id:
352
+ selected_purpose_frame_id:
353
+ confirmation_required:
354
+ validation_results: []
355
+ violations:
356
+ - code:
357
+ message:
358
+ subject_id:
359
+ evidence_ref:
360
+ ```
361
+
362
+ The purpose candidate validator must enforce:
363
+
364
+ - exactly one `primary` candidate when the purpose is selected;
365
+ - every evidence ref resolves to `source-observations.yaml`;
366
+ - P5 evidence never establishes a primary purpose by itself;
367
+ - non-P1 primary candidates have at least two evidence kinds and one of them is
368
+ P2, P3, or P4;
369
+ - every candidate adequacy-frame required element has a material facet,
370
+ actionability surface refs, maturity dimension refs, and supporting evidence or
371
+ an explicit unresolved/limitation state;
372
+ - for `target_material_kind: mixed`, every modeled required element has the
373
+ full lineage set: `member_scope_refs[]`, `member_target_material_kind`,
374
+ `member_source_refs[]`, and `cross_material_ref_refs[]`; a row may omit those
375
+ fields only through a validated limitation-backed or out-of-scope exclusion;
376
+ - contradictions are preserved and make the primary candidate
377
+ `limitation_backed` or `unresolved` unless a source-backed resolution is
378
+ recorded;
379
+ - `confirmation_required` is the runtime predicate field derived from the
380
+ selected candidate status and is the only source for the purpose-confirmation
381
+ gate;
382
+ - the selected purpose candidate id and selected frame id are explicit so seed
383
+ validation can prove projection equivalence.
384
+
385
+ `purpose_source_status` is the canonical field name for source-purpose candidate
386
+ status. Active artifacts must not introduce `source_purpose_status`,
387
+ `inference_status`, or other aliases; validators reject alias-only status fields
388
+ as schema drift. `contradicting_source_refs[]` is the canonical contradiction
389
+ field for source-purpose candidates because contradiction authority is the
390
+ observed source record, not an unscoped evidence label.
391
+
392
+ Implementable `purpose-confirmation.yaml` shape:
393
+
394
+ ```yaml
395
+ schema_version: "1"
396
+ session_id:
397
+ created_at:
398
+ source_purpose_candidates_ref: source-purpose-candidates.yaml
399
+ source_purpose_candidates_validation_ref: source-purpose-candidates-validation.yaml
400
+ purpose_candidate_id:
401
+ confirmation_status: not_required | pending | confirmed | rejected | revised_pending_evidence_check | revised_confirmed | not_available
402
+ confirmed_statement:
403
+ revised_statement:
404
+ confirmed_frame_element_refs: []
405
+ rejected_frame_element_refs: []
406
+ user_response_summary:
407
+ source_conflict_policy:
408
+ limitation_refs: []
409
+ ```
410
+
411
+ Implementable `purpose-confirmation-validation.yaml` shape:
412
+
413
+ ```yaml
414
+ schema_version: "1"
415
+ session_id:
416
+ created_at:
417
+ purpose_confirmation_ref: purpose-confirmation.yaml
418
+ source_purpose_candidates_validation_ref: source-purpose-candidates-validation.yaml
419
+ validation_status: valid | invalid
420
+ purpose_projection_status: usable | blocked | rerun_required
421
+ confirmed_purpose_candidate_id:
422
+ confirmed_statement:
423
+ seed_readiness_effect: may_project_ready_or_limited | must_project_blocked | must_rerun_purpose_discovery
424
+ validation_results: []
425
+ violations:
426
+ - code:
427
+ message:
428
+ subject_id:
429
+ ```
430
+
431
+ `confirmation_required` is authoritative only in
432
+ `source-purpose-candidates-validation.yaml`. `purpose-confirmation.yaml` records
433
+ the user's response to that validated requirement and must not become a second
434
+ gate-applicability source.
435
+
436
+ `ontology-seed.yaml.purpose` is a bounded projection from these two purpose
437
+ authorities after promotion. The seed stores authority refs, selected ids, a
438
+ declared-purpose projection, and a seed-closure projection of the selected
439
+ adequacy frame. It must not copy the full candidate ledger, invent a new purpose
440
+ candidate, or erase rejected/contradicted purpose candidates from the
441
+ source-purpose authority.
442
+
443
+ #### PurposeAdequacyFrame Surface Mapping
444
+
445
+ The canonical `PurposeAdequacyFrame` row lives in the selected
446
+ `source-purpose-candidates.yaml` candidate after
447
+ `source-purpose-candidates-validation.yaml` proves evidence closure and selected
448
+ candidate consistency. The seed stores a projection of that frame so runtime can
449
+ validate seed closure. Maturation must resolve the frame through the selected
450
+ validated candidate and then verify that the seed projection is equivalent before
451
+ using it as a baseline input.
452
+
453
+ Each projected `purpose_adequacy_frame_projection.required_elements[]` row must
454
+ declare the actionability and maturity coverage it is meant to close.
455
+ `closure_status` is a seed-projection status, not canonical requirement meaning.
456
+
457
+ Seed frame projection fields:
458
+
459
+ ```yaml
460
+ purpose_adequacy_frame_projection:
461
+ required_elements:
462
+ - element_id:
463
+ element_kind:
464
+ material_facet_kind:
465
+ actionability_surface_refs: [static_surface | kinetic_surface | dynamic_surface]
466
+ maturity_dimension_refs: [structure | relation | intent | principle | context | evidence | external]
467
+ member_scope_refs: []
468
+ member_target_material_kind:
469
+ member_source_refs: []
470
+ cross_material_ref_refs: []
471
+ closure_status: modeled | limitation_backed | frontier_required
472
+ seed_ref_refs: []
473
+ evidence_refs: []
474
+ limitation_refs: []
475
+ ```
476
+
477
+ Runtime validation must fail loud when a required element has no surface refs,
478
+ no maturity dimension refs, or a `closure_status` inconsistent with its seed
479
+ refs, evidence refs, and limitation refs.
480
+
481
+ For `mixed` targets, runtime validation must also fail loud when a projected
482
+ required element loses the selected validated frame's member lineage. Each row
483
+ must preserve `member_scope_refs[]`, `member_target_material_kind`,
484
+ `member_source_refs[]`, and `cross_material_ref_refs[]`, or cite a
485
+ limitation-backed/out-of-scope exclusion validated by
486
+ `source-purpose-candidates-validation.yaml`. This applies even when aggregate
487
+ readiness is `ready`; member provenance is not only a blocked/limited
488
+ remediation field.
489
+
490
+ Surface closure is evaluated from seed ref families, not from prose. The first
491
+ validator implementation should use these path prefixes:
492
+
493
+ | Surface | Seed ref families that may close it |
494
+ |---|---|
495
+ | `static_surface` | `conceptual_frame.*`, `semantic_layer.object_types`, `semantic_layer.link_types`, `semantic_layer.value_types`, `semantic_layer.constraints`, `data_binding_layer.source_bindings`, `data_binding_layer.provenance_bindings`, `source_authority.*` |
496
+ | `kinetic_surface` | `kinetic_layer.action_types`, `kinetic_layer.functions`, `kinetic_layer.workflows`, `dynamic_layer.state_models`, `data_binding_layer.writebacks` |
497
+ | `dynamic_surface` | `decision_context.*`, `dynamic_layer.actor_types`, `dynamic_layer.actor_roles`, `dynamic_layer.permission_policies`, `dynamic_layer.state_models`, `dynamic_layer.lifecycle_rules`, `dynamic_layer.dynamic_boundaries`, `source_authority.source_gaps`, `handoff_limitations` |
498
+
499
+ `closure_status` must be interpreted deterministically:
500
+
501
+ | `closure_status` | Required refs |
502
+ |---|---|
503
+ | `modeled` | at least one `seed_ref_refs[]` item in an allowed family for every declared actionability surface, plus at least one evidence ref |
504
+ | `limitation_backed` | at least one limitation ref whose affected refs, missing source refs, or mitigation text names the same required element, plus supporting evidence or source-gap evidence |
505
+ | `frontier_required` | at least one limitation ref that names the next source, user, or external authority needed to model the element |
506
+
507
+ If a required element declares several actionability surfaces, each surface must
508
+ be independently closed. A static object ref cannot close the kinetic or dynamic
509
+ surface unless the element also cites action, state, permission, boundary,
510
+ writeback, or limitation refs for that surface.
511
+
512
+ #### Candidate Surface Mapping
513
+
514
+ Candidate inventory and disposition are the bridge from observed evidence to
515
+ seed layers. They must preserve the actionability role of each candidate before
516
+ the seed is authored.
517
+
518
+ Candidate mapping fields:
519
+
520
+ ```yaml
521
+ candidate_inventory:
522
+ candidates:
523
+ - candidate_id:
524
+ candidate_kind:
525
+ material_facet_kind:
526
+ actionability_surface_refs: []
527
+ purpose_element_refs: []
528
+ evidence_observation_ids: []
529
+
530
+ candidate_disposition:
531
+ dispositions:
532
+ - candidate_id:
533
+ disposition_id:
534
+ target_seed_refs: []
535
+ satisfies_purpose_element_refs: []
536
+ actionability_surface_refs: []
537
+ rationale:
538
+ evidence_observation_ids: []
539
+ ```
540
+
541
+ The root `candidate_kind_registry` should remain compact. Material-specific
542
+ facet names begin as source-profile-owned strings through
543
+ `material_facet_kind`; they are promoted to a shared registry only after real
544
+ source runs prove the term is stable across material kinds or validation
545
+ behavior depends on it.
546
+
547
+ Candidate validation must additionally enforce:
548
+
549
+ - every high-salience candidate has `actionability_surface_refs[]` and at least
550
+ one `purpose_element_refs[]` item unless it is explicitly rejected for the
551
+ declared purpose;
552
+ - every disposition copies or narrows the candidate surface refs;
553
+ - `satisfies_purpose_element_refs[]` resolves to the selected
554
+ `PurposeAdequacyFrame.required_elements[]`;
555
+ - every `promoted_to_seed_layer` disposition has `target_seed_refs[]`, and seed
556
+ validation later proves those refs exist;
557
+ - `deferred_by_source_gap` dispositions cite a limitation or source frontier;
558
+ - rejected candidates keep evidence and rationale so salience is not silently
559
+ lost.
560
+
561
+ #### Dynamic Boundary Rows
562
+
563
+ The existing dynamic layer covers actors, roles, permissions, state models, and
564
+ lifecycle rules. That is necessary but not sufficient for the broader dynamic
565
+ surface. Seeding needs one explicit place for conditions and boundaries that
566
+ change an answer without necessarily becoming a state machine.
567
+
568
+ Seed dynamic-boundary fields:
569
+
570
+ ```yaml
571
+ dynamic_layer:
572
+ dynamic_boundaries:
573
+ - boundary_id:
574
+ boundary_kind: condition | exception | runtime_context | external_dependency | unresolved_decision | failure_mode
575
+ target_ref:
576
+ statement:
577
+ changes_answer_for:
578
+ evidence_refs: []
579
+ limitation_refs: []
580
+ ```
581
+
582
+ Use `dynamic_boundaries[]` for runtime conditions, source gaps, external
583
+ dependencies, exception behavior, and user/product decisions that change whether
584
+ a question can be answered or an action can be trusted.
585
+
586
+ Dynamic-boundary validation is part of ontology seed validation:
587
+
588
+ - `boundary_id` is unique inside `dynamic_layer.dynamic_boundaries[]`;
589
+ - `boundary_kind` is one of the listed values;
590
+ - `target_ref` resolves to a known seed ref, purpose element ref, or limitation
591
+ ref;
592
+ - `evidence_refs[]` resolves to `source-observations.yaml` unless the boundary is
593
+ explicitly user-confirmed;
594
+ - `unresolved_decision` and `external_dependency` boundaries must cite
595
+ `limitation_refs[]`;
596
+ - a purpose element that declares `dynamic_surface` cannot be `modeled` unless it
597
+ cites at least one permission, state, lifecycle, dynamic-boundary, source-gap,
598
+ or limitation ref.
599
+
600
+ #### Seeding Validation Additions
601
+
602
+ The seed validator must move from surface declaration to surface closure:
603
+
604
+ | Gate | Required validation behavior |
605
+ |---|---|
606
+ | purpose authority | selected purpose has a valid source-purpose candidate row and confirmation status when inferred |
607
+ | frame surface mapping | every required frame element maps to at least one actionability surface and one maturity dimension |
608
+ | static closure | static required elements cite object/value/constraint/data/source refs or limitation-backed frontier |
609
+ | kinetic closure | kinetic required elements cite action/function/workflow/writeback/state-effect refs or limitation-backed frontier |
610
+ | dynamic closure | dynamic required elements cite permission/state/lifecycle/dynamic-boundary/external/source-gap refs or limitation-backed frontier |
611
+ | candidate realization | every promoted or represented candidate satisfies its declared purpose element and surface mapping |
612
+ | limitation honesty | non-modeled required elements use `closure_status: limitation_backed` or `frontier_required` and resolve limitation refs |
613
+
614
+ This revision keeps the seed small. It does not try to finish actionability
615
+ during seeding; it ensures maturation receives the correct frontier instead of
616
+ rediscovering the target from zero.
617
+
618
+ Implementation order for seeding gates:
619
+
620
+ | Order | Runtime change | First passing evidence |
621
+ |---|---|---|
622
+ | S1 | add artifact types for source-purpose candidates and purpose confirmation | parser/fixture tests reject missing candidate ids, bad evidence refs, and unsupported status values |
623
+ | S2 | add source-purpose candidate author prompt after source observation and before candidate inventory | direct-call run writes `source-purpose-candidates.yaml` with ranked candidates from existing observations |
624
+ | S3 | add purpose candidate validator and registry gate | invalid P5-only purpose and dangling evidence refs fail before seed authoring |
625
+ | S4 | add purpose confirmation artifact and validator | inferred purpose blocks seed readiness until confirmation is valid |
626
+ | S5 | extend candidate inventory/disposition types and prompts with surface/facet mapping | high-salience candidates carry purpose element refs and actionability surface refs |
627
+ | S6 | extend seed author prompt and seed contract with required-element closure fields and `dynamic_boundaries[]` | seed contains mapped purpose elements and dynamic boundary rows where needed |
628
+ | S7 | extend ontology seed validator from axis declaration to surface closure | a seed that lists `static_surface`, `kinetic_surface`, and `dynamic_surface` but lacks content fails loud |
629
+ | S8 | update final output, status, record, and metrics projections | process completion, seed validity, purpose confirmation, and maturation frontier are reported separately |
630
+
631
+ The narrow release target for seeding is one real-source run that reaches
632
+ `ready` or `limited` honestly, or fails at the first invalid gate with a concrete
633
+ validation artifact. A mock-backed run may verify test coverage, but it does not
634
+ count as product completion.
635
+
636
+ #### Seeding Revision Completion Criteria
637
+
638
+ The seeding revision is complete when a fresh real-source run proves:
639
+
640
+ 1. source purpose candidates are ranked, evidence-backed, and validation-closed;
641
+ 2. inferred purpose confirmation is external to the seed and blocks readiness
642
+ when absent;
643
+ 3. every purpose adequacy required element declares actionability surface,
644
+ maturity dimension, and closure status;
645
+ 4. candidate inventory and disposition preserve surface/facet mapping;
646
+ 5. `OntologySeed` includes static, kinetic, and dynamic content or explicit
647
+ limitations for every material required element;
648
+ 6. seed validation fails loud when a surface is declared but has no modeled or
649
+ limitation-backed content; and
650
+ 7. final output reports seed validity, seed iteration readiness, and maturation
651
+ frontier separately.
652
+
653
+ ### 5.2 Ontology Maturation Design
654
+
655
+ `Ontology Maturation` starts only after seeding produces a valid seed or a
656
+ limited seed that is explicitly usable for the next iteration. Maturation does
657
+ not rerun seeding. It consumes the seed, its validation artifacts, limitations,
658
+ competency-question assessment, and source observations.
659
+
660
+ Maturation input authority:
661
+
662
+ ```text
663
+ ontology-seed.yaml
664
+ + ontology-seed-validation.yaml
665
+ + source-purpose-candidates.yaml
666
+ + source-purpose-candidates-validation.yaml
667
+ + purpose-confirmation-validation.yaml
668
+ + candidate-disposition.yaml
669
+ + claim-realization-map.yaml
670
+ + claim-realization-map-validation.yaml
671
+ + competency-questions.yaml
672
+ + competency-questions-validation.yaml
673
+ + competency-question-assessment.yaml
674
+ + competency-question-assessment-validation.yaml
675
+ + handoff-decision-validation.yaml
676
+ + source-observations.yaml
677
+ + reconstruct-record.yaml artifact refs and hashes
678
+ + reconstruct-run-manifest.yaml snapshot refs and hashes
679
+ ```
680
+
681
+ When the seed claims executable queryability, visualization, graph exploration,
682
+ API access, implementation access, or another explicit ontology access surface,
683
+ maturation must also consume the applicable proof authorities and validation
684
+ artifacts defined by `operational-ontology-seed-contract.md`:
685
+
686
+ ```text
687
+ query-proofs.yaml
688
+ + query-proofs-validation.yaml
689
+ + visualization-proofs.yaml
690
+ + visualization-proofs-validation.yaml
691
+ + graph-exploration-proofs.yaml
692
+ + graph-exploration-proofs-validation.yaml
693
+ ```
694
+
695
+ These artifacts are not redefined by this design. `competency-questions.yaml`
696
+ is the question authority, `competency-question-assessment.yaml` is the
697
+ answerability-result authority, and conditional proof artifacts own executable
698
+ proof records. Maturation references those authorities when computing baseline,
699
+ answerability, readiness, and actionability.
700
+
701
+ #### Maturation Process
702
+
703
+ ```text
704
+ 1. Build the maturity baseline from seed refs, required purpose elements,
705
+ actionability surfaces, seven maturity dimensions, CQ assessment, and
706
+ limitations.
707
+ 2. Generate a `MaturationQuestionFrontier` from unanswered, partially answered,
708
+ deferred, contradicted, or limitation-backed seed questions.
709
+ 3. Classify each question by materiality, actionability surface, maturity
710
+ dimension, purpose element, and expected answer kind.
711
+ 4. Answer questions already answerable from the current ontology and evidence.
712
+ 5. For unanswered material questions, author a `MaturationClosureFrontier` that
713
+ names the next source refs or the missing user/external authority.
714
+ 6. Runtime observes approved source refs and records round lineage.
715
+ 7. Build a `AnswerSupportLedger` from direct authority, runtime proof,
716
+ user confirmation, or repeated source signals that imply the same answer.
717
+ 8. Author `MaturationAnswerClaims` only from convergent evidence or explicit
718
+ authority.
719
+ 9. Author `OntologyExpansion` rows that add, refine, defer, or reject ontology
720
+ content.
721
+ 10. Validate expansion against seed refs, evidence refs, source lineage,
722
+ surface coverage, and concept economy.
723
+ 11. Update `ActionabilityMatrix` and remaining frontier.
724
+ 12. Repeat until convergence or an explicit blocked/deferred state.
725
+ ```
726
+
727
+ #### Maturation Artifact Plan
728
+
729
+ | Artifact | Owner | Role |
730
+ |---|---|---|
731
+ | `maturation-baseline.yaml` | runtime | L0-L4 matrix from seed, CQs, limitations, and handoff validation |
732
+ | `maturation-baseline-validation.yaml` | runtime | proves baseline rows derive from validated seed, purpose, CQ/proof, and handoff authorities |
733
+ | `maturation-promotion-request.yaml` | runtime | durable request authority for maturation execution or planned gate promotion |
734
+ | `maturation-promotion-request-validation.yaml` | runtime | proves request id, trigger refs, requested gates, and replay authority before promotion-readiness evaluation |
735
+ | `maturation-runtime-capability-profile.yaml` | runtime | records runtime-observed writer, validator, predicate, and activation capability for planned maturation gates |
736
+ | `maturation-promotion-readiness.yaml` | runtime | per-gate promotion decision before planned maturation gates become executable |
737
+ | `maturation-question-frontier.yaml` | host LLM author | unanswered or weakly answered questions to mature |
738
+ | `maturation-question-frontier-validation.yaml` | runtime | question refs, materiality, surface, dimension, and seed-link validation |
739
+ | `maturation-closure-frontier.yaml` | host LLM author | next source refs or missing authority needed for material questions |
740
+ | `maturation-closure-frontier-validation.yaml` | runtime | frontier duplication, support, and boundary validation |
741
+ | `maturation-authority-response.yaml` | user/runtime/external authority captured by runtime | responses to non-source authority requests from the closure frontier |
742
+ | `maturation-authority-response-validation.yaml` | runtime | proves authority response scope, status, and refs before answer support or continuation decisions consume it |
743
+ | `rounds/<round-id>/source-observation-delta.yaml` | runtime | canonical per-round source delta for `source_frontier` or `maturation_closure_frontier`, distinguished by `frontier_kind` and `frontier_validation_ref` |
744
+ | `answer-support-ledger.yaml` | host LLM author + runtime refs | evidence clusters that support answer claims |
745
+ | `answer-support-ledger-validation.yaml` | runtime | evidence closure, independence, contradiction, and authority checks |
746
+ | `maturation-answer-claims.yaml` | host LLM author | source-backed answers to frontier questions |
747
+ | `maturation-answer-claims-validation.yaml` | runtime | answer claim refs, evidence, and limitation closure |
748
+ | `ontology-expansion.yaml` | host LLM author | ontology additions/refinements/deferred/rejected changes |
749
+ | `ontology-expansion-validation.yaml` | runtime | concept economy, ref closure, surface coverage, and regression guards |
750
+ | `actionability-matrix.yaml` | runtime | static/kinetic/dynamic by 7D and purpose element, with L0-L4 levels |
751
+ | `actionability-matrix-validation.yaml` | runtime | proves matrix rows derive from validated baseline plus validated maturation deltas |
752
+ | `maturation-continuation-decision.yaml` | runtime | continue, ask user, blocked, actionable limited, or actionable ready |
753
+ | `maturation-continuation-decision-validation.yaml` | runtime | proves the continuation or terminal actionability state derives from the validated actionability matrix and any applicable frontier/support authorities |
754
+ | `actionable-ontology.yaml` | host LLM author | matured ontology projection when ready or limited |
755
+ | `actionable-ontology-validation.yaml` | runtime | final actionability, evidence, query/proof, and limitation validation |
756
+
757
+ #### Maturation Authority Graph
758
+
759
+ Maturation artifacts follow one authority direction:
760
+
761
+ ```text
762
+ validated seed + selected validated purpose frame + CQ assessment + proof validations
763
+ -> durable promotion request + runtime capability profile + promotion readiness validation when maturation gates are promoted
764
+ -> immutable maturation-baseline.yaml
765
+ -> maturation-baseline-validation.yaml
766
+ -> question/closure frontier
767
+ -> answer support and answer claims
768
+ -> ontology expansion overlay
769
+ -> current actionability-matrix.yaml
770
+ -> actionability-matrix-validation.yaml
771
+ -> maturation-continuation-decision.yaml
772
+ -> maturation-continuation-decision-validation.yaml
773
+ -> optional actionable-ontology.yaml projection
774
+ ```
775
+
776
+ `maturation-baseline.yaml` is an immutable first snapshot for the maturation
777
+ session. It records the starting L0-L4 state from seed refs, selected validated
778
+ purpose-frame rows, CQ assessment, proof validation, and limitations. It must not
779
+ be updated after the first maturation round. `maturation-baseline-validation.yaml`
780
+ is the authority that later frontier and matrix validators consume; raw baseline
781
+ rows are not sufficient by themselves.
782
+
783
+ `actionability-matrix.yaml` is the current runtime projection after applying
784
+ validated answer claims and ontology expansions. It may be recomputed each round
785
+ from the baseline plus validated deltas. If a row exists in both artifacts, the
786
+ baseline row is historical start state and the actionability row is current
787
+ state; neither may be used as the other's source authority without the
788
+ derivation inputs. `actionability-matrix-validation.yaml` proves the
789
+ recomputation before continuation-decision or actionable ontology projection.
790
+
791
+ In M1, no maturation deltas exist yet. That is a valid zero-delta matrix state:
792
+ the actionability matrix may derive only from
793
+ `maturation-baseline-validation.yaml`, and delta validation artifacts become
794
+ required only when their corresponding answer-claim or expansion artifacts
795
+ exist.
796
+
797
+ Conditional proof authorities are part of the maturation dependency path when
798
+ their downstream claim exists. `maturation-baseline-validation.yaml` consumes the
799
+ applicable proof validations before a runtime/query, visualization, or graph
800
+ claim can affect the baseline; `actionability-matrix-validation.yaml` preserves
801
+ those proof refs in row-level maturity; and `actionable-ontology-validation.yaml`
802
+ rechecks the same proof authority before projecting an actionable ontology claim.
803
+
804
+ Maturation implementation starts as a continuation path from a completed seeding
805
+ session. It must consume artifact refs and hashes from `reconstruct-record.yaml`
806
+ instead of reparsing the target from scratch. New source observation is allowed
807
+ only through a validated maturation closure frontier.
808
+
809
+ Common validation artifact shape for maturation validators:
810
+
811
+ ```yaml
812
+ schema_version: "1"
813
+ session_id:
814
+ created_at:
815
+ validator_id:
816
+ validator_version:
817
+ input_authority_refs: []
818
+ validation_status: valid | invalid
819
+ validation_results: []
820
+ violations:
821
+ - code:
822
+ message:
823
+ subject_id:
824
+ artifact_ref:
825
+ evidence_ref:
826
+ ```
827
+
828
+ The first maturation implementation should be delivered in four slices:
829
+
830
+ | Slice | Active output | Runtime/LLM ownership | Done when |
831
+ |---|---|---|---|
832
+ | M1 baseline | `maturation-baseline.yaml`, `maturation-baseline-validation.yaml`, initial `actionability-matrix.yaml`, and `actionability-matrix-validation.yaml` | runtime projection from seed validation, selected validated purpose frame, CQ/proof assessment, and limitations | every purpose element x actionability surface x maturity dimension row has L0-L4 level, supporting refs, blockers, and next action; baseline is immutable, matrix is derived, and both have validation proof |
833
+ | M2 question frontier | `maturation-question-frontier.yaml` and validation | host LLM authors questions; runtime validates refs/materiality/surface/dimension | every blocker/high L0-L2 row has a frontier question or limitation/user-authority row |
834
+ | M3 support and claims | `maturation-closure-frontier.yaml`, observation delta, `answer-support-ledger.yaml`, `maturation-answer-claims.yaml`, validations | host LLM requests/claims; runtime validates closure frontier, observation lineage, and answer support closure | no answer claim exists without direct authority, runtime proof, user confirmation, or convergent source evidence |
835
+ | M4 expansion/continuation | `ontology-expansion.yaml`, `maturation-continuation-decision.yaml`, `maturation-continuation-decision-validation.yaml`, optional `actionable-ontology.yaml` | host LLM authors expansion; runtime validates matrix/continuation/final projection | continuation decision is `continue`, `ask_user`, `blocked`, `actionable_limited`, or `actionable_ready` from validated matrix and frontier state |
836
+
837
+ M1 and M2 are the minimum useful maturation surface. They let a seed expose its
838
+ next questions without claiming an actionable ontology. M3 and M4 are required
839
+ before the runtime may claim maturation can extend the ontology and project an
840
+ `ActionableOntology`.
841
+
842
+ #### Maturation Question Frontier
843
+
844
+ Each frontier question must be concrete enough to drive evidence search or
845
+ closure:
846
+
847
+ ```yaml
848
+ questions:
849
+ - question_id:
850
+ question:
851
+ materiality: blocker | high | medium | low | info
852
+ materiality_ref:
853
+ actionability_surface_refs: []
854
+ maturity_dimension_refs: []
855
+ purpose_element_refs: []
856
+ baseline_row_refs: []
857
+ competency_question_refs: []
858
+ competency_assessment_refs: []
859
+ domain_competency_trace_refs: []
860
+ seed_ref_refs: []
861
+ current_answer_status: answerable | partially_answerable | unsupported | deferred | contradicted | not_applicable
862
+ expected_answer_kind: yes_no | explanation | list | mapping | gap_statement
863
+ evidence_needed:
864
+ authority_need:
865
+ authority_kind: none | user | external_system | domain_standard | runtime_capability
866
+ authority_scope:
867
+ blocking_if_unavailable: true | false
868
+ expected_response_kind: confirmation | value | policy | capability | external_reference | unavailable_reason
869
+ closure_frontier_hint_refs: []
870
+ limitation_refs: []
871
+ ```
872
+
873
+ The frontier must preserve user-decision and external-authority gaps as first
874
+ class rows. They are not evidence-search questions unless source evidence can
875
+ actually change the answer.
876
+
877
+ Question-frontier validation must enforce:
878
+
879
+ - `question_id` uniqueness;
880
+ - `materiality`, `current_answer_status`, and `expected_answer_kind` values are
881
+ allowed;
882
+ - every question has at least one actionability surface and one maturity
883
+ dimension;
884
+ - every `purpose_element_refs[]`, `seed_ref_refs[]`, and `limitation_refs[]`
885
+ entry resolves against the baseline authorities;
886
+ - every competency question, assessment, and domain trace ref resolves when
887
+ present, so maturation does not lose domain or CQ coverage lineage;
888
+ - `authority_need` is first-class data when the next answer depends on user,
889
+ external-system, domain-standard, or runtime-capability authority rather than
890
+ source evidence;
891
+ - blocker/high questions cite a closure frontier hint, limitation, user authority
892
+ need, or explicit reason why no next source can advance them;
893
+ - low/info questions cannot block the maturation continuation decision.
894
+
895
+ Implementable `maturation-baseline.yaml` shape:
896
+
897
+ ```yaml
898
+ schema_version: "1"
899
+ session_id:
900
+ created_at:
901
+ source_seed_ref: ontology-seed.yaml
902
+ source_seed_validation_ref: ontology-seed-validation.yaml
903
+ source_claim_realization_map_validation_ref: claim-realization-map-validation.yaml
904
+ source_competency_assessment_ref: competency-question-assessment.yaml
905
+ source_reconstruct_record_ref: reconstruct-record.yaml
906
+ source_run_manifest_ref: reconstruct-run-manifest.yaml
907
+ source_handoff_decision_validation_ref:
908
+ purpose_frame_ref:
909
+ baseline_rows:
910
+ - baseline_row_id:
911
+ purpose_element_ref:
912
+ actionability_surface_ref:
913
+ maturity_dimension_ref:
914
+ materiality: blocker | high | medium | low | info
915
+ materiality_ref:
916
+ member_scope_refs: []
917
+ member_target_material_kind:
918
+ member_source_refs: []
919
+ cross_material_ref_refs: []
920
+ competency_question_refs: []
921
+ competency_assessment_refs: []
922
+ domain_competency_trace_refs: []
923
+ maturity_level: L0_missing | L1_identified | L2_modeled | L3_evidenced | L4_validated_for_purpose
924
+ supporting_seed_refs: []
925
+ supporting_evidence_refs: []
926
+ supporting_validation_refs: []
927
+ limitation_refs: []
928
+ blocking_reason:
929
+ ```
930
+
931
+ `maturation-baseline.yaml` is a runtime projection. It does not add ontology
932
+ meaning; it only scores existing seed and validation evidence into rows that the
933
+ question frontier can target.
934
+
935
+ `maturation-baseline-validation.yaml` must prove:
936
+
937
+ - every baseline row resolves to a selected purpose-frame required element,
938
+ actionability surface, and maturity dimension;
939
+ - every row derives from validated seed refs, validated CQ/proof results,
940
+ limitations, or a validated source-purpose/purpose-confirmation authority;
941
+ - every seed claim ref used by the baseline resolves through
942
+ `claim-realization-map-validation.yaml`;
943
+ - baseline source refs and hashes match `reconstruct-record.yaml` and the
944
+ selected run-manifest snapshot so a later maturation session can replay exactly
945
+ which seed authority it consumed;
946
+ - `source_handoff_decision_validation_ref` points to the prior/source seed-session
947
+ handoff authority, not the current terminal handoff artifact being computed;
948
+ - every mixed-material row preserves member source, member material kind, and
949
+ cross-material lineage or an explicit limitation-backed exclusion;
950
+ - every row that originated from competency-question assessment preserves the
951
+ competency question, assessment, and optional domain competency trace refs;
952
+ - blocker/high L0-L2 rows are not silently ignored and project a frontier,
953
+ limitation, or user/external authority need;
954
+ - baseline input refs and hashes are immutable for the maturation session.
955
+
956
+ Materiality authority is explicit. `materiality_ref` may point only to:
957
+
958
+ - `maturation-baseline.yaml.baseline_rows[].baseline_row_id`
959
+ - `maturation-question-frontier.yaml.questions[].question_id`
960
+ - `competency-question-assessment.yaml` answerability rows that are admitted by
961
+ `competency-question-assessment-validation.yaml`
962
+ - admitted domain competency trace refs recorded in the run manifest snapshot
963
+
964
+ When multiple refs apply, the stricter materiality wins. Runtime must not infer
965
+ materiality from prose after these artifacts exist.
966
+
967
+ Required domain competency failures are not diagnostic-only during maturation.
968
+ If an admitted domain competency question is required by the run-manifest
969
+ admission policy and its assessment is unsupported, contradicted, partial, or
970
+ deferred, maturation must project it into at least one of:
971
+
972
+ - a baseline row with materiality and competency refs;
973
+ - a maturation frontier question;
974
+ - a closure-frontier authority request;
975
+ - a limitation-backed exclusion visible to the continuation decision.
976
+
977
+ Implementable `maturation-closure-frontier.yaml` shape:
978
+
979
+ ```yaml
980
+ schema_version: "1"
981
+ session_id:
982
+ created_at:
983
+ round_id:
984
+ question_frontier_ref: maturation-question-frontier.yaml
985
+ source_requests:
986
+ - source_request_id:
987
+ question_refs: []
988
+ member_scope_refs: []
989
+ member_source_refs: []
990
+ cross_material_ref_refs: []
991
+ requested_source_ref:
992
+ requested_location:
993
+ target_material_kind:
994
+ expected_evidence_kind:
995
+ reason:
996
+ authority_requests:
997
+ - authority_request_id:
998
+ question_refs: []
999
+ authority_kind: user | external_system | domain_standard | runtime_capability
1000
+ authority_scope:
1001
+ request_summary:
1002
+ request_rationale:
1003
+ blocking_if_unavailable: true | false
1004
+ expected_response_kind: confirmation | value | policy | capability | external_reference | unavailable_reason
1005
+ limitation_refs: []
1006
+ ```
1007
+
1008
+ The closure-frontier validator must reject duplicate or already-observed source
1009
+ requests, unsupported material refs, semantic-only locations, and requests whose
1010
+ question refs do not resolve to material unanswered questions. For mixed
1011
+ material targets, every source request must preserve member scope, member source,
1012
+ and cross-material refs or cite an explicit limitation. Authority requests are
1013
+ validated as authority gaps, not as source locations. It must also prove
1014
+ authority request id uniqueness, allowed `authority_kind` and
1015
+ `expected_response_kind` values, question-ref closure, blocking semantics against
1016
+ question materiality, duplicate authority request detection by question/scope,
1017
+ and source-request separation.
1018
+
1019
+ Implementable `maturation-authority-response.yaml` shape:
1020
+
1021
+ ```yaml
1022
+ schema_version: "1"
1023
+ session_id:
1024
+ created_at:
1025
+ closure_frontier_ref: maturation-closure-frontier.yaml
1026
+ responses:
1027
+ - authority_response_id:
1028
+ authority_request_ref:
1029
+ authority_kind: user | external_system | domain_standard | runtime_capability
1030
+ authority_identity:
1031
+ authority_id:
1032
+ authority_label:
1033
+ authority_role:
1034
+ authority_snapshot_ref:
1035
+ authority_version_or_timestamp:
1036
+ response_status: provided | unavailable | rejected | deferred | contradicted
1037
+ response_summary:
1038
+ response_source_ref:
1039
+ supporting_refs: []
1040
+ limitation_refs: []
1041
+ ```
1042
+
1043
+ Authority responses are not source observations. If a response supplies source
1044
+ evidence, it must cite source observation refs and go through observation
1045
+ lineage. Otherwise it is an authority artifact consumed by answer-support and
1046
+ continuation-decision validators. Runtime records enough authority identity and
1047
+ snapshot information to replay who or what supplied the answer, which request it
1048
+ answered, and whether the same authority can be queried again.
1049
+
1050
+ #### Answer Support Rules
1051
+
1052
+ A material answer claim may be authored only when one of these support modes is
1053
+ available:
1054
+
1055
+ | Support mode | Requirement |
1056
+ |---|---|
1057
+ | direct authority | source directly states the answer and is target-scoped |
1058
+ | runtime proof | validated query, test, formula, execution, or artifact proof demonstrates the answer |
1059
+ | user confirmation | user confirms a source-inferred purpose or decision boundary |
1060
+ | authority response | user, runtime, external-system, or domain-standard authority answers a closure-frontier authority request |
1061
+ | convergent source evidence | at least two independent evidence records imply the same answer, with contradictions recorded |
1062
+
1063
+ Weak naming, folder structure, or single ambiguous evidence may create a
1064
+ frontier question, but it must not produce a material answer claim.
1065
+
1066
+ Implementable `answer-support-ledger.yaml` shape:
1067
+
1068
+ ```yaml
1069
+ schema_version: "1"
1070
+ session_id:
1071
+ created_at:
1072
+ round_id:
1073
+ evidence_clusters:
1074
+ - evidence_cluster_id:
1075
+ question_refs: []
1076
+ support_mode: direct_authority | runtime_proof | user_confirmation | authority_response | convergent_source_evidence
1077
+ proposed_answer_summary:
1078
+ evidence_refs: []
1079
+ proof_refs: []
1080
+ user_confirmation_refs: []
1081
+ authority_response_refs: []
1082
+ independence_basis:
1083
+ contradiction_refs: []
1084
+ limitation_refs: []
1085
+ ```
1086
+
1087
+ For `convergent_source_evidence`, runtime validation must require at least two
1088
+ evidence refs with different source locations or evidence kinds unless the
1089
+ selected source profile explicitly marks a single source record as direct
1090
+ authority. Contradictions do not automatically invalidate a cluster, but they
1091
+ must prevent answer-claim validation unless the claim records how the
1092
+ contradiction is bounded.
1093
+
1094
+ Positive answer claims and non-positive closure states are different artifacts.
1095
+ `maturation-answer-claims.yaml` may contain only answers that have a positive
1096
+ support mode. Deferred, contradicted, unsupported, not applicable, blocked, and
1097
+ limitation-only rows remain in `maturation-question-frontier.yaml`,
1098
+ `maturation-continuation-decision.yaml`, or limitation artifacts. They may explain why the
1099
+ run cannot answer a question, but they are not support for an answer claim.
1100
+
1101
+ Implementable `maturation-answer-claims.yaml` shape:
1102
+
1103
+ ```yaml
1104
+ schema_version: "1"
1105
+ session_id:
1106
+ created_at:
1107
+ round_id:
1108
+ answer_claims:
1109
+ - answer_claim_id:
1110
+ question_id:
1111
+ answer:
1112
+ answer_status: answered | partially_answered
1113
+ support_mode: direct_authority | runtime_proof | user_confirmation | authority_response | convergent_source_evidence
1114
+ evidence_cluster_refs: []
1115
+ supporting_evidence_refs: []
1116
+ target_surface_refs: []
1117
+ target_dimension_refs: []
1118
+ purpose_element_refs: []
1119
+ limitation_refs: []
1120
+ ```
1121
+
1122
+ Answer-claim validation must reject claims whose support mode is not backed by a
1123
+ valid evidence cluster, proof, or user confirmation. An answer may be
1124
+ `partially_answered` only when the answered portion has positive support and the
1125
+ remaining gap is represented as a limitation or frontier question.
1126
+
1127
+ #### Ontology Expansion Rules
1128
+
1129
+ `ontology-expansion.yaml` may add or refine ontology content only through
1130
+ bounded operations:
1131
+
1132
+ ```yaml
1133
+ expansions:
1134
+ - expansion_id:
1135
+ operation: add | refine | defer | reject
1136
+ target_surface_refs: []
1137
+ target_dimension_refs: []
1138
+ target_seed_or_ontology_refs: []
1139
+ purpose_element_refs: []
1140
+ answer_claim_refs: []
1141
+ evidence_refs: []
1142
+ concept_economy_effect: reduces_surface | preserves_surface | increases_surface
1143
+ rationale:
1144
+ limitation_refs: []
1145
+ ```
1146
+
1147
+ Expansion must prefer reuse or refinement before adding a new concept. A new
1148
+ concept is allowed only when it changes identity, lifecycle, validation,
1149
+ authority, user-visible action, failure handling, or material decision behavior.
1150
+
1151
+ `ontology-expansion-validation.yaml` must enforce:
1152
+
1153
+ - every `answer_claim_refs[]` item resolves to a valid answer claim;
1154
+ - every `evidence_refs[]` item resolves through the validated evidence ledger or
1155
+ prior seed/source observation authority;
1156
+ - `operation: add` with `concept_economy_effect: increases_surface` includes a
1157
+ rationale that explains why reuse/refinement is insufficient;
1158
+ - `operation: defer` or `reject` carries limitation refs or answered question
1159
+ refs;
1160
+ - no expansion rewrites seed authority in place. The expansion is an overlay
1161
+ until the final `actionable-ontology.yaml` projection is validated.
1162
+
1163
+ Implementable `actionable-ontology.yaml` projection shape:
1164
+
1165
+ ```yaml
1166
+ schema_version: "1"
1167
+ session_id:
1168
+ created_at:
1169
+ source_seed_ref: ontology-seed.yaml
1170
+ applied_expansion_refs: []
1171
+ declared_purpose:
1172
+ actionability_claim: actionable_ready | actionable_limited
1173
+ claim_scope:
1174
+ included_matrix_row_refs: []
1175
+ excluded_matrix_row_refs: []
1176
+ limitation_refs: []
1177
+ ontology:
1178
+ structure: []
1179
+ relations: []
1180
+ intent: []
1181
+ principles: []
1182
+ context: []
1183
+ evidence: []
1184
+ external: []
1185
+ action_surfaces:
1186
+ static_surface:
1187
+ status:
1188
+ supporting_refs: []
1189
+ limitation_refs: []
1190
+ kinetic_surface:
1191
+ status:
1192
+ supporting_refs: []
1193
+ limitation_refs: []
1194
+ dynamic_surface:
1195
+ status:
1196
+ supporting_refs: []
1197
+ limitation_refs: []
1198
+ remaining_frontier_refs: []
1199
+ limitation_refs: []
1200
+ ontology_handoff_refs: []
1201
+ query_proof_refs: []
1202
+ visualization_proof_refs: []
1203
+ graph_exploration_proof_refs: []
1204
+ ```
1205
+
1206
+ This projection is user-facing and downstream-facing. Its validation must prove
1207
+ that every included ontology row traces back to the seed, a validated expansion,
1208
+ or an explicit limitation. It must not become a new uncontrolled semantic source.
1209
+ When ontology-domain completeness, external alignment, executable queryability,
1210
+ visualization, or graph exploration is claimed, validation must resolve those
1211
+ claims through the registry-owned handoff axes and the proof authority contracts
1212
+ defined in `operational-ontology-seed-contract.md`.
1213
+
1214
+ #### Actionability Matrix
1215
+
1216
+ `actionability-matrix.yaml` is the runtime projection that tells whether
1217
+ maturation is converging:
1218
+
1219
+ ```yaml
1220
+ rows:
1221
+ - matrix_row_id:
1222
+ baseline_row_refs: []
1223
+ purpose_element_ref:
1224
+ actionability_surface_ref:
1225
+ maturity_dimension_ref:
1226
+ materiality: blocker | high | medium | low | info
1227
+ materiality_ref:
1228
+ member_scope_refs: []
1229
+ member_target_material_kind:
1230
+ member_readiness: closed | limitation_backed | frontier_required | out_of_scope
1231
+ member_source_refs: []
1232
+ cross_material_ref_refs: []
1233
+ competency_question_refs: []
1234
+ competency_assessment_refs: []
1235
+ maturity_level: L0_missing | L1_identified | L2_modeled | L3_evidenced | L4_validated_for_purpose
1236
+ supporting_refs: []
1237
+ blocking_question_refs: []
1238
+ limitation_refs: []
1239
+ next_action:
1240
+ ```
1241
+
1242
+ `ActionableOntology` may be claimed only when every material row is L4 or
1243
+ explicitly limitation-backed without making an actionability claim for that
1244
+ limited area.
1245
+
1246
+ Runtime computes maturity levels with these minimum rules:
1247
+
1248
+ | Level | Minimum runtime evidence |
1249
+ |---|---|
1250
+ | `L0_missing` | no candidate, seed ref, evidence ref, answer claim, or limitation closes the row |
1251
+ | `L1_identified` | candidate or frontier question exists, but no stable seed/ontology ref models the row |
1252
+ | `L2_modeled` | seed or expansion ref models the row and refs close |
1253
+ | `L3_evidenced` | modeled row has direct authority, answer support evidence, runtime proof, or user confirmation |
1254
+ | `L4_validated_for_purpose` | required competency question, query/proof, or validation artifact proves the row is trustworthy for the declared purpose without implying operational runtime proof unless a runtime proof ref is present |
1255
+
1256
+ Rows with `materiality: blocker` or `high` cannot be ignored. They must become
1257
+ `L4_validated_for_purpose`, limitation-backed outside the claim, or a
1258
+ continuation state of `continue`, `ask_user`, or `blocked`.
1259
+
1260
+ `actionability-matrix-validation.yaml` must prove:
1261
+
1262
+ - every matrix row derives from a validated baseline row, a validated answer
1263
+ claim, a validated ontology expansion, or an explicit limitation;
1264
+ - every matrix row has a stable `matrix_row_id` and closes
1265
+ `baseline_row_refs[]` against `maturation-baseline-validation.yaml`;
1266
+ - every row preserves baseline materiality or derives materiality from blocking
1267
+ question refs, and every blocker/high row remains visible to continuation
1268
+ decision validation;
1269
+ - every mixed-material row preserves member readiness, member material kind,
1270
+ member source refs, and cross-material refs or an explicit limitation-backed
1271
+ exclusion;
1272
+ - every `maturity_level` is consistent with supporting refs, blocking questions,
1273
+ and limitation refs;
1274
+ - blocker/high rows cannot be projected as action-ready unless they are
1275
+ `L4_validated_for_purpose` or limitation-backed outside the actionability
1276
+ claim;
1277
+ - recomputation inputs are recorded so continuation decisions can be audited.
1278
+
1279
+ #### Maturation Continuation And Handoff States
1280
+
1281
+ Maturation should project one of these states:
1282
+
1283
+ | State | Meaning |
1284
+ |---|---|
1285
+ | `continue` | at least one material frontier question can be advanced by source evidence |
1286
+ | `ask_user` | user decision or confirmation is the next required authority |
1287
+ | `blocked` | required source, runtime capability, or external authority is unavailable |
1288
+ | `actionable_limited` | material actionability is sufficient for a bounded purpose with named limitations |
1289
+ | `actionable_ready` | static, kinetic, and dynamic surfaces are validated for the declared purpose; operational runtime proof is required only for rows that claim runtime/query/API behavior |
1290
+
1291
+ The runtime presents the state, evidence, limitations, and remaining frontier in
1292
+ a form that lets the user choose the next action.
1293
+
1294
+ Implementable `maturation-continuation-decision.yaml` shape:
1295
+
1296
+ ```yaml
1297
+ schema_version: "1"
1298
+ session_id:
1299
+ created_at:
1300
+ actionability_matrix_validation_ref: actionability-matrix-validation.yaml
1301
+ decision_state: continue | ask_user | blocked | actionable_limited | actionable_ready
1302
+ state_rationale:
1303
+ blocking_row_refs: []
1304
+ next_frontier_refs: []
1305
+ authority_request_refs: []
1306
+ authority_response_refs: []
1307
+ claim_scope:
1308
+ included_row_refs: []
1309
+ excluded_row_refs: []
1310
+ exclusion_rationale:
1311
+ limitation_refs: []
1312
+ ```
1313
+
1314
+ For `actionable_limited`, `claim_scope.included_row_refs[]` names the rows the
1315
+ ontology may support, and `claim_scope.excluded_row_refs[]` names the rows that
1316
+ remain outside the trusted claim. `actionable_ready` may not exclude blocker or
1317
+ high material rows. Required domain competency failures must remain in
1318
+ `blocking_row_refs[]`, `next_frontier_refs[]`, or `limitation_refs[]` until a
1319
+ validated answer, authority response, or limitation-backed exclusion closes
1320
+ them.
1321
+
1322
+ ## 6. Source-Derived Purpose Strategy
1323
+
1324
+ The user's reconstruct intent explains why the run exists. It must not become
1325
+ the target's purpose or adequacy frame. The target purpose must be derived from
1326
+ source material.
1327
+
1328
+ Purpose discovery produces two semantic claims:
1329
+
1330
+ | Claim | Meaning |
1331
+ |---|---|
1332
+ | `source_derived_purpose` | what the target appears built to accomplish for its users or operators |
1333
+ | `purpose_adequacy_frame` | what must be represented, for this material kind, to say the target purpose is adequately captured |
1334
+
1335
+ Purpose discovery must not cause a second full source scan. The runtime first
1336
+ performs material-aware observation into `source-observations.yaml`; purpose
1337
+ discovery and seed authoring are separate projections over that shared evidence
1338
+ store. If user confirmation revises the inferred purpose, runtime checks whether
1339
+ the existing observations already cover the revised purpose. Only missing
1340
+ evidence becomes a targeted frontier. The run must not re-read the whole target
1341
+ only because purpose confirmation occurred.
1342
+
1343
+ The `PurposeAdequacyFrame` is material-kind-specific. For code repositories it
1344
+ may include product surface, actors, actions, state, permissions, data bindings,
1345
+ and observable behavior. For spreadsheets it may include workbook purpose,
1346
+ input ranges, formulas, output cells, assumptions, source data, and decision
1347
+ cells. For documents it may include audience, thesis, claims, evidence, required
1348
+ actions, decisions, and open questions. For meeting records it may include
1349
+ meeting subject, participants, decisions, action items, owners, dates,
1350
+ rationale, and unresolved topics. For databases it may include central tables,
1351
+ relationships, constraints, query/report outputs, update boundaries, and
1352
+ provenance.
1353
+
1354
+ Purpose evidence has a priority order:
1355
+
1356
+ | Priority | Evidence kind | Examples |
1357
+ |---|---|---|
1358
+ | P1 explicit target statement | direct source statement of product/service/workbook/document purpose | README summary, product title, introduction, manifest description, top-level documentation |
1359
+ | P2 primary surface or record center | the source area that carries the target's main user/operator/reader meaning | first screen, dashboard route, default command, primary sheet, executive summary, decision table, meeting action-item section |
1360
+ | P3 observable purpose support | concrete source evidence that the purpose is supported, executed, calculated, decided, or recorded | E2E test, quickstart, sample request, fixture workflow, formula output, decision log row, action item with owner |
1361
+ | P4 domain model center | central objects/actions/records/data that other parts organize around | main entities, route/controller clusters, workbook input-output graph, core tables/views, recurring meeting sections |
1362
+ | P5 naming and metadata signal | weaker hints from names, tags, package metadata, headings, or folder layout | package description, file names, sheet names, route names |
1363
+
1364
+ The source-derived purpose may be accepted from one P1 authority if the evidence
1365
+ is direct and target-scoped. Otherwise, the purpose needs convergent evidence
1366
+ from at least two different evidence kinds. P5 evidence cannot establish purpose
1367
+ by itself.
1368
+
1369
+ When P1 evidence is absent, purpose discovery uses an evidence-weighted
1370
+ inference ledger rather than a single narrative guess:
1371
+
1372
+ 1. Collect purpose-bearing signals from observed source records.
1373
+ 2. Generate purpose candidates in outcome language: "enables
1374
+ [audience/stakeholder] to accomplish or understand [outcome/decision/obligation]
1375
+ using [source evidence]."
1376
+ 3. Map each candidate to a tentative `PurposeAdequacyFrame` selected by
1377
+ `TargetMaterialKind`.
1378
+ 4. Score candidates by evidence-kind diversity, material-kind adequacy coverage,
1379
+ source centrality, observable support, domain-model or record-model
1380
+ centrality, data/record alignment, terminology consistency, and contradiction
1381
+ count.
1382
+ 5. Select `primary` only when the candidate has convergent support and no
1383
+ unresolved contradiction that would change the purpose or adequacy frame.
1384
+ 6. Record weaker candidates as `secondary`, `candidate`, or `rejected`.
1385
+
1386
+ `convergent_inferred` requires support from at least two independent evidence
1387
+ kinds, and at least one supporting kind must be P2, P3, or P4. P5 naming and
1388
+ metadata may strengthen a candidate but must not be the strongest evidence.
1389
+
1390
+ When the selected purpose is inferred rather than directly source-declared, the
1391
+ run must present the inferred purpose and `PurposeAdequacyFrame` to the user
1392
+ before the seed can be treated as ready for maturation. The confirmation prompt
1393
+ should show:
1394
+
1395
+ - the proposed source-derived purpose in outcome language
1396
+ - the selected material-kind adequacy frame and required facets
1397
+ - the top supporting source refs and evidence kinds
1398
+ - competing secondary or candidate purposes, if any
1399
+ - known contradictions or limitations
1400
+
1401
+ User response can have four outcomes:
1402
+
1403
+ | Outcome | Effect |
1404
+ |---|---|
1405
+ | `confirmed` | the inferred purpose may become `purpose.declared_purpose_projection.statement` |
1406
+ | `revised` | the user-provided revision becomes a new purpose candidate; it is `revised_pending_evidence_check` until source evidence check passes, then `revised_confirmed` |
1407
+ | `rejected` | the candidate cannot become the seed purpose; the run must choose another supported candidate or record purpose unresolved |
1408
+ | `not_available` | the run is blocked for seed readiness if confirmation is required |
1409
+
1410
+ The user confirmation does not override source evidence. It confirms whether the
1411
+ inferred purpose is the intended target for this reconstruct run. If the user
1412
+ revision contradicts source material, the run records the contradiction and
1413
+ opens a frontier rather than silently rewriting the source-derived purpose.
1414
+
1415
+ If P1 evidence conflicts with primary surface, record center, observable support,
1416
+ or domain-model evidence, the run must not blindly prefer the prose. It records
1417
+ the conflict and either ranks the candidate with a limitation or opens a
1418
+ frontier to inspect the conflicting source area.
1419
+
1420
+ When multiple purposes compete, `source-purpose-candidates.yaml` must rank them:
1421
+
1422
+ - `primary` — best-supported purpose and adequacy frame for this target
1423
+ - `secondary` — supported but not first-priority for seeding
1424
+ - `candidate` — plausible but insufficiently supported
1425
+ - `rejected` — considered and rejected with rationale
1426
+
1427
+ If no source-derived purpose reaches P1 authority or convergent support, the
1428
+ seed must not invent a purpose or adequacy frame. It records a purpose
1429
+ limitation and the next source frontier needed to resolve it.
1430
+
1431
+ Purpose discovery must avoid these mistakes:
1432
+
1433
+ - treating the user's reconstruct intent as the target purpose
1434
+ - treating implementation mechanism as service purpose
1435
+ - forcing every target into a flow model when the material kind is record,
1436
+ document, spreadsheet, database, or mixed material
1437
+ - picking the most technically complex area instead of the purpose-critical
1438
+ surface, record, calculation, decision, or data model
1439
+ - promoting a secondary admin, setup, export, or diagnostic concern over the
1440
+ target's main purpose without evidence
1441
+ - hiding competing purpose candidates instead of ranking them
1442
+
1443
+ ## 7. Exploration Strategy
1444
+
1445
+ Exploration should look for missing seed layers and maturation frontier, not
1446
+ just missing orientation concepts.
1447
+
1448
+ The next source frontier should prefer source refs that may change:
1449
+
1450
+ - object identity or object boundaries
1451
+ - actor roles and principals
1452
+ - available actions
1453
+ - workflow or state transition understanding
1454
+ - permission or policy treatment
1455
+ - data source, read model, write target, or provenance treatment
1456
+ - competency-question answerability
1457
+ - seed-iteration limitation severity and maturation-frontier priority
1458
+ - source-derived purpose and purpose adequacy frame ranking
1459
+
1460
+ The frontier should not request more source only to add detail that cannot
1461
+ change seed validity for the declared purpose.
1462
+
1463
+ Each repeated observation must be traceable. Runtime records an
1464
+ `observation_batch_id`, `round_id`, `frontier_kind`, `frontier_validation_ref`,
1465
+ and `triggering_frontier_ref` on new observation records, and writes the
1466
+ canonical round-scoped `rounds/<round-id>/source-observation-delta.yaml`
1467
+ artifact before new evidence can enter the next directive, lens judgment,
1468
+ synthesis, maturation answer, ontology expansion, or candidate finalization
1469
+ step. `frontier_kind` is `source_frontier` for seeding exploration and
1470
+ `maturation_closure_frontier` for maturation exploration; the process does not
1471
+ introduce a second maturation-only delta artifact.
1472
+
1473
+ The delta artifact is lineage evidence, not gate truth. Runtime must also write
1474
+ `rounds/<round-id>/source-observation-delta-validation.yaml` to prove the
1475
+ pre-use lineage check passed or failed. Frontier validation authorizes what may
1476
+ be observed; delta validation proves what was actually observed and how it is
1477
+ tied to the round/frontier before downstream semantic use.
1478
+
1479
+ `source_frontier_gate` must validate duplicate status against current
1480
+ `source-observations.yaml`, not only against the source inventory. The
1481
+ `observation_reentry_gate` is the only gate that validates downstream re-entry
1482
+ from declared authority refs: lens judgments, exploration synthesis,
1483
+ candidate inventory/disposition, seed validation artifacts, and maturation
1484
+ downstream artifacts such as `answer-support-ledger.yaml`,
1485
+ `maturation-answer-claims.yaml`, and `ontology-expansion.yaml` when those
1486
+ artifacts can cite frontier-triggered observation ids. The validator must
1487
+ consume the same downstream artifact authorities, or their validation artifacts,
1488
+ that make the relevant generated
1489
+ `frontier_observation_use_by_downstream_artifact` predicate instance true. The
1490
+ aggregate `frontier_observation_used_downstream` predicate is derived from those
1491
+ generated instances and must not maintain a separate artifact list.
1492
+
1493
+ Round-scoped artifacts are append-only. A later round may supersede a prior
1494
+ question, evidence cluster, answer claim, or expansion only by writing a new row
1495
+ with explicit prior refs; it must not mutate prior round authority in place.
1496
+ Readers must resolve historical runs through the registry, active contract,
1497
+ source profile, validator, reference-standard, and migration snapshots recorded
1498
+ in `reconstruct-run-manifest.yaml` and `reconstruct-record.yaml`. If a required
1499
+ snapshot cannot be resolved or migrated, runtime must project `blocked` before
1500
+ semantic reuse.
1501
+
1502
+ ## 8. Candidate Strategy
1503
+
1504
+ The candidate inventory is the bridge between source evidence and seed layers.
1505
+ Root candidate kinds are owned by
1506
+ `reconstruct-contract-registry.yaml#candidate_kind_registry`; this design does
1507
+ not carry an independent candidate-kind enum.
1508
+
1509
+ Every high-salience candidate must appear in `candidate-disposition.yaml`.
1510
+ Disposition is what prevents the seed from losing terms such as user, account,
1511
+ admin, approval, dashboard, cost, export, permission, or invoice simply because
1512
+ they do not fit the conceptual frame.
1513
+
1514
+ `candidate-inventory.yaml` is the candidate-set authority.
1515
+ `candidate-disposition.yaml` is the candidate-disposition authority.
1516
+ `ontology-seed.yaml` may reference those authorities, but it must not restate a
1517
+ second authoritative disposition ledger.
1518
+
1519
+ For `promoted_to_seed_layer`, `target_seed_refs[]` names planned canonical seed
1520
+ refs that the later `ontology-seed.yaml` must realize. The disposition artifact
1521
+ therefore does not prove the seed already exists; it declares the placement
1522
+ commitment that seed validation must close.
1523
+
1524
+ ## 9. Seed Validity Strategy
1525
+
1526
+ Process completion means the run reached an end state and wrote records.
1527
+
1528
+ Seed validity means the authored seed and downstream validation artifacts pass
1529
+ the gates needed for the next `Ontology Maturation` iteration.
1530
+
1531
+ Seed qualitative completion means the seed is the first valid kernel of an
1532
+ actionable ontology. The seed is not expected to be action-ready, but it must
1533
+ preserve enough operational structure for maturation to continue without
1534
+ rediscovering the model from zero.
1535
+
1536
+ A seed satisfies first-kernel quality only when all conditions below hold:
1537
+
1538
+ | Condition | Seed requirement |
1539
+ |---|---|
1540
+ | Purpose boundary | Source-derived purpose, purpose adequacy frame, intended decisions/actions/records, non-goals, and risk boundary are explicit |
1541
+ | Inferred purpose confirmation | If purpose is inferred rather than directly source-declared, user confirmation is recorded as confirmed or revised-and-evidence-checked |
1542
+ | Material primitives | Material objects, actors, decisions, actions, records, states, policies, obligations, and data bindings are present or limitation-backed as required by the material kind |
1543
+ | Purpose adequacy frame | Every required frame element has a seed ref, evidence ref, or limitation-backed frontier |
1544
+ | Salience preservation | Every high-salience candidate has exactly one disposition and promoted candidates are realized in seed refs |
1545
+ | Evidence stance | Claims distinguish observed runtime behavior, schema/contract presence, test/fixture evidence, declared design intent, deferred scope, and unknowns |
1546
+ | Limitation honesty | Missing purpose-critical actors, records, decisions, actions, objects, policies, data, or evidence links are recorded as maturation limitations, not silently omitted |
1547
+ | Frontier usefulness | Unanswered questions are mapped to seed refs, seven dimensions, and plausible next evidence targets |
1548
+ | Validation closure | Required seed, candidate, confirmation, competency-question, assessment, and readiness gates pass or project an explicit limitation state |
1549
+
1550
+ If a seed lacks source-derived purpose authority, or lacks a purpose-critical
1551
+ frame element or limitation-backed frontier for the target material kind, it is
1552
+ not a valid first kernel even when its schema is valid.
1553
+
1554
+ Validation is lifecycle-scoped. A seed-shape validation artifact may not claim
1555
+ final seed validity before seed confirmation, competency-question, assessment,
1556
+ and seed-iteration readiness validation artifacts exist.
1557
+
1558
+ The complete gate and validation-artifact catalog is registry-owned at
1559
+ `reconstruct-contract-registry.yaml#validation_gate_catalog`,
1560
+ `#validator_records`, and `#readiness_projection.handoff_validation_policy`.
1561
+ This design document names gate families only: material profile, source evidence
1562
+ and frontier lineage, candidate disposition, seed layer and connectivity,
1563
+ competency questions and assessment, seed confirmation, conditional query,
1564
+ visualization and graph-exploration proofs, failure/revision handling, run
1565
+ manifest validation, and terminal seed-iteration readiness validation.
1566
+
1567
+ Any planned artifact family becomes executable only as a complete registry set:
1568
+ artifact authority, validation authority, validation gate, validator record,
1569
+ `required_when` predicate, and activation condition must be promoted together.
1570
+ Design prose may describe future artifacts, but runtime readiness may consume
1571
+ only registry-backed validation results. A planned gate without a predicate or
1572
+ validator is a contract defect, not an optional implementation detail.
1573
+
1574
+ Maturation activation is ordered. A planned maturation gate may be promoted only
1575
+ after its upstream gates and validators are implemented:
1576
+
1577
+ | Gate family | Minimum activation prerequisite |
1578
+ |---|---|
1579
+ | baseline | source-purpose candidate authority and seed validation authorities |
1580
+ | actionability matrix | baseline validation |
1581
+ | question frontier | baseline validation |
1582
+ | closure frontier | question-frontier validation |
1583
+ | answer support | question-frontier validation and any applicable authority/proof validation |
1584
+ | authority response | closure-frontier authority request validation |
1585
+ | answer claims | answer-support validation |
1586
+ | ontology expansion | answer-claim validation |
1587
+ | continuation decision | actionability-matrix validation plus any applicable frontier/support/authority validation |
1588
+ | actionable ontology | continuation-decision validation plus any applicable expansion/proof validation |
1589
+
1590
+ In registry activation terms, the continuation decision gate preserves this
1591
+ predecessor explicitly: `maturation_continuation_decision_gate` requires
1592
+ `actionability_matrix_runtime_is_implemented` before promotion. Its validator
1593
+ then consumes `actionability-matrix-validation.yaml` as the evidence that the
1594
+ matrix itself is valid for the concrete maturation state.
1595
+
1596
+ Registry activation prerequisites may include runtime capability predicates and
1597
+ validation-state predicates. Runtime capability predicates prove that a writer,
1598
+ validator, and predicate evaluator exist. Validation-state predicates prove that
1599
+ the concrete upstream artifact for the current run is valid. Promotion readiness
1600
+ must evaluate both classes; an unknown, missing, or false validation-state
1601
+ predicate blocks promotion even when runtime capability exists.
1602
+
1603
+ Promotion readiness is itself a runtime authority. Before a planned maturation
1604
+ gate is activated or a maturation execution is requested, runtime writes and
1605
+ validates:
1606
+
1607
+ ```yaml
1608
+ maturation-promotion-request.yaml:
1609
+ request_id:
1610
+ request_kind: maturation_execution | gate_promotion | combined
1611
+ request_status: requested | accepted | rejected | superseded
1612
+ requested_at:
1613
+ requested_by: user | runtime | external_host
1614
+ trigger_ref:
1615
+ source_session_root:
1616
+ source_reconstruct_record_ref:
1617
+ source_run_manifest_ref:
1618
+ source_handoff_decision_validation_ref:
1619
+ requested_gate_ids: []
1620
+ minimum_required_output_gate_ids:
1621
+ - maturation_baseline_gate
1622
+ - actionability_matrix_gate
1623
+ - maturation_question_frontier_gate
1624
+ minimum_required_output_refs:
1625
+ - maturation-baseline.yaml
1626
+ - actionability-matrix.yaml
1627
+ - maturation-question-frontier.yaml
1628
+ request_rationale:
1629
+ supersedes_request_ref:
1630
+ limitation_refs: []
1631
+
1632
+ maturation-runtime-capability-profile.yaml:
1633
+ gate_capabilities:
1634
+ - gate_id:
1635
+ activation_condition:
1636
+ runtime_flag_observed: true | false
1637
+ artifact_writer_supported: true | false
1638
+ validator_supported: true | false
1639
+ required_when_predicate_supported: true | false
1640
+ validator_id:
1641
+ validator_version:
1642
+ missing_capability_refs: []
1643
+
1644
+ maturation-promotion-readiness.yaml:
1645
+ requested_gate_promotions:
1646
+ - gate_id:
1647
+ requested_activation_condition:
1648
+ upstream_validation_refs: []
1649
+ source_purpose_authority_required: true | false
1650
+ purpose_confirmation_required: true | false
1651
+ promotion_decision: promotable | blocked | deferred
1652
+ missing_authority_refs: []
1653
+ limitation_refs: []
1654
+ ```
1655
+
1656
+ `maturation-promotion-request-validation.yaml` must prove that the request is a
1657
+ durable artifact, requested gates exist in the registry, `trigger_ref` resolves
1658
+ to a user/runtime/external-host authority or prior run artifact, and no
1659
+ runtime-local boolean is used as replay authority. For `request_kind:
1660
+ maturation_execution` or `combined`, validation must also require the minimum
1661
+ executable maturation outputs: `maturation-baseline.yaml`,
1662
+ `actionability-matrix.yaml`, and `maturation-question-frontier.yaml`. If runtime
1663
+ cannot produce one of those outputs, the request must project `blocked` or enter
1664
+ failure/revision classification with explicit limitation refs.
1665
+ `source_handoff_decision_validation_ref` must point to the prior/source seed
1666
+ session handoff authority consumed by maturation. It must not point to the
1667
+ current terminal handoff artifact being computed for the maturation execution
1668
+ itself.
1669
+
1670
+ `maturation-promotion-readiness-validation.yaml` must prove that every requested
1671
+ promotion has runtime-observed capability, a matching artifact writer, validator,
1672
+ `required_when` predicate evaluator support, and concrete upstream validation
1673
+ artifacts whose validation-state predicates are true for the current run.
1674
+ Runtime capability flags are capability evidence only; they are not ordering
1675
+ authority for concrete promotion. Baseline promotion additionally consumes the
1676
+ source-purpose candidate authority when required and purpose-confirmation
1677
+ validation when the selected purpose is inferred or limitation-backed.
1678
+
1679
+ Accepted maturation execution has a minimum output contract. The registry
1680
+ predicates `maturation_baseline_required`, `actionability_matrix_required`, and
1681
+ `maturation_question_frontier_required` become true when a validated
1682
+ `maturation-promotion-request.yaml` has `request_kind: maturation_execution` or
1683
+ `combined`. Missing validation artifacts for those outputs are therefore
1684
+ required-gate failures, not `not_applicable` planned paths.
1685
+
1686
+ Once a planned gate is activated, its missing or failed validation artifact is
1687
+ classified through the same failure/revision path as active seeding gates.
1688
+ Failure classification must consume the failed gate validation artifact or the
1689
+ recorded missing-gate projection; revision proposal then scopes the repair to
1690
+ that gate's authority inputs. Planned maturation failures must not disappear just
1691
+ because the current terminal seed-readiness path can still finish.
1692
+
1693
+ `seed_confirmation_gate` is lifecycle-required whenever seed validity or seed
1694
+ iteration readiness is projected. If `seed-confirmation.yaml` or
1695
+ `seed-confirmation-validation.yaml` is absent at that lifecycle point, runtime
1696
+ must project `blocked`. A limitation state is allowed only when both
1697
+ `seed-confirmation.yaml` and `seed-confirmation-validation.yaml` exist and the
1698
+ validation artifact proves the limitation state against the validated seed and
1699
+ derives CQ eligibility. Assessment-aware seed iteration readiness is evaluated by
1700
+ `handoff-decision-validation.yaml`.
1701
+ `handoff-decision-validation.yaml` must validate against the validation-result
1702
+ authorities that contribute to readiness, including
1703
+ `reconstruct-run-manifest.pre-handoff-validation.yaml`; it may not rely only on raw authored
1704
+ artifacts, unvalidated run manifests, or record projections.
1705
+ The set of contributing validation artifacts is condition-aware. Runtime derives
1706
+ applicability from each gate's `required_when`: missing required-and-applicable
1707
+ validation artifacts project `blocked`, while unmet conditional paths project
1708
+ `not_applicable` and do not block a clean run.
1709
+ Terminal readiness evaluates active gates and promoted/requested planned gates
1710
+ from the registry. Accepted maturation execution admits the baseline,
1711
+ actionability matrix, and question-frontier gates into terminal gate projection
1712
+ through their `*_required` predicates even when the corresponding artifact is
1713
+ absent, so absence becomes `blocked` rather than invisible.
1714
+ `handoff-decision-validation.yaml` must consume the applicable promoted/requested
1715
+ planned-gate validation artifacts or their missing-gate projection, including
1716
+ promotion request, runtime capability, promotion readiness, baseline,
1717
+ actionability matrix, and question-frontier validations for accepted maturation
1718
+ execution. Failure classification must cover those same missing or failed planned
1719
+ gates before terminal output claims readiness.
1720
+ The authoritative set of applicable planned-gate validation refs is derived from
1721
+ `validation_gate_catalog` and `planned_validation_gate_catalog` by evaluating
1722
+ their `required_when` predicates. Hand-maintained consumer lists in validators
1723
+ are cache hints and must not be treated as the authority for terminal readiness
1724
+ or failure classification.
1725
+ Each `required_when` predicate is evaluated from the registry-owned predicate
1726
+ catalog, which names input artifact refs, field-level truth expressions, unknown
1727
+ projection, and the explanation template for status/result surfaces.
1728
+ The `required-when-evaluation-validator` must resolve every concrete `gate_id`
1729
+ against exactly one row from `validation_gate_catalog` or
1730
+ `planned_validation_gate_catalog`, record the source catalog for the evaluated
1731
+ gate instance, and fail closed on unknown or duplicate active/planned gate ids.
1732
+ When multiple predicate rows share the same concept, the registry must model them
1733
+ as generated instances of a predicate family. Frontier-observation downstream-use
1734
+ predicates are generated instances of
1735
+ `frontier_observation_use_by_downstream_artifact`, not separate ontology
1736
+ concepts.
1737
+ If an active gate names a predicate expression that the runtime evaluator does
1738
+ not support, runtime treats that gate as unknown and fails the handoff closed
1739
+ until the evaluator is implemented. Unsupported active predicates must not
1740
+ silently project `not_applicable`.
1741
+ Terminal `handoff-decision-validation.yaml` is produced by `handoff_gate`.
1742
+ `final-output.md` and `reconstruct-record.yaml` are emitted only after
1743
+ `handoff-decision-validation.yaml` passes; they are projections from the
1744
+ validated seed iteration readiness result, not inputs to the terminal readiness
1745
+ validator.
1746
+ `final-output-provenance-validation.yaml` validates the post-handoff user-facing
1747
+ projection. It is not a readiness gate for `handoff-decision-validation.yaml`.
1748
+
1749
+ The canonical seed iteration readiness projection must distinguish:
1750
+
1751
+ - ready for the next maturation iteration
1752
+ - usable for maturation with named limitations
1753
+ - not ready because required seed validity gates failed or the frontier is not actionable
1754
+ - blocked because source or user confirmation is missing
1755
+
1756
+ Artifact-specific readiness fields may use local names, but status/result APIs
1757
+ and final output must project one canonical readiness value:
1758
+ `ready`, `limited`, `not_ready`, or `blocked`.
1759
+
1760
+ The same projection must expose the reason, not just the folded readiness value.
1761
+ `handoff-decision-validation.yaml.gate_projection[]` is the authority for
1762
+ status/result/final-output gate reporting. Each projected gate row must include
1763
+ the concrete gate instance, `gate_id`, `source_catalog_id`,
1764
+ `validation_artifact_ref`, `required_when` predicate, activation condition,
1765
+ activation status, applicability, validation status, readiness effect,
1766
+ limitation refs, and explanation. Unknown or duplicate active/planned gate ids,
1767
+ hidden applicable gates, and missing applicable validation artifacts project
1768
+ `blocked`.
1769
+
1770
+ For `mixed` targets, status/result/final-output surfaces must also expose the
1771
+ member lineage that grounds modeled mixed-purpose elements and the member
1772
+ lineage that caused any non-ready aggregate readiness:
1773
+ `member_id`, `target_ref`, material kind, selected profile id, selected profile
1774
+ snapshot ref, definition hash, support state, runtime implementation status,
1775
+ source refs, cross-material refs, purpose element refs, validation ref,
1776
+ limitation refs, aggregate readiness effect, and next action. A user or caller
1777
+ must not need to re-resolve `target-material-profile.yaml` or candidate
1778
+ artifacts to know which member grounds a seed element, which member blocked the
1779
+ seed, which profile was selected, or what next action is required.
1780
+
1781
+ The registry predicate catalog should contain only executable predicates,
1782
+ predicate-family instances that have current consumers, or explicitly reserved
1783
+ predicates with a named future consumer. Unused executable-looking predicate
1784
+ rows are removed rather than kept as compatibility aliases.
1785
+
1786
+ ## 10. Maturation Convergence Strategy
1787
+
1788
+ `Ontology Maturation` converges when the ontology can support the declared
1789
+ decision or action purpose without material unresolved questions. Convergence
1790
+ does not mean the ontology is globally complete. It means the remaining gaps are
1791
+ outside the source-derived purpose, explicitly deferred, or non-material to the
1792
+ source-derived `PurposeAdequacyFrame`.
1793
+
1794
+ Maturation operates over a kernel completeness matrix:
1795
+
1796
+ | Level | Meaning |
1797
+ |---|---|
1798
+ | L0 missing | The element or dimension is absent |
1799
+ | L1 identified | A candidate is named, but not yet structurally placed |
1800
+ | L2 modeled | The element has a stable ref, type, relation, and declared role |
1801
+ | L3 evidenced | Material claims are backed by convergent evidence or explicit authority |
1802
+ | L4 validated for purpose | The purpose adequacy frame can answer the declared competency questions through positive validation or proof; operational proof is required only for rows that claim runtime/query/API behavior, and residual limitations are tracked outside the actionability claim |
1803
+
1804
+ Seed output should reach at least L2 for material purpose adequacy primitives,
1805
+ with L1/L2 limitation-backed frontier for incomplete dimensions. Maturation
1806
+ should reach L4 for every required purpose adequacy frame element and at least
1807
+ L3 for supporting elements that affect interpretation, governance, or evidence
1808
+ trust.
1809
+
1810
+ The kernel completeness matrix is evaluated separately for `static_surface`,
1811
+ `kinetic_surface`, and `dynamic_surface`. A seed may be valid for maturation
1812
+ with a limitation-backed `dynamic_surface`, but an `ActionableOntology` may not
1813
+ claim actionability while any material static, kinetic, or dynamic surface is
1814
+ absent, unsupported, or only named without evidence.
1815
+
1816
+ Maturation may claim the output is an `ActionableOntology` only when all
1817
+ convergence conditions hold:
1818
+
1819
+ | Condition | Maturation requirement |
1820
+ |---|---|
1821
+ | Source-purpose coverage | Every required purpose adequacy frame element derived from source purpose is modeled, evidenced, or limitation-backed |
1822
+ | Competency answerability | Required competency questions for the declared purpose are answerable from ontology refs, evidence refs, or validated query/proof artifacts |
1823
+ | Material gap closure | No blocker or high-severity unresolved question remains for the source-derived purpose adequacy frame |
1824
+ | Evidence convergence | Each material answer is supported by sufficient convergent evidence, or is explicitly marked as authority-provided or externally blocked |
1825
+ | Runtime/query proof | Claimed query, graph, visualization, API, or implementation access paths are validated when they are part of the declared downstream use |
1826
+ | Policy and permission closure | Sensitive actions and sensitive data have actor, role, permission, and exception treatment or an explicit non-actionable limitation |
1827
+ | Data authority closure | Read sources, write targets, provenance, derived projections, and source gaps are distinguishable and closed for the declared purpose |
1828
+ | External boundary closure | External systems, standards, integrations, and alignment requirements are either modeled, limitation-backed, or declared out of scope |
1829
+ | Frontier exhaustion by materiality | Remaining frontier questions are non-material, explicitly deferred, or cannot be advanced without new source/user authority |
1830
+ | Static/kinetic/dynamic actionability | Static structure, kinetic behavior, and dynamic condition boundaries are each answerable from ontology refs and evidence refs, or limitation-backed without claiming actionability |
1831
+
1832
+ Maturation should continue when a frontier question can still change any
1833
+ material purpose adequacy element, including object boundary, actor authority,
1834
+ record completeness, decision/action availability, permission, state transition,
1835
+ data binding, evidence trust, or external dependency. Maturation should not
1836
+ continue merely to add explanatory detail that cannot change the declared
1837
+ decision/action/record outcome.
1838
+
1839
+ ## 11. Artifact Plan
1840
+
1841
+ The complete target artifact list is registry-owned at
1842
+ `reconstruct-contract-registry.yaml#artifact_authorities`. This plan groups the
1843
+ artifact families as preparation/observation, round exploration,
1844
+ candidate/disposition, seed/validation, competency questions and assessment,
1845
+ confirmation, conditional proof authorities, failure/revision, metrics,
1846
+ handoff, final output, run manifest, and reconstruct record.
1847
+
1848
+ `ontology-seed.yaml` is the seed semantic authority.
1849
+ `candidate-disposition.yaml` is the disposition authority.
1850
+ `claim-realization-map.yaml` is the per-seed-claim realization stance authority
1851
+ registered in `reconstruct-contract-registry.yaml`; it records exactly one
1852
+ realization row per seed claim and closes realization evidence refs against
1853
+ `source-observations.yaml`. It is not a legacy compatibility projection.
1854
+ `competency-questions.yaml` is the question authority.
1855
+ `competency-question-assessment.yaml` is the answerability-result authority.
1856
+ `reconstruct-contract-registry.yaml` is the active runtime authority graph.
1857
+ `reconstruct-record.yaml` is the run authority and artifact index; it contains
1858
+ refs, hashes, validation statuses, and bounded projections only.
1859
+
1860
+ ## 12. Runtime Validation Plan
1861
+
1862
+ Runtime validation should be deterministic and fail loud.
1863
+
1864
+ Validation responsibilities:
1865
+
1866
+ - schema parse and required field checks
1867
+ - allowed enum checks
1868
+ - id uniqueness
1869
+ - cross-reference closure
1870
+ - evidence-ref closure
1871
+ - material-kind/source-ref alignment
1872
+ - pre-use round lineage, frontier-to-observation closure, and post-use
1873
+ observation re-entry closure
1874
+ - seed layer closure
1875
+ - source-derived purpose and purpose adequacy evidence closure
1876
+ - inferred-purpose user confirmation closure
1877
+ - candidate disposition completeness
1878
+ - action actor/object binding
1879
+ - permission coverage or declared limitation
1880
+ - data binding coverage or declared limitation
1881
+ - ontology-facing mapping or limitation coverage
1882
+ - competency-question coverage and assessment trace
1883
+ - failure classification and revision proposal bounds
1884
+ - stop-decision and handoff-validation consistency
1885
+ - registry-selected artifact, gate, profile, lens judgment, and readiness
1886
+ projection consistency
1887
+ - lifecycle-required seed confirmation and seed-iteration validation-result authority
1888
+ closure
1889
+ - final-output provenance footer
1890
+
1891
+ Runtime may calculate metrics from artifacts, but metrics are not semantic truth.
1892
+
1893
+ ## 13. Prompt Plan
1894
+
1895
+ Prompt packets should give the host LLM:
1896
+
1897
+ - reconstruct intent, target refs, and source-derived purpose evidence
1898
+ - material profile
1899
+ - compact source observations
1900
+ - full artifact ref locations
1901
+ - active seed contract
1902
+ - required output schema for the current stage
1903
+ - validation failure from the previous attempt, when retrying
1904
+ - selected registry snapshot, source profile ids, and reconstruct lens ids
1905
+ - validator ids, validator versions, and prior validation failure artifacts when
1906
+ retrying
1907
+
1908
+ Prompt packets must not include development history. If the model needs to know
1909
+ why a previous attempt failed, it should receive the validation artifact, not
1910
+ archived design discussion.
1911
+
1912
+ ## 14. Result UX Plan
1913
+
1914
+ The beginning of a run should state:
1915
+
1916
+ - target refs
1917
+ - material kind and profile
1918
+ - execution profile and provider route, without secrets
1919
+ - reconstruct intent, discovered source purpose, purpose adequacy frame, and review direction
1920
+ - expected artifact path
1921
+
1922
+ Progress updates should be stepwise:
1923
+
1924
+ ```text
1925
+ [1/8] Source classified
1926
+ [2/8] Source evidence observed
1927
+ [3/8] Semantic judgments running
1928
+ [4/8] Candidate disposition built
1929
+ [5/8] Seed authored
1930
+ [6/8] Seed-shape validation running
1931
+ [7/8] Questions, assessment, and seed-readiness validation running
1932
+ [8/8] Final output and record written
1933
+ ```
1934
+
1935
+ Updates should include new information learned from artifacts, not only process
1936
+ metadata. Example:
1937
+
1938
+ - newly identified object candidates
1939
+ - unresolved actor or permission gaps
1940
+ - actions found without writeback evidence
1941
+ - source areas that changed the frontier
1942
+ - validation gates that passed or failed
1943
+
1944
+ No separate HTML UI is required. CLI/MCP hosts should receive progress through
1945
+ LLM-presentable status text, status polling, and native progress notifications
1946
+ where supported.
1947
+
1948
+ ## 15. Implementation Sequence
1949
+
1950
+ Use this sequence as the coding roadmap. Each stage must leave the runtime in a
1951
+ verifiable state; do not start a later stage by stubbing semantic artifacts just
1952
+ to make the process look complete.
1953
+
1954
+ Implementation file map:
1955
+
1956
+ | Concern | Primary files |
1957
+ |---|---|
1958
+ | artifact/type seats | `src/core-runtime/reconstruct/artifact-types.ts` |
1959
+ | registry/gate authority | `.onto/processes/reconstruct/reconstruct-contract-registry.yaml`, `src/core-runtime/reconstruct/contract-registry.ts` |
1960
+ | seeding runtime sequence and prompts | `src/core-runtime/reconstruct/run.ts` |
1961
+ | source-purpose candidate validation | new `src/core-runtime/reconstruct/purpose-candidates-validation.ts` plus tests |
1962
+ | purpose confirmation validation | new or extended `src/core-runtime/reconstruct/purpose-confirmation-validation.ts` plus tests |
1963
+ | candidate surface/facet validation | existing candidate-disposition validation path and tests |
1964
+ | seed surface closure validation | `src/core-runtime/reconstruct/ontology-seed-validation.ts` and tests |
1965
+ | post-seed readiness and terminal projection | `src/core-runtime/reconstruct/post-seed-validation.ts`, `src/core-runtime/reconstruct/terminal-validation.ts`, `src/core-runtime/reconstruct/record.ts` |
1966
+ | MCP/API projection | `src/core-api/reconstruct-api.ts`, `src/mcp/server.ts` |
1967
+ | active docs and user-facing guide | this document, `operational-ontology-seed-contract.md`, `README.md`, `IMPLEMENTATION_MAP.html` |
1968
+
1969
+ First implementation branch must start with Stage 0, then prioritize seeding
1970
+ S1-S8. Maturation M1-M2 can follow once seed readiness has real-source evidence.
1971
+ M3-M4 should not be promoted until source-frontier observation,
1972
+ maturation-authority-response validation, and answer-support-ledger validation
1973
+ are real runtime behavior.
1974
+
1975
+ Required test path for each implementation slice:
1976
+
1977
+ 1. add or update a narrow fixture test for the validator or prompt output shape;
1978
+ 2. add an integration test around `run.ts` for the changed artifact sequence;
1979
+ 3. run `npx vitest run` on the changed reconstruct tests;
1980
+ 4. run `npm run check:ts-core`;
1981
+ 5. run `npm run build:ts-core`;
1982
+ 6. for release or merge, run one real-source reconstruct E2E and verify the first
1983
+ invalid gate fails loud or the seed/maturation artifacts pass with named
1984
+ limitations.
1985
+
1986
+ ### Stage 0. Registry And Projection Substrate
1987
+
1988
+ Expected result:
1989
+
1990
+ - `src/core-runtime/reconstruct/contract-registry.ts` parses active and planned
1991
+ artifact authorities, validation gates, validators, activation conditions, and
1992
+ required-when predicates
1993
+ - terminal validation evaluates active gates plus requested/promoted planned
1994
+ gates from the registry, not from hand-maintained consumer lists
1995
+ - planned gates are inactive by default; a requested/promoted planned gate
1996
+ projects `inactive`, `requested`, `promoted`, `applicable`,
1997
+ `not_applicable`, `blocked_missing_runtime`,
1998
+ `blocked_missing_validation`, or `failed_validation`
1999
+ - status/result/final-output surfaces expose gate projection rows with
2000
+ `source_catalog_id`, activation condition/status, applicability, validation
2001
+ refs/status, readiness effect, limitations, and explanation
2002
+ - unknown or duplicate active/planned `gate_id` values fail closed
2003
+ - `mixed` target status/result projection preserves member lineage from
2004
+ `target-material-profile-validation.yaml`, including the blocking member,
2005
+ modeled purpose element, member source refs, cross-material refs, selected
2006
+ profile, material kind, validation ref, limitation, and next action
2007
+ - the required-when predicate catalog contains only predicates with current
2008
+ consumers or explicitly reserved predicates with a named future consumer
2009
+
2010
+ ### Stage 1. Active Documentation Baseline
2011
+
2012
+ Expected result:
2013
+
2014
+ - active reconstruct docs reference only the current seed model
2015
+ - active docs list the current contract set
2016
+ - operation-facing docs do not load development history
2017
+ - `README.md`, `AGENTS.md`, and `IMPLEMENTATION_MAP.html` point to the same
2018
+ seed target
2019
+
2020
+ ### Stage 2. Schema And Type Seats
2021
+
2022
+ Expected result:
2023
+
2024
+ - TypeScript types exist for target artifacts and validation results
2025
+ - current runtime artifact names match this design
2026
+ - registry entries exist for every active artifact, validation gate, source
2027
+ profile, reconstruct lens judgment, and readiness projection
2028
+ - old implementation-only shape names are removed from public status/result
2029
+ surfaces
2030
+ - fixture parsers reject malformed seed layers and dangling refs
2031
+
2032
+ ### Stage 3. Prompt Rewire
2033
+
2034
+ Expected result:
2035
+
2036
+ - author prompts request `candidate-inventory.yaml`,
2037
+ `candidate-disposition.yaml`, and `ontology-seed.yaml`
2038
+ - author prompts request `source-purpose-candidates.yaml` before seed authoring
2039
+ and consume `purpose-confirmation-validation.yaml` when purpose is inferred
2040
+ - author prompts derive target purpose and purpose adequacy frame from source
2041
+ evidence, not from the user's generic reconstruct intent
2042
+ - seed authoring receives source-profile facet guidance and maps purpose
2043
+ adequacy required elements, candidates, and seed content to
2044
+ `static_surface`, `kinetic_surface`, and `dynamic_surface`
2045
+ - prompt flow requests user confirmation before treating an inferred purpose as
2046
+ the seed purpose
2047
+ - question prompts request `competency-questions.yaml` only after seed-shape
2048
+ validation succeeds or records explicit seed limitations
2049
+ - prompts load only active contracts and compact source evidence
2050
+ - retry prompts receive validation failures as the repair context
2051
+
2052
+ ### Stage 4. Runtime Gates
2053
+
2054
+ Expected result:
2055
+
2056
+ - every validation gate named by the purpose discovery, seed validity, and
2057
+ maturation convergence strategies has a deterministic validator before it
2058
+ becomes active
2059
+ - source-purpose candidate validation and purpose-confirmation validation are
2060
+ separate runtime gates before seed readiness can project `ready` or `limited`
2061
+ - ontology seed validation checks actionability surface closure, not only
2062
+ declaration: required purpose elements must be modeled, limitation-backed, or
2063
+ frontier-backed across static, kinetic, and dynamic surfaces
2064
+ - inferred-purpose confirmation is represented as a blocking gate when no direct
2065
+ source-declared purpose exists
2066
+ - validation phases are split into seed-shape, question coverage, question
2067
+ assessment, confirmation, and seed iteration readiness validation
2068
+ - active source-frontier validation records dependency proof on
2069
+ `target-material-profile-validation.yaml`; source-observation deltas,
2070
+ admission lineage, and post-use re-entry validation remain planned gates until
2071
+ their validators are promoted in the registry
2072
+ - target material profile facts and material profile gate status are separated
2073
+ into `target-material-profile.yaml` and `target-material-profile-validation.yaml`
2074
+ - source frontier validation is represented by `source_frontier_gate`
2075
+ - seed confirmation validation is represented by `seed_confirmation_gate`
2076
+ - seed confirmation is required before seed validity or seed iteration readiness is
2077
+ projected; missing confirmation projects `blocked` unless a valid limitation
2078
+ state is recorded
2079
+ - seed-confirmation and seed-readiness validators consume validation-result authorities,
2080
+ not only raw authored artifacts or reconstruct-record projections
2081
+ - seed-readiness validation applies each validation artifact through the registry's
2082
+ `required_when` conditions so inactive source-frontier, failure, or revision
2083
+ paths project `not_applicable` instead of `blocked`
2084
+ - ontology seed validation may validate expected competency coverage axes, but
2085
+ it must not require downstream competency-question ids before
2086
+ `competency-questions.yaml` is authored
2087
+ - source-frontier validation owns duplicate/inventory/upstream material-profile
2088
+ checks; planned round-lineage and observation-reentry validators own pre-use
2089
+ lineage and downstream re-entry checks after promotion
2090
+ - failure classification and revision proposal validators run when required
2091
+ applicable validation artifacts are missing, gates fail, or halt conditions
2092
+ occur
2093
+ - failure classification validation consumes failed-gate validation artifacts or
2094
+ runtime halt evidence, and revision proposal validation consumes
2095
+ `failure-classification-validation.yaml`
2096
+ - failed gates write structured validation artifacts
2097
+ - no gate repairs missing semantic content
2098
+ - status/result APIs expose failed gates and seed-iteration limitations
2099
+
2100
+ ### Stage 5. Final Output And Record
2101
+
2102
+ Expected result:
2103
+
2104
+ - final output presents purpose, seed layers, maturity frontier, trust limits,
2105
+ next iteration target, and artifact refs
2106
+ - `reconstruct-record.yaml` indexes every artifact and validation result
2107
+ - `handoff-decision-validation.yaml` proves the stop decision and runtime
2108
+ readiness projection agree with validation artifacts and the validated
2109
+ pre-handoff run-manifest snapshot before final output and record projections
2110
+ are emitted
2111
+ - final output and status/result APIs expose one canonical seed iteration
2112
+ readiness projection
2113
+ - seed validity and process completion are reported separately
2114
+ - final output explains which source evidence established the purpose adequacy frame
2115
+ - final output reports whether the purpose was directly source-declared or
2116
+ user-confirmed after inference
2117
+
2118
+ ### Stage 6. Maturation Runtime Surface
2119
+
2120
+ Expected result:
2121
+
2122
+ - maturation begins from validated seed artifacts and does not rerun seeding
2123
+ - `maturation-baseline.yaml` records the immutable starting matrix and
2124
+ `maturation-baseline-validation.yaml` proves its derivation
2125
+ - `actionability-matrix.yaml` records the current derived projection and
2126
+ `actionability-matrix-validation.yaml` proves recomputation from validated
2127
+ baseline plus validated maturation deltas
2128
+ - `maturation-question-frontier.yaml` classifies unanswered questions by
2129
+ materiality, actionability surface, maturity dimension, and purpose element
2130
+ - `maturation-closure-frontier.yaml` requests only source refs or user/external
2131
+ authority that can change material answers
2132
+ - `answer-support-ledger.yaml` separates direct authority, runtime proof,
2133
+ user confirmation, and convergent source evidence
2134
+ - `maturation-authority-response.yaml` records user, runtime-capability,
2135
+ external-system, or domain-standard responses to closure-frontier authority
2136
+ requests; `maturation-authority-response-validation.yaml` is the intermediate
2137
+ authority that answer support and continuation logic consume
2138
+ - `maturation-answer-claims.yaml` and `ontology-expansion.yaml` author bounded
2139
+ semantic changes from validated evidence only
2140
+ - `actionability-matrix.yaml` records L0-L4 levels for static, kinetic, and
2141
+ dynamic surfaces across the seven dimensions, including
2142
+ `aggregate_readiness_effect` for mixed-member and aggregate rows
2143
+ - `maturation-continuation-decision.yaml` projects `continue`, `ask_user`, `blocked`,
2144
+ `actionable_limited`, or `actionable_ready`
2145
+ - `maturation-continuation-decision-validation.yaml` proves the projection follows the
2146
+ validated matrix and any applicable frontier/evidence authorities
2147
+ - `actionable-ontology.yaml` is emitted only when final actionability validation
2148
+ passes or a bounded limited projection is explicit
2149
+
2150
+ ### Stage 7. E2E Verification
2151
+
2152
+ Expected result:
2153
+
2154
+ - a real repository run produces `ontology-seed.yaml`
2155
+ - source refs close against `source-observations.yaml`
2156
+ - candidate disposition includes salient objects, actors, actions, permissions,
2157
+ and data sources
2158
+ - source-derived purpose and purpose adequacy frame are ranked and evidence-backed
2159
+ - inferred source purpose is user-confirmed before seed readiness projects
2160
+ `ready` or `limited`
2161
+ - competency questions and assessments are authored from validated seed refs and
2162
+ close through traceable evidence
2163
+ - round-scoped observation lineage links frontier-triggered observations back
2164
+ into lens judgment and synthesis
2165
+ - run manifest records the registry ref/hash, active contract refs/hashes,
2166
+ source profile snapshots and migration mappings, lens ids, validator
2167
+ versions, reference authority snapshots, and pattern catalog URI/snapshot
2168
+ facts used for the run
2169
+ - review over the produced seed can evaluate seed adequacy and maturation
2170
+ frontier without needing development history
2171
+ - failures are visible at the first invalid gate
2172
+
2173
+ ## 16. Completion Definition For This Recomposition
2174
+
2175
+ The recomposition is implemented when a fresh reconstruct run against a real
2176
+ target produces:
2177
+
2178
+ 1. material-aware source observations,
2179
+ 2. source-purpose candidates, purpose candidate validation, and purpose
2180
+ confirmation validation when required,
2181
+ 3. candidate inventory and disposition with purpose-element and actionability
2182
+ surface mapping,
2183
+ 4. `ontology-seed.yaml` using the active seed contract,
2184
+ 5. source-derived purpose and purpose adequacy evidence closure,
2185
+ 6. user confirmation for inferred purpose when direct source purpose is absent,
2186
+ 7. deterministic validation artifacts for every gate,
2187
+ 8. canonical candidate-disposition, competency-question, assessment, and
2188
+ handoff-validation authorities, including diagnostic or claim-based P3
2189
+ competency-question disposition when ontology domain competency admission is present,
2190
+ 9. active source-frontier dependency validation, plus promoted pre-use lineage
2191
+ and post-use re-entry validation when multi-round validators become active,
2192
+ 10. registry ref/hash plus active contract ref/hash, source profile migration,
2193
+ lens judgment, concrete gate-instance, validator, reference-standard,
2194
+ pattern-catalog URI/snapshot, and readiness-projection snapshots,
2195
+ 11. separate process-completion and seed-validity reporting,
2196
+ 12. final output that explains `OntologySeed` content, source-derived purpose,
2197
+ purpose adequacy frame, seed iteration readiness, maturation frontier, and
2198
+ limitations, and
2199
+ 13. a reconstruct record whose artifact refs are the source of truth.
2200
+
2201
+ The maturation stage is implemented when a fresh run can continue from that
2202
+ seed and produce:
2203
+
2204
+ 1. `maturation-runtime-capability-profile.yaml`,
2205
+ `maturation-promotion-request.yaml`, `maturation-promotion-readiness.yaml`,
2206
+ and their validations when planned maturation gates are promoted or maturation
2207
+ execution is requested,
2208
+ 2. `maturation-baseline.yaml` and validation,
2209
+ 3. `maturation-question-frontier.yaml` and validation,
2210
+ 4. `maturation-closure-frontier.yaml` and validation when additional evidence is
2211
+ needed,
2212
+ 5. `answer-support-ledger.yaml` and validation,
2213
+ 6. `maturation-authority-response.yaml` and validation when user,
2214
+ runtime-capability, external-system, or domain-standard authority is needed,
2215
+ 7. `maturation-answer-claims.yaml` and validation,
2216
+ 8. `ontology-expansion.yaml` and validation,
2217
+ 9. `actionability-matrix.yaml` and validation,
2218
+ 10. `maturation-continuation-decision.yaml` and validation, and
2219
+ 11. `actionable-ontology.yaml` plus validation when readiness is
2220
+ `actionable_limited` or `actionable_ready`.