onto-mcp 0.3.0 → 0.3.1

package/.onto/authority/core-lexicon.yaml

@@ -1108,6 +1108,17 @@ terms:
       - "Orthogonal to medium: medium is a cross-product reference and learning frame such as excel or cli; target_material_kind is a per-run target classification."
       - "Orthogonal to target_input_kind: target_input_kind says how the target entered the runtime, such as single_file or git_diff; target_material_kind says what kind of material is being handled."
       - "Do not use review context `source_kind` for this axis. In review artifacts, source_kind identifies context-source artifacts such as materialized_input or review_target_profile."
+  - term_id: "pipeline_execution_ledger"
+    canonical_label: "PipelineExecutionLedger"
+    korean_label: "파이프라인 실행 단위 원장"
+    axis: "execution_unit"
+    term_status: "active"
+    definition: "Runtime-owned ledger projection that records per-unit execution status, artifact refs, hashes, trust status, and upstream/downstream boundaries across review, reconstruct, evolve, and later onto pipelines."
+    notes:
+      - "Primary purpose is artifact trust and provenance: which outputs are trusted, untrusted, or blocked by upstream failure."
+      - "Continuation and repair flows consume this ledger, but they are not the ledger's only purpose."
+      - "Semantic ledgers such as review finding-ledger.yaml and issue-ledger.yaml explain meaning; PipelineExecutionLedger explains whether the execution process that produced artifacts can be trusted."
+      - "Shared process contract: .onto/processes/shared/pipeline-execution-ledger-contract.md."
   - term_id: "context_isolated_reasoning_unit"
     canonical_label: "ContextIsolatedReasoningUnit"
     korean_label: "맥락 격리 추론 단위"

package/.onto/processes/evolve/material-kind-adapter-contract.md

@@ -20,6 +20,7 @@ The shared material contract is:
 
 ```text
 .onto/processes/shared/target-material-kind-contract.md
+.onto/processes/shared/pipeline-execution-ledger-contract.md
 ```
 
 No `evolve` runtime or MCP tool is active in this repository. This document is
@@ -52,6 +53,7 @@ Runtime may own:
 - source and artifact refs
 - deterministic metrics and validation reports
 - unsupported or unknown material failure records
+- pipeline pipeline execution ledger projection for artifact trust and provenance
 
 Host LLM and user-mediated flow own:
 
@@ -87,6 +89,7 @@ design-stage output:
 | `evolve-adapter-selection.yaml` | runtime | selected adapter id, material kind, support status, and unsupported reason |
 | `evolve-context-observations.yaml` | runtime | material-specific current-state observations without design recommendations |
 | `evolve-specification.yaml` | host LLM, user confirmed | proposed design change after inquiry and scope agreement |
+| future `pipeline-execution-ledger.yaml` or status projection | runtime | trust status for target profile, adapter selection, observations, specification, validation, and final disposition units |
 | `evolve-record.yaml` | runtime assembly | artifact refs, material status, validation summaries, and final disposition refs |
 
 These names are future contract placeholders. Runtime implementation must either
@@ -111,3 +114,6 @@ When future evolve implementation starts, the first tests should prove:
 - unsupported material states produce explicit structured output
 - generated artifacts preserve `target_material_kind`
 - runtime outputs bounded observations and refs, not design decisions
+- status/result surfaces expose an pipeline execution ledger projection so callers
+  can see which evolve artifacts are trusted, untrusted, or blocked by upstream
+  failure

package/.onto/processes/reconstruct/reconstruct-boundary-contract.md

@@ -1,6 +1,6 @@
 # Reconstruct Boundary Contract
 
-> Status: design contract with bounded happy-path runtime.
+> Status: design contract with bounded happy-path runtime and post-Seed loop target.
 > Purpose: define how `reconstruct` should be reintroduced without reviving the
 > retired runtime ontology generator path.
 
@@ -19,10 +19,11 @@ The shared goal contract for this axis is
 
 The active full product runtime remains `review`. `reconstruct` now has a
 bounded MCP surface for source profile listing, source observation, directive
-validation, happy-path execution, status, and result reads. The happy path is
-not a general ontology generator: it requires pluggable LLM-owned directive
-authors and confirmation providers for Seed content, competency questions, stop
-decisions, and final output.
+validation, post-Seed mock execution, status, and result reads. The runtime path
+is not a general ontology generator: it requires pluggable LLM-owned directive
+authors and confirmation providers for Seed content, claim realization,
+competency questions, assessments, failure classifications, revision proposals,
+stop decisions, and final output.
 
 Retired material stays retired:
 
@@ -36,8 +37,10 @@ The current design seat is:
 
 ```text
 .onto/processes/reconstruct/reconstruct-boundary-contract.md
+.onto/processes/reconstruct/reconstruct-execution-ux-contract.md
 .onto/processes/reconstruct/source-profile-contract.md
 .onto/processes/reconstruct/source-profiles/
+.onto/processes/shared/pipeline-execution-ledger-contract.md
 ```
 
 The planned implementation seat is:
@@ -52,15 +55,15 @@ src/mcp/server.ts
 Current runtime helpers under `src/core-runtime/reconstruct/` load source
 profiles, write preparation artifacts, validate source-observation boundaries,
 validate `SourceObservationDirective` evidence refs, validate
-`SeedCandidateDirective` shape plus evidence refs, compute deterministic
-metrics, and assemble `reconstruct-record.yaml`. The happy-path runner
-orchestrates these gates and delegates semantic directives to a pluggable
+`SeedCandidateDirective` shape plus evidence refs, validate post-Seed artifacts,
+compute deterministic metrics, and assemble `reconstruct-record.yaml`. The
+runner orchestrates these gates and delegates semantic directives to a pluggable
 directive author.
 
 `src/core-api/reconstruct-api.ts` exposes these helpers as a bounded library
 facade for MCP tooling. It can prepare reconstruct artifacts, list source
-profiles, validate LLM-authored directive files, run the happy path, assemble
-records, and read status/result artifacts. It does not author semantic
+profiles, validate LLM-authored directive files, run the post-Seed mock loop,
+assemble records, and read status/result artifacts. It does not author semantic
 directives.
 
 Runtime implementation must not start from tool schemas alone. The ready order is:
@@ -119,6 +122,7 @@ Current concept decisions:
 | Name | Decision | Reason |
 |---|---|---|
 | `target_material_kind` | promoted shared term | Review, reconstruct, and evolve all need a target-material axis that is separate from domain, medium, target input kind, and artifact role. |
+| `PipelineExecutionLedger` | promoted shared term | Review, reconstruct, evolve, and later pipelines need the same runtime-owned artifact trust/provenance projection. |
 | `source_kind` | not used for material classification | Review already uses `source_kind` for context-source artifacts. Reconstruct must not overload it to mean code/spreadsheet/document/database. |
 | `SourceProfile` | reconstruct design-local until runtime attachment | A profile guides observation for one `target_material_kind`; it is not a semantic explorer and not yet an active runtime artifact. |
 | `SourceObservation` | reconstruct design-local until runtime attachment | Runtime-produced structural observation with stable ids; not an ontology fact and not legacy `fact_type`. |
@@ -126,10 +130,15 @@ Current concept decisions:
 | `ReconstructDirective` | schema/union name | LLM-authored directive envelope, not an entity. |
 | `SeedConfirmation` | reconstruct design-local | User/host-mediated confirmation artifact for a Seed candidate; not a semantic concept by itself. |
 | `CompetencyQuestion` | reconstruct design-local | LLM-authored question artifact used to test a confirmed Seed against its declared purpose. |
+| `ClaimRealization` | reconstruct design-local | Claim-level stance about whether a Seed claim is observed behavior, declared intent, contract presence, fixture-only evidence, deferred/non-goal, or unknown. |
+| `CompetencyQuestionAssessment` | reconstruct design-local | LLM-authored assessment of every authoritative competency question against the confirmed Seed and evidence. |
+| `FailureClassification` | reconstruct design-local | LLM-authored explanation of why a competency question or claim cannot be trusted for the declared purpose. |
+| `RevisionProposal` | reconstruct design-local | LLM-authored bounded proposal to reuse, extend, rename, split, reject, or defer ontology content. |
 | `ReconstructMetrics` | reconstruct design-local | Runtime projection from existing artifacts; counts and pass rates, not a quality judgment. |
 | `StopDecision` | reconstruct design-local | LLM-authored directive that interprets metrics for the declared purpose. |
-| `ReconstructRunManifest` | reconstruct design-local | Runtime execution manifest for the reconstruct happy path. |
+| `ReconstructRunManifest` | reconstruct design-local | Runtime execution manifest for the reconstruct mock path. |
 | `FinalOutput` | shared artifact role, reconstruct-local seat | Human-readable result text grounded in reconstruct artifacts; not an ontology draft authority. |
+| `ReconstructStageId` | reconstruct design-local | Stable append-only stage identifier for progress, manifests, status reads, and implementation planning. |
 | `RuntimeGate` | design shorthand only | Runtime implementation should use specific validators, boundary policy, and failure artifacts instead of a generic public concept. |
 | `DomainContextPack` | design shorthand only | Use selected domain-document refs from invocation/binding rather than creating a new domain context entity. |
 
@@ -144,8 +153,14 @@ Current concept decisions:
 | `SourceObservation` | Runtime-produced structural fact about paths, cells, formulas, schemas, headings, symbols, or code patterns | TS runtime |
 | `ReconstructDirective` | LLM-authored structured output submitted to a runtime gate | host LLM |
 | `SeedConfirmation` | User/host-mediated decision over the Seed candidate before downstream questions and metrics | user/host mediated |
+| `ClaimRealization` | Claim-level evidence stance used to separate observed runtime behavior from declared design intent, schema presence, fixture-only evidence, deferred scope, and unknowns | host LLM |
+| `CompetencyQuestion` | Authoritative question set used to test the confirmed Seed for its declared purpose | host LLM |
+| `CompetencyQuestionAssessment` | Answer status and evidence basis for every authoritative competency question | host LLM |
+| `FailureClassification` | Cause classification for unanswered, contradicted, unsupported, or deferred questions and claims | host LLM |
+| `RevisionProposal` | Bounded change proposal derived from failures and claim realization gaps | host LLM |
 | `ReconstructMetrics` | Deterministic projection from validation, confirmation, and question artifacts | TS runtime |
-| `ReconstructRunManifest` | Step and artifact-ref manifest for the bounded happy path | TS runtime |
+| `ReconstructRunManifest` | Step and artifact-ref manifest for the bounded mock path | TS runtime |
+| `PipelineExecutionLedger` | Shared trust/provenance projection over reconstruct stages, validations, outputs, and upstream/downstream boundaries | TS runtime |
 | `RuntimeGate` | Design shorthand for shape, source existence, evidence ref, and metric validation | TS runtime |
 | `DomainContextPack` | Design shorthand for domain documents selected by invocation/binding | `.onto/domains/` plus invocation binding |
 
@@ -167,7 +182,7 @@ Initial bounded tools are exposed through `src/core-api/reconstruct-api.ts`.
 | `onto.list_source_profiles` | active | list source profiles, target material kinds, scan targets, and support status | choose ontology meaning |
 | `onto.observe_source` | active | materialize target profile, inventory, source observations, and initial reconstruct record | infer entities, relations, actions, properties, or rules |
 | `onto.validate_reconstruct_directive` | active | validate LLM-authored source-observation or Seed-candidate directive shape and evidence refs | repair or rewrite the directive |
-| `onto.reconstruct` | active | orchestrate the bounded happy path from target refs and intent to final output, run manifest, and reconstruct record; requires explicit mock semantic/confirmation realization until live providers exist | author ontology meaning |
+| `onto.reconstruct` | active | orchestrate the bounded post-Seed mock loop from target refs and intent to final output, run manifest, and reconstruct record; requires explicit mock semantic/confirmation realization until live providers exist | author ontology meaning |
 | `onto.reconstruct_status` | active | read `reconstruct-record.yaml` stage and artifact refs | infer missing semantic content |
 | `onto.reconstruct_result` | active | read record, run manifest, and final output text | rewrite or improve the result |
 
@@ -208,20 +223,159 @@ from expanding their own boundary.
 4. LLM writes SourceObservationDirective
 5. Runtime validates observation directive
 6. LLM selects domain-document context refs
-7. LLM writes SeedCandidateDirective
-8. Runtime validates Seed evidence and shape
-9. User confirms or rejects Seed candidate
-10. LLM writes competency questions
-11. Runtime computes question/test metrics
-12. LLM classifies failures and proposes revisions
-13. Runtime validates revisions and recomputes metrics
-14. LLM writes StopDecisionDirective
-15. User confirms final ontology direction if needed
+7. Runtime validates domain-context selection and source snapshot refs
+8. LLM writes SeedCandidateDirective
+9. Runtime validates Seed evidence and shape
+10. LLM writes ClaimRealizationDirective
+11. Runtime validates claim realization refs and stance enums
+12. User or host confirms Seed claims at claim level
+13. Runtime validates confirmation transitions and derived claim sets
+14. LLM writes authoritative competency questions
+15. Runtime validates competency question ids, claim links, and evidence refs
+16. LLM assesses every authoritative competency question
+17. Runtime validates question assessment completeness and refs
+18. LLM classifies material failures and unresolved gaps
+19. Runtime validates failure classifications and linkage
+20. LLM proposes bounded revisions or deferrals
+21. Runtime validates revision proposal ids, targets, and actions
+22. Runtime computes deterministic metrics from artifacts
+23. LLM writes StopDecisionDirective
+24. LLM writes final decision-ready output grounded in artifact refs
+25. User confirms final ontology direction if needed
 ```
 
 This flow intentionally uses the review product pattern: LLM-authored meaning,
 runtime-owned gates, explicit artifacts, and user-facing decision points.
 
+### 7.1 Stage Registry And Evolution Rules
+
+`ReconstructStageId` values are stable and append-only. Status, progress
+presentation, run manifest steps, and future continuation logic must use these
+ids rather than prose labels.
+
+| Stage id | Required artifact boundary | Owner |
+|---|---|---|
+| `invocation_binding` | interpretation and binding refs | host LLM plus runtime |
+| `target_material_profile` | `target-material-profile.yaml` | runtime |
+| `source_inventory` | `source-inventory.yaml` | runtime |
+| `source_observation` | `source-observations.yaml` | runtime |
+| `observation_directive` | `source-observation-directive.yaml` | host LLM |
+| `observation_directive_validation` | `source-observation-directive-validation.yaml` | runtime |
+| `domain_context_selection` | `domain-context-selection.yaml` | host LLM |
+| `domain_context_selection_validation` | `domain-context-selection-validation.yaml` | runtime |
+| `seed_candidate` | `seed-candidate.yaml` | host LLM |
+| `seed_candidate_validation` | `seed-candidate-validation.yaml` | runtime |
+| `claim_realization` | `claim-realization-map.yaml` | host LLM |
+| `claim_realization_validation` | `claim-realization-map-validation.yaml` | runtime |
+| `seed_confirmation` | `seed-confirmation.yaml` | user/host mediated |
+| `seed_confirmation_validation` | `seed-confirmation-validation.yaml` | runtime |
+| `competency_questions` | `competency-questions.yaml` | host LLM |
+| `competency_questions_validation` | `competency-questions-validation.yaml` | runtime |
+| `competency_question_assessment` | `competency-question-assessment.yaml` | host LLM |
+| `competency_question_assessment_validation` | `competency-question-assessment-validation.yaml` | runtime |
+| `failure_classification` | `failure-classification.yaml` | host LLM |
+| `failure_classification_validation` | `failure-classification-validation.yaml` | runtime |
+| `revision_proposal` | `revision-proposal.yaml` | host LLM |
+| `revision_proposal_validation` | `revision-proposal-validation.yaml` | runtime |
+| `metrics` | `reconstruct-metrics.yaml` | runtime |
+| `stop_decision` | `stop-decision.yaml` | host LLM |
+| `final_output` | `final-output.md` | host LLM |
+| `record_assembly` | `reconstruct-record.yaml` and `reconstruct-run-manifest.yaml` | runtime |
+
+Rules:
+
+- Existing stage ids must not be renamed after runtime exposure.
+- Optional stages must be recorded as `skipped` with a reason, not omitted from
+  the manifest.
+- Terminal halted stages must keep already-produced artifacts immutable unless a
+  future explicit continuation contract says otherwise.
+- New stages may be appended between semantic phases only when their input and
+  output artifact authority is explicit.
+
+### 7.2 Pipeline Execution Unit Ledger
+
+Reconstruct must map every `ReconstructStageId` into the shared
+`PipelineExecutionLedger` contract. The ledger verifies artifact trust and
+provenance for both runtime-owned and LLM-authored stages.
+
+Rules:
+
+- Runtime validation stages are trust gates for LLM-authored artifacts.
+- An LLM-authored artifact may exist while its `trustStatus` remains
+  `untrusted` until the corresponding validation stage completes.
+- A downstream stage is `blocked_by_upstream` if any required source artifact is
+  missing, failed validation, or belongs to an untrusted producing stage.
+- `reconstruct_status` should expose the ledger, or a bounded projection of it,
+  so callers can see which artifacts are trustworthy and where the pipeline
+  halted.
+- Future reconstruct continuation must derive its frontier from this ledger, not
+  from ad hoc file existence.
+
+The shared contract is
+`.onto/processes/shared/pipeline-execution-ledger-contract.md`.
+
+### 7.3 Identifier Authority
+
+Every cross-artifact reference must point back to one authority artifact. Derived
+views may expose ids, but must not become a second source of truth.
+
+| Id family | Authority artifact |
+|---|---|
+| source observation ids | `source-observations.yaml` |
+| selected observation ids | `source-observation-directive.yaml` |
+| domain context ids and `domain_snapshot_id` | `domain-context-selection.yaml` |
+| Seed claim ids | `seed-candidate.yaml` |
+| claim realization ids | `claim-realization-map.yaml` |
+| confirmation-derived claim sets | `seed-confirmation-validation.yaml` |
+| competency question ids | `competency-questions.yaml` |
+| competency question result ids | `competency-question-assessment.yaml` |
+| failure ids | `failure-classification.yaml` |
+| proposal ids | `revision-proposal.yaml` |
+
+### 7.4 Claim Realization Stances
+
+`claim-realization-map.yaml` must classify every Seed claim with one of these
+stances:
+
+| Stance | Meaning |
+|---|---|
+| `observed_runtime_behavior` | The claim is supported by observed behavior in the target material. |
+| `declared_design_intent` | The claim is stated as design or product intent, but runtime behavior is not directly observed. |
+| `schema_or_contract_presence` | The claim is supported by a schema, type, contract, config, or interface boundary. |
+| `test_or_fixture_only` | The claim is supported only by tests, fixtures, mocks, or examples. |
+| `deferred_or_non_goal` | The claim belongs to deferred scope or a declared non-goal. |
+| `unknown` | The available artifacts do not justify a stronger stance. |
+
+### 7.5 Claim Confirmation State Rules
+
+Seed confirmation is claim-level. A single run may contain accepted, rejected,
+partial, and deferred claims.
+
+| State | Downstream rule |
+|---|---|
+| `accepted` | Included in the current confirmed Seed set and eligible for competency-question assessment. |
+| `rejected` | Excluded from the confirmed Seed set and ineligible except for questions about rejection rationale. |
+| `partial` | Excluded from the accepted claim set unless validated accepted sub-claim ids exist; unresolved count increases. |
+| `deferred` | Excluded from current competency-question eligibility unless the question explicitly targets deferred scope; deferred and unresolved counts increase. |
+
+`seed-confirmation-validation.yaml` owns the derived sets:
+
+- `accepted_claim_ids`
+- `rejected_claim_ids`
+- `partial_claim_ids`
+- `deferred_claim_ids`
+- `cq_eligible_claim_ids`
+
+### 7.6 Competency Question Authority
+
+`competency-questions.yaml` is the authoritative competency-question set for a
+run. It is authored after Seed confirmation so that questions test the confirmed
+Seed and declared purpose, not a discarded draft.
+
+`competency-question-assessment.yaml` must assess every authoritative question
+exactly once. Domain-provided question templates are not in-scope unless
+`domain-context-selection.yaml` explicitly admits them into the run.
+
 ## 8. Prompt-Backed Reference Path
 
 Before runtime replacement, reconstruct needs at least one prompt-backed
@@ -241,18 +395,22 @@ Runtime implementation may replace only one deterministic boundary at a time:
 source profile loading, source observation, directive validation, metric
 calculation, then MCP exposure.
 
-## 9. LLM-Owned Directives
+## 9. Meaning Directives And Runtime Gates
 
 | Directive | Purpose | Runtime gate |
 |---|---|---|
 | `SourceObservationDirective` | choose which runtime observations are evidence candidates | observation id, material kind, source ref, and location validation |
-| `DomainContextSelectionDirective` | choose domain documents and explain why | context existence and scope validation |
+| `DomainContextSelectionDirective` | choose domain documents and explain why | context existence, scope, and `domain_snapshot_id` validation |
 | `SeedCandidateDirective` | propose purpose, non-goals, entities, relations, actions, properties, and rules | schema shape, prior observation-directive status, selected observation, and evidence ref validation |
+| `ClaimRealizationDirective` | classify each Seed claim's evidence stance | claim id, stance enum, source/evidence ref, and rationale presence validation |
 | `EvidenceMapDirective` | connect claims to evidence | dangling ref and duplicate evidence checks |
-| `CompetencyQuestionDirective` | define execution questions and scope boundaries | duplicate and coverage metric checks |
-| `FailureClassificationDirective` | classify why a question cannot be answered | enum and question/result linkage checks |
-| `OntologyRevisionProposal` | propose reuse, extend, rename, split, or reject decisions | id collision, target, schema, and regression checks |
+| `SeedConfirmationDirective` | record claim-level accepted, rejected, partial, or deferred confirmation | state transition, duplicate claim, missing claim, and derived-set validation |
+| `CompetencyQuestionDirective` | define the authoritative execution question set and scope boundaries | duplicate id, closed question set, claim linkage, and evidence-ref validation |
+| `CompetencyQuestionAssessmentDirective` | answer or mark every authoritative question | exactly-once question coverage, answer-state enum, claim linkage, and evidence-ref validation |
+| `FailureClassificationDirective` | classify why a question or claim cannot be trusted for the declared purpose | enum, question/result linkage, claim linkage, and materiality rationale checks |
+| `OntologyRevisionProposal` | propose reuse, extend, rename, split, reject, or defer decisions | proposal id, target id, action enum, schema, and regression checks |
 | `StopDecisionDirective` | decide continue, stop, or ask user based on metrics and purpose | metrics presence and enum validation |
+| `FinalOutputDirective` | present decision-ready user-facing output | artifact provenance, section presence, and unresolved/deferred disclosure checks |
 
 Every semantic claim in a Seed or revision proposal needs evidence refs. A claim
 without evidence remains a hypothesis or open question.
@@ -270,46 +428,59 @@ Current and provisional artifact contract:
 | `target-material-profile.yaml` | runtime | helper implemented | selected target material kind, candidates, confidence, selected source profiles, and unsupported-material status |
 | `source-inventory.yaml` | runtime | helper implemented | selected source roots, material-specific inventory units, and scan boundaries |
 | `source-observations.yaml` | runtime | helper implemented | adapter id, material kind, location, structural data, and stable observation ids |
-| `source-observation-directive.yaml` | LLM | happy path implemented through pluggable author | selected observations and evidence-candidate rationale |
+| `source-observation-directive.yaml` | LLM | implemented through pluggable author | selected observations and evidence-candidate rationale |
 | `source-observation-directive-validation.yaml` | runtime | helper implemented | validation status and violations for LLM-selected observation refs |
 | `domain-context-selection.yaml` | LLM | future | chosen domain context refs and rationale |
-| `seed-candidate.yaml` | LLM | happy path implemented through pluggable author | proposed Ontology Seed before user confirmation |
+| `domain-context-selection-validation.yaml` | runtime | future | context existence, scope, and snapshot validation |
+| `seed-candidate.yaml` | LLM | implemented through pluggable author | proposed Ontology Seed before user confirmation |
 | `seed-candidate-validation.yaml` | runtime | helper implemented | validation status and violations for LLM-authored Seed claim shape and observation evidence refs |
-| `seed-confirmation.yaml` | user/host mediated | happy path implemented through pluggable provider | confirmed, rejected, or partially confirmed Seed decisions |
-| `competency-questions.yaml` | LLM | happy path implemented through pluggable author | execution questions and boundaries |
-| `failure-classification.yaml` | LLM | future | failed question causes and recommended action |
-| `revision-proposal.yaml` | LLM | future | bounded ontology changes |
-| `reconstruct-metrics.yaml` | runtime | happy path implemented | deterministic counts and pass rates |
-| `stop-decision.yaml` | LLM | happy path implemented through pluggable author | continue, stop, or ask-user judgment |
-| `final-output.md` | LLM | happy path implemented through pluggable author | user-facing result text grounded in artifacts |
-| `reconstruct-run-manifest.yaml` | runtime assembly | happy path implemented | step list, owner boundary, performed-by provenance, happy-path scope, artifact refs, and execution profile |
-| `reconstruct-record.yaml` | runtime assembly | helper implemented, primary artifact in happy path | primary structured reconstruct artifact with material, validation, and artifact refs |
+| `claim-realization-map.yaml` | LLM | mock loop implemented through pluggable author | evidence stance for every Seed claim |
+| `claim-realization-map-validation.yaml` | runtime | implemented | claim id, stance enum, and evidence linkage validation |
+| `seed-confirmation.yaml` | user/host mediated | mock loop implemented through pluggable provider | claim-level accepted, rejected, partial, or deferred Seed decisions |
+| `seed-confirmation-validation.yaml` | runtime | implemented | confirmation transition validation and derived claim sets |
+| `competency-questions.yaml` | LLM | implemented through pluggable author | authoritative execution questions and boundaries |
+| `competency-questions-validation.yaml` | runtime | implemented | closed CQ set, duplicate id, claim-link, and evidence validation |
+| `competency-question-assessment.yaml` | LLM | mock loop implemented through pluggable author | answer status and evidence basis for every authoritative question |
+| `competency-question-assessment-validation.yaml` | runtime | implemented | exactly-once coverage, status enum, and evidence validation |
+| `failure-classification.yaml` | LLM | mock loop implemented through pluggable author | failed or unsafe-to-trust question and claim causes |
+| `failure-classification-validation.yaml` | runtime | implemented | failure enum, linkage, and materiality rationale validation |
+| `revision-proposal.yaml` | LLM | mock loop implemented through pluggable author | bounded ontology changes, deferrals, or rejection proposals |
+| `revision-proposal-validation.yaml` | runtime | implemented | proposal id, target id, action enum, and regression guard validation |
+| `reconstruct-metrics.yaml` | runtime | implemented | deterministic counts and pass rates |
+| `stop-decision.yaml` | LLM | implemented through pluggable author | continue, stop, or ask-user judgment |
+| `final-output.md` | LLM | implemented through pluggable author and provenance-checked by runtime | user-facing result text grounded in artifacts |
+| `reconstruct-run-manifest.yaml` | runtime assembly | implemented | step list, owner boundary, performed-by provenance, happy-path scope, artifact refs, and execution profile |
+| `reconstruct-record.yaml` | runtime assembly | helper implemented, primary artifact in mock loop | primary structured reconstruct artifact with material, validation, and artifact refs |
 
 These artifact names are provisional but contract-owned. Runtime implementation
 must either implement this contract or update this contract before code lands.
 Runtime code must not silently fix a different schema.
 
-The current happy path explicitly implements:
+The current mock runtime path explicitly implements:
 
 - target material profile, inventory, and source observations
 - source-observation directive plus validation
 - Seed candidate plus validation
+- claim realization plus validation
 - Seed confirmation through an explicit mock confirmation provider
+- Seed confirmation validation and derived claim sets
 - competency questions through an explicit mock directive author
+- competency-question validation and assessment
+- failure classification plus validation
+- revision proposal plus validation
 - deterministic reconstruct metrics
-- stop decision and final output through an explicit mock directive author
+- stop decision and provenance-checked final output through an explicit mock directive author
 - reconstruct run manifest and primary reconstruct record
 
-The current happy path explicitly defers:
+The current mock runtime path explicitly defers:
 
 - `domain-context-selection.yaml`
-- `failure-classification.yaml`
-- `revision-proposal.yaml`
+- `domain-context-selection-validation.yaml`
 
 These deferred artifacts require additional host/user semantic decisions and
-must not be implied by a completed mock happy-path run.
+must not be implied by a completed mock run.
 
-`reconstruct-record.yaml` is the primary artifact for the happy path in the same
+`reconstruct-record.yaml` is the primary artifact for the mock path in the same
 way `review-record.yaml` is primary for review.
 
 ## 11. Completion Rule
@@ -318,8 +489,12 @@ Runtime computes, but does not decide:
 
 - evidence ref count
 - Seed concept count
+- claim realization stance counts
+- confirmation state counts and derived claim-set counts
 - competency question count
+- competency question assessment status counts
 - failed question count
+- failure classification counts
 - proposed revision count
 - unresolved count
 - pass rate
@@ -333,9 +508,19 @@ writes a `StopDecisionDirective` with `continue`, `stop`, or `ask_user`.
 The user-facing result should separate:
 
 - confirmed Seed content
+- claim realization summary
+- competency question assessment summary
+- failure classifications
+- revision proposals or deferrals
 - unresolved material questions
 - unsupported or out-of-scope requests
 - proposed next actions
+- artifact provenance for the claims, questions, failures, proposals, and stop
+  rationale it mentions
+
+`final-output.md` is decision-ready prose, not a new truth source. Any claim it
+presents as confirmed, unresolved, failed, deferred, or proposed must point back
+to the artifact id family that owns that state.
 
 ## 12. Runtime Implementation Readiness
 
@@ -347,9 +532,12 @@ Runtime attachment is ready only when all of these are true:
    `.onto/processes/reconstruct/source-profiles/`.
 4. `target_material_kind` is recorded before source adapter selection.
 5. Source adapter output has stable observation ids and boundary failure rules.
-6. Directive validation has schemas for every LLM-owned directive it accepts.
+6. Directive validation has schemas for every meaning directive it accepts.
 7. Metrics are defined as deterministic projections from existing artifacts.
 8. MCP schemas expose only bounded facts and artifact refs.
+9. Stage ids are stable and recorded in status, run manifest, and records.
+10. Cross-artifact id authority is explicit and validators reject dangling refs.
+11. Final output provenance is validated against artifact ids rather than prose.
 
 ## 13. Verification Target
 
@@ -358,9 +546,21 @@ When the implementation starts, use at least:
 ```bash
 npm run check:ts-core
 npx vitest run src/core-runtime/reconstruct
+npx vitest run src/core-api/reconstruct-api.test.ts
 npm run test:mcp:review
 git diff --check
 ```
 
 `test:mcp:review` remains review-focused, but it protects the shared MCP server
 from regressions when reconstruct tools are introduced.
+
+The first end-to-end fixture may use the `day1co/day1co-ai-usage-dashboard`
+repository or an equivalent temporary fixture. An equivalent fixture must cover:
+
+- multiple selected source observations
+- at least five Seed claims
+- at least one accepted claim and one rejected, partial, or deferred claim
+- at least one competency question that is not fully answered
+- at least one failure classification
+- at least one revision proposal
+- final output references back to the owning artifact ids

package/.onto/processes/reconstruct/reconstruct-execution-ux-contract.md

@@ -0,0 +1,144 @@
+# Reconstruct Execution UX Contract
+
+> Status: design contract.
+> Purpose: define the user-visible reconstruct run experience without adding a
+> separate UI implementation.
+
+## 1. Position
+
+`reconstruct` can take a long time because the host LLM must read source
+observations, choose evidence, propose Seed meaning, assess competency questions,
+and explain unresolved gaps. The user-facing experience must therefore expose
+new information as it is discovered, not only meta status such as "still
+running".
+
+The runtime owns structured facts, stage ids, artifact refs, liveness hints, and
+deterministic counts. The host LLM owns the short explanation shown to the user.
+
+No standalone HTML, web UI, or dashboard is required for this contract. MCP and
+CLI hosts should render the same information from runtime status/result payloads
+and reconstruct artifacts.
+
+## 2. Opening Brief
+
+At run start, the host should show a compact opening brief before expensive
+work begins.
+
+The brief must include:
+
+- environment: project root or declared source boundary, session root, and
+  write policy
+- method: MCP/runtime path, source profile, semantic author realization, and
+  confirmation provider realization
+- model/provider: provider family or realization label without secrets
+- domain: selected domain, no-domain mode, or pending domain-context selection
+- material: `target_material_kind`, target input kind, and unsupported-material
+  status if known
+- reconstruction direction: what the reconstruct run will try to explain, and
+  what it will treat as out of scope
+- ownership boundary: runtime observes and validates; the host LLM proposes
+  meaning; the user or host confirmation controls Seed acceptance
+
+The opening brief should be declarative. It should not ask the user to approve
+internal implementation details unless the target boundary, domain, or write
+policy is ambiguous.
+
+## 3. Progress Presentation
+
+Progress is stepwise. Each update should include the current
+`ReconstructStageId`, a short label, a liveness state, and one or two newly
+learned facts.
+
+Recommended update shape:
+
+```text
+[stage 6/26] source_observation
+Status: running
+Learned: 38 source observations across routes, components, and API helpers.
+Next: select evidence-bearing observations for the Seed candidate.
+```
+
+Progress updates should prefer facts such as:
+
+- material kind and profile confidence
+- scanned roots and skipped boundaries
+- source inventory counts by material-specific unit
+- selected observation count and evidence-candidate rationale
+- domain context refs and snapshot id
+- Seed claim count by entity, relation, action, property, and rule
+- claim realization stance counts
+- confirmation state counts
+- competency question count and assessment status counts
+- failure classification counts
+- revision proposal action counts
+- unresolved, deferred, and out-of-scope counts
+- current halt reason and reusable artifact refs when halted
+
+Progress updates should avoid pretending that intermediate semantic claims are
+final. Before Seed confirmation, claims are candidates. Before competency
+question assessment, quality statements are preliminary.
+
+## 4. Decision Points
+
+User-facing prompts are needed only when a decision changes the product result
+or the allowed boundary.
+
+Decision points:
+
+- target boundary is ambiguous or would require reading outside the bound root
+- material kind is unsupported or mixed in a way that changes adapter behavior
+- domain context selection changes the interpretation standard
+- Seed claim confirmation requires accepted, rejected, partial, or deferred
+  state
+- unresolved material questions require a final direction: continue, defer, or
+  accept with disclosed limits
+
+The host should phrase choices by outcome, not internal jargon.
+
+## 5. Final Output
+
+`final-output.md` must be decision-ready and artifact-tethered. It should
+separate:
+
+- confirmed Seed content
+- claim realization summary
+- competency question assessment summary
+- material failures and unsafe-to-trust gaps
+- revision proposals and action candidates
+- unresolved, deferred, unsupported, or out-of-scope items
+- artifact provenance: the owning ids and artifact refs behind the statements
+
+The final output is not the authority for truth. It is a user-facing projection
+of `reconstruct-record.yaml`, `reconstruct-run-manifest.yaml`, and the
+stage-owned artifacts.
+
+## 6. Halted Or Partial Runs
+
+If a run halts, the output should still be useful:
+
+- show the last completed stage id
+- show which artifact refs are reusable
+- show which stage failed and why
+- show the strongest safe statement supported by completed artifacts
+- avoid summarizing missing stages as if they ran
+
+A halted run may provide candidate Seed content only if the corresponding
+artifact and validation refs exist. It may not imply Seed confirmation, CQ
+assessment, failure classification, revision proposal, stop decision, or final
+ontology direction unless those artifacts exist.
+
+## 7. Runtime Payload Expectations
+
+Future status/result payloads should expose enough facts for the host LLM to
+render this contract without scraping prose:
+
+- current stage id and total planned stage count
+- stage state: pending, running, completed, skipped, or halted
+- stage artifact refs and owner
+- liveness state and recommended polling interval
+- deterministic count summaries from the latest completed artifacts
+- unresolved/deferred/out-of-scope summaries
+- opening, progress, halt, and final presentation prompts or facts
+
+The payload may be compact. It should expose bounded facts and artifact refs,
+not duplicate semantic authority.