Sigil: Ontology Vault

• --ontology-type <id>: explicitly select one reusable ontology archetype from the ontology type catalog.
• Without the argument, infer one type only when the user's intent clearly matches one catalog entry.
• When two or more types remain plausible, ask the user to select from the two or three strongest mutually exclusive choices. Each choice must state what will be modeled and the consequence of choosing it.
• A project-local type may be supplied as a runtime-profile alias. The profile must map it to one catalog type. Keep the local alias in the report; do not add it to reusable Arcanum vocabulary by proximity.

The initial catalog contains:

• knowledge-vault: roles, confidence, premises, sessions, evidence, and convention lifecycle;
• business-domain: domain meaning, actors, rules, policies, workflows, outcomes, and value;
• system-runtime: components, interfaces, events, data, tests, telemetry, deployment, and runtime constraints;
• business-system-bridge: realization, traceability, coverage, observation, constraints, evidence gaps, and drift across the two branches;
• authority-governance: authority kinds, source posture, owners, gates, reliance, non-collapse, and residue;
• architecture-property: architecture element types, typed properties, allowed relations, constraint operators, architecture profiles, observation projections, and explainable property findings.

Architecture-enforcement intent that asks an ontology to understand or test an architecture's properties selects architecture-property. Do not silently substitute intent-to-implementation traceability; that is business-system-bridge.

• map --branch business: map domain language, intent, rules, outcomes, premises, policies, and value claims.
• map --branch system: map components, services, APIs, events, jobs, data structures, tests, metrics, and runtime constraints.
• map --branches business,system: map both branches and classify mixed or ambiguous documents.
• validate --bridge business-system: validate cross-branch links, drift, tests, observability, constraints, and evidence gaps.
• promote-confidence --branch business: promote or demote business knowledge only when evidence and commitment gates pass.
• promote-confidence --branch system: promote or demote system knowledge only when implementation/runtime evidence supports it.
• convention-update --branch business|system|bridge: propose convention changes scoped to one branch or to bridge rules.

Ontology type and branch arguments are compatible but not interchangeable:

1. Ontology type selects the model shape and validation questions.
2. --branch, --branches, and --bridge select traversal or reporting scope within that model.
3. When no branch argument is explicit, use the catalog entry's derived branch defaults. business-domain derives --branch business; system-runtime and architecture-property derive --branch system; and business-system-bridge derives --branches business,system --bridge business-system.
4. An explicit compatible branch argument overrides only the derived traversal scope. It never changes the selected ontology type.
5. If the explicit branch excludes the selected type's required evidence—for example, a bridge type with only one branch—report the conflict and ask for one correction rather than silently rerouting.
6. Existing invocations without --ontology-type remain valid. Infer a type from clear intent and arguments; otherwise use the ambiguity policy before scanning broadly.

• --profile <path>: load a project-local runtime profile that names local ontology refs, owner refs, source-spine refs, implementation/runtime refs, allowed runtime modes, allowed outputs, blocked outputs, owner gates, residue route, and observability route.
• A profile may declare ontology_type with one catalog ID and may declare ontology_type_alias for its project-local name. The alias does not extend the reusable catalog.
• --runtime inline: default. Run the selected Ontology Vault mode directly over the profile sources inside the current agent session.
• --runtime agents: use a governed subagent strategy as an execution backend only when the profile permits it and the repository has a local strategy owner. The subagent strategy must handle trigger checks, tension design, explicit human confirmation, registration, closeout, and ledger evidence.

Profile outputs are evidence artifacts, validation reports, confidence action reports, drift reports, and optional read-model projections. They are not promotion verdicts, source authority, spec mutations, runtime conformance verdicts, or canonical source edits unless a separate owner route explicitly permits that movement.

• explicit ontology type or user intent from which it can be selected,
• repository root,
• vault, ontology, notes, wiki, or docs folders,
• session records,
• discovery or research folders,
• premise, axiom, constitution, or convention documents,
• existing inventory entries,
• project-local runtime profile, when using --profile,
• local ontology, owner, source-spine, implementation, test, telemetry, or projection references named by that profile,
• prior findings and audits,
• schema or frontmatter conventions,
• user-stated ontology goal.

This default applies only after <materialization-contract> classifies the work as single-artifact-allowed. A run artifact or validation receipt is not the product ontology's state store.

This governs artifacts the sigil writes. It places no requirement on records an owner writes, and no consuming repository is obliged to adopt this shape.

If the user does not provide --output, write the primary artifact to the first suitable location:

1. .arcanum/ontology-vault/<mode>-<date>.json when .arcanum/ exists,
2. docs/ontology/<mode>-<date>.json when docs/ontology/ exists,
3. docs/knowledge/<mode>-<date>.json when docs/knowledge/ exists,
4. a JSON object returned in chat when no safe write location exists.

Render markdown beside the primary artifact only when a human view is wanted, and mark it as derived. A markdown view that has drifted from its JSON source is stale, not authoritative.

This declaration promotes no candidate schema to canonical and imports no label under deferred governance. Authority for it is development/schema-validation-plan/decision-gates/OVS-GATE-004-default-output-declaration.md.

An invocation or validation receipt may remain one machine-readable JSON artifact. A durable ontology is different: it owns reusable state across runs and must be materialized as a package.

Return package-required when any of these deterministic triggers is true:

1. The user requests a durable, reusable, evolving, project-owned, or packaged ontology.
2. More than one branch or view is modeled, or a bridge is requested.
3. Stable ontology identity is intended to survive the invocation.
4. Existing ontology nodes, relations, operations, sources, views, or residue are being enriched or revised.
5. The output needs independently validated schemas, source bindings, human navigation, or reusable projections.
6. A runtime profile points at an owned ontology surface and the run would mutate that surface rather than only validate it.

Record count and byte size are never materialization triggers.

Return single-artifact-allowed only when all of these are true:

• one bounded ontology type and one branch;
• one-off mapping or reporting intent;
• no existing durable ontology is being enriched;
• no reuse or future evolution is claimed;
• no bridge or multi-view behavior is requested; and
• the output is invocation evidence, not the product ontology's state store.

When package intent is clear, require both a package owner route and an exact package root. For public/private movement, also require an explicit visibility classification. If any required ownership input is unresolved, return block, write no ontology state into an earlier run artifact, and emit only a blocked invocation receipt with the detected trigger, proposed package inventory, authority_effect: none, and typed blockers such as package_owner_unresolved, package_output_unresolved, or package_visibility_unresolved.

A governed durable package has these minimum surfaces:

• required: profile, source identities and digests, nodes, typed relations (an explicitly empty collection is allowed), residue ledger, human README or index, owned schemas or schema bindings, deterministic validator, and append-only validation receipts;
• conditional: branch views and bridge view for branch-aware work; migration manifest for prior-run imports; schema-amendment witness for evolving record shape; operation composition when it is load-bearing ontology state;
• optional: projections, visualizations, generated read models, context packs, and domain-specific indexes.

Package validation must check source currency, closed record shapes, stable-ID uniqueness, relation endpoint closure, branch polarity, separate bridge-source evidence, view and residue references, authority ceilings, and stale receipts. Check-only validation must not write. Receipt materialization is a separate, explicit operation, and prior receipts remain history rather than being overwritten.

This contract governs Ontology Vault output behavior. It does not require an unrelated existing ontology to migrate, adopt one universal graph schema, or promote package contents into authority.

1. Load catalogs/ontology-types.json and record all viable catalog matches before broad source discovery.
2. Resolve selection in this precedence order:
   • explicit --ontology-type catalog ID,
   • runtime profile ontology_type and optional project-local alias,
   • one high-confidence intent match,
   • user selection from the two or three strongest candidates.
3. Clear intent must not prompt. Record selection_source as explicit, profile, or inferred, the confidence, and why competing types were excluded.
4. Ambiguous intent must not silently pick a generic map. Present two or three concise, mutually exclusive choices using the catalog labels and selection consequences. After selection, record selection_source: user and preserve the rejected candidates as routing evidence.
5. When a profile names a project-local alias, require its reusable ontology_type base. Record the alias but do not register it in the catalog.
6. Resolve derived branch defaults from the selected type, then apply only compatible explicit branch arguments.

Step 0A - Decide Run Artifact Or Durable Package

A1. Build the materialization facts before choosing an output path: durability intent, branch and view count, bridge use, stable cross-run identity, existing state enrichment, required reusable surfaces, runtime-profile mutation, owner route, package root, and visibility. A2. Apply <materialization-contract> before <default-output>. A3. For single-artifact-allowed, keep ontology content and the invocation receipt distinguishable even when one JSON artifact carries both for the bounded run. A4. For package-required, write ontology state only inside the resolved package root and emit validation history under that package's receipt surface. A5. For block, preserve source evidence and existing run artifacts byte for byte. Never keep appending product ontology state to one invocation receipt.

Step 1 - Resolve Scope And Local Vocabulary

7. Resolve the target repository, source folders, mode, and output path.
8. Detect local knowledge-governance structures before asking questions.
9. When --profile is provided, load the project-local runtime profile before broad source discovery and treat its source refs as the execution boundary.
10. Identify local labels for roles, statuses, confidence dimensions, tags, edge types, and sessions.
11. Translate local labels into generic Arcanum concepts:

• knowledge role,
• maturity status,
• evidence confidence,
• commitment confidence,
• session record,
• delegated research,
• synthesis findings,
• convention change,
• business ontology,
• system ontology,
• bridge ontology,
• architecture property ontology.

12. Preserve local label names as aliases only when reporting on the repository. Do not promote local labels into canonical Arcanum vocabulary.

Step 2 - Map Current Ontology

6. Inventory source folders and representative documents.
7. Record observed roles, axes, statuses, tags, edge types, promotion rules, and source authority rules.
8. Identify gaps, contradictions, stale conventions, and undocumented practices.
9. Estimate the domain-knowledge inflection position:
   • low knowledge: prioritize discovery and session distillation,
   • near inflection: prioritize decision gates and focused ontology experiments,
   • high knowledge: justify promotion gates, convention changes, and heavier ontology investment.

Step 2A - Map Architecture Properties When Selected

When ontology_type: architecture-property is selected:

10. Map architecture element types and their inheritance or composition rules.
11. Map typed property definitions, including value domains, valid subjects, observation stages, owner routes, and forbidden inferences.
12. Map allowed relation definitions, endpoint types, relation properties, direction, cycle policy, and evidence requirements.
13. Map architecture profiles as explicit constraints over properties and relations. Keep portable constraints separate from language- or project-specific realizations.
14. Map observation projections from source, AST, compiler, module, runtime, test, or telemetry evidence into typed facts. Projections are evidence, not architecture authority.
15. Validate generic constraint operators and require findings to retain the subject, property or relation, expected value, observed value, originating profile, evidence ref, and owner route.
16. Preserve unknown or indeterminate observations as typed unsupported evidence. Never infer a passing value from absence or naming similarity.
17. Use bridge edges only when the requested question also concerns alignment between domain intent and implementation. Architecture-property selection alone does not imply a business-system bridge.

Step 2B - Map Branch-Aware Ontology When Needed

When branch-aware mapping is requested or clearly useful:

10. Classify documents and claims as business, system, bridge, mixed, or unknown.
11. Map business ontology claims around intent, meaning, actors, rules, policies, workflows, outcomes, premises, decisions, and value measures.
12. Map system ontology claims around components, services, APIs, events, jobs, data structures, tests, metrics, deployment units, runtime behavior, and technical constraints.
13. Preserve mixed documents when they are useful, but assign branch ownership at the claim or section level.
14. Create bridge edges only when there is evidence on both sides of the branch boundary.
15. Use these starter bridge edge types:

• realized_by: business concept or behavior is implemented by a system artifact,
• depends_on: business behavior depends on a system capability,
• constrained_by: business rule or outcome is limited by a technical constraint,
• observed_by: business outcome or behavior is measured by a metric, log, event, or trace,
• tested_by: business claim, rule, or outcome is verified by a test,
• drifts_from: observed system behavior diverges from business intent,
• traced_to: system artifact links back to a business premise, decision, discovery, or rule.

Step 2C - Validate Branch Bridges

16. Every promoted business behavior with implementation impact should have at least one bridge edge or an explicit evidence gap.
17. Every promoted system artifact claim should identify whether it realizes, observes, tests, constrains, or merely supports a business claim.
18. Drift edges must preserve both the business expectation and the observed system behavior.
19. Bridge claims that assert alignment must cite evidence from both branches.
20. System claims must not silently redefine business meaning; business claims must not pretend implementation exists without bridge evidence.

Step 2D - Execute A Project-Local Runtime Profile When Provided

When --profile is provided:

21. Validate that the profile names at least local ontology refs, local owner refs, source or evidence refs, allowed runtime modes, allowed outputs, blocked outputs, owner gates, and residue route.
22. Treat profile refs as local aliases to generic concepts; do not add profile labels, statuses, or roles to canonical Arcanum vocabulary by default.
23. For --runtime inline, run the selected mode over the profile refs and record profile coverage, profile gaps, and blocked output attempts.
24. For --runtime agents, verify the profile permits an agent backend and route through the repository-local governed subagent strategy. Do not spawn agents directly from Ontology Vault when the local strategy requires its own trigger check, tension gate, human confirmation, registry append, and closeout.
25. Treat agent returns, dispatch findings, close rows, and ledger evidence as delegated evidence records. They may support synthesis or confidence review, but they do not decide authority.
26. Emit only allowed profile outputs. Block or escalate any attempt to emit a promotion verdict, source mutation, spec mutation, runtime conformance verdict, or generated projection that outranks its owner evidence.

Step 3 - Distill Sessions And Delegated Evidence

27. Treat sessions as evidence records, not authority.
28. Extract durable claims, decisions, contradictions, open questions, and promoted candidates.
29. Preserve context and goal for each distillation.
30. When delegated research exists, keep raw delegated research separate from synthesis findings.
31. Require synthesis findings to cite delegated research before making load-bearing claims.
32. Surface contradictions between raw evidence outputs instead of resolving them silently.

Step 4 - Review Premises And Confidence

33. For each premise or working bet, identify evidence, counterevidence, current use, falsification criteria, and confidence state.
34. Separate evidence confidence from commitment confidence.
35. Recommend one action: promote, keep, revise, demote, split, merge, retire, or escalate to decision gate.
36. Block promotion when evidence links are missing, contradictions remain unresolved, or the claim would outrank its sources.
37. For branch-aware promotion, keep business confidence and system confidence separate until bridge evidence supports alignment.
38. For project-local profiles, promotion recommendations must name the local owner route and remain non-executing unless that owner route returns an approval or PromotionRecord-compatible decision.

Step 5 - Propose Convention Changes

39. For schema or ontology changes, record current rule, proposed rule, rationale, migration impact, affected files, and rollback path.
40. Ask one blocker-level governance decision at a time.
41. Do not mutate conventions unless the user explicitly approves the change.
42. For branch-aware convention changes, state whether the rule affects business, system, bridge, or cross-branch validation.
43. For project-local profile changes, separate reusable profile convention changes from one repository's private profile data.

Step 6 - Validate And Report

44. Validate ontology type selection, type-specific model shape, links, role consistency, confidence gates, delegated-evidence traceability, source authority rules, branch ownership, bridge edges, drift findings, test links, and observability links.
45. When a project-local profile is used, validate profile completeness, runtime mode permission, blocked output attempts, owner-gate coverage, and whether agent backend evidence has closeout receipts.
46. Return a concise report with outputs, blockers, promotion decisions, convention changes, runtime profile state, and next action.

Business roles can include: actor, capability, business rule, policy, premise, outcome, workflow, domain event, decision, constraint, value measure.

System roles can include: component, service, module, endpoint, event, schema, table, queue, job, configuration, metric, test, deployment unit.

Bridge roles can include: traceability link, realization map, drift finding, test coverage link, observability link, constraint mapping, evidence gap.