onto-mcp 0.3.0

package/.onto/processes/reconstruct/source-profiles/spreadsheet.md

@@ -0,0 +1,79 @@
+# Source Profile: Spreadsheet
+
+> Target material kind: `spreadsheet`
+
+## Support Status
+
+Design profile only. Planned first runtime support should cover `.xlsx` and
+`.csv`. Other spreadsheet formats such as `.xls` and `.ods` must fail explicitly
+until adapter support is implemented.
+
+## Target Material Identification Hints
+
+- File extension is `.xlsx`, `.csv`, `.xls`, or `.ods`.
+- MIME type indicates a spreadsheet workbook.
+- User identifies the target as a spreadsheet, workbook, sheet, model, report, or
+  accounting file.
+
+## Module Inventory Unit
+
+Workbook, sheet, named range, table, or used range.
+
+## Structural Recognition Scope
+
+- cell values
+- formulas and formula references
+- formatting such as background color, font, borders, and merged cells
+- cross-sheet references
+- data validation rules
+- named ranges
+- hidden rows and columns
+- macros or VBA presence
+
+## Correct Observation Examples
+
+> Cells `A1:F1` are merged with background color `#4472C4`, bold font, and
+> formatting different from the rows below.
+
+> Cell `B2` contains `=VLOOKUP(A2, Sheet2!A:C, 3, FALSE)` and references columns
+> `A:C` of `Sheet2`.
+
+## Prohibited Interpretation Examples
+
+> `A1:F1` is a table header.
+
+> This sheet is a sales report.
+
+> The formula is a cost-recognition policy.
+
+## Detail Location Format
+
+```text
+{description} -- {sheet}:{cell range}
+```
+
+Example:
+
+```text
+formula =SUM(B2:B10) -- Sheet1:B11
+```
+
+## Context Questions
+
+- What is the primary purpose of this file: report, data collection, calculation
+  model, dashboard, accounting schedule, or another use?
+- Do colors or formatting have special meaning?
+- Who primarily uses this file?
+- Is there an existing domain glossary or accounting policy reference?
+
+## Scan Targets
+
+- sheet list and used range per sheet
+- named ranges
+- table definitions
+- formula cells and cross-sheet references
+- merged ranges and distinct formatting regions
+- hidden rows and columns
+- data validation rules
+- macro/VBA presence
+- external data connections

package/.onto/processes/review/binding-contract.md

@@ -0,0 +1,270 @@
+# Review Binding Contract
+
+> 상태: Active
+> 목적: MCP review 호출이 `검토 해석 (InvocationInterpretation)` 다음에 수행해야 하는 `검토 고정 (InvocationBinding)` 책임을 고정한다.
+> 기준 문서:
+> - `.onto/processes/review/interpretation-contract.md`
+> - `.onto/authority/core-lexicon.yaml`
+
+---
+
+## 1. Position
+
+`검토 고정 (InvocationBinding)`은
+`검토 해석 (InvocationInterpretation)`의 결과를 받아
+실제 실행 가능한 review request로 고정하는 runtime/host 소유 단계다.
+
+즉 이 단계의 핵심은:
+
+- 해석 결과를 믿고
+- 실제 path, domain, session, artifact path를 확정하고
+- 이후 lens/synthesize execution이 사용할 deterministic shell을 만드는 것
+
+이다.
+
+---
+
+## 2. Why This Is Runtime-Owned
+
+아래 일들은 semantic judgment보다
+closed-world validation에 가깝다.
+
+1. target path가 실제로 존재하는지 확인
+2. domain token이 유효한지 확인
+3. session ID를 만들고 session directory를 생성
+4. review artifact 경로를 정함
+5. execution mode를 실제로 고정
+6. 팀 생성 또는 background task 호출에 필요한 explicit 값을 준비
+
+이것들은 의미 판단이 아니라 검증, 생성, 고정이므로 runtime/host 소유다.
+
+---
+
+## 3. Inputs
+
+`검토 고정 (InvocationBinding)`의 입력은 아래다.
+
+1. `검토 해석 (InvocationInterpretation)` 출력
+2. 현재 project root
+3. 실제 filesystem 상태
+4. `.onto/settings.json`
+5. host execution capability
+   - Claude plugin
+   - Codex CLI availability
+   - domain document location
+6. explicit user selection
+   - domain confirmation
+   - core-axis/full override
+
+---
+
+## 4. Outputs
+
+`검토 고정 (InvocationBinding)`의 출력은 아래를 포함해야 한다.
+
+1. `resolved_target_scope`
+2. `domain_final_selection`
+3. `resolved_session_domain`
+4. `resolved_execution_realization`
+5. `resolved_host_runtime`
+6. `resolved_review_mode`
+   - `core-axis` 또는 `full`
+7. `resolved_lens_set`
+8. `session_id`
+9. `session_root`
+10. `round1_root`
+11. `execution_preparation_root`
+12. `execution_plan_path`
+13. `session_metadata_path`
+14. `interpretation_artifact_path`
+15. `binding_output_path`
+16. `target_snapshot_path`
+17. `target_snapshot_manifest_path`
+18. `materialized_input_path`
+19. `context_candidate_assembly_path`
+20. `synthesis_output_path`
+21. `review_record_path`
+22. `final_output_path`
+23. `boundary_policy`
+24. `boundary_presentation`
+25. `boundary_enforcement_profile`
+26. `effective_boundary_state`
+27. `binding_notes`
+
+### 4.1 `resolved_target_scope` shape
+
+`resolved_target_scope`는 최소 아래 kind를 허용해야 한다.
+
+1. `file`
+   - `resolved_refs`에 1개 파일 경로
+2. `directory`
+   - `resolved_refs`에 포함 파일 또는 대상 디렉터리 기준 ref set
+3. `bundle`
+   - `resolved_refs`에 bundle member 전체
+   - `bundle_kind`로 묶음 종류를 추가 표기 가능
+
+예시:
+
+```yaml
+resolved_target_scope:
+  kind: bundle
+  bundle_kind: seed_domain_bundle
+  resolved_refs:
+    - /Users/kangmin/.onto/drafts/ontology/domain_scope.md
+    - /Users/kangmin/.onto/drafts/ontology/concepts.md
+    - /Users/kangmin/.onto/drafts/ontology/competency_qs.md
+```
+
+---
+
+## 5. Example
+
+### 5.1 Input
+
+`검토 해석 (InvocationInterpretation)` 출력:
+
+```yaml
+entrypoint: review
+target_scope_candidate:
+  kind: file
+  primary_ref: .onto/principles/ontology-as-code-guideline.md
+intent_summary: production semantic quality bar planning의 완결성과 실용성을 검토한다.
+domain_recommendation: "@ontology"
+domain_selection_required: true
+review_mode_recommendation: full
+lens_selection_plan:
+  always_include:
+    - axiology
+  recommended_lenses:
+    - logic
+    - pragmatics
+    - evolution
+ambiguity_notes: []
+```
+
+### 5.2 Binding Output
+
+```yaml
+resolved_target_scope:
+  kind: file
+  resolved_refs:
+    - /Users/kangmin/cowork/onto/.onto/principles/ontology-as-code-guideline.md
+domain_final_selection:
+  recommendation: "@ontology"
+  final_value: ontology
+  selection_mode: user_confirmed_recommendation
+resolved_session_domain: ontology
+resolved_execution_realization: worker
+resolved_host_runtime: codex
+resolved_review_mode: full
+resolved_lens_set:
+  - logic
+  - structure
+  - dependency
+  - semantics
+  - pragmatics
+  - evolution
+  - coverage
+  - conciseness
+  - axiology
+session_id: 20260404-a1b2c3d4
+session_root: /Users/kangmin/cowork/onto/.onto/review/20260404-a1b2c3d4
+round1_root: /Users/kangmin/cowork/onto/.onto/review/20260404-a1b2c3d4/round1
+execution_preparation_root: /Users/kangmin/cowork/onto/.onto/review/20260404-a1b2c3d4/execution-preparation
+execution_plan_path: /Users/kangmin/cowork/onto/.onto/review/20260404-a1b2c3d4/execution-plan.yaml
+session_metadata_path: /Users/kangmin/cowork/onto/.onto/review/20260404-a1b2c3d4/session-metadata.yaml
+interpretation_artifact_path: /Users/kangmin/cowork/onto/.onto/review/20260404-a1b2c3d4/interpretation.yaml
+binding_output_path: /Users/kangmin/cowork/onto/.onto/review/20260404-a1b2c3d4/binding.yaml
+target_snapshot_path: /Users/kangmin/cowork/onto/.onto/review/20260404-a1b2c3d4/execution-preparation/target-snapshot.md
+target_snapshot_manifest_path: /Users/kangmin/cowork/onto/.onto/review/20260404-a1b2c3d4/execution-preparation/target-snapshot-manifest.yaml
+materialized_input_path: /Users/kangmin/cowork/onto/.onto/review/20260404-a1b2c3d4/execution-preparation/materialized-input.md
+context_candidate_assembly_path: /Users/kangmin/cowork/onto/.onto/review/20260404-a1b2c3d4/execution-preparation/context-candidate-assembly.yaml
+synthesis_output_path: /Users/kangmin/cowork/onto/.onto/review/20260404-a1b2c3d4/synthesis.md
+error_log_path: /Users/kangmin/cowork/onto/.onto/review/20260404-a1b2c3d4/error-log.md
+review_record_path: /Users/kangmin/cowork/onto/.onto/review/20260404-a1b2c3d4/review-record.yaml
+final_output_path: /Users/kangmin/cowork/onto/.onto/review/20260404-a1b2c3d4/final-output.md
+boundary_policy:
+  web_research_policy: denied
+  repo_exploration_policy: allowed
+  recursive_reference_expansion_policy: denied
+boundary_presentation:
+  primary_target_presentation: embedded_and_ref
+  required_context_presentation: ref_only
+boundary_enforcement_profile:
+  prompt_boundary_enforcement: prompt_declared_only
+  network_boundary_enforcement: prompt_declared_only
+effective_boundary_state:
+  web_research:
+    requested_policy: denied
+    effective_policy: denied
+    guarantee_level: prompt_declared_only
+binding_notes:
+  - "explicit domain token was not provided; ontology was recommended by interpretation and explicitly confirmed by the user"
+  - "full review was preserved from interpretation recommendation"
+```
+
+---
+
+## 6. What It Must Not Do
+
+`검토 고정 (InvocationBinding)` 단계는 아래를 하면 안 된다.
+
+1. 경량/전원 리뷰 필요성을 새로 semantic 판단한다
+2. lens finding을 작성한다
+3. synthesis judgment를 작성한다
+4. contradiction 여부를 판단한다
+5. domain recommendation을 새로 해석한다
+
+즉 이 단계는 `interpretation 결과를 실행 가능한 형태로 고정`하는 데까지만 책임진다.
+
+`resolved_lens_set`도 이 단계가 새로 semantic하게 고르는 것이 아니라,
+이미 해석 단계에서 나온 `lens_selection_plan`과 explicit user choice를
+실행 가능한 값으로 materialize한 결과여야 한다.
+
+`domain_final_selection`도 마찬가지로,
+이 단계가 recommendation을 새로 만드는 것이 아니라
+recommendation, explicit token, 주체자 확인 결과를
+최종 값으로 materialize한 결과여야 한다.
+
+---
+
+## 7. Prompt / MCP / Runtime Effect
+
+현재 MCP-native runtime에서 이 단계가 뜻하는 바는 아래다.
+
+1. `onto.review` 또는 `onto.prepare_review` 호출은 interpretation 결과를 받은 뒤
+   - target scope를 검증하고
+   - domain/context를 고정하고
+   - review mode와 lens set을 materialize하고
+   - session directory를 만든다
+2. runtime은 이 binding 결과를 바탕으로 configured provider executor를 사용할 수 있다.
+
+즉 MCP host/provider가 바뀌어도 binding output은 같아야 한다.
+
+prompt-backed reference path에서 team lead는
+최소 아래 artifact를 이 output에 맞춰 실제로 작성해야 한다.
+
+1. `session-metadata.yaml`
+2. `interpretation.yaml`
+3. `binding.yaml`
+4. `execution-plan.yaml`
+5. `execution-preparation/*`
+
+즉 `binding`은 단순 내부 결정이 아니라,
+artifact seat를 포함한 deterministic shell materialization이다.
+
+또한 현재 `binding`은 최소한 아래 boundary seat를 같이 가져야 한다.
+
+1. `BoundaryPolicy`
+2. `BoundaryPresentation`
+3. `BoundaryEnforcementProfile`
+4. `EffectiveBoundaryState`
+
+---
+
+## 8. Immediate Follow-up
+
+이 문서 다음 단계는 아래다.
+
+1. `src/core-api/review-api.ts`와 `src/mcp/server.ts`가 interpretation -> binding 순서를 보존한다
+2. 이후 `lens prompt contract`와 `synthesize prompt contract`를 분리한다

package/.onto/processes/review/execution-preparation-artifacts.md

@@ -0,0 +1,281 @@
+# Review Execution Preparation Artifacts
+
+> 상태: Active
+> 목적: `검토 고정 (InvocationBinding)` 이후 lens 실행 전에 materialize되어야 하는 bridge artifact를 고정한다.
+> 기준 문서:
+> - `.onto/processes/review/productized-live-path.md`
+> - `.onto/processes/review/binding-contract.md`
+> - `.onto/processes/review/record-contract.md`
+> - `.onto/processes/review/pre-dispatch-contracts.md`
+> - `.onto/authority/core-lexicon.yaml`
+
+---
+
+## 1. Position
+
+`검토 해석 (InvocationInterpretation)`과 `검토 고정 (InvocationBinding)`만으로는
+lens가 실제로 무엇을 읽어야 하는지가 닫히지 않는다.
+
+그래서 lens 실행 전에 최소 아래 bridge artifact와 gate artifact가 필요하다.
+
+1. `review_session_metadata`
+2. `target_snapshot`
+3. `review_target_materialized_input`
+4. `review_target_profile`
+5. `context_candidate_assembly`
+6. `actor_invocation_profiles`
+7. `actor_consumer_bindings`
+8. `domain_binding`
+9. `review_value_alignment_criteria`
+10. `review_context_manifest`
+
+이 artifact들은 이후 `ReviewRecord`의 execution preparation layer를 이룬다.
+
+---
+
+## 2. Canonical Filesystem Seats
+
+현재 prompt-backed reference path의 canonical seat는 아래다.
+
+```text
+.onto/review/{session_id}/
+  session-metadata.yaml
+  interpretation.yaml
+  binding.yaml
+  execution-plan.yaml
+  error-log.md
+  execution-preparation/
+    target-snapshot.md
+    target-snapshot-manifest.yaml
+    materialized-input.md
+    review-target-profile.yaml
+    context-candidate-assembly.yaml
+    actor-invocation-profiles.yaml
+    actor-consumer-bindings.yaml
+    domain-binding.yaml
+    review-value-alignment-criteria.yaml
+    review-context-manifest.yaml
+```
+
+원칙:
+
+- `interpretation.yaml`과 `binding.yaml`은 invocation phase 산출물이다
+- `execution-plan.yaml`은 lens/synthesize/finalize seat를 고정하는 deterministic coordination artifact다
+- `binding.yaml`과 `execution-plan.yaml`은 boundary seat도 함께 가진다
+  - `BoundaryPolicy`
+  - `BoundaryPresentation`
+  - `BoundaryEnforcementProfile`
+  - `EffectiveBoundaryState`
+- `error-log.md`는 deterministic conformance log seat다
+- `degradation-summary.yaml`은 degraded case / partial failure를 기록하는 structured source seat다
+- `execution-preparation/` 아래 artifact들은 lens 실행 직전 basis artifact다
+- `pre-dispatch-contracts.md`가 정한 gate를 통과하지 못하면 lens dispatch를 시작하지 않는다
+- later runtime implementation도 이 구분은 유지해야 한다
+
+---
+
+## 3. review_session_metadata
+
+`review_session_metadata`는 실행 단위의 deterministic metadata다.
+
+최소 필드:
+
+- `session_id`
+- `entrypoint`
+- `execution_realization`
+- `host_runtime`
+- `review_mode`
+- `created_at`
+- `project_root`
+- `requested_target`
+- `requested_domain_token`
+- `onto_home`
+
+예시:
+
+```yaml
+session_id: 20260404-a1b2c3d4
+entrypoint: review
+execution_realization: worker
+host_runtime: codex
+review_mode: full
+created_at: 2026-04-04T15:20:00+09:00
+project_root: /Users/kangmin/cowork/onto-mcp
+requested_target: src/core-runtime/review
+requested_domain_token: "@ontology"
+onto_home: /Users/kangmin/cowork/onto-mcp
+```
+
+`onto_home`는 review 실행 시점에 resolve 된 onto-mcp runtime resource root의 snapshot 이다.
+
+---
+
+## 4. target_snapshot
+
+`target_snapshot`은 review 당시 실제로 읽은 target basis다.
+
+중요:
+
+- current file state를 나중에 다시 읽는 것으로 대체하면 안 된다
+- 당시 review basis를 그대로 보존해야 한다
+
+`target-snapshot.md`는 실제 읽힌 본문을 보존한다.
+`target-snapshot-manifest.yaml`은 snapshot metadata를 보존한다.
+
+`target-snapshot-manifest.yaml` 최소 필드:
+
+- `review_target_scope_kind`
+- `resolved_target_refs`
+- `review_target_profile_ref`
+- `captured_at`
+- `capture_reason`
+
+예시:
+
+```yaml
+review_target_scope_kind: bundle
+resolved_target_refs:
+  - /Users/kangmin/cowork/onto-mcp/src/core-runtime/review
+  - /Users/kangmin/cowork/onto-mcp/.onto/processes/review
+review_target_profile_ref: /Users/kangmin/cowork/onto-mcp/.onto/review/20260404-a1b2c3d4/execution-preparation/review-target-profile.yaml
+captured_at: 2026-04-04T15:21:00+09:00
+capture_reason: prompt-backed review execution
+```
+
+---
+
+## 5. review_target_materialized_input
+
+`review_target_materialized_input`은 lens가 실제로 읽는 normalized execution input이다.
+
+이 artifact는 `review_target_scope`를 실행 친화적 shape로 materialize한다.
+
+허용 shape:
+
+1. `single_text`
+2. `directory_listing`
+3. `bundle_member_texts`
+
+원칙:
+
+- `target_snapshot`은 basis preservation이다
+- `review_target_materialized_input`은 execution-friendly reading bundle이다
+- 둘은 같은 것이 아니다
+
+예시:
+
+```yaml
+kind: bundle_member_texts
+members:
+  - ref: /Users/kangmin/cowork/onto-mcp/src/core-runtime/review
+    label: review_runtime
+    content_path: execution-preparation/materialized-input.md#review_runtime
+  - ref: /Users/kangmin/cowork/onto-mcp/.onto/processes/review
+    label: review_contracts
+    content_path: execution-preparation/materialized-input.md#review_contracts
+```
+
+---
+
+## 6. review_target_profile
+
+`review_target_profile`은 현재 review target의 artifact role, target
+material kind, closure obligation을 고정한다.
+
+이 artifact는 target을 다시 읽기 위한 권한이 아니라, 이미 고정된 target refs를
+어떤 종류의 artifact로 평가할지 정하는 runtime-owned profile이다.
+
+최소 필드:
+
+- `target_scope_kind`
+- `materialized_input_kind`
+- `target_input_kind`
+- `target_material_kind`
+- `artifact_roles`
+- `domain`
+- `maturity`
+- `closure_level`
+- `review_goal`
+- `closure_obligation_policy`
+- `target_refs`
+- `material_profile`
+- `boundary`
+- `inference`
+
+허용 `target_input_kind`:
+
+1. `single_file`
+2. `directory`
+3. `explicit_bundle`
+4. `git_diff`
+5. `generated_packet`
+
+기준 문서:
+
+- `.onto/processes/review/review-target-profile-contract.md`
+
+---
+
+## 7. context_candidate_assembly
+
+`context_candidate_assembly`는 각 lens가 self-loading 또는 main-context loading으로 접근할 수 있는 candidate context set을 적는다.
+
+최소 필드:
+
+- `system_purpose_refs`
+- `domain_context_refs`
+- `role_definition_refs`
+- `execution_rule_refs`
+
+예시:
+
+```yaml
+system_purpose_refs:
+  - /Users/kangmin/cowork/onto-mcp/README.md
+domain_context_refs:
+  - /Users/kangmin/.onto/domains/ontology/domain_scope.md
+role_definition_refs:
+  - /Users/kangmin/cowork/onto-mcp/.onto/roles/logic.md
+execution_rule_refs:
+  - /Users/kangmin/cowork/onto-mcp/.onto/processes/review/productized-live-path.md
+  - /Users/kangmin/cowork/onto-mcp/.onto/processes/review/prompt-execution-runner-contract.md
+```
+
+원칙:
+
+- 이것은 candidate set이다
+- 어떤 항목이 실제로 중요한지는 lens가 판단한다
+- 즉 runtime/host는 context relevance judgment를 대신하지 않는다
+
+---
+
+## 8. Ownership
+
+이 artifact들의 owner는 아래다.
+
+| Artifact | Owner |
+|---|---|
+| `session-metadata.yaml` | runtime/host |
+| `interpretation.yaml` | `LLM` |
+| `binding.yaml` | runtime/host |
+| `target-snapshot.*` | runtime/host |
+| `materialized-input.md` | runtime/host |
+| `review-target-profile.yaml` | runtime/host |
+| `context-candidate-assembly.yaml` | runtime/host |
+| `actor-invocation-profiles.yaml` | runtime/host |
+| `actor-consumer-bindings.yaml` | runtime/host |
+| `domain-binding.yaml` | runtime/host |
+| `review-value-alignment-criteria.yaml` | runtime/host with principal authority |
+| `review-context-manifest.yaml` | runtime/host |
+
+즉 semantic interpretation은 `LLM`이 맡고,
+그 해석을 실제 실행 basis로 materialize하는 것은 runtime/host가 맡는다.
+
+---
+
+## 9. Immediate Follow-up
+
+다음 단계는 아래다.
+
+1. prompt-backed path에서 이 artifact 내용을 실제 field shape로 안정화한다
+2. later runtime replacement에서 file generator를 하나씩 치환한다