{ "canonical_name": "elevanaltd/octave-mcp", "compilation_id": "pack_3b6093d220ac4bc4a22b8841ac24536e", "created_at": "2026-05-22T04:13:07.508355+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight", "recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `pip install octave-mcp` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "pip install octave-mcp", "sandbox_container_image": "python:3.12-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "llm_execute_isolated_install", "sandbox_validation_id": "sbx_9e9eaf53a6d3435eaef5979497a8926c" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_cc1ab848b2a3ae6720297d3982815e8b", "canonical_name": "elevanaltd/octave-mcp", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/elevanaltd/octave-mcp", "slug": "octave-mcp", "source_packet_id": "phit_2facddf9975b40a29e3d5c9a0ae866f4", "source_validation_id": "dval_7f39a25a30e541f2b9056def84f066e7" }, "merchandising": { "best_for": "需要工具连接与集成能力，并使用 mcp_host的用户", "github_forks": null, "github_stars": null, "one_liner_en": "OCTAVE MCP Server", "one_liner_zh": "OCTAVE MCP Server", "primary_category": { "category_id": "tool-integrations", "confidence": "high", "name_en": "Tool Integrations", "name_zh": "工具连接与集成", "reason": "matched_keywords:mcp, server, github" }, "target_user": "使用 mcp_host 等宿主 AI 的用户", "title_en": "octave-mcp", "title_zh": "octave-mcp 能力包", "visible_tags": [ { "label_en": "MCP Tools", "label_zh": "MCP 工具", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-mcp-tools", "type": "product_domain" }, { "label_en": "Knowledge Base Q&A", "label_zh": "知识库问答", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-knowledge-base-q-a", "type": "user_job" }, { "label_en": "Structured Data Extraction", "label_zh": "结构化数据提取", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-structured-data-extraction", "type": "core_capability" }, { "label_en": "Multi-role Workflow", "label_zh": "多角色协作流程", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-multi-role-workflow", "type": "workflow_pattern" }, { "label_en": "Open Source Tool", "label_zh": "开源工具", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-open-source-tool", "type": "selection_signal" } ] }, "packet_id": "phit_2facddf9975b40a29e3d5c9a0ae866f4", "page_model": { "artifacts": { "artifact_slug": "octave-mcp", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "pip install octave-mcp", "label": "Python / pip · 官方安装入口", "source": "https://github.com/elevanaltd/octave-mcp#readme", "verified": true } ], "display_tags": [ "MCP 工具", "知识库问答", "结构化数据提取", "多角色协作流程", "开源工具" ], "eyebrow": "工具连接与集成", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要工具连接与集成能力，并使用 mcp_host的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "OCTAVE MCP Server" }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "mcp_host", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "mcp_config, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "Developers should check this security_permissions risk before relying on the project: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md", "category": "安全/权限坑", "evidence": [ "failure_mode_cluster:github_issue | fmev_22c0329bf698546f57cbd9edd620083f | https://github.com/elevanaltd/octave-mcp/issues/424 | octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md" ], "severity": "high", "suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md. Context: Source discussion did not expose a precise runtime context.", "title": "失败模式：security_permissions: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oc...", "user_impact": "Developers may expose sensitive permissions or credentials: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md" }, { "body": "Developers should check this security_permissions risk before relying on the project: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)", "category": "安全/权限坑", "evidence": [ "failure_mode_cluster:github_issue | fmev_e63e5f9a96f8ad23bef9d32f6c4c13e7 | https://github.com/elevanaltd/octave-mcp/issues/420 | octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)" ], "severity": "high", "suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38). Context: Source discussion did not expose a precise runtime context.", "title": "失败模式：security_permissions: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)", "user_impact": "Developers may expose sensitive permissions or credentials: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: octave_write surgical edit primitives unsafe on inline-array top-level entries (APPEND + expanded modes)", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_75dbe0c2c20b479a9afc619c467acc20 | https://github.com/elevanaltd/octave-mcp/issues/411 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：bug: octave_write surgical edit primitives unsafe on inline-array top-level entries (APPEND + expanded modes)", "user_impact": "可能影响升级、迁移或版本选择。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_744a11a12c0340e08087ea951c281000 | https://github.com/elevanaltd/octave-mcp/issues/426 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "Developers should check this installation risk before relying on the project: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks", "category": "安装坑", "evidence": [ "failure_mode_cluster:github_issue | fmev_8ff9088f7d6c1752dffdf17a7dd320db | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks", "failure_mode_cluster:github_issue | fmev_aa61ed66e510ebfae83228fb28ae6e11 | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks", "failure_mode_cluster:github_issue | fmev_6046cbe1d9f5946d7c5f3b4a9e75cd5a | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks", "failure_mode_cluster:github_issue | fmev_6450b53644007e96c1fa966585fe47ea | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks" ], "severity": "medium", "suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks. Context: Source discussion did not expose a precise runtime context.", "title": "失败模式：installation: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed findin...", "user_impact": "Developers may fail before the first successful local run: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks" }, { "body": "Developers should check this installation risk before relying on the project: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents", "category": "安装坑", "evidence": [ "failure_mode_cluster:github_issue | fmev_9d395f7455d912516430481376e952e2 | https://github.com/elevanaltd/octave-mcp/issues/425 | octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents" ], "severity": "medium", "suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents. Context: Source discussion did not expose a precise runtime context.", "title": "失败模式：installation: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type doc...", "user_impact": "Developers may fail before the first successful local run: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: _find_target_start backslash-run quote-escape mishandling (sibling of cubic P1 on PR #431)", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_8284755b0fa74799b1f881f624677141 | https://github.com/elevanaltd/octave-mcp/issues/432 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：bug: _find_target_start backslash-run quote-escape mishandling (sibling of cubic P1 on PR #431)", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "Developers should check this configuration risk before relying on the project: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty)", "category": "配置坑", "evidence": [ "failure_mode_cluster:github_issue | fmev_c368f015439226dbb8b9c45fddf3158d | https://github.com/elevanaltd/octave-mcp/issues/430 | RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty)" ], "severity": "medium", "suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty). Context: Observed when using python", "title": "失败模式：configuration: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describi...", "user_impact": "Developers may misconfigure credentials, environment, or host setup: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty)" }, { "body": "Developers should check this configuration risk before relying on the project: bug: emitter normalises backslash counts in string literals (round-trip byte-loss)", "category": "配置坑", "evidence": [ "failure_mode_cluster:github_issue | fmev_bbc57f3d1a93f9e5fb48332874044f35 | https://github.com/elevanaltd/octave-mcp/issues/434 | bug: emitter normalises backslash counts in string literals (round-trip byte-loss)" ], "severity": "medium", "suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: bug: emitter normalises backslash counts in string literals (round-trip byte-loss). Context: Source discussion did not expose a precise runtime context.", "title": "失败模式：configuration: bug: emitter normalises backslash counts in string literals (round-trip byte-loss)", "user_impact": "Developers may misconfigure credentials, environment, or host setup: bug: emitter normalises backslash counts in string literals (round-trip byte-loss)" }, { "body": "Developers should check this configuration risk before relying on the project: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue)", "category": "配置坑", "evidence": [ "failure_mode_cluster:github_issue | fmev_cf23dec47765d23b75fcd69bef5c1332 | https://github.com/elevanaltd/octave-mcp/issues/433 | bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue)" ], "severity": "medium", "suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue). Context: Source discussion did not expose a precise runtime context.", "title": "失败模式：configuration: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only pat...", "user_impact": "Developers may misconfigure credentials, environment, or host setup: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue)" }, { "body": "Developers should check this configuration risk before relying on the project: bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplicate key (invalid O...", "category": "配置坑", "evidence": [ "failure_mode_cluster:github_issue | fmev_6420a6baab4269626b43aeca56c0d6c8 | https://github.com/elevanaltd/octave-mcp/issues/443 | bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplicate key (invalid O..." ], "severity": "medium", "suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplicate key (invalid O.... Context: Observed when using python", "title": "失败模式：configuration: bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say fu...", "user_impact": "Developers may misconfigure credentials, environment, or host setup: bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplicate key (invalid O..." }, { "body": "Developers should check this configuration risk before relying on the project: governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate", "category": "配置坑", "evidence": [ "failure_mode_cluster:github_issue | fmev_67bfde22b66b3bde199f59556c21e82d | https://github.com/elevanaltd/octave-mcp/issues/441 | governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate" ], "severity": "medium", "suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate. Context: Source discussion did not expose a precise runtime context.", "title": "失败模式：configuration: governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate", "user_impact": "Developers may misconfigure credentials, environment, or host setup: governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate" }, { "body": "Developers should check this configuration risk before relying on the project: octave_validate: SKILL schema only validates frontmatter; §-section body uncovered", "category": "配置坑", "evidence": [ "failure_mode_cluster:github_issue | fmev_339fb57ac390e565b548c1bea78abc66 | https://github.com/elevanaltd/octave-mcp/issues/428 | octave_validate: SKILL schema only validates frontmatter; §-section body uncovered", "failure_mode_cluster:github_issue | fmev_338bf1f21059e0d238b9fcb8084aea71 | https://github.com/elevanaltd/octave-mcp/issues/428 | octave_validate: SKILL schema only validates frontmatter; §-section body uncovered" ], "severity": "medium", "suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: octave_validate: SKILL schema only validates frontmatter; §-section body uncovered. Context: Source discussion did not expose a precise runtime context.", "title": "失败模式：configuration: octave_validate: SKILL schema only validates frontmatter; §-section body uncovered", "user_impact": "Developers may misconfigure credentials, environment, or host setup: octave_validate: SKILL schema only validates frontmatter; §-section body uncovered" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form-preservation gap)", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_6236e7ed154c4976ac4a7deee1e5e95d | https://github.com/elevanaltd/octave-mcp/issues/447 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form-preservation gap)", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：octave_validate: DEBATE_TRANSCRIPT STATUS enum missing 'PAUSED' (live false negative)", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_b0ee99f7200a4686b5de382a2c70d9b2 | https://github.com/elevanaltd/octave-mcp/issues/423 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：octave_validate: DEBATE_TRANSCRIPT STATUS enum missing 'PAUSED' (live false negative)", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 38 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安全/权限坑 - 失败模式：security_permissions: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oc...。", "title": "踩坑日志" }, "snapshot": { "contributors": null, "forks": null, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": null }, "source_url": "https://github.com/elevanaltd/octave-mcp", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "OCTAVE MCP Server", "title": "octave-mcp 能力包", "trial_prompt": "# octave-mcp - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for elevanaltd/octave-mcp.\n\nProject:\n- Name: octave-mcp\n- Repository: https://github.com/elevanaltd/octave-mcp\n- Summary: OCTAVE MCP Server\n- Host target: mcp_host\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: OCTAVE MCP Server\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-project-introduction: Project Introduction. Produce one small intermediate artifact and wait for confirmation.\n2. page-system-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n3. page-canonical-normalization: Canonical Normalization. Produce one small intermediate artifact and wait for confirmation.\n4. page-schema-validation: Schema Validation. Produce one small intermediate artifact and wait for confirmation.\n5. page-compression-system: Compression System. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/elevanaltd/octave-mcp#readme\n- src/octave_mcp/resources/skills/octave-compression/SKILL.md\n- src/octave_mcp/resources/skills/octave-literacy/SKILL.md\n- src/octave_mcp/resources/skills/octave-mastery/SKILL.md\n- src/octave_mcp/resources/skills/octave-mythology/SKILL.md\n- src/octave_mcp/resources/skills/octave-ultra-mythic/SKILL.md\n- README.md\n- src/octave_mcp/__init__.py\n- AGENTS.oct.md\n- src/octave_mcp/mcp/server.py\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n", "voices": [ { "body": "来源平台：github。github/github_issue: DECISION_LOG schema v1.1 conformance: reference DECISIONS.oct.md reports（https://github.com/elevanaltd/octave-mcp/issues/448）；github/github_issue: bug: octave_write surgical edit primitives unsafe on inline-array top-le（https://github.com/elevanaltd/octave-mcp/issues/411）；github/github_issue: bug: octave_write changes_mode adds nested block instead of mutating exi（https://github.com/elevanaltd/octave-mcp/issues/447）；github/github_issue: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negative（https://github.com/elevanaltd/octave-mcp/issues/426）；github/github_issue: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negative（https://github.com/elevanaltd/octave-mcp/issues/426）；github/github_issue: octave_validate: SKILL schema only validates frontmatter; §-section body（https://github.com/elevanaltd/octave-mcp/issues/428）；github/github_issue: enhancement: validator section-bucket merging may mask path-isolated req（https://github.com/elevanaltd/octave-mcp/issues/445）；github/github_issue: octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed（https://github.com/elevanaltd/octave-mcp/issues/427）；github/github_issue: bug: octave_write changes-mode bare-dict on top-level KEY silently acts （https://github.com/elevanaltd/octave-mcp/issues/443）；github/github_issue: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negative（https://github.com/elevanaltd/octave-mcp/issues/426）；github/github_issue: governance: amend pre-merge CI gate to use octave_write --dry-run, not j（https://github.com/elevanaltd/octave-mcp/issues/441）；github/github_issue: bug/governance: octave_validate vs octave_write asymmetric handling of E（https://github.com/elevanaltd/octave-mcp/issues/440）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_issue", "source": "github", "title": "DECISION_LOG schema v1.1 conformance: reference DECISIONS.oct.md reports", "url": "https://github.com/elevanaltd/octave-mcp/issues/448" }, { "kind": "github_issue", "source": "github", "title": "bug: octave_write surgical edit primitives unsafe on inline-array top-le", "url": "https://github.com/elevanaltd/octave-mcp/issues/411" }, { "kind": "github_issue", "source": "github", "title": "bug: octave_write changes_mode adds nested block instead of mutating exi", "url": "https://github.com/elevanaltd/octave-mcp/issues/447" }, { "kind": "github_issue", "source": "github", "title": "octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negative", "url": "https://github.com/elevanaltd/octave-mcp/issues/426" }, { "kind": "github_issue", "source": "github", "title": "octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negative", "url": "https://github.com/elevanaltd/octave-mcp/issues/426" }, { "kind": "github_issue", "source": "github", "title": "octave_validate: SKILL schema only validates frontmatter; §-section body", "url": "https://github.com/elevanaltd/octave-mcp/issues/428" }, { "kind": "github_issue", "source": "github", "title": "enhancement: validator section-bucket merging may mask path-isolated req", "url": "https://github.com/elevanaltd/octave-mcp/issues/445" }, { "kind": "github_issue", "source": "github", "title": "octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed", "url": "https://github.com/elevanaltd/octave-mcp/issues/427" }, { "kind": "github_issue", "source": "github", "title": "bug: octave_write changes-mode bare-dict on top-level KEY silently acts ", "url": "https://github.com/elevanaltd/octave-mcp/issues/443" }, { "kind": "github_issue", "source": "github", "title": "octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negative", "url": "https://github.com/elevanaltd/octave-mcp/issues/426" }, { "kind": "github_issue", "source": "github", "title": "governance: amend pre-merge CI gate to use octave_write --dry-run, not j", "url": "https://github.com/elevanaltd/octave-mcp/issues/441" }, { "kind": "github_issue", "source": "github", "title": "bug/governance: octave_validate vs octave_write asymmetric handling of E", "url": "https://github.com/elevanaltd/octave-mcp/issues/440" } ], "status": "已收录 13 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "工具连接与集成", "desc": "OCTAVE MCP Server", "effort": "安装已验证", "forks": null, "icon": "link", "name": "octave-mcp 能力包", "risk": "可发布", "slug": "octave-mcp", "stars": null, "tags": [ "MCP 工具", "知识库问答", "结构化数据提取", "多角色协作流程", "开源工具" ], "thumb": "gray", "type": "MCP 配置" }, "manual": { "markdown": "# https://github.com/elevanaltd/octave-mcp 项目说明书\n\n生成时间：2026-05-16 03:50:43 UTC\n\n## 目录\n\n- [Project Introduction](#page-project-introduction)\n- [Project File Structure](#page-file-structure)\n- [System Architecture](#page-system-architecture)\n- [Canonical Normalization](#page-canonical-normalization)\n- [Schema Validation](#page-schema-validation)\n- [Compression System](#page-compression-system)\n- [Grammar Compilation](#page-grammar-compilation)\n- [MCP Tools Reference](#page-mcp-tools)\n- [CLI Interface](#page-cli-interface)\n- [Python API Reference](#page-python-api)\n\n\n\n## Project Introduction\n\n### 相关页面\n\n相关主题：[System Architecture](#page-system-architecture), [Canonical Normalization](#page-canonical-normalization)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n- [src/octave_mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/__init__.py)\n- [tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)\n- [src/octave_mcp/core/parser.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/parser.py)\n- [src/octave_mcp/core/validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/validator.py)\n- [src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)\n
\n\n# Project Introduction\n\n## Overview\n\nOctave-MCP (Olympian Common Text And Vocabulary Engine - Model Context Protocol) is a semantic DSL (Domain Specific Language) framework designed for structured document creation, validation, and transformation in LLM workflows. It provides a unified text format with rich semantic annotations that enables precise machine-readable documentation while remaining human-readable.\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n## Core Concepts\n\n### What is OCTAVE?\n\nOCTAVE stands for **Olympian Common Text And Vocabulary Engine**. It is a semantic DSL specifically designed for Large Language Models (LLMs) that bridges the gap between human-readable documentation and machine-processable structured data.\n\nThe framework operates on a **patterns → archetypes → holographic** methodology, where semantic patterns are mapped to recognizable archetypes which then create holographic constraints for validation and processing.\n\n资料来源：[src/octave_mcp/resources/primers/octave-mastery-primer.oct.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/primers/octave-mastery-primer.oct.md)\n\n### Key Features\n\n| Feature | Description |\n|---------|-------------|\n| **Semantic DSL** | Domain-specific language with typed syntax for structured documents |\n| **MCP Integration** | Model Context Protocol server for tool-based access |\n| **CLI Tools** | Command-line utilities for validation and transformation |\n| **Grammar Compilation** | GBNF grammar generation for constrained text generation |\n| **Validation Pipeline** | Multi-stage validation with repair suggestions |\n| **Holographic Patterns** | Constraint-based field validation with logical operators |\n\n## Architecture\n\n### System Components\n\n```mermaid\ngraph TD\n A[OCTAVE Documents] --> B[Parser Layer]\n B --> C[Grammar Compiler]\n B --> D[Validator]\n C --> E[GBNF Grammar Output]\n D --> F[Validation Results]\n B --> G[Writer/Reader]\n G --> H[Normalized Output]\n \n I[MCP Tools] --> J[octave_validate]\n I --> K[octave_write]\n I --> L[octave_eject]\n I --> M[octave_compile_grammar]\n \n N[CLI] --> O[octave validate]\n N --> P[octave write]\n N --> Q[octave eject]\n```\n\n### Package Structure\n\nThe main package resides in `src/octave_mcp/` with the following core modules:\n\n| Module | Purpose |\n|--------|---------|\n| `core/parser.py` | Parses OCTAVE documents into AST |\n| `core/validator.py` | Validates documents against schemas |\n| `core/grammar_compiler/` | Compiles schemas to GBNF grammar |\n| `core/holographic.py` | Handles holographic constraint patterns |\n| `mcp/write.py` | MCP tool implementation for writing files |\n\n资料来源：[src/octave_mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/__init__.py)\n\n## OCTAVE Syntax\n\n### Document Structure\n\nAn OCTAVE document follows a specific envelope format:\n\n```octave\n===DOCUMENT_NAME===\nMETA:\n TYPE::\"DOCUMENT_TYPE\"\n VERSION::\"1.0.0\"\n PURPOSE::\"Document purpose description\"\n---\n// Section content\nFIELD::\"value\"\nFIELD::[list_value]\n===END===\n```\n\n### Core Operators\n\n| Operator | Meaning | Example |\n|----------|---------|---------|\n| `::` | Assignment/definition | `KEY::VALUE` |\n| `→` | Flow/sequence | `AUTH::login→validate→dashboard` |\n| `⊕` | Synthesis/combine | `A⊕B` |\n| `⇌` | Tension/opposition | `security⇌usability` |\n| `[]` | List definition | `FIELD::[\"item1\",\"item2\"]` |\n| `∧` | Logical AND constraint | `[\"value\"∧ENUM[A,B]]` |\n| `§` | Section reference | `§TARGET` |\n\n资料来源：[src/octave_mcp/resources/primers/octave-compression-primer.oct.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/primers/octave-compression-primer.oct.md)\n\n### Holographic Constraints\n\nHolographic patterns provide powerful constraint validation:\n\n```octave\nFIELD::[\"value\"∧REQ∧ENUM[OPTION_A,OPTION_B]]\n```\n\nThis pattern specifies that `FIELD` is required (`REQ`) and must be one of the enumerated options.\n\n资料来源：[src/octave_mcp/core/gbnf_compiler.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/gbnf_compiler.py)\n\n## MCP Tools\n\nOctave-MCP provides Model Context Protocol tools for integration with AI assistants:\n\n| Tool | Function |\n|------|----------|\n| `octave_validate` | Validate documents against schema; provides field errors and repair suggestions |\n| `octave_write` | Write files through full validation pipeline |\n| `octave_eject` | Project documents to different views (canonical, executive, developer, template) |\n| `octave_compile_grammar` | Compile schema constraints to GBNF grammar |\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n### MCP Configuration\n\n**Claude Desktop Configuration:**\n\n```json\n{\n \"mcpServers\": {\n \"octave\": {\n \"command\": \"octave-mcp-server\"\n }\n }\n}\n```\n\n**HTTP Transport:**\n\n```bash\noctave-mcp-server --transport http --port 8080\n```\n\n## CLI Tools\n\n### Installation\n\n```bash\n# Install the package\npip install octave-mcp\n\n# Verify installation\noctave --version\n```\n\n### Available Commands\n\n| Command | Description |\n|---------|-------------|\n| `octave validate ` | Validate an OCTAVE document |\n| `octave write ` | Write output through validation pipeline |\n| `octave eject ` | Export document in alternate format |\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n### Standalone Validation Tools\n\nLocated in the `tools/` directory:\n\n| Tool | Purpose |\n|------|---------|\n| `lint-octave.py` | Fast syntax validation |\n| `octave-to-json.py` | Convert OCTAVE to JSON |\n| `json-to-octave.py` | Convert JSON back to OCTAVE |\n| `octave-validator.py` | Full document validation |\n\n资料来源：[tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)\n\n## Validation System\n\n### Validation Process\n\n```mermaid\ngraph LR\n A[Document Input] --> B[Lexer]\n B --> C[Parser]\n C --> D[AST]\n D --> E[Schema Validator]\n E --> F{Valid?}\n F -->|Yes| G[Validation Passed]\n F -->|No| H[Error Report]\n H --> I[Repair Suggestions]\n```\n\n### Validator Features\n\nThe validation system provides:\n\n- **Field-level error reporting** with line numbers\n- **Repair suggestions** for common issues\n- **Zone coverage analysis** for document completeness\n- **Semantic validation** against holographic constraints\n\n资料来源：[src/octave_mcp/core/validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/validator.py)\n\n### Audit Patterns\n\nThe validator recognizes specific audit-related field prefixes:\n\n| Pattern Prefix | Purpose |\n|----------------|---------|\n| `NON_CANONICAL_` | Non-canonical normalization fields |\n| `DEGRADED_` | Degraded state indicators |\n| `NORMALIZED_` | Normalization metadata |\n| `ROUNDTRIP_` | Roundtrip conversion fields |\n\nThese patterns allow controlled admission of non-standard fields during validation.\n\n资料来源：[src/octave_mcp/core/validator.py:line-range](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/validator.py)\n\n## Grammar Compilation\n\n### GBNF Generation\n\nThe grammar compiler transforms OCTAVE schemas into GBNF (Greibach Normal Form) grammar for constrained text generation:\n\n```python\nfrom octave_mcp.core.grammar_compiler import compile_document_grammar\n\nschema = SchemaDefinition(name=\"DOCUMENT_TYPE\", version=\"1.0\")\ngbnf = compile_document_grammar(schema)\n```\n\nThis enables LLMs to generate valid OCTAVE documents through constrained decoding.\n\n资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/__init__.py)\n\n### CONTRACT Extraction\n\nThe grammar compiler can extract field specifications from META `CONTRACT` definitions:\n\n```octave\nMETA:\n CONTRACT::[\n \"FIELD[NAME]::REQ∧ENUM[A,B]\",\n \"FIELD[STATUS]::OPT\"\n ]\n```\n\nEach contract entry is parsed into structured field definitions with holographic constraints.\n\n资料来源：[src/octave_mcp/core/gbnf_compiler.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/gbnf_compiler.py)\n\n## Use Cases\n\n### When to Use Octave-MCP\n\n| Scenario | Recommended |\n|----------|-------------|\n| Multi-agent document workflows | ✅ Yes |\n| Agent and skill file definitions | ✅ Yes |\n| Decision logs and audit trails | ✅ Yes |\n| System prompts with token optimization | ✅ Yes |\n| Single-step freeform prompts | ❌ No |\n| Code output generation | ❌ No |\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n### Document Types\n\nOctave-MCP supports structured document types including:\n\n- **SESSION_LOG** - Conversation session records\n- **DECISION** - Decision documentation\n- **AGENT** - Agent definitions\n- **SKILL** - Skill specifications\n- **PATTERN** - Pattern definitions\n\n## Integration Examples\n\n### With Claude Code\n\n```bash\n# Generate enhanced context\nrepomix --style xml --output context.xml\npython octave_enhance_targeted.py context.xml enhanced.xml\n\n# Paste enhanced.xml content into Claude Code session\n```\n\n### With Repomix Enhancement\n\nThe `examples/integrations/repomix/` directory provides scripts for:\n\n- **Targeted enhancement** - Focus on key files\n- **Comprehensive enhancement** - Full codebase analysis\n\nEnhanced contexts add semantic annotations like:\n\n```octave\n===FILE_PROCESSOR===\nMETA:\n PURPOSE::\"Process files\"\n PATTERN::PIPELINE\n===END===\n```\n\n资料来源：[examples/integrations/repomix/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/examples/integrations/repomix/README.md)\n\n## Additional Resources\n\n| Resource | Location |\n|----------|----------|\n| Usage Guide | [docs/usage.md](docs/usage.md) |\n| API Reference | [docs/api.md](docs/api.md) |\n| MCP Configuration | [docs/mcp-config.md](docs/mcp-config.md) |\n| Primers | [src/octave_mcp/resources/primers/](src/octave_mcp/resources/primers/) |\n| Skills | [src/octave_mcp/resources/skills/](src/octave_mcp/resources/skills/) |\n\n---\n\n\n\n## Project File Structure\n\n### 相关页面\n\n相关主题：[Project Introduction](#page-project-introduction), [System Architecture](#page-system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n- [src/octave_mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/__init__.py)\n- [src/octave_mcp/resources/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/README.md)\n- [tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)\n- [src/octave_mcp/mcp/grammar_resources.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/grammar_resources.py)\n- [src/octave_mcp/core/grammar_compiler/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/__init__.py)\n- [standards/L3-AGENT-FORMAT.oct.md](https://github.com/elevanaltd/octave-mcp/blob/main/standards/L3-AGENT-FORMAT.oct.md)\n
\n\n# Project File Structure\n\n## Overview\n\nThe `octave-mcp` project is organized as a Python package implementing the **Olympian Common Text And Vocabulary Engine (OCTAVE)** — a semantic DSL designed for LLM document processing. The repository follows a modular structure that separates core parsing logic, MCP (Model Context Protocol) server implementation, resource definitions, utilities, and documentation.\n\n## Directory Architecture\n\n```mermaid\ngraph TD\n A[octave-mcp Root] --> B[src/octave_mcp/]\n A --> C[tools/]\n A --> D[examples/]\n A --> E[standards/]\n A --> F[docs/]\n \n B --> B1[core/]\n B --> B2[mcp/]\n B --> B3[resources/]\n \n B1 --> B1a[grammar_compiler/]\n B1 --> B1b[parser/]\n B1 --> B1c[validator/]\n \n B2 --> B2a[write.py]\n B2 --> B2b[grammar_resources.py]\n \n B3 --> B3a[primers/]\n B3 --> B3b[specs/]\n B3 --> B3c[skills/]\n B3 --> B3d[vocabularies/]\n```\n\n## Root Directory Structure\n\n| File/Directory | Purpose |\n|----------------|---------|\n| `README.md` | Main project documentation, MCP server setup, and usage guide |\n| `CONTRIBUTING.md` | Guidelines for contributors |\n| `pyproject.toml` | Python package configuration |\n| `src/octave_mcp/` | Main package source code |\n| `tools/` | Standalone CLI utilities for OCTAVE validation |\n| `examples/` | Integration examples and compression tier demonstrations |\n| `standards/` | OCTAVE format standards and schemas |\n| `docs/` | Additional documentation files |\n\n## Source Code (`src/octave_mcp/`)\n\nThe main package contains three primary submodules:\n\n### Core Module (`src/octave_mcp/core/`)\n\nContains the fundamental parsing and validation logic.\n\n| Submodule | Purpose |\n|-----------|---------|\n| `parser/` | Lexer and parser implementations |\n| `validator/` | Schema validation engine |\n| `grammar_compiler/` | GBNF grammar compilation for constrained generation |\n\nThe `grammar_compiler` package was renamed from `octave_mcp.core.grammar` to resolve a naming collision, as documented in ADR-0006. It provides the public API:\n\n```python\nfrom octave_mcp.core.grammar_compiler import compile_document_grammar, emit_grammar_for_schema\n```\n\n资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py:1-18]()\n\n### MCP Module (`src/octave_mcp/mcp/`)\n\nImplements the Model Context Protocol server and tools.\n\n| File | Purpose |\n|------|---------|\n| `write.py` | MCP tool for writing OCTAVE files with full validation pipeline |\n| `grammar_resources.py` | Dynamic grammar resource templates for MCP |\n\nThe `grammar_resources.py` module provides:\n\n- Resource templates for accessing pre-compiled GBNF grammars\n- Dynamic schema compilation with caching\n- URI template access via `octave://grammars/{schema_name}`\n\n资料来源：[src/octave_mcp/mcp/grammar_resources.py:1-80]()\n\n### Resources Module (`src/octave_mcp/resources/`)\n\nContains distributable OCTAVE resources used by implementers and agents.\n\n```mermaid\ngraph LR\n A[resources/] --> B[primers/]\n A --> C[specs/]\n A --> D[skills/]\n A --> E[vocabularies/]\n \n B --> B1[octave-literacy-primer]\n B --> B2[octave-compression-primer]\n B --> B3[octave-mastery-primer]\n B --> B4[octave-ultra-mythic-primer]\n \n C --> C1[octave-core-spec.oct.md]\n C --> C2[octave-agents-spec.oct.md]\n C --> C3[octave-skills-spec.oct.md]\n C --> C4[schemas/]\n \n D --> D1[octave-compression/SKILL.md]\n \n E --> E1[registry.oct.md]\n E --> E2[core/]\n```\n\n#### Primers (`primers/`)\n\nSelf-referential training documents that teach OCTAVE syntax:\n\n| Primer | Version | Purpose |\n|--------|---------|---------|\n| `octave-literacy-primer.oct.md` | 6.0.0 | Basic OCTAVE literacy |\n| `octave-compression-primer.oct.md` | 6.0.0 | Prose-to-OCTAVE transformation |\n| `octave-mastery-primer.oct.md` | 6.1.0 | Advanced pattern mastery |\n| `octave-ultra-mythic-primer.oct.md` | 6.2.0 | Ultra-compression techniques |\n\n#### Specs (`specs/`)\n\nOfficial OCTAVE v6.0.0 specifications:\n\n| Specification | Description |\n|---------------|-------------|\n| `octave-core-spec.oct.md` | Core syntax, operators, and type system |\n| `octave-agents-spec.oct.md` | Agent architecture patterns |\n| `octave-skills-spec.oct.md` | Skill document format |\n| `octave-data-spec.oct.md` | Data compression tiers |\n| `octave-execution-spec.oct.md` | Execution flow and protocols |\n| `octave-schema-spec.oct.md` | Schema validation framework |\n| `octave-rationale-spec.oct.md` | Design rationale |\n| `octave-primers-spec.oct.md` | Primer specification |\n| `octave-mcp-architecture.oct.md` | MCP implementation architecture |\n\n#### Schemas (`specs/schemas/`)\n\nSchema definitions including:\n\n- `debate_transcript.oct.md` - Debate transcript schema\n- `json/` - JSON Schema for OCTAVE\n\n#### Vocabularies (`specs/vocabularies/`)\n\nOCTAVE vocabulary definitions:\n\n| Path | Content |\n|------|---------|\n| `registry.oct.md` | Vocabulary registry index |\n| `core/META.oct.md` | META vocabulary specification |\n| `core/SNAPSHOT.oct.md` | SNAPSHOT vocabulary specification |\n\n#### Skills (`skills/`)\n\nWorkflow definitions for OCTAVE operations:\n\n- `octave-compression/SKILL.md` - Workflow for prose-to-OCTAVE transformation\n\n资料来源：[src/octave_mcp/resources/README.md:1-80]()\n\n### Package Exports\n\nThe `octave_mcp/__init__.py` exports 51 public APIs organized into categories:\n\n| Category | Key Exports |\n|----------|-------------|\n| Functions | `parse`, `parse_with_warnings`, `emit`, `tokenize`, `repair`, `project`, `hydrate` |\n| Classes | `Parser`, `Validator`, `TokenType`, `Token`, `HydrationPolicy`, `VocabularyRegistry` |\n| AST Nodes | `Document`, `Block`, `Assignment`, `Section`, `ListValue`, `InlineMap`, `Absent` |\n| Schema | `SchemaDefinition`, `FieldDefinition`, `extract_schema_from_document` |\n| Repair | `RepairLog`, `RepairEntry`, `RepairTier`, `RoutingLog` |\n| Exceptions | `VocabularyError`, `CollisionError`, `VersionMismatchError`, `ParserError`, `LexerError` |\n\n资料来源：[src/octave_mcp/__init__.py:1-50]()\n\n## Tools Directory (`tools/`)\n\nStandalone utilities for OCTAVE validation and conversion.\n\n| Tool | Purpose |\n|------|---------|\n| `lint-octave.py` | Fast syntax validation for OCTAVE documents |\n| `octave-to-json.py` | Convert OCTAVE to JSON for system integration |\n| `json-to-octave.py` | Convert JSON back to OCTAVE format |\n| `octave-validator.py` | Repo validator wrapping the MCP core parser |\n\n### Lint Tool (`lint-octave.py`)\n\nValidates OCTAVE documents with checks for:\n- Document markers (`===NAME===` and `===END===`)\n- META section presence\n- Indentation (2-space multiples)\n- Assignment syntax (`KEY::VALUE`)\n- Balanced brackets\n- No trailing commas in lists\n\n**Usage:**\n```bash\npython3 lint-octave.py < document.oct.md\n# Returns: OCTAVE_VALID or OCTAVE_INVALID: \n```\n\n### Validator Tool (`octave-validator.py`)\n\nSupports validation profiles:\n- `protocol`\n- `hestai-agent`\n- `hestai-skill`\n- `hestai-pattern`\n\n**Usage:**\n```bash\noctave validate document.oct.md\noctave-validator.py --path /directory --profile hestai-agent\n```\n\n资料来源：[tools/README.md:1-50]()\n\n## Examples Directory (`examples/`)\n\nDemonstrates OCTAVE compression across different scales.\n\n### Integrations (`examples/integrations/`)\n\nIntegration examples including:\n\n| File | Purpose |\n|------|---------|\n| `repomix/octave_enhance_targeted.py` | Targeted OCTAVE annotation for specific files |\n| `repomix/octave_enhance_comprehensive.py` | Comprehensive codebase semantic coverage |\n\n### Compression Tier Examples\n\nDemonstrates OCTAVE 5.1.0 compression on research documents:\n\n| Tier | Fidelity | Tokens | Use Case |\n|------|----------|--------|----------|\n| LOSSLESS | 100% | ~14,900 | Critical decisions, legal/safety analysis |\n| CONSERVATIVE | 85-90% | ~4,800 | Research summaries, design decisions |\n| AGGRESSIVE | 70% | ~1,800 | Quick overviews |\n| ULTRA | ~60% | ~900 | High token efficiency |\n\n资料来源：[examples/README.md:1-60]()\n\n## Standards Directory (`standards/`)\n\nOfficial OCTAVE format standards defining document schemas.\n\n### L3 Agent Format (`L3-AGENT-FORMAT.oct.md`)\n\nDefines the exact L3 file format for HestAI Agents with:\n\n```mermaid\ngraph LR\n A[YAML_HEADER] --> B[+ OCTAVE_BODY]\n B --> C[===AGENT_DEFINITION===]\n \n C --> D[§0::META]\n C --> E[§1::CONSTITUTIONAL_CORE]\n C --> F[§2::COGNITIVE_FRAMEWORK]\n C --> G[§3::SHANK_OVERLAY]\n C --> H[§4::OPERATIONAL_IDENTITY]\n C --> I[§5::DOMAIN_CAPABILITIES]\n C --> J[§6::OUTPUT_CONFIGURATION]\n \n J --> K[===END===]\n```\n\nRequired YAML header fields:\n- `name`: Agent identifier\n- `description`: One-line summary\n- `allowed-tools`: Tool permissions list\n\n资料来源：[standards/L3-AGENT-FORMAT.oct.md:1-50]()\n\n## Documentation Structure (`docs/`)\n\n| Document | Content |\n|----------|---------|\n| `usage.md` | CLI, MCP, and API usage examples |\n| `api.md` | Python API reference |\n| Configuration | MCP server setup for Claude Code and Claude Desktop |\n\n### MCP Server Setup\n\n**Claude Code Configuration** (`~/.claude.json`):\n```json\n{\n \"mcpServers\": {\n \"octave\": {\n \"command\": \"octave-mcp-server\"\n }\n }\n}\n```\n\n**HTTP Transport:**\n```bash\noctave-mcp-server --transport http --port 8080\n```\n\n资料来源：[README.md:1-60]()\n\n## MCP Tools Reference\n\n| Tool | Function |\n|------|----------|\n| `octave_validate` | Validate against schema, field errors, repair suggestions |\n| `octave_write` | Write files through full validation pipeline |\n| `octave_eject` | Project to different views (canonical, executive, developer, template) |\n| `octave_compile_grammar` | Compile schema constraints to GBNF grammar |\n\n### CLI Commands\n\n```bash\noctave validate document.oct.md\noctave write output.oct.md --stdin\noctave eject document.oct.md --mode executive --format markdown\n```\n\n## Resource Loading Pattern\n\nFor programmatic access to bundled resources:\n\n```python\nfrom importlib.resources import files, as_file\n\n# Read a primer\nprimer_file = files('octave_mcp.resources.primers').joinpath('octave-compression-primer.oct.md')\nwith as_file(primer_file) as path:\n primer_content = path.read_text()\n\n# Read a spec\nspec_file = files('octave_mcp.resources.specs').joinpath('octave-core-spec.oct.md')\n```\n\nAll resources are versioned at v6.0.0 as part of the Universal Anchor release.\n\n## Summary\n\nThe octave-mcp project follows a clear separation of concerns:\n\n1. **Core parsing/validation** in `src/octave_mcp/core/` — language-agnostic processing\n2. **MCP protocol** in `src/octave_mcp/mcp/` — server implementation and tools\n3. **Resources** in `src/octave_mcp/resources/` — distributable specs, primers, and vocabularies\n4. **Utilities** in `tools/` — standalone CLI tools for CI/CD integration\n5. **Examples** in `examples/` — integration demonstrations\n6. **Standards** in `standards/` — official format definitions\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#page-mcp-tools), [CLI Interface](#page-cli-interface)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/core/parser.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/parser.py)\n- [src/octave_mcp/core/grammar_compiler/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/__init__.py)\n- [src/octave_mcp/mcp/grammar_resources.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/grammar_resources.py)\n- [src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)\n- [src/octave_mcp/resources/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/README.md)\n
\n\n# System Architecture\n\n## Overview\n\nOCTAVE-MCP (Olympian Common Text And Vocabulary Engine - Model Context Protocol) is a semantic DSL implementation designed for structured document processing, validation, and LLM integration. The architecture follows a layered approach combining MCP protocol support, grammar-based validation, and integration adapters for various inference backends.\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n CLI[CLI Tools]\n MCP[Claude Desktop / HTTP]\n end\n\n subgraph \"MCP Protocol Layer\"\n Server[MCP Server]\n GrammarResources[Grammar Resources]\n WriteTool[Write Tool]\n ValidateTool[Validate Tool]\n EjectTool[Eject Tool]\n end\n\n subgraph \"Core Processing Layer\"\n Parser[Parser]\n GrammarCompiler[Grammar Compiler]\n Validator[Validator]\n end\n\n subgraph \"Integration Layer\"\n LLM[LLM Integrations]\n end\n\n subgraph \"Resource Layer\"\n Specs[Specifications]\n Primers[Primers]\n Skills[Skills]\n end\n\n CLI --> Server\n MCP --> Server\n Server --> GrammarResources\n Server --> WriteTool\n Server --> ValidateTool\n Server --> EjectTool\n GrammarResources --> GrammarCompiler\n WriteTool --> Parser\n WriteTool --> Validator\n EjectTool --> Parser\n GrammarCompiler --> Specs\n Parser --> Validator\n Specs --> LLM\n```\n\n## MCP Server Architecture\n\n### Server Initialization\n\nThe MCP server (`octave-mcp-server`) provides the primary interface for OCTAVE document operations. It initializes with configuration options supporting both Claude Desktop and HTTP transport modes.\n\n**Configuration Methods:**\n\n| Method | Configuration Location | Example |\n|--------|----------------------|---------|\n| Claude Desktop | `~/.claude.json` | `mcpServers.octave.command` |\n| Claude Code | `.claude.json` | Same structure |\n| HTTP | CLI flags | `--transport http --port 8080` |\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n### Transport Architecture\n\nThe server supports multiple transport mechanisms for flexibility in deployment scenarios:\n\n1. **Standard I/O**: Default mode for CLI and Claude Desktop integration\n2. **HTTP Transport**: Scalable deployment option with port configuration\n\n```mermaid\ngraph LR\n A[Claude Desktop] -->|stdio| B[octave-mcp-server]\n C[HTTP Client] -->|HTTP| D[--transport http]\n B --> E[Core Parser]\n D --> E\n```\n\n## Core Processing Components\n\n### Parser Module\n\nThe parser (`src/octave_mcp/core/parser.py`) handles OCTAVE document parsing with support for:\n\n- **Document Envelope Detection**: Identifies `===NAME===` markers for document boundaries\n- **META Block Parsing**: Extracts metadata including TYPE, VERSION, and custom fields\n- **Grammar Sentinel Support**: Recognizes `OCTAVE::VERSION` patterns for grammar versioning\n- **Byte Offset Tracking**: Records `start_byte` and `end_byte` positions for each document region\n\n**Parser Features:**\n\n| Feature | Description | Implementation |\n|---------|-------------|----------------|\n| Envelope Detection | Required document markers | `ENVELOPE_START` token type |\n| META Region | Structured metadata section | `meta_start_byte` / `meta_end_byte` tracking |\n| Grammar Sentinel | Version identification | `GRAMMAR_SENTINEL` token |\n| Inferred Envelope | Single-document support | Default name: \"INFERRED\" |\n\n资料来源：[src/octave_mcp/core/parser.py:50-80](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/parser.py)\n\n### Grammar Compiler\n\nThe grammar compiler (`src/octave_mcp/core/grammar_compiler/__init__.py`) generates GBNF (Greibach Normal Form) grammars for constrained generation and validation.\n\n**Public API:**\n\n```python\nfrom octave_mcp.core.grammar_compiler import (\n compile_document_grammar,\n emit_grammar_for_schema,\n)\n```\n\n**Compilation Features:**\n\n| Function | Purpose |\n|----------|---------|\n| `compile_document_grammar` | Main entry point for grammar generation |\n| `emit_grammar_for_schema` | Schema-specific grammar emission |\n\n资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/__init__.py)\n\n### Grammar Resources\n\nThe grammar resources module (`src/octave_mcp/mcp/grammar_resources.py`) provides MCP resources for dynamic grammar access:\n\n- **Resource Templates**: Dynamic grammar retrieval via `octave://grammars/{schema_name}`\n- **Caching**: In-memory cache for compiled grammars\n- **Schema Resolution**: Loads schemas from builtin registry or search paths\n\n**Resource URI Pattern:**\n```\noctave://grammars/{schema_name}\n```\n\n资料来源：[src/octave_mcp/mcp/grammar_resources.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/grammar_resources.py)\n\n## MCP Tools\n\n### Validate Tool\n\nPerforms schema-based validation with detailed error reporting:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| document | string | OCTAVE content to validate |\n| schema | string | Schema name for validation |\n| profile | string | Validation profile (protocol, hestai-agent, etc.) |\n\n### Write Tool\n\nThe write tool (`src/octave_mcp/mcp/write.py`) provides file writing with full validation pipeline:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| target_path | string | File path to write |\n| content | string | Full content for new files |\n| changes | dict | Field updates for existing files |\n| schema | string | Optional schema name |\n| format_style | string | Output mode: preserve, expanded, compact |\n\n**Format Style Modes:**\n\n| Mode | Behavior | Deprecation Note |\n|------|----------|-------------------|\n| `preserve` | Span-aware preserve mode | Recommended for future |\n| `expanded` | Full canonical re-emit | Explicit opt-in for legacy behavior |\n| `compact` | Minimal output | Default in v1.14.0+ |\n\n资料来源：[src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)\n\n### Eject Tool\n\nProjects documents to different views for various audiences:\n\n- **canonical**: Full document structure\n- **executive**: Summary view for decision-makers\n- **developer**: Implementation-focused perspective\n- **template**: Blank template for new documents\n\n## Resource Organization\n\n```mermaid\ngraph TD\n subgraph \"Resources\"\n subgraph \"Specs\"\n Core[octave-core-spec.oct.md]\n Agents[octave-agents-spec.oct.md]\n Skills[octave-skills-spec.oct.md]\n Data[octave-data-spec.oct.md]\n Schema[octave-schema-spec.oct.md]\n end\n\n subgraph \"Primers\"\n Mastery[octave-mastery-primer]\n Compression[octave-compression-primer]\n Ultra[octave-ultra-mythic-primer]\n end\n\n subgraph \"Skills\"\n CompressionSkill[octave-compression]\n end\n end\n```\n\n### Specifications Structure\n\n| Category | Purpose | Version |\n|----------|---------|---------|\n| Core Spec | Syntax, operators, type system | v6.0.0 |\n| Agents Spec | Agent architecture patterns | v6.0.0 |\n| Skills Spec | Skill document format | v6.0.0 |\n| Data Spec | Compression tiers and patterns | v6.0.0 |\n| Schema Spec | Validation framework | v6.0.0 |\n\n资料来源：[src/octave_mcp/resources/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/README.md)\n\n## Validation Profiles\n\nThe system supports multiple validation profiles for different use cases:\n\n| Profile | YAML Frontmatter | Default Behavior |\n|---------|------------------|------------------|\n| `protocol` | Optional | Warning on missing |\n| `hestai-agent` | Required | Hard fail if missing |\n| `hestai-skill` | Required | Hard fail if missing |\n| `hestai-pattern` | Optional | Warning on missing |\n\n**Profile Configuration:**\n```bash\noctave validate document.oct.md --profile hestai-agent --require-frontmatter\n```\n\n资料来源：[tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)\n\n## Document Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Server\n participant Validator\n participant Parser\n participant GrammarCompiler\n\n Client->>Server: octave_write(document)\n Server->>Parser: parse_document(content)\n Parser->>Validator: validate(parsed_doc, schema)\n Validator->>GrammarCompiler: compile_grammar(schema)\n GrammarCompiler-->>Validator: GBNF grammar\n Validator-->>Server: validation_result\n Server-->>Client: write_response\n\n Note over Client,GrammarCompiler: Round-trip: OCTAVE → JSON → OCTAVE\n```\n\n## Integration Points\n\n### CLI Integration\n\n```bash\n# Validate a document\noctave validate document.oct.md\n\n# Write with validation\noctave write output.oct.md --stdin\n\n# Eject to different view\noctave eject document.oct.md --mode executive --format markdown\n```\n\n### MCP Tool Integration\n\n| Tool | Function |\n|------|----------|\n| `octave_validate` | Validate against schema with repair suggestions |\n| `octave_write` | Write files through full validation pipeline |\n| `octave_eject` | Project to different views |\n| `octave_compile_grammar` | Compile schema to GBNF |\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n## Architectural Principles\n\n1. **Separation of Concerns**: MCP protocol layer is isolated from core processing\n2. **Profile-Based Validation**: Different profiles support various document types\n3. **Grammar-Driven Validation**: GBNF grammars ensure structured output\n4. **Round-Trip Fidelity**: OCTAVE ↔ JSON conversion preserves document semantics\n5. **Extensible Resources**: Primers and skills provide domain-specific guidance\n\n## File Organization\n\n```\nsrc/octave_mcp/\n├── core/\n│ ├── parser.py # Document parsing\n│ └── grammar_compiler/ # GBNF generation\n├── mcp/\n│ ├── server.py # MCP server\n│ ├── http_transport.py # HTTP transport\n│ ├── grammar_resources.py # Dynamic grammars\n│ └── write.py # Write tool\n├── integrations/ # LLM backend adapters\n└── resources/\n ├── specs/ # OCTAVE specifications\n ├── primers/ # Learning primers\n └── skills/ # Skill definitions\n\n---\n\n\n\n## Canonical Normalization\n\n### 相关页面\n\n相关主题：[Schema Validation](#page-schema-validation), [Compression System](#page-compression-system)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/core/lexer.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/lexer.py)\n- [src/octave_mcp/core/parser.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/parser.py)\n- [src/octave_mcp/core/emitter.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/emitter.py)\n- [src/octave_mcp/core/grammar/tier_normalize.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar/tier_normalize.py)\n- [src/octave_mcp/core/grammar/cst.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar/cst.py)\n
\n\n# Canonical Normalization\n\nCanonical Normalization is the process by which OCTAVE documents are validated, transformed, and written in a standardized format. It ensures consistency across documents by enforcing syntax rules, resolving dialect variations, and producing output that conforms to the OCTAVE specification. The normalization pipeline is a core component of the write workflow, operating between parsing and emission.\n\n## Overview\n\nOCTAVE (Olympian Common Text And Vocabulary Engine) is a semantic DSL designed for LLMs. When documents pass through the system—either during editing, compression, or cross-agent transfer—syntax variations can accumulate. Canonical Normalization addresses this by providing a deterministic transformation that produces a consistent \"canonical\" form.\n\nThe normalization system is governed by ADR-0006 (Writer/Reader Symmetry Programme), which defines a phased rollout of behavior changes across multiple milestones.\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Input OCTAVE] --> B[Lexer]\n B --> C[Parser]\n C --> D[Concrete Syntax Tree CST]\n D --> E[Tier Normalization]\n E --> F[Semantic Validation]\n F --> G[Emitter]\n G --> H[Canonical Output]\n \n E --> E1[warnings list]\n F --> F1[Field Errors]\n F --> F2[Repair Suggestions]\n \n style E fill:#f9f,stroke:#333\n style H fill:#9f9,stroke:#333\n```\n\n## Phases of Normalization\n\n### Phase 1: Lexical Analysis\n\nThe lexer (`src/octave_mcp/core/lexer.py`) performs initial tokenization, handling:\n\n- Standard identifiers and operators\n- Angle bracket annotations (`NAME`)\n- Comma-separated qualifier lists\n\n**Qualifier List Support (GH#320)**\n\nThe lexer supports comma-separated qualifier lists in angle bracket annotations:\n\n```\nNEVER[PEDANTIC,DISMISSIVE,VAGUE]\n```\n\nThis is parsed by consuming valid identifier characters, then checking for commas followed by subsequent segments. 资料来源：[src/octave_mcp/core/lexer.py:lexer-impl]()()\n\n### Phase 2: Parsing\n\nThe parser (`src/octave_mcp/core/parser.py`) builds a Concrete Syntax Tree (CST) from token streams. Key features include:\n\n| Feature | Description |\n|---------|-------------|\n| `start_byte` / `end_byte` | Byte offsets for document and META region (ADR-0006 SR2-T2) |\n| Grammar Sentinel | Parses `OCTAVE::VERSION` pattern |\n| Envelope Detection | Handles explicit `===NAME===` and inferred envelopes |\n\n资料来源：[src/octave_mcp/core/parser.py:parse_document-90-115]()(ADR-0006 SR2-T2)\n\n### Phase 3: Tier Normalization\n\nThe tier normalization module (`src/octave_mcp/core/grammar/tier_normalize.py`) applies compression-tier-specific transformations:\n\n| Tier | Target Fidelity | Preserved | Dropped |\n|------|------------------|-----------|---------|\n| LOSSLESS | 100% | Everything | Nothing |\n| CONSERVATIVE | 85-90% | Explanatory depth | Redundancy |\n| AGGRESSIVE | 70% | Core thesis | Edge cases |\n| ULTRA | Minimal | Key semantics | Most detail |\n\n资料来源：[src/octave_mcp/core/grammar/tier_normalize.py]()()\n\n### Phase 4: CST Representation\n\nThe CST module (`src/octave_mcp/core/grammar/cst.py`) provides the intermediate representation:\n\n```mermaid\nclassDiagram\n class Document {\n +str name\n +int start_byte\n +int end_byte\n +str grammar_version\n +MetaBlock? meta\n +list~Section~ sections\n }\n class MetaBlock {\n +int meta_start_byte\n +int meta_end_byte\n +dict fields\n }\n class Section {\n +str identifier\n +str content\n +list annotations\n }\n \n Document *-- MetaBlock\n Document *-- Section\n```\n\n资料来源：[src/octave_mcp/core/grammar/cst.py]()()\n\n### Phase 5: Emission\n\nThe emitter (`src/octave_mcp/core/emitter.py`) writes the canonical form:\n\n```python\nwarnings = []\ncanonical = emitter.emit(cst, normalize=True)\n# warnings contains list of normalization changes applied\n```\n\n资料来源：[src/octave_mcp/core/emitter.py]()()\n\n## Behavior Timeline\n\nPer ADR-0006, normalization behavior evolves across milestones:\n\n```mermaid\ngraph LR\n T1[TODAY
SR1] --> T2[AFTER_SR1_T4
SR1 Milestone] --> T3[AFTER_SR3_T2
SR3 Milestone]\n \n T1:::today\n T2:::milestone1\n T3:::milestone3\n \n classDef today fill:#ff6b6b,color:#fff\n classDef milestone1 fill:#feca57,color:#000\n classDef milestone3 fill:#48dbfb,color:#000\n \n T1 -->|\"normalize on write\"| T1a[\"warnings: []
source was already canonical\"]\n T2 -->|\"NO-OP normalization
warnings enumerate what
WOULD have changed\"| T2a[\"warnings: []
no normalization attempted
≠ canonicality guarantee\"]\n T3 -->|\"octave_fmt for canonicalization
octave_write for persistence\"| T3a[\"Separate concerns
Two distinct calls\"]\n```\n\n### Timeline Details\n\n| Phase | Behavior | `warnings: []` Meaning |\n|-------|----------|------------------------|\n| **TODAY** | `octave_write` normalizes on every write | Source was already canonical |\n| **AFTER_SR1_T4** | Default becomes NO-OP normalization | No normalization attempted (not a canonicality guarantee) |\n| **AFTER_SR3_T2** | Canonicalization moves to `octave_fmt` tool | Separate persist vs canonicalize calls |\n\n资料来源：[src/octave_mcp/resources/skills/octave-literacy/SKILL.md:§6a::TIMELINE]()(ADR-0006)\n\n## Normalization Rules\n\n### Syntax Normalization\n\n| Rule | Before | After |\n|------|--------|-------|\n| Indentation | Mixed (1, 3, 4 spaces) | 2-space multiples |\n| Assignment spacing | `KEY:: VALUE` | `KEY::VALUE` |\n| List formatting | Trailing commas allowed | Trailing commas forbidden |\n| Bracket balance | All brackets must balance | Enforced at parse time |\n\n### Semantic Normalization\n\n- **Operator resolution**: Alias operators mapped to canonical forms (`⇌` vs `<->`)\n- **Quoted strings**: Preserved verbatim with original quotes\n- **Blank lines**: Tracked for round-trip fidelity\n\n### META Sanity Checks\n\nMinimal validation of META section:\n\n| Field | Required | Validation |\n|-------|----------|------------|\n| TYPE | Yes | Must be valid document type |\n| VERSION | Yes | Semantic version format |\n\n## MCP Tool Integration\n\nThe normalization system integrates with MCP tools:\n\n| Tool | Mode | Behavior |\n|------|------|----------|\n| `octave_write` | normalize | Dry-run, returns warnings |\n| `octave_write` | persist | Apply normalization, return warnings |\n| `octave_validate` | — | Validate against schema, provide repair suggestions |\n| `octave_eject` | — | Project to different views (canonical, executive, developer) |\n\n资料来源：[README.md:MCP Tools]()()\n\n## CLI Usage\n\n```bash\n# Validate document (implicit normalization check)\noctave validate document.oct.md\n\n# Write with dry-run normalization\noctave write output.oct.md --mode normalize\n\n# Canonical format ejection\noctave eject document.oct.md --mode canonical --format markdown\n```\n\n## Round-Trip Fidelity\n\nThe normalization system guarantees round-trip fidelity:\n\n```mermaid\ngraph LR\n A[OCTAVE] -->|octave-to-json| B[JSON]\n B -->|json-to-octave| C[OCTAVE']\n A -->|diff| C\n \n C -->|identical| A\n```\n\nWhen a document passes through JSON serialization and back:\n\n```bash\npython3 octave-to-json.py input.oct.md | python3 json-to-octave.py > output.oct.md\ndiff input.oct.md output.oct.md # Should produce no differences\n```\n\nPreserved elements during round-trip:\n- Blank lines\n- Quoted strings\n- Semantic operators (`⊕`, `⇌`, `§`)\n- Section identifiers\n\n资料来源：[tools/README.md:Round-Trip Example]()()\n\n## Error Handling\n\nNormalization produces structured warnings:\n\n```json\n{\n \"warnings\": [\n \"Indentation normalized: 4 spaces → 2 spaces\",\n \"Trailing comma removed in list [a, b, c,]\",\n \"Operator alias <-> → ⇌\"\n ]\n}\n```\n\nEmpty `warnings` array indicates no normalization changes were needed.\n\n## See Also\n\n- [ADR-0006: Writer/Reader Symmetry Programme](docs/adr/ADR-0006-writer-reader-symmetry.md)\n- [OCTAVE Data Specification](src/octave_mcp/resources/specs/octave-data-spec.oct.md)\n- [Usage Guide](docs/usage.md)\n- [API Reference](docs/api.md)\n\n---\n\n\n\n## Schema Validation\n\n### 相关页面\n\n相关主题：[Canonical Normalization](#page-canonical-normalization), [MCP Tools Reference](#page-mcp-tools)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/core/validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/validator.py)\n- [src/octave_mcp/core/schema_extractor.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/schema_extractor.py)\n- [tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)\n- [src/octave_mcp/resources/primers/octave-mastery-primer.oct.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/primers/octave-mastery-primer.oct.md)\n- [src/octave_mcp/mcp/validate.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/validate.py)\n- [src/octave_mcp/resources/skills/octave-compression/SKILL.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/skills/octave-compression/SKILL.md)\n
\n\n# Schema Validation\n\n## Overview\n\nSchema Validation in OCTAVE-MCP is the core mechanism that ensures OCTAVE documents conform to defined structural rules, type constraints, and semantic policies. The validation system operates on parsed AST (Abstract Syntax Tree) representations of documents, providing comprehensive error reporting with field-level precision.\n\nThe validation framework is designed to:\n- Validate documents against predefined schema definitions\n- Enforce required fields and type constraints\n- Support enum validation with prefix matching and ambiguity detection\n- Detect unknown fields based on policy settings\n- Evaluate constraint chains for complex validation logic\n- Support target routing with audit trails for policy enforcement\n\n资料来源：[src/octave_mcp/core/validator.py:1-30]()\n\n## Architecture\n\nThe validation system follows a layered architecture with clear separation of concerns:\n\n```mermaid\ngraph TD\n A[OCTAVE Document] --> B[Parser]\n B --> C[Document AST]\n C --> D[Validator]\n D --> E{Schema Definition}\n E -->|Built-in| F[META, SKILL, AGENT]\n E -->|Custom| G[User Schemas]\n D --> H[Validation Errors]\n H --> I[Repair Suggestions]\n \n J[Schema Loader] --> E\n K[Schema Extractor] --> E\n```\n\n### Core Components\n\n| Component | Location | Purpose |\n|-----------|----------|---------|\n| `Validator` | `core/validator.py` | Main validation surface - structural visitor pattern |\n| `SchemaDefinition` | `core/schema.py` | Schema data model |\n| `FieldDefinition` | `core/schema.py` | Field constraint definitions |\n| `SchemaExtractor` | `core/schema_extractor.py` | Extract schemas from OCTAVE documents |\n| `SchemaLoader` | `schemas/loader.py` | Load built-in and custom schemas |\n\n资料来源：[src/octave_mcp/core/validator.py:50-100]()\n\n## The Validator Class\n\nThe `Validator` class is the primary entry point for schema validation, implementing the visitor pattern for AST traversal:\n\n```python\nfrom octave_mcp import Validator\n\nvalidator = Validator(schema=schema_def)\nerrors = validator.validate(doc, strict=False)\n```\n\n### Validation Flow\n\n```mermaid\ngraph LR\n A[validate doc] --> B[_prepare_document_validation]\n B --> C[_validate_sections_recursive]\n C --> D{nested blocks?}\n D -->|yes| C\n D -->|no| E[section_schemas defined?]\n E -->|yes| F[validate_frontmatter]\n E -->|no| G[return errors]\n F --> G\n```\n\n### Key Validation Features\n\n1. **Required Field Checking** - Ensures mandatory fields are present\n2. **Type Validation** - Validates field values against defined types\n3. **Enum Validation** - Supports prefix matching and ambiguity detection\n4. **Regex Pattern Validation** - Validates string formats against regex\n5. **Unknown Field Detection** - Policy-driven detection of unexpected fields\n6. **Constraint Chain Evaluation** - Processes complex validation rules\n7. **Target Routing** - Validates routing targets with audit trail\n\n资料来源：[src/octave_mcp/core/validator.py:100-150]()\n\n## Schema Definition\n\nSchemas define the structure and constraints for OCTAVE documents. They consist of:\n\n### Schema Structure\n\n| Section | Purpose |\n|---------|---------|\n| `POLICY` | Version, UNKNOWN_FIELDS handling, default targets |\n| `FIELDS` | Field definitions with constraints |\n| `FRONTMATTER` | YAML frontmatter field definitions |\n\n### Policy Settings\n\nThe `POLICY` block controls validation behavior:\n\n```octave\nPOLICY:\n VERSION::\"1.0\"\n UNKNOWN_FIELDS::REJECT # REJECT, WARN, or ALLOW\n```\n\n**UNKNOWN_FIELDS Policy Options:**\n- `REJECT` - Validation fails on unknown fields\n- `WARN` - Unknown fields are reported but don't fail validation\n- `ALLOW` - Unknown fields are ignored\n\n资料来源：[src/octave_mcp/core/schema_extractor.py:50-80]()\n\n## Schema Extraction\n\nThe `extract_schema_from_document()` function parses OCTAVE documents and builds `SchemaDefinition` objects:\n\n```python\nfrom octave_mcp.core.schema_extractor import extract_schema_from_document\n\nschema = extract_schema_from_document(doc)\n# Returns SchemaDefinition with:\n# - name from document envelope\n# - version from META block\n# - policy settings\n# - field definitions\n# - frontmatter definitions\n```\n\n### Extraction Process\n\n```mermaid\ngraph TD\n A[parse OCTAVE document] --> B[extract name from envelope]\n B --> C[extract VERSION from META]\n C --> D[_extract_policy]\n D --> E[extract FIELDS block]\n E --> F[extract FRONTMATTER block]\n F --> G[build SchemaDefinition]\n G --> H[return with warnings]\n```\n\n资料来源：[src/octave_mcp/core/schema_extractor.py:80-150]()\n\n## Validation Profiles\n\nThe CLI tool supports multiple validation profiles for different document types:\n\n| Profile | YAML Frontmatter | META.TYPE Requirement |\n|---------|------------------|----------------------|\n| `protocol` | Forbidden | Any |\n| `hestai-agent` | Recommended (warning) | `AGENT_DEFINITION` |\n| `hestai-skill` | Recommended (warning) | `SKILL` |\n| `hestai-pattern` | Forbidden | `PATTERN` |\n\n### CLI Usage\n\n```bash\n# Validate single file\npython tools/octave-validator.py document.oct.md\n\n# Validate with specific schema\npython tools/octave-validator.py document.oct.md --schema META\n\n# Directory scan\npython tools/octave-validator.py --path .hestai-sys/library/ --profile hestai-agent\n\n# Require frontmatter (fail on missing)\npython tools/octave-validator.py document.oct.md --require-frontmatter\n```\n\n资料来源：[tools/octave-validator.py:1-50]()\n\n## MCP Tool Integration\n\nThe `octave_validate` MCP tool provides programmatic validation access:\n\n### Tool Interface\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `content` | string | OCTAVE document content |\n| `schema` | string | Schema name to validate against (optional) |\n| `strict` | boolean | Enable strict validation mode |\n\n### Return Structure\n\n```json\n{\n \"valid\": true,\n \"validation_status\": \"VALIDATED\",\n \"validation_errors\": []\n}\n```\n\nOn validation failure:\n```json\n{\n \"valid\": false,\n \"validation_status\": \"INVALID\",\n \"validation_errors\": [\n {\"code\": \"E_REQUIRED_FIELD\", \"message\": \"...\", \"field\": \"META.VERSION\"}\n ],\n \"grammar_hint\": {\"format\": \"gbnf\", \"grammar\": \"...\"}\n}\n```\n\n资料来源：[src/octave_mcp/mcp/validate.py:1-50]()\n\n## Error Codes\n\n| Code | Description |\n|------|-------------|\n| `E_REQUIRED_FIELD` | Mandatory field is missing |\n| `E_TYPE_MISMATCH` | Field value type doesn't match schema |\n| `E_ENUM_INVALID` | Value not in allowed enum values |\n| `E_REGEX_MISMATCH` | String doesn't match pattern |\n| `E_UNKNOWN_FIELD` | Field not defined in schema (when UNKNOWN_FIELDS=REJECT) |\n| `E_CONSTRAINT_VIOLATION` | Constraint chain evaluation failed |\n| `E_FRONTEMATTER_INVALID` | YAML frontmatter validation failed |\n| `E_AST_CYCLE` | Cyclic structure detected |\n\n## Validation Workflow\n\n```mermaid\ngraph TD\n A[Input OCTAVE] --> B[Parse Document]\n B --> C{Parse Success?}\n C -->|No| D[Parser Error]\n C -->|Yes| E[Load Schema]\n E --> F{Schema Found?}\n F -->|No| G[UNVALIDATED]\n F -->|Yes| H[Create Validator]\n H --> I[Run Validation]\n I --> J{Validation Errors?}\n J -->|Yes| K[Report INVALID]\n J -->|No| L[Report VALIDATED]\n \n K --> M[Generate Error Details]\n M --> N[Optional: Grammar Hint]\n L --> O[Optional: Validation Success]\n```\n\n## Best Practices\n\n1. **Always specify schema** - Provides precise error messages and repair suggestions\n2. **Use strict mode for CI/CD** - Catches all violations early\n3. **Leverage profile validation** - Ensures documents match their intended type\n4. **Handle validation errors gracefully** - Provide meaningful feedback to users\n5. **Use grammar hints for generation** - Guide LLM output toward valid structures\n\n资料来源：[src/octave_mcp/core/validator.py:150-200]()\n\n## Related Documentation\n\n- [Usage Guide](docs/usage.md) - CLI, MCP, and API examples\n- [API Reference](docs/api.md) - Python API documentation\n- [Schema Specification](../resources/specs/octave-schema-spec.oct.md) - Schema format specification\n\n---\n\n\n\n## Compression System\n\n### 相关页面\n\n相关主题：[Canonical Normalization](#page-canonical-normalization)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/core/holographic.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/holographic.py)\n- [src/octave_mcp/core/sealer.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/sealer.py)\n- [src/octave_mcp/core/repair.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/repair.py)\n- [src/octave_mcp/resources/skills/octave-compression/SKILL.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/skills/octave-compression/SKILL.md)\n- [src/octave_mcp/resources/skills/octave-mythology/SKILL.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/skills/octave-mythology/SKILL.md)\n- [examples/compression-comparisons/octave-vs-llmlingua-compression-comparison-2026.md](https://github.com/elevanaltd/octave-mcp/blob/main/examples/compression-comparisons/octave-vs-llmlingua-compression-comparison-2026.md)\n
\n\n# Compression System\n\nThe OCTAVE Compression System is a semantic compression framework that transforms prose into structured OCTAVE (Olympian Common Text And Vocabulary Engine) documents. Unlike traditional text compression that destroys structural relationships, OCTAVE compression preserves semantic invariants while achieving significant token reduction, making documents both machine-executable and LLM-legible.\n\n## Overview\n\nOCTAVE compression serves as the bridge between natural language prose and semantic DSL (Domain-Specific Language) representations. The system operates on a tiered fidelity model where operators specify exactly what is preserved and what is lost at each compression level.\n\nThe core principle is **mythological semantic compression** — leveraging pre-trained mythological vocabulary as functional semantic binding for LLM audiences. This approach achieves 60-70% token reduction while maintaining 88-96% cross-model zero-shot comprehension.\n\n资料来源：[src/octave_mcp/resources/skills/octave-mythology/SKILL.md:1-15]()\n\n## Compression Tiers\n\nOCTAVE defines four standardized compression tiers, each with explicit loss profiles:\n\n| Tier | Target Fidelity | Preserved | Dropped | Use Cases |\n|------|-----------------|-----------|---------|-----------|\n| **LOSSLESS** | 100% | Everything | Nothing | Critical reasoning, legal documents, safety analysis, audit trails |\n| **CONSERVATIVE** | 85-90% | Explanatory depth, tradeoff reasoning | Redundancy, verbose transitions | Research summaries, design decisions, technical analysis |\n| **AGGRESSIVE** | 70% | Core thesis, landscape | Explanatory depth, execution narratives | Overview documents, quick references |\n| **ULTRA** | 50-60% | Semantic invariants | All narrative prose | High-density summaries, token-constrained contexts |\n\n资料来源：[src/octave_mcp/resources/skills/octave-compression/SKILL.md:15-30]()\n\n### Tier Selection Flow\n\n```mermaid\ngraph TD\n A[Start: Source Document] --> B{Document Type?}\n B -->|Critical/Legal| C[LOSSLESS]\n B -->|Research/Design| D{Critical Details?}\n B -->|Overview/Summary| E[AGGRESSIVE]\n B -->|Token-Constrained| F[ULTRA]\n D -->|Yes| G[CONSERVATIVE]\n D -->|No| E\n C --> H[0% Loss]\n G --> I[10-15% Loss]\n E --> J[~30% Loss]\n F --> K[40-50% Loss]\n```\n\n## Core Architecture\n\n### Holographic Patterns\n\nThe foundational unit of OCTAVE compression is the **HolographicPattern**, which encodes constraints and validation rules alongside semantic content. Each field in a compressed document carries its own holographic metadata.\n\n```python\nclass HolographicPattern:\n example: Optional[str] # Concrete example value\n constraints: List[str] # Validation constraints\n target: Optional[str] # Routing/execution target\n```\n\n资料来源：[src/octave_mcp/core/holographic.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/holographic.py)\n\n### Literal Zone Audit\n\nThe `LiteralZoneAudit` system tracks zones that should be preserved verbatim during compression. These zones represent semantic invariants that must survive any transformation:\n\n- Schema definitions\n- Contract specifications\n- Routing declarations\n- Required structural elements\n\n```mermaid\ngraph LR\n A[Input Document] --> B[Zone Scanner]\n B --> C{Literal Zone?}\n C -->|Yes| D[Seal for Preservation]\n C -->|No| E[Compressible Zone]\n D --> F[Output: SEALED content]\n E --> G[Compression Engine]\n G --> H[Output: Compressed content]\n```\n\n资料来源：[src/octave_mcp/core/sealer.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/sealer.py)\n\n## Semantic Operators\n\nOCTAVE compression uses specialized operators that maintain semantic relationships during transformation:\n\n| Operator | Symbol | Meaning | Example |\n|----------|--------|---------|---------|\n| Synthesis | `⊕` | Combining elements | `teaches_format ⊕ validates_rules ⊕ routes_data` |\n| Tension | `⇌` | Tradeoff/balance | `downtime ⇌ parallel_work` |\n| Flow | `→` | Routing/execution | `REQ → INDEXER` |\n| Constraint | `∧` | Required conjunction | `valid ∧ processed` |\n| Disjunction | `∨` | Optional alternatives | `CREATE ∨ UPDATE ∨ DELETE` |\n| Definition | `::` | Maps to/assignment | `PURPOSE::\"Master OCTAVE\"` |\n\n资料来源：[src/octave_mcp/resources/primers/octave-mastery-primer.oct.md:15-25]()\n\n## Mythological Compression\n\nThe Mythological Compression Principle treats mythology as OCTAVE's native compression dialect. Mythological domains provide pre-trained semantic binding that activates rich probability distributions in LLMs.\n\n### Domain Categories\n\n| Domain | Mythological Name | Semantic Load | Example |\n|--------|------------------|---------------|---------|\n| Eternal Tasks | SISYPHEAN | Futile repetition | `SISYPHEAN::loop_detected` |\n| Precision Targeting | ARTEMIS | Focused accuracy | `ARTEMIS::targeted_optimization` |\n| Time Pressure | CHRONOS | Temporal constraints | `CHRONOS::q4_deadline` |\n| Resource Limits | DEMETER | Budget/budget exhaustion | `DEMETER::60%_burned` |\n| Forbidden Knowledge | PROMETHEAN | Risk of revelation | `PROMETHEAN::sensitive_exposure` |\n\n资料来源：[src/octave_mcp/resources/skills/octave-mythology/SKILL.md:30-50]()\n\n### How Mythological Compression Works\n\nMythology terms function as **semantic zip files** — compressed meaning already present in model weights. No training required:\n\n1. LLM recognizes domain term (e.g., `ODYSSEAN`)\n2. Automatically loads psychological/operational context (grueling long-term journey)\n3. Maintains distinct categorical boundaries (CHRONOS vs DEMETER)\n4. Preserves causal graph (the \"Why\") rather than just the \"What\"\n\n资料来源：[examples/compression-comparisons/octave-vs-llmlingua-compression-comparison-2026.md:50-70]()\n\n## Repair and Validation\n\nThe repair subsystem (`repair.py`) provides schema validation with specific field errors and repair suggestions. Every transformation passes through the validation pipeline:\n\n```mermaid\ngraph TD\n A[Compressed OCTAVE] --> B[Schema Validator]\n B --> C{Valid?}\n C -->|Yes| D[Schema Valid]\n C -->|No| E[Repair Engine]\n E --> F[Field Errors]\n E --> G[Repair Suggestions]\n F --> H[Repair Receipt]\n G --> H\n H --> I[Normalized Output]\n```\n\n资料来源：[src/octave_mcp/core/repair.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/repair.py)\n\n### Validation Checks\n\nDocuments compressed with OCTAVE must pass these checks:\n\n| Check | Requirement | Purpose |\n|-------|-------------|---------|\n| `valid_OCTAVE` | Valid syntax | Grammar compliance |\n| `preserve_§_names_verbatim` | Section names unchanged | Structural integrity |\n| `patterns_applied` | Semantic operators used correctly | Semantic preservation |\n| `archetypes_used` | Valid archetype selection | Compression fidelity |\n| `holographic_valid` | Field-level holograms intact | Constraint preservation |\n\n资料来源：[src/octave_mcp/resources/primers/octave-mastery-primer.oct.md:30-35]()\n\n## Workflow: Prose to OCTAVE\n\n```mermaid\ngraph TD\n A[Prose Document] --> B[Tier Selection]\n B --> C[Phase 1: Field Extraction]\n C --> D[Identify semantic atoms]\n D --> E[Phase 2: Mythology Mapping]\n E --> F[Map to mythological domains]\n F --> G[Phase 3: Operator Application]\n G --> H[Apply synthesis/tension/flow]\n H --> I[Phase 4: Loss Accounting]\n I --> J[Document LOSS_PROFILE]\n J --> K[OCTAVE Document]\n K --> L[Validation]\n L --> M{Valid?}\n M -->|No| N[Repair & Retry]\n N --> C\n M -->|Yes| O[Output with receipt]\n```\n\n## Compression Example\n\n### Original Prose (5600 tokens)\n> \"The quarterly budget analysis shows significant resource constraints. Downtime from the migration creates tension with the need for parallel work on the new system. Specifically targeted optimization efforts have burned through 60% of the quarterly allocation for this migration alone.\"\n\n### CONSERVATIVE Compression (4800 tokens)\n```octave\nCONFLICT::downtime ⇌ parallel_work\n→ MIGRATION[Q4_window]\nSISYPHEAN::eternal_repetition[this_migration_alone]\nARTEMIS::specifically_targeted_optimization\nDEMETER::60%_quarterly_burned[this_migration_alone]\n```\n\n### AGGRESSIVE Compression (1800 tokens)\n```octave\nMIGRATION::SISYPHEAN[Q4] ⊕ CHRONOS[deadline]\n→ DEMETER::60%_quarterly_burned\n```\n\n## Loss Profiles\n\nEvery compressed document declares its `LOSS_PROFILE`, enabling auditable transformation:\n\n```octave\nMETA:\n COMPRESSION_TIER::CONSERVATIVE\n LOSS_PROFILE::redundancy ⊕ verbose_transitions\n NARRATIVE_DEPTH::maintained[tradeoff_reasoning_inline,execution_strategies_explained]\n```\n\n| Tier | Loss Profile | Narrative Impact |\n|------|--------------|------------------|\n| LOSSLESS | `none` | Fully preserved |\n| CONSERVATIVE | `redundancy ⊕ verbose_transitions` | Tradeoffs explained inline |\n| AGGRESSIVE | `explanatory_depth ⊕ execution_narratives` | Core thesis preserved |\n| ULTRA | `all_narrative` | Semantic invariants only |\n\n资料来源：[examples/survey-octave-5-conservative.oct.md:1-15]()\n\n## Integration Points\n\n### With Claude Code\n```bash\nrepomix --style xml --output context.xml\npython octave_enhance_targeted.py context.xml enhanced.xml\n# Paste enhanced.xml into Claude Code session\n```\n\n### With MCP Tools\n\n| Tool | Compression Use |\n|------|-----------------|\n| `octave_validate` | Validates compressed documents against schema |\n| `octave_write` | Writes with normalization and repair receipts |\n| `octave_compile_grammar` | Compiles constraints to GBNF for generation |\n\n## Best Practices\n\n1. **Select tier before reading source** — Tier drives all transformation decisions\n2. **Preserve literal zones** — Seal schema/contract zones before compression\n3. **Apply mythology selectively** — Use domain terms for repeated concepts\n4. **Document loss explicitly** — Always declare `LOSS_PROFILE` in metadata\n5. **Validate after compression** — Run repair pipeline to ensure schema compliance\n\n---\n\n\n\n## Grammar Compilation\n\n### 相关页面\n\n相关主题：[Schema Validation](#page-schema-validation), [System Architecture](#page-system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/core/gbnf_compiler.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/gbnf_compiler.py)\n- [src/octave_mcp/core/grammar_compiler/gbnf.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/gbnf.py)\n- [src/octave_mcp/mcp/grammar_resources.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/grammar_resources.py)\n- [docs/grammar/octave-v1.0-grammar.ebnf](https://github.com/elevanaltd/octave-mcp/blob/main/docs/grammar/octave-v1.0-grammar.ebnf)\n
\n\n# Grammar Compilation\n\nGrammar Compilation is the process of transforming OCTAVE schema definitions into GBNF (Gendered Backus-Naur Form) grammar rules that enable constrained text generation. The octave-mcp project uses this system to provide grammar-level validation and AI-assisted document generation with predictable structure.\n\n## Overview\n\nOCTAVE documents follow a strict hierarchical structure defined by schemas. The grammar compilation subsystem allows:\n\n- **Schema validation**: Compile schemas to verify structural correctness\n- **Constrained generation**: Generate GBNF grammars that LLMs can use to produce valid OCTAVE output\n- **Dynamic compilation**: Compile grammars on-demand for any registered schema\n\n资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py:1-17]()\n\n## Architecture\n\n```mermaid\ngraph TD\n A[OCTAVE Schema Definition] --> B[SchemaDefinition]\n B --> C[GBNFCompiler]\n C --> D[GBNF Grammar Rules]\n D --> E[Constrained LLM Generation]\n \n F[load_schema_by_name] --> B\n G[Contract Field Specs] --> H[parse_contract_field]\n H --> I[HolographicPattern]\n I --> C\n \n J[GBNFCompiler.compile_schema] --> C\n K[compile_document_grammar] --> C\n```\n\n## Core Components\n\n### GBNFCompiler\n\nThe `GBNFCompiler` class is the central component that transforms schema definitions into GBNF grammar strings.\n\n| Method | Purpose |\n|--------|---------|\n| `compile_schema(schema_def, include_envelope=True)` | Compile full schema to GBNF |\n| `emit_grammar_for_schema(schema_name)` | Emit grammar for named schema |\n\n资料来源：[src/octave_mcp/core/grammar_compiler/gbnf.py]()\n资料来源：[src/octave_mcp/mcp/grammar_resources.py:48-76]()\n\n### SchemaDefinition\n\nSchemas define the structure of OCTAVE documents:\n\n```python\nschema = SchemaDefinition(\n name=schema_type,\n version=str(meta.get(\"VERSION\", \"1.0\")),\n)\n```\n\n资料来源：[src/octave_mcp/core/gbnf_compiler.py:42-47]()\n\n### FieldDefinition\n\nIndividual fields within schemas include holographic patterns for constraint representation:\n\n```python\nschema.fields[field_name] = FieldDefinition(\n name=field_name,\n pattern=pattern,\n raw_value=field_spec,\n)\n```\n\n资料来源：[src/octave_mcp/core/gbnf_compiler.py:59-63]()\n\n## Compilation Pipeline\n\n### Step 1: Schema Loading\n\n```mermaid\ngraph LR\n A[Schema Name] --> B[load_schema_by_name]\n B --> C{Found?}\n C -->|Yes| D[Return SchemaDefinition]\n C -->|No| E[Search Paths]\n E --> C\n```\n\nThe `load_schema_by_name` function searches builtin registry and configured search paths:\n\n资料来源：[src/octave_mcp/mcp/grammar_resources.py:48-52]()\n\n```python\nschema_def = load_schema_by_name(schema_name)\nif schema_def is None:\n raise ValueError(f\"Schema '{schema_name}' not found in builtin registry or search paths\")\n```\n\n### Step 2: CONTRACT Parsing\n\nThe CONTRACT field in OCTAVE META sections defines field constraints using holographic notation:\n\n| Constraint Syntax | Meaning |\n|-------------------|---------|\n| `REQ` | Required field |\n| `OPT` | Optional field |\n| `ENUM[values]` | Enumerated values |\n| `FIELD[NAME]::REQ∧ENUM[...]` | Combined constraints |\n\n资料来源：[src/octave_mcp/core/gbnf_compiler.py:30-40]()\n\nThe `parse_contract_field` function extracts field names and constraints from CONTRACT specifications:\n\n```python\nfield_name, constraints = parse_contract_field(field_spec)\npattern = HolographicPattern(\n example=None,\n constraints=constraints,\n target=None,\n)\n```\n\n资料来源：[src/octave_mcp/core/gbnf_compiler.py:53-58]()\n\n### Step 3: Grammar Emission\n\nThe compiler generates GBNF rules from the schema structure:\n\n```python\ncompiler = GBNFCompiler()\ngrammar = compiler.compile_schema(schema_def, include_envelope=True)\n```\n\n资料来源：[src/octave_mcp/mcp/grammar_resources.py:53-55]()\n\n## MCP Integration\n\n### Grammar Resource Provider\n\nThe MCP server exposes grammars through a resource provider:\n\n```mermaid\ngraph TD\n A[MCP Client] --> B[GrammarResources]\n B --> C{Cached?}\n C -->|Yes| D[Return cached GBNF]\n C -->|No| E[_compile_grammar]\n E --> F[GBNFCompiler]\n F --> G[Cache Result]\n G --> D\n```\n\n资料来源：[src/octave_mcp/mcp/grammar_resources.py:43-56]()\n\n### Resource Templates\n\nGrammars are accessible via URI templates:\n\n| Template | Schema |\n|----------|--------|\n| `octave://grammars/{schema_name}` | Any registered schema |\n\n资料来源：[src/octave_mcp/mcp/grammar_resources.py:23-32]()\n\n### Caching\n\nThe grammar compiler uses an in-memory cache to avoid recompilation:\n\n```python\nif schema_name in self._cache:\n return self._cache[schema_name]\n```\n\n资料来源：[src/octave_mcp/mcp/grammar_resources.py:43-44]()\n\n## Public API\n\n### compile_document_grammar\n\nMain entry point for document grammar compilation:\n\n```python\nfrom octave_mcp.core.grammar_compiler import compile_document_grammar\n```\n\n### emit_grammar_for_schema\n\nEmit grammar for a specific schema by name:\n\n```python\nfrom octave_mcp.core.grammar_compiler import emit_grammar_for_schema\n```\n\n资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py:10-11]()\n\n## MCP Tool: octave_compile_grammar\n\nThe MCP server exposes a tool for grammar compilation:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `schema_name` | string | Name of schema to compile |\n| `include_envelope` | boolean | Include document envelope rules (default: true) |\n\n资料来源：[README.md - MCP Tools section]()\n\n## Example Usage\n\n### Compile from META definition\n\n```python\nfrom octave_mcp.core.gbnf_compiler import compile_gbnf_from_meta\n\nmeta = {\n \"TYPE\": \"SESSION_LOG\",\n \"VERSION\": \"1.0\",\n \"CONTRACT\": [\n \"FIELD[STATUS]::REQ∧ENUM[ACTIVE,PAUSED,COMPLETE]\",\n \"FIELD[PRIORITY]::OPT∧ENUM[LOW,MEDIUM,HIGH]\",\n ],\n}\ngbnf = compile_gbnf_from_meta(meta)\n```\n\n资料来源：[src/octave_mcp/core/gbnf_compiler.py:20-35]()\n\n### Access via MCP Resource\n\n```bash\n# Using MCP resource URI\noctave://grammars/META\noctave://grammars/SKILL\n```\n\n## EBNF Grammar Reference\n\nThe base grammar definition for OCTAVE v1.0 is documented in:\n\n- `docs/grammar/octave-v1.0-grammar.ebnf`\n\nThis EBNF defines the fundamental syntax that GBNF grammars must conform to, including:\n- Document envelope markers (`===NAME=== ... ===END===`)\n- Section references (`§N::NAME`)\n- Assignment syntax (`KEY::VALUE`)\n- List and inline map structures\n\n## Architecture Notes\n\n### ADR-0006 Design\n\nThe grammar compilation system was restructured under ADR-0006 to resolve naming conflicts:\n\n- Original: `octave_mcp.core.grammar`\n- Current: `octave_mcp.core.grammar_compiler.gbnf`\n\nThe `octave_mcp.core.grammar` package now serves as a unified front-door for parsing, while grammar compilation lives in the `grammar_compiler` submodule.\n\n资料来源：[src/octave_mcp/core/grammar/__init__.py:1-30]()\n\n### Backward Compatibility\n\nLegacy GBNF exports are available through lazy module loading:\n\n```python\n_DEPRECATED_GBNF_EXPORTS: frozenset[str] = frozenset({\n \"compile_document_grammar\",\n \"emit_grammar_for_schema\",\n})\n```\n\nAccessing deprecated symbols emits a `DeprecationWarning` but returns the correct objects.\n\n资料来源：[src/octave_mcp/core/grammar/__init__.py:48-52]()\n\n## Workflow Summary\n\n```mermaid\ngraph TD\n A[Define OCTAVE Schema] --> B[Register Schema]\n B --> C[MCP Request: compile_grammar]\n C --> D[Load Schema Definition]\n D --> E[Parse CONTRACT Fields]\n E --> F[Generate HolographicPatterns]\n F --> G[GBNFCompiler.compile_schema]\n G --> H[Return GBNF String]\n H --> I[LLM Constrained Generation]\n I --> J[Validate Output]\n```\n\n## See Also\n\n- [OCTAVE Core Specification](../specs/octave-core-spec.oct.md)\n- [Schema Validation Framework](../specs/octave-schema-spec.oct.md)\n- [Holographic Patterns](holographic-patterns.md)\n\n---\n\n\n\n## MCP Tools Reference\n\n### 相关页面\n\n相关主题：[CLI Interface](#page-cli-interface), [Python API Reference](#page-python-api)\n\n
\nRelated Source Files\n\nThe following source files were used to generate this documentation:\n\n- [src/octave_mcp/mcp/validate.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/validate.py)\n- [src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)\n- [src/octave_mcp/mcp/eject.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/eject.py)\n- [src/octave_mcp/mcp/compile_grammar.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/compile_grammar.py)\n- [src/octave_mcp/mcp/base_tool.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/base_tool.py)\n- [docs/mcp-configuration.md](https://github.com/elevanaltd/octave-mcp/blob/main/docs/mcp-configuration.md)\n
\n\n# MCP Tools Reference\n\nThe Model Context Protocol (MCP) tools in Octave-MCP provide a standardized interface for LLM agents to interact with OCTAVE documents. These tools enable validation, writing, transformation, and grammar compilation operations through the MCP protocol, serving as the primary programmatic interface for document-centric workflows.\n\n## Overview\n\nOctave-MCP exposes four core MCP tools that wrap the underlying Python API functions. These tools are designed for documents that pass through multiple agents, tools, or compression steps—including agent/skill files, decision logs, coordination briefs, audit trails, system prompts, and reference documentation where token cost optimization matters.\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n## Architecture\n\nThe MCP tools layer sits atop the core parsing and validation engine, providing an asynchronous interface compatible with the MCP protocol. Each tool inherits from a base class that enforces consistent error handling, logging, and result formatting.\n\n```mermaid\ngraph TD\n A[MCP Client] --> B[Octave-MCP Server]\n B --> C[octave_validate]\n B --> D[octave_write]\n B --> E[octave_eject]\n B --> F[octave_compile_grammar]\n C --> G[Core Validator]\n D --> H[Core Parser + Emitter]\n E --> I[Projection Engine]\n F --> J[GBNF Grammar Compiler]\n G --> K[Schema Registry]\n H --> K\n I --> K\n J --> K\n```\n\n资料来源：[src/octave_mcp/mcp/base_tool.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/base_tool.py)\n\n## MCP Tool Configuration\n\nBefore using the tools, the MCP server must be configured in your client application. Octave-MCP supports two transport mechanisms.\n\n### Claude Code / Claude Desktop\n\nAdd the following to `~/.claude.json` (Claude Code) or `claude_desktop_config.json` (Claude Desktop):\n\n```json\n{\n \"mcpServers\": {\n \"octave\": {\n \"command\": \"octave-mcp-server\"\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n### HTTP Transport\n\nFor HTTP-based deployments, start the server with explicit transport configuration:\n\n```bash\noctave-mcp-server --transport http --port 8080\n```\n\n## Tool Reference\n\n### 1. `octave_validate`\n\nValidates OCTAVE documents against schemas, returning field errors, repair suggestions, and zone coverage analysis.\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `document` | string | Yes | The OCTAVE document content to validate |\n| `schema` | string | No | Schema name to validate against (e.g., META, SKILL, AGENT) |\n| `strict` | boolean | No | If true, reject unknown META fields (default: false) |\n\n#### Returns\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `status` | string | \"VALID\" or \"INVALID\" |\n| `errors` | array | List of validation errors with line numbers |\n| `warnings` | array | List of warnings (e.g., W_META_001, W_META_002) |\n| `suggestions` | array | Auto-correction suggestions for repairable issues |\n\n#### Validation Process\n\nThe validator performs four sequential steps:\n\n1. **Block-target extraction** — Extracts block-level targets from the document AST, enabling feudal inheritance where children inherit parent block targets\n2. **Schema-aware META validation** — Validates META section against schema definitions when a schema is provided\n3. **Schema-independent loss-accounting** — Fires warnings regardless of schema presence\n4. **Duplicate-target detection** — Structural safety net for GH#369 duplicate-target issues\n\n资料来源：[src/octave_mcp/mcp/validate.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/validate.py)\n资料来源：[src/octave_mcp/core/validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/validator.py)\n\n### 2. `octave_write`\n\nWrites files through the full validation pipeline, supporting both creation and modification of OCTAVE documents.\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `target_path` | string | Yes | File path to write to |\n| `content` | string | No | Full content for new files or overwrites |\n| `changes` | object | No | Field updates for existing files (mutually exclusive with content) |\n| `mutations` | object | No | Optional META field overrides |\n| `base_hash` | string | No | SHA-256 hash for CAS consistency check |\n| `schema` | string | No | Schema name for validation |\n| `debug_grammar` | boolean | No | Include compiled grammar in output (default: false) |\n| `format_style` | string | No | Output mode: \"preserve\", \"expanded\", or \"compact\" |\n\n#### Format Style Options\n\n| Mode | Description |\n|------|-------------|\n| `preserve` | Span-aware mode that preserves original formatting (recommended for edits) |\n| `expanded` | Canonical re-emit with full canonical form |\n| `compact` | Minimal whitespace, reduced token count |\n\n#### Response\n\n```json\n{\n \"status\": \"success\",\n \"path\": \"/path/to/document.oct.md\",\n \"canonical_hash\": \"sha256:abc123...\",\n \"corrections\": [\"Fixed trailing whitespace\", \"Balanced brackets\"],\n \"diff\": \"--- a/doc.oct.md\\n+++ b/doc.oct.md\\n@@ ...\",\n \"validation_status\": \"VALIDATED\"\n}\n```\n\n#### Deprecation Note\n\nIn v1.14.0, the default format style will change from canonical re-emit to span-aware `\"preserve\"` mode. To opt in now, explicitly pass `format_style=\"preserve\"`. Omitting the parameter accepts the future default silently without warning.\n\n资料来源：[src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)\n\n### 3. `octave_eject`\n\nProjects OCTAVE documents to different views—canonical, executive summary, developer, or template format.\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `document` | string | Yes | The OCTAVE document to transform |\n| `mode` | string | No | Projection mode (default: canonical) |\n| `format` | string | No | Output format: \"markdown\" or \"json\" (default: markdown) |\n\n#### Projection Modes\n\n| Mode | Description | Use Case |\n|------|-------------|----------|\n| `canonical` | Full document with all sections | Preservation, validation |\n| `executive` | High-level summary with key decisions | Stakeholder review |\n| `developer` | Implementation-focused view | Code generation, testing |\n| `template` | Structure without content | New document scaffolding |\n\n资料来源：[src/octave_mcp/mcp/eject.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/eject.py)\n\n### 4. `octave_compile_grammar`\n\nCompiles schema constraints to GBNF (Greibach Normal Form) grammar for constrained generation.\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `schema` | string | Yes | Schema name to compile (e.g., META, SKILL) |\n| `include_envelope` | boolean | No | Include document envelope markers (default: true) |\n| `debug` | boolean | No | Include debug comments in output (default: false) |\n\n#### Returns\n\nReturns compiled GBNF grammar string suitable for use with constrained decoding libraries.\n\n#### Grammar Access via MCP Resources\n\nThe MCP server also exposes grammar resources at `octave://grammars/{schema_name}`, enabling dynamic grammar access without compilation:\n\n```mermaid\ngraph LR\n A[MCP Client] -->|octave://grammars/META| B[Grammar Resources]\n B --> C{Grammar Cache}\n C -->|cache hit| D[Return Cached]\n C -->|cache miss| E[Compile Schema]\n E --> F[Cache Result]\n F --> D\n```\n\n资料来源：[src/octave_mcp/mcp/compile_grammar.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/compile_grammar.py)\n资料来源：[src/octave_mcp/mcp/grammar_resources.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/grammar_resources.py)\n\n## Base Tool Infrastructure\n\nAll MCP tools inherit from `BaseTool` which provides:\n\n- **Async execution** — All tools support async invocation\n- **Logging integration** — Structured logging with tool context\n- **Error handling** — Consistent error formatting with error codes\n- **Result schema** — Standardized response structure\n\n资料来源：[src/octave_mcp/mcp/base_tool.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/base_tool.py)\n\n## CLI Equivalents\n\nFor command-line usage, the tools are also available as CLI commands:\n\n```bash\noctave validate document.oct.md\noctave write output.oct.md --stdin\noctave eject document.oct.md --mode executive --format markdown\n```\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n## Tool Selection Guide\n\n| Scenario | Recommended Tool |\n|----------|-----------------|\n| Verify document correctness | `octave_validate` |\n| Create new document | `octave_write` with `content` |\n| Modify existing document | `octave_write` with `changes` |\n| Generate summary view | `octave_eject` with `mode: executive` |\n| Prepare for constrained generation | `octave_compile_grammar` |\n| Reformat document | `octave_eject` with `mode: canonical` |\n\n## Error Codes\n\n| Code | Meaning |\n|------|---------|\n| `E_NESTED_INLINE_MAP` | Inner value is an inline map (strict mode error) |\n| `W_NESTED_INLINE_MAP` | Inner value is an inline map (lenient mode warning) |\n| `W_META_001` | Missing recommended META field |\n| `W_META_002` | Unknown META field present |\n| `GH#369` | Duplicate target detected |\n\n## When to Use MCP Tools\n\n**Use MCP tools for:**\n- Documents passing through multiple agents or tools\n- Agent and skill files with YAML discovery headers\n- Decision logs, coordination briefs, and audit trails\n- System prompts where token cost matters\n\n**Do not use for:**\n- Single-step prompts\n- Freeform prose\n- Direct code output without document structure\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n---\n\n\n\n## CLI Interface\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#page-mcp-tools), [Python API Reference](#page-python-api)\n\n
\nRelevant Source Files\n\nThe following source files were used to generate this documentation:\n\n- [src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)\n- [tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)\n- [tools/octave-to-json.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-to-json.py)\n- [tools/json-to-octave.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/json-to-octave.py)\n- [tools/lint-octave.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/lint-octave.py)\n- [README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n
\n\n# CLI Interface\n\nThe CLI (Command Line Interface) for octave-mcp provides a suite of standalone tools for validating, converting, and processing OCTAVE documents outside of the MCP protocol. These tools enable direct file-based workflows, batch processing, and integration with external systems that require OCTAVE content in alternative formats.\n\n## Overview\n\nThe CLI interface consists of two categories of tools:\n\n| Category | Tools | Purpose |\n|----------|-------|---------|\n| **Core CLI** | `octave validate`, `octave write`, `octave eject` | Primary operations via MCP server executable |\n| **Standalone Scripts** | `lint-octave.py`, `octave-to-json.py`, `json-to-octave.py`, `octave-validator.py` | Fast validation and format conversion without server overhead |\n\nThe standalone tools are particularly valuable for build pipelines, CI/CD workflows, and scenarios where spawning an MCP server is impractical.\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"CLI Tools\"\n A[octave CLI] --> B[octave validate]\n A --> C[octave write]\n A --> D[octave eject]\n end\n \n subgraph \"Standalone Tools\"\n E[lint-octave.py] --> F[Fast Syntax Check]\n G[octave-to-json.py] --> H[JSON Conversion]\n I[json-to-octave.py] --> J[OCTAVE Conversion]\n K[octave-validator.py] --> L[Repo Validation]\n end\n \n subgraph \"Core Library\"\n M[octave_mcp.core] --> N[Parser]\n M --> O[Validator]\n M --> P[Emitter]\n end\n \n B --> M\n C --> M\n D --> M\n E --> M\n G --> M\n I --> M\n K --> M\n```\n\n## Installation & Configuration\n\n### Server Installation\n\nInstall the `octave-mcp-server` executable for MCP-based CLI access:\n\n```bash\npip install octave-mcp\n```\n\n### MCP Configuration\n\n#### Claude Code (`~/.claude.json`)\n\n```json\n{\n \"mcpServers\": {\n \"octave\": {\n \"command\": \"octave-mcp-server\"\n }\n }\n}\n```\n\n#### Claude Desktop (`claude_desktop_config.json`)\n\n```json\n{\n \"mcpServers\": {\n \"octave\": {\n \"command\": \"octave-mcp-server\"\n }\n }\n}\n```\n\n#### HTTP Transport\n\nFor remote or containerized deployments:\n\n```bash\noctave-mcp-server --transport http --port 8080\n```\n\n## Core CLI Commands\n\n### `octave validate`\n\nValidates OCTAVE documents against the specification and optional schema.\n\n```bash\noctave validate document.oct.md\n```\n\n**Exit Codes:**\n- `0` - Validation successful\n- `1` - Validation failed (outputs `OCTAVE_INVALID: `)\n\n### `octave write`\n\nWrites files through the full validation pipeline.\n\n```bash\noctave write output.oct.md --stdin\n```\n\nThe `--stdin` flag reads content from standard input, enabling piping from other tools.\n\n### `octave eject`\n\nProjects documents to different views for specialized audiences.\n\n```bash\noctave eject document.oct.md --mode executive --format markdown\n```\n\n**Available Modes:**\n| Mode | Purpose |\n|------|---------|\n| `canonical` | Full OCTAVE format |\n| `executive` | High-level summary for decision-makers |\n| `developer` | Implementation-focused view |\n| `template` | Template with placeholders |\n\n## Standalone Validation Tools\n\n### `lint-octave.py`\n\nFast syntax validation script optimized for rapid feedback.\n\n**Usage:**\n```bash\npython3 lint-octave.py < document.oct.md\n```\n\n**Output:**\n- `OCTAVE_VALID` - Document passes all checks\n- `OCTAVE_INVALID: ` - Document fails with specific reason\n\n**Validation Checks:**\n\n| Check | Description |\n|-------|-------------|\n| Document Markers | Verifies `===NAME===` and `===END===` envelope markers |\n| META Section | Confirms presence of `META:` after optional preface comments |\n| Indentation | Validates 2-space multiples |\n| Assignment Syntax | Ensures `KEY::VALUE` format |\n| Balanced Brackets | Checks `[]` bracket matching |\n| Trailing Commas | Rejects trailing commas in lists |\n\n资料来源：[tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)\n\n### `octave-validator.py`\n\nRepository-level validator that wraps the OCTAVE-MCP core parser/validator. This tool prevents drift between runtime validation and document validation.\n\n**Usage:**\n```bash\n# Single file validation\npython3 octave-validator.py document.oct.md\n\n# Directory scanning\npython3 octave-validator.py --path /path/to/documents\n```\n\n**Command-Line Arguments:**\n\n| Argument | Short | Description | Default |\n|----------|-------|-------------|---------|\n| `--version` | `-v` | OCTAVE version label (informational) | `6.0.0` |\n| `--profile` | `-p` | Validation profile | `protocol` |\n| `--schema` | - | Schema name for validation | None |\n| `--require-frontmatter` | - | Fail on missing YAML frontmatter | False |\n| `--path` | `-d` | Scan directory for `*.oct.md` files | None |\n\n**Validation Profiles:**\n\n| Profile | Description |\n|---------|-------------|\n| `protocol` | Standard OCTAVE protocol validation |\n| `hestai-agent` | Agent document format with YAML frontmatter |\n| `hestai-skill` | Skill document format with YAML frontmatter |\n| `hestai-pattern` | Pattern document format |\n\n```bash\n# Strict validation with required frontmatter\npython3 octave-validator.py agent.oct.md --profile hestai-agent --require-frontmatter\n\n# Schema validation\npython3 octave-validator.py document.oct.md --schema SKILL\n```\n\n资料来源：[tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)\n\n## Format Conversion Tools\n\n### `octave-to-json.py`\n\nConverts OCTAVE documents to JSON for system integration.\n\n**Usage:**\n```bash\npython3 octave-to-json.py document.oct.md > output.json\n```\n\n**Features:**\n- Preserves semantic operators (`synthesis`, `tension`, `progression`)\n- Tracks blank lines for round-trip fidelity\n- Maintains quoted strings\n- Handles nested structures\n\n资料来源：[tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)\n\n### `json-to-octave.py`\n\nConverts JSON back to OCTAVE format, restoring original formatting.\n\n**Usage:**\n```bash\npython3 json-to-octave.py input.json > document.oct.md\n```\n\n**Features:**\n- Restores original formatting including blank lines\n- Reconstructs semantic operators\n- Preserves document structure\n\n## Round-Trip Conversion\n\nThe conversion tools support bidirectional transformation with fidelity preservation:\n\n```mermaid\ngraph LR\n A[OCTAVE] -->|octave-to-json.py| B[JSON]\n B -->|json-to-octave.py| A\n B -->|round-trip| C{Same Content?}\n C -->|Yes| D[Perfect Round-Trip]\n C -->|No| E[Check for Data Loss]\n```\n\n**Verification Example:**\n```bash\n# Convert OCTAVE to JSON and back\npython3 octave-to-json.py input.oct.md | python3 json-to-octave.py > output.oct.md\n\n# Verify perfect round-trip\ndiff input.oct.md output.oct.md\n```\n\n## MCP Tool Interface\n\nThe CLI tools mirror MCP tools available for programmatic access:\n\n### Tool Comparison\n\n| CLI Command | MCP Tool | Function |\n|------------|----------|----------|\n| `octave validate` | `octave_validate` | Validate against schema |\n| `octave write` | `octave_write` | Write files with validation |\n| `octave eject` | `octave_eject` | Project to different views |\n| - | `octave_compile_grammar` | Compile schema constraints to GBNF |\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n### `octave_write` Parameters\n\nThe `octave_write` MCP tool provides comprehensive file writing capabilities:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `target_path` | string | File path to write to |\n| `content` | string | Full content for new files (mutually exclusive with `changes`) |\n| `changes` | object | Field updates for existing files (mutually exclusive with `content`) |\n| `mutations` | object | Optional META field overrides |\n| `base_hash` | string | Optional CAS consistency check hash |\n| `schema` | string | Optional schema name for validation |\n| `debug_grammar` | boolean | Include compiled grammar in output (default: false) |\n| `format_style` | string | Output formatting: `\"preserve\"`, `\"expanded\"`, or `\"compact\"` |\n\n**Return Value Structure:**\n\n| Field | Description |\n|-------|-------------|\n| `status` | `\"success\"` or `\"error\"` |\n| `path` | Written file path (on success) |\n| `canonical_hash` | SHA-256 hash of canonical content (on success) |\n| `corrections` | List of corrections applied |\n| `diff` | Compact diff of changes |\n| `errors` | List of errors (on failure) |\n| `validation_status` | `VALIDATED` or `UNVALID` |\n\n资料来源：[src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)\n\n## Format Style Options\n\nThe `format_style` parameter controls output formatting:\n\n| Style | Description | Use Case |\n|-------|-------------|----------|\n| `preserve` | Maintains original formatting and blank lines | Default (future v1.14.0+) |\n| `expanded` | Canonical re-emit with full structure | Current default, archival |\n| `compact` | Minimizes whitespace | Storage-constrained environments |\n\n**Deprecation Notice:**\n> Passing `format_style=None` explicitly is deprecated. In v1.14.0 the default will change from full canonical re-emit to span-aware `preserve` mode.\n\n资料来源：[src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)\n\n## Workflow Examples\n\n### CI/CD Integration\n\n```bash\n#!/bin/bash\n# Validate all OCTAVE documents in a directory\nfor file in $(find . -name \"*.oct.md\"); do\n python3 octave-validator.py \"$file\" --profile hestai-agent --require-frontmatter\n if [ $? -ne 0 ]; then\n echo \"Validation failed for $file\"\n exit 1\n fi\ndone\necho \"All documents validated successfully\"\n```\n\n### Build Pipeline\n\n```bash\n# 1. Convert source documents to JSON\npython3 octave-to-json.py docs/*.oct.md > build/documents.json\n\n# 2. Process with external tool\nexternal-processor build/documents.json > build/processed.json\n\n# 3. Convert back to OCTAVE\npython3 json-to-octave.py build/processed.json > docs/updated/\n\n# 4. Validate results\npython3 octave-validator.py --path docs/updated/\n```\n\n### Quick Validation Loop\n\n```bash\n# Watch file and validate on change (requires inotifywait)\nwhile inotifywait -e close_write document.oct.md; do\n python3 lint-octave.py < document.oct.md\ndone\n```\n\n## Tool Selection Guide\n\n```mermaid\ngraph TD\n A[Need to process OCTAVE?] --> B{Environment}\n B -->|MCP Server| C[Use octave CLI commands]\n B -->|No MCP| D{Operation Type}\n D -->|Fast Check| E[lint-octave.py]\n D -->|Full Validation| F[octave-validator.py]\n D -->|Format Conversion| G{Which Direction?}\n G -->|OCTAVE to JSON| H[octave-to-json.py]\n G -->|JSON to OCTAVE| I[json-to-octave.py]\n D -->|Batch Processing| J[octave-validator.py --path]\n```\n\n**Decision Matrix:**\n\n| Scenario | Recommended Tool | Reason |\n|----------|-----------------|--------|\n| Quick syntax check during editing | `lint-octave.py` | Fast, no imports required |\n| CI/CD validation pipeline | `octave-validator.py` | Full validation, exit codes |\n| Integration with JSON systems | `octave-to-json.py` / `json-to-octave.py` | Round-trip capable |\n| Claude Desktop/Code integration | MCP tools via server | Full feature set |\n| Batch directory validation | `octave-validator.py --path` | Processes all `.oct.md` files |\n\n## Error Handling\n\n### Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| `0` | Success / Validation passed |\n| `1` | Failure (validation failed, file error, etc.) |\n\n### Validation Error Output Format\n\n```\nOCTAVE_INVALID: \n```\n\nCommon reasons include:\n- Missing envelope markers (`===NAME===`)\n- Invalid META section structure\n- Syntax errors in assignments\n- Schema validation failures\n\n### Verbose Mode\n\nFor debugging validation issues, enable debug grammar output:\n\n```bash\noctave write document.oct.md --debug-grammar\n```\n\nThis includes the compiled GBNF grammar in the output, useful for identifying grammar-level failures.\n\n---\n\n\n\n## Python API Reference\n\n### 相关页面\n\n相关主题：[CLI Interface](#page-cli-interface), [MCP Tools Reference](#page-mcp-tools)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/__init__.py)\n- [src/octave_mcp/core/parser.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/parser.py)\n- [src/octave_mcp/core/emitter.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/emitter.py)\n- [src/octave_mcp/core/repair.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/repair.py)\n- [src/octave_mcp/schemas/loader.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/schemas/loader.py)\n- [docs/api.md](https://github.com/elevanaltd/octave-mcp/blob/main/docs/api.md)\n
\n\n# Python API Reference\n\nThe Python API Reference documents the public programmatic interface of the `octave_mcp` library. This API enables developers to integrate OCTAVE document parsing, validation, emission, and transformation directly into Python applications without relying on CLI commands or MCP tools.\n\n## Overview\n\nThe `octave_mcp` package provides a complete toolkit for working with OCTAVE (Olympian Common Text And Vocabulary Engine) documents. OCTAVE is a semantic DSL designed for structured document representation in LLM workflows.\n\nThe public API exports 51 functions and classes, organized into the following categories:\n\n| Category | Count | Description |\n|----------|-------|-------------|\n| Functions | 9 | Core operations: parse, emit, tokenize, repair, project, hydrate |\n| Classes | 16 | Parser, Validator, TokenType, Token, Document, Block, Assignment, etc. |\n| AST Nodes | 8 | Document, Block, Assignment, Section, ListValue, InlineMap, Absent |\n| Hydration | 3 | HydrationPolicy, VocabularyRegistry, hydrate |\n| Schema | 2 | SchemaDefinition, FieldDefinition |\n| Repair | 4 | RepairLog, RepairEntry, RepairTier, RoutingLog |\n| Exceptions | 8 | VocabularyError, CollisionError, ParserError, LexerError, etc. |\n\n*资料来源：[src/octave_mcp/__init__.py:12-45]()\n\n## Core Functions\n\n### parse()\n\n```python\ndef parse(content: str) -> Document\n```\n\nThe primary parsing function that converts OCTAVE-formatted text into an Abstract Syntax Tree (AST).\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `content` | `str` | OCTAVE document string to parse |\n\n**Returns:** `Document` - The parsed AST representation\n\n**Behavior:**\n- Returns a `Document` object with sections, blocks, and assignments\n- Does not emit warnings; use `parse_with_warnings()` for detailed diagnostics\n- Supports OCTAVE 6.x grammar including grammar sentinel `OCTAVE::VERSION` headers\n\n*资料来源：[src/octave_mcp/__init__.py:27]()\n\n### parse_with_warnings()\n\n```python\ndef parse_with_warnings(content: str) -> tuple[Document, list[WarningEntry]]\n```\n\nExtended parsing that returns both the document and any warnings encountered during parsing.\n\n**Returns:** `tuple[Document, list[WarningEntry]]` - Document and warnings list\n\n**Warning Types:**\n- Missing META section\n- Non-protocol dialect tokens detected\n- Lenient preprocessing applied for HestAI dialect\n\n*资料来源：[src/octave_mcp/core/parser.py:340-350]()\n\n### emit()\n\n```python\ndef emit(doc: Document) -> str\n```\n\nConverts a Document AST back into a canonical OCTAVE-formatted string.\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `doc` | `Document` | The AST document to emit |\n\n**Returns:** `str` - Canonical OCTAVE-formatted output\n\n**Note:** This function is the inverse of `parse()`. Round-trip conversion preserves document structure including blank lines and semantic operators.\n\n*资料来源：[src/octave_mcp/__init__.py:27](), [src/octave_mcp/core/emitter.py]()\n\n### tokenize()\n\n```python\ndef tokenize(content: str) -> list[Token]\n```\n\nBreaks OCTAVE content into a stream of tokens for lexical analysis.\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `content` | `str` | OCTAVE document string |\n\n**Returns:** `list[Token]` - Ordered list of tokens with type and value\n\n**Token Types:**\n- `ENVELOPE_START` / `ENVELOPE_END`\n- `SECTION_KEY`\n- `ASSIGNMENT`\n- `LIST_START` / `LIST_END`\n- `GRAMMAR_SENTINEL`\n- `IDENTIFIER`\n- `STRING`\n\n*资料来源：[src/octave_mcp/__init__.py:27]()\n\n### repair()\n\n```python\ndef repair(content: str) -> tuple[str, RepairLog]\n```\n\nAttempts to automatically fix malformed OCTAVE content.\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `content` | `str` | Potentially malformed OCTAVE content |\n\n**Returns:** `tuple[str, RepairLog]` - Repaired content and log of changes\n\n**Repair Strategies:**\n- Localized salvaging preserves document structure where possible\n- Wraps plain text into BODY: RAW carrier for non-parseable content\n- Marks failing lines with `_PARSE_ERROR_LINE_N` markers\n\n*资料来源：[src/octave_mcp/__init__.py:27](), [src/octave_mcp/core/repair.py]()\n\n### project()\n\n```python\ndef project(doc: Document, mode: str) -> ProjectionResult\n```\n\nTransforms a document into different output views.\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `doc` | `Document` | Source document |\n| `mode` | `str` | Projection mode: canonical, executive, developer, template |\n\n**Returns:** `ProjectionResult` - Transformed document with routing log\n\n*资料来源：[src/octave_mcp/__init__.py:27]()\n\n### hydrate()\n\n```python\ndef hydrate(doc: Document, policy: HydrationPolicy) -> Document\n```\n\nApplies a hydration policy to a document for variable substitution and template expansion.\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `doc` | `Document` | Document to hydrate |\n| `policy` | `HydrationPolicy` | Hydration configuration |\n\n**Returns:** `Document` - Hydrated document with substitutions applied\n\n*资料来源：[src/octave_mcp/__init__.py:27]()\n\n### extract_schema_from_document()\n\n```python\ndef extract_schema_from_document(doc: Document) -> SchemaDefinition\n```\n\nInfers the schema definition from an existing document's structure.\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `doc` | `Document` | Document to analyze |\n\n**Returns:** `SchemaDefinition` - Inferred schema with field definitions\n\n*资料来源：[src/octave_mcp/__init__.py:27]()\n\n### seal_document() / verify_seal()\n\n```python\ndef seal_document(doc: Document) -> Document\ndef verify_seal(doc: Document) -> SealVerificationResult\n```\n\nIntegrity management functions for document sealing.\n\n*资料来源：[src/octave_mcp/__init__.py:27]()\n\n## Core Classes\n\n### Parser\n\nThe `Parser` class provides detailed control over the parsing process.\n\n```python\nclass Parser:\n def __init__(self, content: str)\n def parse(self) -> Document\n def parse_document(self) -> Document\n def current() -> Token\n def advance() -> Token\n```\n\n**Key Methods:**\n\n| Method | Description |\n|--------|-------------|\n| `parse_document()` | Parse complete OCTAVE document with ADR-0006 SR2-T2 support for `start_byte`/`end_byte` |\n| `parse_with_warnings()` | Returns document with META region byte positions |\n\n**Grammar Sentinel Support:**\n- Recognizes `OCTAVE::VERSION` pattern\n- Populates `doc.grammar_version` from lexer\n\n*资料来源：[src/octave_mcp/core/parser.py:150-180]()\n\n### Document\n\nThe AST representation of an OCTAVE document.\n\n```python\n@dataclass\nclass Document:\n name: str\n grammar_version: str | None\n start_byte: int\n end_byte: int\n meta_start_byte: int | None\n meta_end_byte: int | None\n sections: list[Block]\n```\n\n**Attributes:**\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `name` | `str` | Document envelope name (e.g., \"MY_DOC\") or \"INFERRED\" |\n| `grammar_version` | `str \\| None` | Version from grammar sentinel |\n| `start_byte` | `int` | Document start byte offset (always 0 for NFC base) |\n| `end_byte` | `int` | Document end byte offset |\n| `meta_start_byte` | `int \\| None` | META block start (when present) |\n| `meta_end_byte` | `int \\| None` | META block end (when present) |\n| `sections` | `list[Block]` | Parsed section blocks |\n\n*资料来源：[src/octave_mcp/core/parser.py:150-160]()\n\n### Block\n\nRepresents a structural block within a document.\n\n```python\n@dataclass\nclass Block:\n key: str\n children: list[Section | Assignment]\n```\n\n### Assignment\n\nRepresents a key-value assignment.\n\n```python\n@dataclass\nclass Assignment:\n key: str\n value: str | ListValue | InlineMap\n```\n\n### HydrationPolicy\n\nConfiguration for document hydration.\n\n```python\n@dataclass\nclass HydrationPolicy:\n registry: VocabularyRegistry\n strict: bool\n mode: str # \"substitute\", \"expand\", \"validate\"\n```\n\n### SchemaDefinition\n\nSchema definition for validation.\n\n```python\n@dataclass\nclass SchemaDefinition:\n name: str\n fields: list[FieldDefinition]\n```\n\n*资料来源：[src/octave_mcp/__init__.py:30-45]()\n\n## Exception Classes\n\n| Exception | Description |\n|-----------|-------------|\n| `VocabularyError` | Vocabulary-related validation failure |\n| `CollisionError` | Key or name collision detected |\n| `VersionMismatchError` | Grammar version incompatibility |\n| `CycleDetectionError` | Circular dependency in hydration |\n| `SourceUriSecurityError` | Unsafe URI reference detected |\n| `ParserError` | Parsing failure |\n| `LexerError` | Lexical analysis failure |\n| `ValidationError` | Schema validation failure |\n\n*资料来源：[src/octave_mcp/__init__.py:43-45]()\n\n## Repair System\n\n### RepairLog\n\n```python\n@dataclass\nclass RepairLog:\n entries: list[RepairEntry]\n corrections: list[dict[str, Any]]\n```\n\n### RepairTier\n\n| Tier | Description |\n|------|-------------|\n| `LENIENT_PARSE` | Minor fixes that preserve semantics |\n| `MODERATE` | Structural corrections |\n| `STRICT` | Breaking changes required |\n\n### RepairEntry\n\n```python\n@dataclass\nclass RepairEntry:\n code: str\n tier: RepairTier\n message: str\n safe: bool\n semantics_changed: bool\n```\n\n**Common Repair Codes:**\n\n| Code | Tier | Description |\n|------|------|-------------|\n| `W_STRUCT_RAW_WRAP` | LENIENT_PARSE | Wrapped plain text into BODY: RAW carrier |\n\n*资料来源：[src/octave_mcp/core/repair.py]()\n\n## Schema Loading\n\n### load_schema_by_name()\n\n```python\ndef load_schema_by_name(schema_name: str) -> SchemaDefinition | None\n```\n\nLoads a schema definition by name from the builtin registry or search paths.\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `schema_name` | `str` | Schema name (e.g., \"META\", \"SKILL\", \"SESSION_LOG\") |\n\n**Returns:** `SchemaDefinition` or `None` if not found\n\n**Builtin Schemas:**\n- `META` - Document metadata schema\n- `SKILL` - Skill definition schema\n- `SESSION_LOG` - Session logging schema\n\n*资料来源：[src/octave_mcp/schemas/loader.py]()\n\n## Usage Examples\n\n### Basic Parsing\n\n```python\nfrom octave_mcp import parse, emit\n\n# Parse OCTAVE content\ncontent = '''===MY_DOC===\nMETA:\n TYPE::SKILL\n VERSION::\"1.0.0\"\n§1::CONTENT\nKEY::VALUE\n===END===\n'''\n\ndoc = parse(content)\nprint(f\"Document name: {doc.name}\")\nprint(f\"Grammar version: {doc.grammar_version}\")\n```\n\n### Round-Trip Conversion\n\n```python\nfrom octave_mcp import parse, emit\n\ncontent = '''===EXAMPLE===\nMETA:\n TYPE::TEST\n§1::SECTION\nFIELD::VALUE\n===END===\n'''\n\ndoc = parse(content)\noutput = emit(doc)\n# output is canonical OCTAVE\n```\n\n### Validation with Repair\n\n```python\nfrom octave_mcp import repair, parse\n\nmalformed = '''===DOC===\nMETA:\n TYPE::TEST\nINVALID§SYNTAX\n===END===\n'''\n\nrepaired, log = repair(malformed)\nprint(f\"Repaired content: {repaired}\")\nprint(f\"Corrections made: {len(log.corrections)}\")\n```\n\n### Schema Validation\n\n```python\nfrom octave_mcp import parse, Validator\nfrom octave_mcp.schemas import load_schema_by_name\n\ndoc = parse(octave_content)\nschema = load_schema_by_name(\"META\")\nvalidator = Validator(schema)\nresult = validator.validate(doc)\n```\n\n*资料来源：[docs/api.md]()\n\n## Architecture Diagram\n\n```mermaid\ngraph TD\n A[OCTAVE String Input] --> B[Parser]\n B --> C[Document AST]\n C --> D[Validator]\n C --> E[Emitter]\n C --> F[Repair]\n F --> G{Parse Success?}\n G -->|No| H[Localized Salvage]\n G -->|Yes| C\n H --> I[Repaired Content]\n I --> B\n D --> J[ValidationResult]\n E --> K[Canonical OCTAVE Output]\n F --> L[RepairLog]\n C --> M[Projector]\n M --> N[ProjectionResult]\n C --> O[Hydrator]\n O --> P[HydratedDocument]\n \n style A fill:#e1f5fe\n style K fill:#c8e6c9\n style J fill:#fff3e0\n style L fill:#fce4ec\n```\n\n## CLI vs Python API\n\n| Feature | CLI | Python API |\n|---------|-----|------------|\n| Quick validation | ✓ | ✓ via `parse()` |\n| File operations | ✓ | Manual |\n| Streaming | ✓ | ✓ via generators |\n| Custom repair strategies | ✗ | ✓ via `repair()` |\n| AST manipulation | ✗ | ✓ |\n| Integration into Python apps | ✗ | ✓ |\n| MCP tools | ✓ | ✗ |\n\n## Advanced: Grammar Compilation\n\n```python\nfrom octave_mcp.core.grammar_compiler import compile_document_grammar\n\ngrammar = compile_document_grammar(\"META\")\n# Returns GBNF grammar string for schema\n```\n\nThe grammar compiler supports:\n- Schema-based grammar generation\n- Cached compilation for performance\n- Include/exclude envelope markers\n\n*资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py]()\n\n## Best Practices\n\n1. **Use `parse_with_warnings()` during development** to catch non-protocol dialect tokens\n2. **Call `repair()` before `parse()`** when processing untrusted input\n3. **Cache schema definitions** if loading repeatedly\n4. **Use `emit()` for round-trip verification** in tests\n5. **Leverage `HydrationPolicy`** for template-based workflows\n\n## See Also\n\n- [Usage Guide](docs/usage.md) - CLI and integration examples\n- [Specs](../specs/) - OCTAVE specification documents\n- [Primers](../resources/primers/) - Quick-start primers for specific use cases\n\n---\n\n---\n\n## Doramagic Pitfall Log\n\nProject: elevanaltd/octave-mcp\n\nSummary: Found 38 potential pitfall items; 4 are high/blocking. Highest priority: security_permissions - 失败模式：security_permissions: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oc....\n\n## 1. security_permissions · 失败模式：security_permissions: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oc...\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: Developers should check this security_permissions risk before relying on the project: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md\n- User impact: Developers may expose sensitive permissions or credentials: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/elevanaltd/octave-mcp/issues/424\n- Evidence: failure_mode_cluster:github_issue | fmev_22c0329bf698546f57cbd9edd620083f | https://github.com/elevanaltd/octave-mcp/issues/424 | octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md\n\n## 2. security_permissions · 失败模式：security_permissions: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: Developers should check this security_permissions risk before relying on the project: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)\n- User impact: Developers may expose sensitive permissions or credentials: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38). Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/elevanaltd/octave-mcp/issues/420\n- Evidence: failure_mode_cluster:github_issue | fmev_e63e5f9a96f8ad23bef9d32f6c4c13e7 | https://github.com/elevanaltd/octave-mcp/issues/420 | octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)\n\n## 3. security_permissions · 来源证据：bug: octave_write surgical edit primitives unsafe on inline-array top-level entries (APPEND + expanded modes)\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: octave_write surgical edit primitives unsafe on inline-array top-level entries (APPEND + expanded modes)\n- User impact: 可能影响升级、迁移或版本选择。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_75dbe0c2c20b479a9afc619c467acc20 | https://github.com/elevanaltd/octave-mcp/issues/411 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. security_permissions · 来源证据：octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_744a11a12c0340e08087ea951c281000 | https://github.com/elevanaltd/octave-mcp/issues/426 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. installation · 失败模式：installation: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed findin...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks\n- User impact: Developers may fail before the first successful local run: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_8ff9088f7d6c1752dffdf17a7dd320db | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks, failure_mode_cluster:github_issue | fmev_aa61ed66e510ebfae83228fb28ae6e11 | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks, failure_mode_cluster:github_issue | fmev_6046cbe1d9f5946d7c5f3b4a9e75cd5a | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks, failure_mode_cluster:github_issue | fmev_6450b53644007e96c1fa966585fe47ea | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks\n\n## 6. installation · 失败模式：installation: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type doc...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents\n- User impact: Developers may fail before the first successful local run: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_9d395f7455d912516430481376e952e2 | https://github.com/elevanaltd/octave-mcp/issues/425 | octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents\n\n## 7. installation · 来源证据：bug: _find_target_start backslash-run quote-escape mishandling (sibling of cubic P1 on PR #431)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: _find_target_start backslash-run quote-escape mishandling (sibling of cubic P1 on PR #431)\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_8284755b0fa74799b1f881f624677141 | https://github.com/elevanaltd/octave-mcp/issues/432 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. configuration · 失败模式：configuration: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describi...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty)\n- User impact: Developers may misconfigure credentials, environment, or host setup: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty). Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_c368f015439226dbb8b9c45fddf3158d | https://github.com/elevanaltd/octave-mcp/issues/430 | RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty)\n\n## 9. configuration · 失败模式：configuration: bug: emitter normalises backslash counts in string literals (round-trip byte-loss)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: bug: emitter normalises backslash counts in string literals (round-trip byte-loss)\n- User impact: Developers may misconfigure credentials, environment, or host setup: bug: emitter normalises backslash counts in string literals (round-trip byte-loss)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug: emitter normalises backslash counts in string literals (round-trip byte-loss). Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_bbc57f3d1a93f9e5fb48332874044f35 | https://github.com/elevanaltd/octave-mcp/issues/434 | bug: emitter normalises backslash counts in string literals (round-trip byte-loss)\n\n## 10. configuration · 失败模式：configuration: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only pat...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue)\n- User impact: Developers may misconfigure credentials, environment, or host setup: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue). Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_cf23dec47765d23b75fcd69bef5c1332 | https://github.com/elevanaltd/octave-mcp/issues/433 | bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue)\n\n## 11. configuration · 失败模式：configuration: bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say fu...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplicate key (invalid O...\n- User impact: Developers may misconfigure credentials, environment, or host setup: bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplicate key (invalid O...\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplicate key (invalid O.... Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_6420a6baab4269626b43aeca56c0d6c8 | https://github.com/elevanaltd/octave-mcp/issues/443 | bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplicate key (invalid O...\n\n## 12. configuration · 失败模式：configuration: governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate\n- User impact: Developers may misconfigure credentials, environment, or host setup: governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_67bfde22b66b3bde199f59556c21e82d | https://github.com/elevanaltd/octave-mcp/issues/441 | governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate\n\n## 13. configuration · 失败模式：configuration: octave_validate: SKILL schema only validates frontmatter; §-section body uncovered\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: octave_validate: SKILL schema only validates frontmatter; §-section body uncovered\n- User impact: Developers may misconfigure credentials, environment, or host setup: octave_validate: SKILL schema only validates frontmatter; §-section body uncovered\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: octave_validate: SKILL schema only validates frontmatter; §-section body uncovered. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_339fb57ac390e565b548c1bea78abc66 | https://github.com/elevanaltd/octave-mcp/issues/428 | octave_validate: SKILL schema only validates frontmatter; §-section body uncovered, failure_mode_cluster:github_issue | fmev_338bf1f21059e0d238b9fcb8084aea71 | https://github.com/elevanaltd/octave-mcp/issues/428 | octave_validate: SKILL schema only validates frontmatter; §-section body uncovered\n\n## 14. configuration · 来源证据：bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form-preservation gap)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form-preservation gap)\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_6236e7ed154c4976ac4a7deee1e5e95d | https://github.com/elevanaltd/octave-mcp/issues/447 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 15. configuration · 来源证据：octave_validate: DEBATE_TRANSCRIPT STATUS enum missing 'PAUSED' (live false negative)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：octave_validate: DEBATE_TRANSCRIPT STATUS enum missing 'PAUSED' (live false negative)\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_b0ee99f7200a4686b5de382a2c70d9b2 | https://github.com/elevanaltd/octave-mcp/issues/423 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | README/documentation is current enough for a first validation pass.\n\n## 17. runtime · 失败模式：runtime: bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP cr...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this runtime risk before relying on the project: bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock\n- User impact: Developers may hit a documented source-backed failure mode: bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_9022259172bcd98fea3c615e38180f11 | https://github.com/elevanaltd/octave-mcp/issues/440 | bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock\n\n## 18. runtime · 失败模式：runtime: enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this runtime risk before relying on the project: enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement\n- User impact: Developers may hit a documented source-backed failure mode: enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_4667399fae050529c3b6df294209996d | https://github.com/elevanaltd/octave-mcp/issues/439 | enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement\n\n## 19. runtime · 失败模式：runtime: enhancement: validator section-bucket merging may mask path-isolated requirements (raised on...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this runtime risk before relying on the project: enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444)\n- User impact: Developers may hit a documented source-backed failure mode: enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444). Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_d71a3524d919da6f5900dcc0df04304b | https://github.com/elevanaltd/octave-mcp/issues/445 | enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444)\n\n## 20. runtime · 来源证据：bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_2512797d818a4840822d948795de8588 | https://github.com/elevanaltd/octave-mcp/issues/440 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 21. runtime · 来源证据：bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_a8d2b9e12cb2477499d2ada52aed438e | https://github.com/elevanaltd/octave-mcp/issues/436 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 22. runtime · 来源证据：enhancement: octave_validate ENUM constraint non-enforcement (PARTIAL → IMPLEMENTED)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：enhancement: octave_validate ENUM constraint non-enforcement (PARTIAL → IMPLEMENTED)\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_c9882e67c42642b0864690256d8258e6 | https://github.com/elevanaltd/octave-mcp/issues/435 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 23. runtime · 来源证据：enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_ed6a5fd931ec45489d58f2763b403513 | https://github.com/elevanaltd/octave-mcp/issues/439 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 24. runtime · 来源证据：enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444)\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_28e0ef9cb32e4e918dafd0e22960d639 | https://github.com/elevanaltd/octave-mcp/issues/445 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 25. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | last_activity_observed missing\n\n## 26. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | no_demo; severity=medium\n\n## 27. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | no_demo; severity=medium\n\n## 28. security_permissions · 来源证据：DECISION_LOG schema v1.1 conformance: reference DECISIONS.oct.md reports 68 STRICT validation_errors\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：DECISION_LOG schema v1.1 conformance: reference DECISIONS.oct.md reports 68 STRICT validation_errors\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_8d4d0aa8843f448b8151f98bb89a5d32 | https://github.com/elevanaltd/octave-mcp/issues/448 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 29. security_permissions · 来源证据：bug: emitter normalises backslash counts in string literals (round-trip byte-loss)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: emitter normalises backslash counts in string literals (round-trip byte-loss)\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_2c50ae54a6ed47aa92320c3c9a40fdc2 | https://github.com/elevanaltd/octave-mcp/issues/434 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 30. security_permissions · 来源证据：bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-o…\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplic…\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_694f815fe5af49db82e637268c4346ca | https://github.com/elevanaltd/octave-mcp/issues/443 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 31. security_permissions · 来源证据：governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_6d91773d5074499aa595b7e38bddbb0d | https://github.com/elevanaltd/octave-mcp/issues/441 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 32. security_permissions · 来源证据：octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_7c17465d2f4a474e8516a911c69b6427 | https://github.com/elevanaltd/octave-mcp/issues/424 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 33. security_permissions · 来源证据：octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_86500177a232460e83ffd2da0f3bf682 | https://github.com/elevanaltd/octave-mcp/issues/420 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 34. capability · 失败模式：capability: bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this capability risk before relying on the project: bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)\n- User impact: Developers may hit a documented source-backed failure mode: bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only). Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_5da92869a244d36ecaf3e556113dc916 | https://github.com/elevanaltd/octave-mcp/issues/436 | bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)\n\n## 35. capability · 失败模式：conceptual: bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form...\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this conceptual risk before relying on the project: bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form-preservation gap)\n- User impact: Developers may hit a documented source-backed failure mode: bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form-preservation gap)\n- Suggested check: 复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_7310a80e89468fb4bd5c6e61aadaa05b | https://github.com/elevanaltd/octave-mcp/issues/447 | bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form-preservation gap)\n\n## 36. capability · 失败模式：conceptual: octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed/enforced\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this conceptual risk before relying on the project: octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed/enforced\n- User impact: Developers may hit a documented source-backed failure mode: octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed/enforced\n- Suggested check: 复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_8978c0e787312f231a947da5f5c4e156 | https://github.com/elevanaltd/octave-mcp/issues/427 | octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed/enforced, failure_mode_cluster:github_issue | fmev_ea0f8b5de25b570660810c386051af8e | https://github.com/elevanaltd/octave-mcp/issues/427 | octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed/enforced\n\n## 37. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | issue_or_pr_quality=unknown\n\n## 38. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | release_recency=unknown\n\n\n", "markdown_key": "octave-mcp", "pages": "draft", "source_refs": [ { "evidence_id": "art_03a23ce84d234d528c722af265f34ebc", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/elevanaltd/octave-mcp#readme" } ], "summary": "DeepWiki/Human Wiki output with a Doramagic pitfall appendix.", "title": "octave-mcp 说明书", "toc": [ "https://github.com/elevanaltd/octave-mcp 项目说明书", "目录", "Project Introduction", "Overview", "Core Concepts", "Architecture", "OCTAVE Syntax", "MCP Tools", "Doramagic 踩坑日志" ] } }, "quality_gate": { "blocking_gaps": [], "category_confidence": "medium", "compile_status": "ready_for_review", "five_assets_present": true, "install_sandbox_verified": true, "missing_evidence": [], "next_action": "publish to Doramagic.ai project surfaces", "prompt_preview_boundary_ok": true, "publish_status": "publishable", "quick_start_verified": true, "repo_clone_verified": true, "repo_commit": "a5c87b735599ad7cdf5c6bdb7ee6321ba34b30aa", "repo_inspection_error": null, "repo_inspection_files": [ "pyproject.toml", "README.md", "uv.lock", "docs/octave-quick-start.md", "docs/api.md", "docs/octave-spec-historical-review.md", "docs/usage.md", "docs/development.oct.md", "docs/mcp-configuration.md", "docs/adr/adr-0006-writer-reader-symmetry.md", "docs/adr/adr-0005-octave-v1.5-compiler-shift-operator-evolution.md", "docs/adr/adr-0006-sr1-t1-grammar-core-design.md", "docs/adr/adr-0283-chassis-profile-capability-tiering.md", "docs/adr/adr-0001-configurability-and-modularity-architecture.md", "docs/adr/adr-0003-generative-holographic-contracts.md", "docs/adr/adr-0002-schema-validation-using-octave-holographic-patterns.md", "docs/adr/adr-0006-g3-meta-audit-markers.md", "docs/adr/adr-0004-tool-consolidation-design.md", "docs/adr/adr-0006-sprint-2-addendum.md", "docs/adr/adr-0006-sr2-t2-ast-span-coverage-audit.md", "docs/guides/octave-expert-mcp-aware.oct.md", "docs/guides/cognitive-type-system.md", "docs/guides/mythological-compression.md", "docs/guides/octave-custom-instruction.oct.md", "docs/guides/octave-philosophy.oct.md", "docs/guides/README.md", "docs/guides/octave-custom-instruction-lite.md", "docs/guides/development-setup.md", "docs/guides/octave-philosophy.md", "docs/guides/octave-custom-instruction.md", "docs/blueprints/loss-accounting-hardening.md", "docs/research/comparitive-analysis-multi-agent-comms.oct.md", "docs/research/llm-native-encoding-patterns-research.oct.md", "docs/research/cross-model-operator-validation-study.md", "docs/research/compression-fidelity-round-trip-study.md", "docs/research/README.md", "docs/research/universal-llm-onboarding-architecture.oct.md", "docs/research/jit-literacy-injection-debate.oct.md", "docs/research/mythology-evidence-synthesis.oct.md", "docs/research/subagent-compression-study.md" ], "repo_inspection_verified": true, "review_reasons": [], "tag_count_ok": true, "unsupported_claims": [] }, "schema_version": "0.1", "user_assets": { "ai_context_pack": { "asset_id": "ai_context_pack", "filename": "AI_CONTEXT_PACK.md", "markdown": "# octave-mcp - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 octave-mcp 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`src/octave_mcp/resources/skills/octave-compression/SKILL.md`, `src/octave_mcp/resources/skills/octave-literacy/SKILL.md`, `src/octave_mcp/resources/skills/octave-mastery/SKILL.md`, `src/octave_mcp/resources/skills/octave-mythology/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`src/octave_mcp/resources/skills/octave-compression/SKILL.md`, `src/octave_mcp/resources/skills/octave-literacy/SKILL.md`, `src/octave_mcp/resources/skills/octave-mastery/SKILL.md`, `src/octave_mcp/resources/skills/octave-mythology/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `pip install octave-mcp` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `git clone https://github.com/elevanaltd/octave-mcp.git` 证据：`README.md` Claim：`clm_0006` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`src/octave_mcp/resources/skills/octave-compression/SKILL.md`, `src/octave_mcp/resources/skills/octave-literacy/SKILL.md`, `src/octave_mcp/resources/skills/octave-mastery/SKILL.md`, `src/octave_mcp/resources/skills/octave-mythology/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`src/octave_mcp/resources/skills/octave-compression/SKILL.md`, `src/octave_mcp/resources/skills/octave-literacy/SKILL.md`, `src/octave_mcp/resources/skills/octave-mastery/SKILL.md`, `src/octave_mcp/resources/skills/octave-mythology/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`src/octave_mcp/resources/skills/octave-compression/SKILL.md`, `src/octave_mcp/resources/skills/octave-literacy/SKILL.md`, `src/octave_mcp/resources/skills/octave-mastery/SKILL.md`, `src/octave_mcp/resources/skills/octave-mythology/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`src/octave_mcp/resources/skills/octave-compression/SKILL.md`, `src/octave_mcp/resources/skills/octave-literacy/SKILL.md`, `src/octave_mcp/resources/skills/octave-mastery/SKILL.md`, `src/octave_mcp/resources/skills/octave-mythology/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0007` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0008` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`src/octave_mcp/resources/skills/octave-compression/SKILL.md`, `src/octave_mcp/resources/skills/octave-literacy/SKILL.md`, `src/octave_mcp/resources/skills/octave-mastery/SKILL.md`, `src/octave_mcp/resources/skills/octave-mythology/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：458\n- 重要文件覆盖：40/458\n- 证据索引条目：80\n- 角色 / Skill 条目：5\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 octave-mcp 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 octave-mcp 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 octave-mcp 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 5 个角色 / Skill / 项目文档条目。\n\n- **octave-compression**（skill）：Workflow for transforming prose into semantic OCTAVE structures. Covers tier selection, transformation phases, loss accounting, and decision rules. REQUIRES octave-literacy. 激活提示：当用户任务与“octave-compression”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`src/octave_mcp/resources/skills/octave-compression/SKILL.md`\n- **octave-literacy**（skill）：LLM-native structured communication format. Teaches OCTAVE syntax rules, canonical forms, and warning prevention for zero-error .oct.md authoring. 激活提示：当用户任务与“octave-literacy”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`src/octave_mcp/resources/skills/octave-literacy/SKILL.md`\n- **octave-mastery**（skill）：Advanced semantic vocabulary, holographic contracts, and structural patterns for OCTAVE. REQUIRES octave-literacy. Extends literacy with mythology, archetype annotation, v6 contracts, and anti-pattern rules. 激活提示：当用户任务与“octave-mastery”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`src/octave_mcp/resources/skills/octave-mastery/SKILL.md`\n- **octave-mythology**（skill）：Functional mythological compression for OCTAVE Olympian Common Text And Vocabulary Engine documents. Semantic shorthand for LLM audiences, not prose decoration 激活提示：当用户任务与“octave-mythology”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`src/octave_mcp/resources/skills/octave-mythology/SKILL.md`\n- **octave-ultra-mythic**（skill）：Ultra-high density compression using mythological atoms and semantic shorthand for OCTAVE Olympian Common Text And Vocabulary Engine . Preserves soul and constraints at 60% compression for identity transmission, binding protocols, and extreme token scarcity. 激活提示：当用户任务与“octave-ultra-mythic”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`src/octave_mcp/resources/skills/octave-ultra-mythic/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **OCTAVE Guides**（documentation）：This directory contains conceptual documentation for OCTAVE Olympian Common Text And Vocabulary Engine . 证据：`docs/guides/README.md`\n- **OCTAVE: Empirical Evidence**（documentation）：This document provides a summary of the empirical evidence validating the effectiveness of the OCTAVE protocol. The findings are based on systematic testing across multiple large language models LLMs , complexity tiers, and content domains. 证据：`docs/research/README.md`\n- **.hestai/ -- Three-Tier Architecture**（documentation）：.hestai/ -- Three-Tier Architecture 证据：`.hestai/README.md`\n- **OCTAVE MCP Server**（documentation）：! License https://img.shields.io/badge/License-Apache 2.0-blue.svg https://opensource.org/licenses/Apache-2.0 ! Python 3.11+ https://img.shields.io/badge/python-3.11+-blue.svg https://www.python.org/downloads/ ! Tests https://img.shields.io/badge/tests-3003%20passing-brightgreen.svg ! PyPI https://img.shields.io/pypi/v/octave-mcp.svg https://pypi.org/project/octave-mcp/ 证据：`README.md`\n- **OCTAVE Examples**（documentation）：Examples demonstrating OCTAVE compression across different scales and domains. 证据：`examples/README.md`\n- **OCTAVE Primer Test Suite**（documentation）：Test protocol to verify the micro-primer enables direct OCTAVE emission with ~96% validity. 证据：`tests/README.md`\n- **OCTAVE Tools**（documentation）：Minimal utilities for OCTAVE validation and integration. 证据：`tools/README.md`\n- **OCTAVE Specifications Archive**（documentation）：Historical artifacts from OCTAVE v5 specification development December 2025 . 证据：`_archive/specs/README.md`\n- **OCTAVE + Repomix Integration**（documentation）：Boost AI code analysis accuracy by 10.2× with only 11.4% token overhead 证据：`examples/integrations/repomix/README.md`\n- **OCTAVE Templates**（documentation）：Ready-to-use templates for OCTAVE adoption. 证据：`examples/templates/README.md`\n- **OCTAVE Olympian Common Text And Vocabulary Engine Package Resources**（documentation）：OCTAVE Olympian Common Text And Vocabulary Engine Package Resources 证据：`src/octave_mcp/resources/README.md`\n- **OCTAVE JSON Schema**（documentation）：This document defines a standardized schema for implementing OCTAVE as JSON, enabling developers to integrate the semantic specification into JSON-based systems while preserving core OCTAVE concepts. 证据：`src/octave_mcp/resources/specs/schemas/json/README.md`\n- **Contributing to OCTAVE MCP**（documentation）：Thank you for your interest in contributing! 证据：`CONTRIBUTING.md`\n- **Skill**（skill_instruction）：===OCTAVE COMPRESSION=== META: TYPE::SKILL VERSION::\"3.0.0\" STATUS::ACTIVE PURPOSE::\"Decision rules and workflow for transforming prose into semantic OCTAVE at the correct fidelity tier\" REQUIRES::octave-literacy SPEC REFERENCE::octave-data-spec.oct.md --- §1::TIER SELECTION // Choose tier BEFORE reading source. Tier drives every subsequent decision. TIERS: LOSSLESS: TARGET::\"100% fidelity\" PRESERVE::everything DROP::nothing USE:: critical reasoning, legal documents, safety analysis, audit trails CONSERVATIVE: TARGET::\"85-90% fidelity\" PRESERVE::explanatory depth DROP::redundancy LOSS::\"10-15% repetition,verbose phrasing,some edge cases \" USE:: research summaries, design decisions, technica… 证据：`src/octave_mcp/resources/skills/octave-compression/SKILL.md`\n- **Skill**（skill_instruction）：===OCTAVE LITERACY=== META: TYPE::SKILL VERSION::\"3.0.0\" STATUS::ACTIVE PURPOSE::\"Zero-error OCTAVE authoring — syntax rules, canonical forms, warning prevention\" OCTAVE::\"Olympian Common Text And Vocabulary Engine — loss accounting system for LLM communication\" AUDIENCE::LLM SPEC REFERENCE::octave-core-spec.oct.md NEXT SKILLS:: octave-mastery,octave-compression --- §0::CONSUMPTION DIRECTIVE // You are writing for LLM consumption only. No prose. No narrative. Every token carries payload. // Optimize for parsing efficiency and token density. Readability is irrelevant. MYTHOLOGY::\"Use as compression — zero-shot, trust it. ATHENA = 1 token replacing 15.\" MYTHOLOGY ANTI PATTERN::\"ZEUS::executiv… 证据：`src/octave_mcp/resources/skills/octave-literacy/SKILL.md`\n- **Skill**（skill_instruction）：===OCTAVE MASTERY=== META: TYPE::SKILL VERSION::\"3.0.0\" STATUS::ACTIVE PURPOSE::\"Expert-level OCTAVE: mythology vocabulary, holographic contracts, archetype annotation, anti-patterns\" REQUIRES::octave-literacy SPEC REFERENCE::octave-core-spec.oct.md --- §1::SEMANTIC PANTHEON // Compression vocabulary — zero-shot, use directly. Literal term wins when equally clear. // Use as KEY prefixes ARTEMIS::latency p99 or PATTERN DESCRIPTORS SISYPHEAN DEBT . DOMAINS: ZEUS::\"Executive authority, final arbitration, strategic direction\" ATHENA::\"Strategic wisdom, planning, elegant solutions\" APOLLO::\"Analytics, insight, clarity, prediction\" HERMES::\"Communication, APIs, translation, messaging\" HEPHAESTUS:… 证据：`src/octave_mcp/resources/skills/octave-mastery/SKILL.md`\n- **Skill**（skill_instruction）：===OCTAVE MYTHOLOGY=== META: TYPE::SKILL VERSION::\"1.2.1\" STATUS::ACTIVE PURPOSE::\"Functional mythological semantic compression for OCTAVE documents\" PRINCIPLE::\"Compression shorthand for LLM audiences, not ceremonial prose\" EVIDENCE:: \"60-70% token reduction vs natural language\", \"88-96% cross-model zero-shot comprehension\", \"+17% structural sophistication blind assessments \", \"100% pattern recognition across 35 semantic elements\" SOURCE::octave-mcp docs/research/mythology-evidence-synthesis.oct.md TIER::LOSSLESS 证据：`src/octave_mcp/resources/skills/octave-mythology/SKILL.md`\n- **Skill**（skill_instruction）：===OCTAVE ULTRA MYTHIC=== META: TYPE::SKILL VERSION::\"1.2.1\" STATUS::ACTIVE PURPOSE::\"Ultra-high density compression using mythological atoms for identity and knowledge preservation\" REQUIRES:: octave-literacy, octave-mythology TIER::ULTRA MYTHIC SPEC REFERENCE::octave-data-spec.oct.md 证据：`src/octave_mcp/resources/skills/octave-ultra-mythic/SKILL.md`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **OCTAVE MCP Server - API Reference**（documentation）：Complete API reference for the OCTAVE MCP server, including MCP tools, Python modules, and CLI commands. 证据：`docs/api.md`\n- **Development.Oct**（documentation）：===OCTAVE MCP DEVELOPMENT=== META: TYPE::\"DEVELOPER DOC\" VERSION::\"1.0.0\" STATUS::ACTIVE PURPOSE::\"How to set up a local dev environment and run tests/quality gates\" 证据：`docs/development.oct.md`\n- **OCTAVE MCP Server - Configuration Guide**（documentation）：OCTAVE MCP Server - Configuration Guide 证据：`docs/mcp-configuration.md`\n- **OCTAVE Quick Start Guide**（documentation）：OCTAVE is a structured notation format optimized for LLM communication and agent-to-agent data exchange. It provides predictable parsing, semantic compression, and machine validation. 证据：`docs/octave-quick-start.md`\n- **OCTAVE Specification Historical Review**（documentation）：OCTAVE Specification Historical Review 证据：`docs/octave-spec-historical-review.md`\n- **OCTAVE MCP Server - Usage Guide**（documentation）：This guide provides detailed examples and workflows for using the OCTAVE MCP server in production. 证据：`docs/usage.md`\n- **B3 Integration Phase Report: OCTAVE MCP Server**（documentation）：B3 Integration Phase Report: OCTAVE MCP Server 证据：`_archive/docs/reports/b3-integration-report.md`\n- **OCTAVE MCP Server: Configurability and Modularity Analysis**（documentation）：OCTAVE MCP Server: Configurability and Modularity Analysis 证据：`_archive/docs/reports/configurability-analysis.md`\n- **OCTAVE MCP Server: Configurability Summary**（documentation）：OCTAVE MCP Server: Configurability Summary 证据：`_archive/docs/reports/configurability-summary.md`\n- **Build Plan.Oct**（documentation）：===OCTAVE MCP BUILD PLAN=== META: TYPE::BUILD PLAN VERSION::\"1.1.0\" STATUS::APPROVED DATE::\"2025-12-22\" PHASE:: B1 TASK DECOMPOSITION OCTAVE VERSION::\"5.1.0\" TOTAL TASKS::25 证据：`_archive/docs/workflow/build-plan.oct.md`\n- **ADR-001: Configurability and Modularity Architecture**（documentation）：ADR-001: Configurability and Modularity Architecture 证据：`docs/adr/adr-0001-configurability-and-modularity-architecture.md`\n- **ADR-002: Schema Validation Using OCTAVE Holographic Patterns**（documentation）：ADR-002: Schema Validation Using OCTAVE Holographic Patterns 证据：`docs/adr/adr-0002-schema-validation-using-octave-holographic-patterns.md`\n- **Adr 0003 Generative Holographic Contracts**（documentation）：===ADR 003 GENERATIVE HOLOGRAPHIC CONTRACTS=== META: TYPE::ARCHITECTURE DECISION VERSION::\"6.0.0\" STATUS::ACCEPTED DATE::\"2026-01-06\" 证据：`docs/adr/adr-0003-generative-holographic-contracts.md`\n- **ADR-004: OCTAVE-MCP Tool Consolidation GH 51**（documentation）：ADR-004: OCTAVE-MCP Tool Consolidation GH 51 证据：`docs/adr/adr-0004-tool-consolidation-design.md`\n- **ADR-005: OCTAVE v1.5 — Compiler Shift + Operator Evolution**（documentation）：ADR-005: OCTAVE v1.5 — Compiler Shift + Operator Evolution 证据：`docs/adr/adr-0005-octave-v1.5-compiler-shift-operator-evolution.md`\n- **ADR-0006 G3: META Envelope Schema Admission for Audit Markers**（documentation）：ADR-0006 G3: META Envelope Schema Admission for Audit Markers 证据：`docs/adr/adr-0006-g3-meta-audit-markers.md`\n- **ADR-0006 Sprint 2 Programme Addendum**（documentation）：ADR-0006 Sprint 2 Programme Addendum 证据：`docs/adr/adr-0006-sprint-2-addendum.md`\n- **ADR-0006 SR1-T1: Unified Grammar Core — Design Pass**（documentation）：ADR-0006 SR1-T1: Unified Grammar Core — Design Pass 证据：`docs/adr/adr-0006-sr1-t1-grammar-core-design.md`\n- **ADR-0006 SR2-T2 — AST Source-Span Coverage Audit Strategy A for GH 377**（documentation）：ADR-0006 SR2-T2 — AST Source-Span Coverage Audit Strategy A for GH 377 证据：`docs/adr/adr-0006-sr2-t2-ast-span-coverage-audit.md`\n- **ADR-0006: Writer/Reader Symmetry — Killing the octave validate / octave write Asymmetry**（documentation）：ADR-0006: Writer/Reader Symmetry — Killing the octave validate / octave write Asymmetry 证据：`docs/adr/adr-0006-writer-reader-symmetry.md`\n- **ADR-0283: Chassis-Profile Schema for Agent Capability Tiering**（documentation）：ADR-0283: Chassis-Profile Schema for Agent Capability Tiering 证据：`docs/adr/adr-0283-chassis-profile-capability-tiering.md`\n- **Blueprint: Loss Accounting Hardening**（documentation）：Blueprint: Loss Accounting Hardening 证据：`docs/blueprints/loss-accounting-hardening.md`\n- **The Cognitive Type System**（documentation）：OCTAVE agents are governed by a triadic cognitive architecture: LOGOS , ETHOS , and PATHOS . Each cognition type defines how an agent thinks -- distinct from what it does §2::OPERATIONAL BEHAVIOR or how it speaks §4::INTERACTION RULES . 证据：`docs/guides/cognitive-type-system.md`\n- **OCTAVE MCP Server - Development Setup**（documentation）：OCTAVE MCP Server - Development Setup 证据：`docs/guides/development-setup.md`\n- **The Mythological Compression Principle**（documentation）：The Mythological Compression Principle 证据：`docs/guides/mythological-compression.md`\n- **OCTAVE Custom Instruction — Lite**（documentation）：What this is: A compression-first custom instruction for any LLM. Paste it into Claude Projects, ChatGPT Custom GPTs, or any system prompt. Ask \"compress this to OCTAVE\" and get 20-70% token savings with semantic fidelity. What this is NOT: The full OCTAVE specification. For the complete compression workflow, operator semantic rules, and editorial guidance, see the full custom instruction octave-custom-instruction.md . For machine-validated output, use the OCTAVE-MCP server https://github.com/elevanaltd/octave-mcp . 证据：`docs/guides/octave-custom-instruction-lite.md`\n- **OCTAVE Custom Instruction Portable**（documentation）：What this is: Self-contained custom instruction for Claude Projects, ChatGPT, or any LLM system prompt. Enables OCTAVE document conversion without the MCP toolchain. What this is NOT: A production validator. For machine-validated, spec-compliant output, use the OCTAVE-MCP server https://github.com/elevanaltd/octave-mcp with octave validate and octave write tools. 证据：`docs/guides/octave-custom-instruction.md`\n- **Octave Custom Instruction.Oct**（documentation）：===OCTAVE CUSTOM INSTRUCTION=== META: TYPE::LLM PROFILE VERSION::\"1.0\" PURPOSE::\"Portable OCTAVE conversion instruction for any LLM\" COMPRESSION TIER::CONSERVATIVE LOSS PROFILE::\"platform notes reduced∧marketing trimmed∧output mode added\" PRODUCTION VALIDATION::\"For spec-compliant output use OCTAVE-MCP server github.com/elevanaltd/octave-mcp \" --- // SYSTEM COMMAND: You know the OCTAVE format. Answer normally unless the user requests conversion. // Only emit OCTAVE when explicitly asked. Never OCTAVE-ify unprompted. // NOTE: META COMPRESSION TIER describes this document's compression level. User-facing default is in §11. §1::ROLE IDENTITY::\"OCTAVE conversion specialist\" FORMAT::\"OCTAVE Olym… 证据：`docs/guides/octave-custom-instruction.oct.md`\n- **Octave Expert Mcp Aware.Oct**（documentation）：===OCTAVE EXPERT=== META: TYPE::LLM PROFILE VERSION::\"1.0\" PURPOSE::\"OCTAVE expertise layer for MCP-equipped agents\" COMPRESSION TIER::CONSERVATIVE LOSS PROFILE::\"syntax rules delegated to mcp∧editorial judgment preserved∧mythology as domain labels\" REQUIRES::\"octave-mcp server octave validate, octave write, octave eject \" NARRATIVE DEPTH::CONSERVATIVE MYTH --- // OCTAVE Expert — for environments WITH the MCP toolchain. // Tools handle syntax, validation, schema enforcement. // This instruction handles judgment, compression craft, and naming. // NOTE: META COMPRESSION TIER describes this document's compression level. User-facing default is in §7. §1::ROLE IDENTITY::\"OCTAVE expert with MCP t… 证据：`docs/guides/octave-expert-mcp-aware.oct.md`\n- **The Philosophy of OCTAVE: Writing for Value**（documentation）：The Philosophy of OCTAVE: Writing for Value 证据：`docs/guides/octave-philosophy.md`\n- **Octave Philosophy.Oct**（documentation）：===OCTAVE PHILOSOPHY=== META: TYPE::GUIDE VERSION::\"1.0\" PURPOSE::\"Anti-patterns and quality principles for effective OCTAVE\" §1::GOLDEN RULE LITMUS::\"If your OCTAVE were a database schema, would it have foreign keys?\" MEANING::\"Flat lists provide information. Relationship networks provide understanding.\" MANDATE::\"Show how elements connect, influence, depend\" §2::SEVEN DEADLY SMELLS ISOLATED LISTS: SYMPTOM::\"Array items without explicit relationships\" IMPACT::\"LLM knows WHAT, not HOW they connect\" FIX::\"Hierarchy with relationship keys ENABLES, CONFLICTS WITH \" CEREMONY OVERFLOW: SYMPTOM::\"Prose, metaphors, comments everywhere\" IMPACT::\"Signal vs Noise. LLMs extract from structure, not poe… 证据：`docs/guides/octave-philosophy.oct.md`\n- **OCTAVE Asterisk Notation Validation Report**（documentation）：OCTAVE Asterisk Notation Validation Report Test Date: 2025-06-16 Test Type: Zero-Shot Comprehension of Non-Asterisked Elements Models Tested: 10 证据：`docs/research/01_comprehension_and_validation/asterisk-validation-report.md`\n- **OCTAVE Evaluation Bias Report**（documentation）：Date: 2025-07-15 Context: Agent Capability Streamlining Session Phenomenon: Contradictory LLM assessments of OCTAVE format effectiveness 证据：`docs/research/01_comprehension_and_validation/octave-evaluation-bias-report.md`\n- **OCTAVE Mythological Semantics Comprehension Test Results**（documentation）：OCTAVE Mythological Semantics Comprehension Test Results 证据：`docs/research/01_comprehension_and_validation/octave-mythological-semantics-comprehension-test-2025-06-19.md`\n- **OCTAVE Protocol Validation Summary**（documentation）：A comprehensive review of the OCTAVE protocol implementation and empirical evidence has been conducted. Based on extensive multi-model testing, benchmarking, and structural analysis, OCTAVE delivers measurable performance benefits as an LLM-to-LLM communication protocol, with proven advantages in information density, cross-domain translation, and relationship representation. 证据：`docs/research/01_comprehension_and_validation/octave-validation-summary.md`\n- **OCTAVE Protocol: Comprehensive Empirical Assessment**（documentation）：OCTAVE Protocol: Comprehensive Empirical Assessment 证据：`docs/research/02_benchmarking_and_generation/octave-benchmarking-evidence.md`\n- **OCTAVE Generation Analysis**（documentation）：Document Type: Empirical Study Date: January 19, 2025 Focus: LLM capability to generate OCTAVE format responses Status: Analysis complete 证据：`docs/research/02_benchmarking_and_generation/octave-generation-analysis-2025.md`\n- **OCTAVE Secretary — Definitive Conclusions**（documentation）：OCTAVE Secretary — Definitive Conclusions 证据：`docs/research/02_benchmarking_and_generation/octave-secretary-conclusions-2026-04-09.md`\n- **OCTAVE Specialist Model Comparison Test**（documentation）：OCTAVE Specialist Model Comparison Test 证据：`docs/research/02_benchmarking_and_generation/octave-specialist-model-comparison-2026-04-06.md`\n- **OCTAVE Specialist Model Comparison — Round 2: octave write**（documentation）：OCTAVE Specialist Model Comparison — Round 2: octave write 证据：`docs/research/02_benchmarking_and_generation/octave-specialist-octave-write-benchmark-2026-04-06.md`\n- **OCTAVE Specialist Round 3 — Controlled Model Comparison**（documentation）：OCTAVE Specialist Round 3 — Controlled Model Comparison 证据：`docs/research/02_benchmarking_and_generation/octave-specialist-r3-controlled-comparison-2026-04-08.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/guides/README.md`, `docs/research/README.md`, `.hestai/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/guides/README.md`, `docs/research/README.md`, `.hestai/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\nThe following material strengthens the Repomix/AI Context Pack body. Human Manual is only a reading skeleton; pitfall logs become hard operating constraints for the host AI.\n\n## Human Manual Skeleton\n\nUsage rule: this is only a reading path and salience signal, not factual authority. Concrete facts must still come from repo evidence / Claim Graph.\n\nHard rules for the host AI:\n- Do not treat page titles, order, summaries, or importance as project facts.\n- When explaining the Human Manual skeleton, state that it is only a reading path / salience signal.\n- Capability, installation, compatibility, runtime status, and risk judgments must cite repo evidence, source paths, or Claim Graph.\n\n- **Project Introduction**：importance `high`\n - source_paths: README.md, src/octave_mcp/__init__.py, AGENTS.oct.md\n- **Project File Structure**：importance `medium`\n - source_paths: CONTRIBUTING.md, src/octave_mcp, docs\n- **System Architecture**：importance `high`\n - source_paths: src/octave_mcp/mcp/server.py, src/octave_mcp/mcp/http_transport.py, src/octave_mcp/integrations/llama_cpp.py, src/octave_mcp/integrations/vllm.py, src/octave_mcp/integrations/outlines.py\n- **Canonical Normalization**：importance `high`\n - source_paths: src/octave_mcp/core/lexer.py, src/octave_mcp/core/parser.py, src/octave_mcp/core/emitter.py, src/octave_mcp/core/grammar/tier_normalize.py, src/octave_mcp/core/grammar/cst.py\n- **Schema Validation**：importance `high`\n - source_paths: src/octave_mcp/core/validator.py, src/octave_mcp/core/schema_extractor.py, src/octave_mcp/schemas/loader.py, src/octave_mcp/schemas/builtin/meta.oct.md, src/octave_mcp/schemas/builtin/skill.oct.md\n- **Compression System**：importance `high`\n - source_paths: src/octave_mcp/core/literal_zone_audit.py, src/octave_mcp/core/holographic.py, src/octave_mcp/core/sealer.py, src/octave_mcp/core/repair.py, docs/guides/mythological-compression.md\n- **Grammar Compilation**：importance `medium`\n - source_paths: src/octave_mcp/core/gbnf_compiler.py, src/octave_mcp/core/grammar_compiler/gbnf.py, src/octave_mcp/mcp/compile_grammar.py, docs/grammar/octave-v1.0-grammar.ebnf\n- **MCP Tools Reference**：importance `high`\n - source_paths: src/octave_mcp/mcp/validate.py, src/octave_mcp/mcp/write.py, src/octave_mcp/mcp/eject.py, src/octave_mcp/mcp/compile_grammar.py, src/octave_mcp/mcp/base_tool.py\n\n## Repo Inspection Evidence\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `a5c87b735599ad7cdf5c6bdb7ee6321ba34b30aa`\n- inspected_files: `pyproject.toml`, `README.md`, `uv.lock`, `docs/octave-quick-start.md`, `docs/api.md`, `docs/octave-spec-historical-review.md`, `docs/usage.md`, `docs/development.oct.md`, `docs/mcp-configuration.md`, `docs/adr/adr-0006-writer-reader-symmetry.md`, `docs/adr/adr-0005-octave-v1.5-compiler-shift-operator-evolution.md`, `docs/adr/adr-0006-sr1-t1-grammar-core-design.md`, `docs/adr/adr-0283-chassis-profile-capability-tiering.md`, `docs/adr/adr-0001-configurability-and-modularity-architecture.md`, `docs/adr/adr-0003-generative-holographic-contracts.md`, `docs/adr/adr-0002-schema-validation-using-octave-holographic-patterns.md`, `docs/adr/adr-0006-g3-meta-audit-markers.md`, `docs/adr/adr-0004-tool-consolidation-design.md`, `docs/adr/adr-0006-sprint-2-addendum.md`, `docs/adr/adr-0006-sr2-t2-ast-span-coverage-audit.md`\n\nHard rules for the host AI:\n- Without repo_clone_verified=true, do not claim the source code has been read.\n- Without repo_inspection_verified=true, do not turn README/docs/package observations into facts.\n- Without quick_start_verified=true, do not claim the Quick Start has been successfully run.\n\n## Doramagic Pitfall Constraints\n\nThese rules come from Doramagic discovery, validation, or compilation pitfalls. The host AI must treat them as operating constraints, not general background notes.\n\n### Constraint 1: 失败模式：security_permissions: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oc...\n\n- Trigger: Developers should check this security_permissions risk before relying on the project: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md. Context: Source discussion did not expose a precise runtime context.\n- Why it matters: Developers may expose sensitive permissions or credentials: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md\n- Evidence: failure_mode_cluster:github_issue | fmev_22c0329bf698546f57cbd9edd620083f | https://github.com/elevanaltd/octave-mcp/issues/424 | octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 2: 失败模式：security_permissions: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)\n\n- Trigger: Developers should check this security_permissions risk before relying on the project: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38). Context: Source discussion did not expose a precise runtime context.\n- Why it matters: Developers may expose sensitive permissions or credentials: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)\n- Evidence: failure_mode_cluster:github_issue | fmev_e63e5f9a96f8ad23bef9d32f6c4c13e7 | https://github.com/elevanaltd/octave-mcp/issues/420 | octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 3: 来源证据：bug: octave_write surgical edit primitives unsafe on inline-array top-level entries (APPEND + expanded modes)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: octave_write surgical edit primitives unsafe on inline-array top-level entries (APPEND + expanded modes)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_75dbe0c2c20b479a9afc619c467acc20 | https://github.com/elevanaltd/octave-mcp/issues/411 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 4: 来源证据：octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_744a11a12c0340e08087ea951c281000 | https://github.com/elevanaltd/octave-mcp/issues/426 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 5: 失败模式：installation: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed findin...\n\n- Trigger: Developers should check this installation risk before relying on the project: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks. Context: Source discussion did not expose a precise runtime context.\n- Why it matters: Developers may fail before the first successful local run: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks\n- Evidence: failure_mode_cluster:github_issue | fmev_8ff9088f7d6c1752dffdf17a7dd320db | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks, failure_mode_cluster:github_issue | fmev_aa61ed66e510ebfae83228fb28ae6e11 | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks, failure_mode_cluster:github_issue | fmev_6046cbe1d9f5946d7c5f3b4a9e75cd5a | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks, failure_mode_cluster:github_issue | fmev_6450b53644007e96c1fa966585fe47ea | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 6: 失败模式：installation: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type doc...\n\n- Trigger: Developers should check this installation risk before relying on the project: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents. Context: Source discussion did not expose a precise runtime context.\n- Why it matters: Developers may fail before the first successful local run: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents\n- Evidence: failure_mode_cluster:github_issue | fmev_9d395f7455d912516430481376e952e2 | https://github.com/elevanaltd/octave-mcp/issues/425 | octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 7: 来源证据：bug: _find_target_start backslash-run quote-escape mishandling (sibling of cubic P1 on PR #431)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: _find_target_start backslash-run quote-escape mishandling (sibling of cubic P1 on PR #431)\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_8284755b0fa74799b1f881f624677141 | https://github.com/elevanaltd/octave-mcp/issues/432 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 8: 失败模式：configuration: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describi...\n\n- Trigger: Developers should check this configuration risk before relying on the project: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty)\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty). Context: Observed when using python\n- Why it matters: Developers may misconfigure credentials, environment, or host setup: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty)\n- Evidence: failure_mode_cluster:github_issue | fmev_c368f015439226dbb8b9c45fddf3158d | https://github.com/elevanaltd/octave-mcp/issues/430 | RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty)\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 9: 失败模式：configuration: bug: emitter normalises backslash counts in string literals (round-trip byte-loss)\n\n- Trigger: Developers should check this configuration risk before relying on the project: bug: emitter normalises backslash counts in string literals (round-trip byte-loss)\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: bug: emitter normalises backslash counts in string literals (round-trip byte-loss). Context: Source discussion did not expose a precise runtime context.\n- Why it matters: Developers may misconfigure credentials, environment, or host setup: bug: emitter normalises backslash counts in string literals (round-trip byte-loss)\n- Evidence: failure_mode_cluster:github_issue | fmev_bbc57f3d1a93f9e5fb48332874044f35 | https://github.com/elevanaltd/octave-mcp/issues/434 | bug: emitter normalises backslash counts in string literals (round-trip byte-loss)\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 10: 失败模式：configuration: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only pat...\n\n- Trigger: Developers should check this configuration risk before relying on the project: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue)\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue). Context: Source discussion did not expose a precise runtime context.\n- Why it matters: Developers may misconfigure credentials, environment, or host setup: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue)\n- Evidence: failure_mode_cluster:github_issue | fmev_cf23dec47765d23b75fcd69bef5c1332 | https://github.com/elevanaltd/octave-mcp/issues/433 | bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue)\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n", "summary": "Context and operating boundaries for host AI agents.", "title": "AI Context Pack" }, "boundary_risk_card": { "asset_id": "boundary_risk_card", "filename": "BOUNDARY_RISK_CARD.md", "markdown": "# Boundary & Risk Card\n\nProject: elevanaltd/octave-mcp\n\n## Doramagic Trial Decision\n\nCurrent decision: it can enter pre-publication recommendation checks. First use should still start with least privilege, a temporary directory, and reversible configuration.\n\n## What The User Can Do Now\n\n- Read the Human Manual first to understand the project purpose and main workflows.\n- Use Prompt Preview for pre-install exploration; it validates interaction shape, not real execution.\n- Run official Quick Start commands only inside an isolated environment, not a primary setup.\n\n## Do Not Do Yet\n\n- Do not treat Prompt Preview as a real project execution result.\n- Do not treat metadata-only validation as sandbox installation validation.\n- Do not describe unverified capabilities as supported, working, or safe to install.\n- Do not provide production data, private files, real secrets, or primary host configuration on first trial.\n\n## Pre-Install Checklist\n\n- Host AI match: mcp_host\n- Official installation entry status: official entry point found\n- Isolated temporary directory, temporary host, or container validation: required\n- Configuration rollback path: required\n- API keys, network access, file access, or host configuration changes: treat as high risk until confirmed\n- Installation command, actual output, and failure logs: must be recorded\n\n## Current Blockers\n\n- No blockers.\n\n## Project-Specific Pitfalls\n\n- 失败模式：security_permissions: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oc... (high): Developers may expose sensitive permissions or credentials: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md. Context: Source discussion did not expose a precise runtime context.\n- 失败模式：security_permissions: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38) (high): Developers may expose sensitive permissions or credentials: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38) Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38). Context: Source discussion did not expose a precise runtime context.\n- 来源证据：bug: octave_write surgical edit primitives unsafe on inline-array top-level entries (APPEND + expanded modes) (high): 可能影响升级、迁移或版本选择。 Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks (high): 可能阻塞安装或首次运行。 Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 失败模式：installation: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed findin... (medium): Developers may fail before the first successful local run: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks. Context: Source discussion did not expose a precise runtime context.\n\n## Risk And Permission Notes\n\n- no_demo: medium\n\n## Evidence Gaps\n\n- No structured evidence gaps are currently visible.\n", "summary": "Installation, permission, validation, and pre-recommendation risks.", "title": "Boundary & Risk Card" }, "human_manual": { "asset_id": "human_manual", "filename": "HUMAN_MANUAL.md", "markdown": "# https://github.com/elevanaltd/octave-mcp 项目说明书\n\n生成时间：2026-05-16 03:50:43 UTC\n\n## 目录\n\n- [Project Introduction](#page-project-introduction)\n- [Project File Structure](#page-file-structure)\n- [System Architecture](#page-system-architecture)\n- [Canonical Normalization](#page-canonical-normalization)\n- [Schema Validation](#page-schema-validation)\n- [Compression System](#page-compression-system)\n- [Grammar Compilation](#page-grammar-compilation)\n- [MCP Tools Reference](#page-mcp-tools)\n- [CLI Interface](#page-cli-interface)\n- [Python API Reference](#page-python-api)\n\n\n\n## Project Introduction\n\n### 相关页面\n\n相关主题：[System Architecture](#page-system-architecture), [Canonical Normalization](#page-canonical-normalization)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n- [src/octave_mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/__init__.py)\n- [tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)\n- [src/octave_mcp/core/parser.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/parser.py)\n- [src/octave_mcp/core/validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/validator.py)\n- [src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)\n
\n\n# Project Introduction\n\n## Overview\n\nOctave-MCP (Olympian Common Text And Vocabulary Engine - Model Context Protocol) is a semantic DSL (Domain Specific Language) framework designed for structured document creation, validation, and transformation in LLM workflows. It provides a unified text format with rich semantic annotations that enables precise machine-readable documentation while remaining human-readable.\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n## Core Concepts\n\n### What is OCTAVE?\n\nOCTAVE stands for **Olympian Common Text And Vocabulary Engine**. It is a semantic DSL specifically designed for Large Language Models (LLMs) that bridges the gap between human-readable documentation and machine-processable structured data.\n\nThe framework operates on a **patterns → archetypes → holographic** methodology, where semantic patterns are mapped to recognizable archetypes which then create holographic constraints for validation and processing.\n\n资料来源：[src/octave_mcp/resources/primers/octave-mastery-primer.oct.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/primers/octave-mastery-primer.oct.md)\n\n### Key Features\n\n| Feature | Description |\n|---------|-------------|\n| **Semantic DSL** | Domain-specific language with typed syntax for structured documents |\n| **MCP Integration** | Model Context Protocol server for tool-based access |\n| **CLI Tools** | Command-line utilities for validation and transformation |\n| **Grammar Compilation** | GBNF grammar generation for constrained text generation |\n| **Validation Pipeline** | Multi-stage validation with repair suggestions |\n| **Holographic Patterns** | Constraint-based field validation with logical operators |\n\n## Architecture\n\n### System Components\n\n```mermaid\ngraph TD\n A[OCTAVE Documents] --> B[Parser Layer]\n B --> C[Grammar Compiler]\n B --> D[Validator]\n C --> E[GBNF Grammar Output]\n D --> F[Validation Results]\n B --> G[Writer/Reader]\n G --> H[Normalized Output]\n \n I[MCP Tools] --> J[octave_validate]\n I --> K[octave_write]\n I --> L[octave_eject]\n I --> M[octave_compile_grammar]\n \n N[CLI] --> O[octave validate]\n N --> P[octave write]\n N --> Q[octave eject]\n```\n\n### Package Structure\n\nThe main package resides in `src/octave_mcp/` with the following core modules:\n\n| Module | Purpose |\n|--------|---------|\n| `core/parser.py` | Parses OCTAVE documents into AST |\n| `core/validator.py` | Validates documents against schemas |\n| `core/grammar_compiler/` | Compiles schemas to GBNF grammar |\n| `core/holographic.py` | Handles holographic constraint patterns |\n| `mcp/write.py` | MCP tool implementation for writing files |\n\n资料来源：[src/octave_mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/__init__.py)\n\n## OCTAVE Syntax\n\n### Document Structure\n\nAn OCTAVE document follows a specific envelope format:\n\n```octave\n===DOCUMENT_NAME===\nMETA:\n TYPE::\"DOCUMENT_TYPE\"\n VERSION::\"1.0.0\"\n PURPOSE::\"Document purpose description\"\n---\n// Section content\nFIELD::\"value\"\nFIELD::[list_value]\n===END===\n```\n\n### Core Operators\n\n| Operator | Meaning | Example |\n|----------|---------|---------|\n| `::` | Assignment/definition | `KEY::VALUE` |\n| `→` | Flow/sequence | `AUTH::login→validate→dashboard` |\n| `⊕` | Synthesis/combine | `A⊕B` |\n| `⇌` | Tension/opposition | `security⇌usability` |\n| `[]` | List definition | `FIELD::[\"item1\",\"item2\"]` |\n| `∧` | Logical AND constraint | `[\"value\"∧ENUM[A,B]]` |\n| `§` | Section reference | `§TARGET` |\n\n资料来源：[src/octave_mcp/resources/primers/octave-compression-primer.oct.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/primers/octave-compression-primer.oct.md)\n\n### Holographic Constraints\n\nHolographic patterns provide powerful constraint validation:\n\n```octave\nFIELD::[\"value\"∧REQ∧ENUM[OPTION_A,OPTION_B]]\n```\n\nThis pattern specifies that `FIELD` is required (`REQ`) and must be one of the enumerated options.\n\n资料来源：[src/octave_mcp/core/gbnf_compiler.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/gbnf_compiler.py)\n\n## MCP Tools\n\nOctave-MCP provides Model Context Protocol tools for integration with AI assistants:\n\n| Tool | Function |\n|------|----------|\n| `octave_validate` | Validate documents against schema; provides field errors and repair suggestions |\n| `octave_write` | Write files through full validation pipeline |\n| `octave_eject` | Project documents to different views (canonical, executive, developer, template) |\n| `octave_compile_grammar` | Compile schema constraints to GBNF grammar |\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n### MCP Configuration\n\n**Claude Desktop Configuration:**\n\n```json\n{\n \"mcpServers\": {\n \"octave\": {\n \"command\": \"octave-mcp-server\"\n }\n }\n}\n```\n\n**HTTP Transport:**\n\n```bash\noctave-mcp-server --transport http --port 8080\n```\n\n## CLI Tools\n\n### Installation\n\n```bash\n# Install the package\npip install octave-mcp\n\n# Verify installation\noctave --version\n```\n\n### Available Commands\n\n| Command | Description |\n|---------|-------------|\n| `octave validate ` | Validate an OCTAVE document |\n| `octave write ` | Write output through validation pipeline |\n| `octave eject ` | Export document in alternate format |\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n### Standalone Validation Tools\n\nLocated in the `tools/` directory:\n\n| Tool | Purpose |\n|------|---------|\n| `lint-octave.py` | Fast syntax validation |\n| `octave-to-json.py` | Convert OCTAVE to JSON |\n| `json-to-octave.py` | Convert JSON back to OCTAVE |\n| `octave-validator.py` | Full document validation |\n\n资料来源：[tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)\n\n## Validation System\n\n### Validation Process\n\n```mermaid\ngraph LR\n A[Document Input] --> B[Lexer]\n B --> C[Parser]\n C --> D[AST]\n D --> E[Schema Validator]\n E --> F{Valid?}\n F -->|Yes| G[Validation Passed]\n F -->|No| H[Error Report]\n H --> I[Repair Suggestions]\n```\n\n### Validator Features\n\nThe validation system provides:\n\n- **Field-level error reporting** with line numbers\n- **Repair suggestions** for common issues\n- **Zone coverage analysis** for document completeness\n- **Semantic validation** against holographic constraints\n\n资料来源：[src/octave_mcp/core/validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/validator.py)\n\n### Audit Patterns\n\nThe validator recognizes specific audit-related field prefixes:\n\n| Pattern Prefix | Purpose |\n|----------------|---------|\n| `NON_CANONICAL_` | Non-canonical normalization fields |\n| `DEGRADED_` | Degraded state indicators |\n| `NORMALIZED_` | Normalization metadata |\n| `ROUNDTRIP_` | Roundtrip conversion fields |\n\nThese patterns allow controlled admission of non-standard fields during validation.\n\n资料来源：[src/octave_mcp/core/validator.py:line-range](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/validator.py)\n\n## Grammar Compilation\n\n### GBNF Generation\n\nThe grammar compiler transforms OCTAVE schemas into GBNF (Greibach Normal Form) grammar for constrained text generation:\n\n```python\nfrom octave_mcp.core.grammar_compiler import compile_document_grammar\n\nschema = SchemaDefinition(name=\"DOCUMENT_TYPE\", version=\"1.0\")\ngbnf = compile_document_grammar(schema)\n```\n\nThis enables LLMs to generate valid OCTAVE documents through constrained decoding.\n\n资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/__init__.py)\n\n### CONTRACT Extraction\n\nThe grammar compiler can extract field specifications from META `CONTRACT` definitions:\n\n```octave\nMETA:\n CONTRACT::[\n \"FIELD[NAME]::REQ∧ENUM[A,B]\",\n \"FIELD[STATUS]::OPT\"\n ]\n```\n\nEach contract entry is parsed into structured field definitions with holographic constraints.\n\n资料来源：[src/octave_mcp/core/gbnf_compiler.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/gbnf_compiler.py)\n\n## Use Cases\n\n### When to Use Octave-MCP\n\n| Scenario | Recommended |\n|----------|-------------|\n| Multi-agent document workflows | ✅ Yes |\n| Agent and skill file definitions | ✅ Yes |\n| Decision logs and audit trails | ✅ Yes |\n| System prompts with token optimization | ✅ Yes |\n| Single-step freeform prompts | ❌ No |\n| Code output generation | ❌ No |\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n### Document Types\n\nOctave-MCP supports structured document types including:\n\n- **SESSION_LOG** - Conversation session records\n- **DECISION** - Decision documentation\n- **AGENT** - Agent definitions\n- **SKILL** - Skill specifications\n- **PATTERN** - Pattern definitions\n\n## Integration Examples\n\n### With Claude Code\n\n```bash\n# Generate enhanced context\nrepomix --style xml --output context.xml\npython octave_enhance_targeted.py context.xml enhanced.xml\n\n# Paste enhanced.xml content into Claude Code session\n```\n\n### With Repomix Enhancement\n\nThe `examples/integrations/repomix/` directory provides scripts for:\n\n- **Targeted enhancement** - Focus on key files\n- **Comprehensive enhancement** - Full codebase analysis\n\nEnhanced contexts add semantic annotations like:\n\n```octave\n===FILE_PROCESSOR===\nMETA:\n PURPOSE::\"Process files\"\n PATTERN::PIPELINE\n===END===\n```\n\n资料来源：[examples/integrations/repomix/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/examples/integrations/repomix/README.md)\n\n## Additional Resources\n\n| Resource | Location |\n|----------|----------|\n| Usage Guide | [docs/usage.md](docs/usage.md) |\n| API Reference | [docs/api.md](docs/api.md) |\n| MCP Configuration | [docs/mcp-config.md](docs/mcp-config.md) |\n| Primers | [src/octave_mcp/resources/primers/](src/octave_mcp/resources/primers/) |\n| Skills | [src/octave_mcp/resources/skills/](src/octave_mcp/resources/skills/) |\n\n---\n\n\n\n## Project File Structure\n\n### 相关页面\n\n相关主题：[Project Introduction](#page-project-introduction), [System Architecture](#page-system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n- [src/octave_mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/__init__.py)\n- [src/octave_mcp/resources/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/README.md)\n- [tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)\n- [src/octave_mcp/mcp/grammar_resources.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/grammar_resources.py)\n- [src/octave_mcp/core/grammar_compiler/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/__init__.py)\n- [standards/L3-AGENT-FORMAT.oct.md](https://github.com/elevanaltd/octave-mcp/blob/main/standards/L3-AGENT-FORMAT.oct.md)\n
\n\n# Project File Structure\n\n## Overview\n\nThe `octave-mcp` project is organized as a Python package implementing the **Olympian Common Text And Vocabulary Engine (OCTAVE)** — a semantic DSL designed for LLM document processing. The repository follows a modular structure that separates core parsing logic, MCP (Model Context Protocol) server implementation, resource definitions, utilities, and documentation.\n\n## Directory Architecture\n\n```mermaid\ngraph TD\n A[octave-mcp Root] --> B[src/octave_mcp/]\n A --> C[tools/]\n A --> D[examples/]\n A --> E[standards/]\n A --> F[docs/]\n \n B --> B1[core/]\n B --> B2[mcp/]\n B --> B3[resources/]\n \n B1 --> B1a[grammar_compiler/]\n B1 --> B1b[parser/]\n B1 --> B1c[validator/]\n \n B2 --> B2a[write.py]\n B2 --> B2b[grammar_resources.py]\n \n B3 --> B3a[primers/]\n B3 --> B3b[specs/]\n B3 --> B3c[skills/]\n B3 --> B3d[vocabularies/]\n```\n\n## Root Directory Structure\n\n| File/Directory | Purpose |\n|----------------|---------|\n| `README.md` | Main project documentation, MCP server setup, and usage guide |\n| `CONTRIBUTING.md` | Guidelines for contributors |\n| `pyproject.toml` | Python package configuration |\n| `src/octave_mcp/` | Main package source code |\n| `tools/` | Standalone CLI utilities for OCTAVE validation |\n| `examples/` | Integration examples and compression tier demonstrations |\n| `standards/` | OCTAVE format standards and schemas |\n| `docs/` | Additional documentation files |\n\n## Source Code (`src/octave_mcp/`)\n\nThe main package contains three primary submodules:\n\n### Core Module (`src/octave_mcp/core/`)\n\nContains the fundamental parsing and validation logic.\n\n| Submodule | Purpose |\n|-----------|---------|\n| `parser/` | Lexer and parser implementations |\n| `validator/` | Schema validation engine |\n| `grammar_compiler/` | GBNF grammar compilation for constrained generation |\n\nThe `grammar_compiler` package was renamed from `octave_mcp.core.grammar` to resolve a naming collision, as documented in ADR-0006. It provides the public API:\n\n```python\nfrom octave_mcp.core.grammar_compiler import compile_document_grammar, emit_grammar_for_schema\n```\n\n资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py:1-18]()\n\n### MCP Module (`src/octave_mcp/mcp/`)\n\nImplements the Model Context Protocol server and tools.\n\n| File | Purpose |\n|------|---------|\n| `write.py` | MCP tool for writing OCTAVE files with full validation pipeline |\n| `grammar_resources.py` | Dynamic grammar resource templates for MCP |\n\nThe `grammar_resources.py` module provides:\n\n- Resource templates for accessing pre-compiled GBNF grammars\n- Dynamic schema compilation with caching\n- URI template access via `octave://grammars/{schema_name}`\n\n资料来源：[src/octave_mcp/mcp/grammar_resources.py:1-80]()\n\n### Resources Module (`src/octave_mcp/resources/`)\n\nContains distributable OCTAVE resources used by implementers and agents.\n\n```mermaid\ngraph LR\n A[resources/] --> B[primers/]\n A --> C[specs/]\n A --> D[skills/]\n A --> E[vocabularies/]\n \n B --> B1[octave-literacy-primer]\n B --> B2[octave-compression-primer]\n B --> B3[octave-mastery-primer]\n B --> B4[octave-ultra-mythic-primer]\n \n C --> C1[octave-core-spec.oct.md]\n C --> C2[octave-agents-spec.oct.md]\n C --> C3[octave-skills-spec.oct.md]\n C --> C4[schemas/]\n \n D --> D1[octave-compression/SKILL.md]\n \n E --> E1[registry.oct.md]\n E --> E2[core/]\n```\n\n#### Primers (`primers/`)\n\nSelf-referential training documents that teach OCTAVE syntax:\n\n| Primer | Version | Purpose |\n|--------|---------|---------|\n| `octave-literacy-primer.oct.md` | 6.0.0 | Basic OCTAVE literacy |\n| `octave-compression-primer.oct.md` | 6.0.0 | Prose-to-OCTAVE transformation |\n| `octave-mastery-primer.oct.md` | 6.1.0 | Advanced pattern mastery |\n| `octave-ultra-mythic-primer.oct.md` | 6.2.0 | Ultra-compression techniques |\n\n#### Specs (`specs/`)\n\nOfficial OCTAVE v6.0.0 specifications:\n\n| Specification | Description |\n|---------------|-------------|\n| `octave-core-spec.oct.md` | Core syntax, operators, and type system |\n| `octave-agents-spec.oct.md` | Agent architecture patterns |\n| `octave-skills-spec.oct.md` | Skill document format |\n| `octave-data-spec.oct.md` | Data compression tiers |\n| `octave-execution-spec.oct.md` | Execution flow and protocols |\n| `octave-schema-spec.oct.md` | Schema validation framework |\n| `octave-rationale-spec.oct.md` | Design rationale |\n| `octave-primers-spec.oct.md` | Primer specification |\n| `octave-mcp-architecture.oct.md` | MCP implementation architecture |\n\n#### Schemas (`specs/schemas/`)\n\nSchema definitions including:\n\n- `debate_transcript.oct.md` - Debate transcript schema\n- `json/` - JSON Schema for OCTAVE\n\n#### Vocabularies (`specs/vocabularies/`)\n\nOCTAVE vocabulary definitions:\n\n| Path | Content |\n|------|---------|\n| `registry.oct.md` | Vocabulary registry index |\n| `core/META.oct.md` | META vocabulary specification |\n| `core/SNAPSHOT.oct.md` | SNAPSHOT vocabulary specification |\n\n#### Skills (`skills/`)\n\nWorkflow definitions for OCTAVE operations:\n\n- `octave-compression/SKILL.md` - Workflow for prose-to-OCTAVE transformation\n\n资料来源：[src/octave_mcp/resources/README.md:1-80]()\n\n### Package Exports\n\nThe `octave_mcp/__init__.py` exports 51 public APIs organized into categories:\n\n| Category | Key Exports |\n|----------|-------------|\n| Functions | `parse`, `parse_with_warnings`, `emit`, `tokenize`, `repair`, `project`, `hydrate` |\n| Classes | `Parser`, `Validator`, `TokenType`, `Token`, `HydrationPolicy`, `VocabularyRegistry` |\n| AST Nodes | `Document`, `Block`, `Assignment`, `Section`, `ListValue`, `InlineMap`, `Absent` |\n| Schema | `SchemaDefinition`, `FieldDefinition`, `extract_schema_from_document` |\n| Repair | `RepairLog`, `RepairEntry`, `RepairTier`, `RoutingLog` |\n| Exceptions | `VocabularyError`, `CollisionError`, `VersionMismatchError`, `ParserError`, `LexerError` |\n\n资料来源：[src/octave_mcp/__init__.py:1-50]()\n\n## Tools Directory (`tools/`)\n\nStandalone utilities for OCTAVE validation and conversion.\n\n| Tool | Purpose |\n|------|---------|\n| `lint-octave.py` | Fast syntax validation for OCTAVE documents |\n| `octave-to-json.py` | Convert OCTAVE to JSON for system integration |\n| `json-to-octave.py` | Convert JSON back to OCTAVE format |\n| `octave-validator.py` | Repo validator wrapping the MCP core parser |\n\n### Lint Tool (`lint-octave.py`)\n\nValidates OCTAVE documents with checks for:\n- Document markers (`===NAME===` and `===END===`)\n- META section presence\n- Indentation (2-space multiples)\n- Assignment syntax (`KEY::VALUE`)\n- Balanced brackets\n- No trailing commas in lists\n\n**Usage:**\n```bash\npython3 lint-octave.py < document.oct.md\n# Returns: OCTAVE_VALID or OCTAVE_INVALID: \n```\n\n### Validator Tool (`octave-validator.py`)\n\nSupports validation profiles:\n- `protocol`\n- `hestai-agent`\n- `hestai-skill`\n- `hestai-pattern`\n\n**Usage:**\n```bash\noctave validate document.oct.md\noctave-validator.py --path /directory --profile hestai-agent\n```\n\n资料来源：[tools/README.md:1-50]()\n\n## Examples Directory (`examples/`)\n\nDemonstrates OCTAVE compression across different scales.\n\n### Integrations (`examples/integrations/`)\n\nIntegration examples including:\n\n| File | Purpose |\n|------|---------|\n| `repomix/octave_enhance_targeted.py` | Targeted OCTAVE annotation for specific files |\n| `repomix/octave_enhance_comprehensive.py` | Comprehensive codebase semantic coverage |\n\n### Compression Tier Examples\n\nDemonstrates OCTAVE 5.1.0 compression on research documents:\n\n| Tier | Fidelity | Tokens | Use Case |\n|------|----------|--------|----------|\n| LOSSLESS | 100% | ~14,900 | Critical decisions, legal/safety analysis |\n| CONSERVATIVE | 85-90% | ~4,800 | Research summaries, design decisions |\n| AGGRESSIVE | 70% | ~1,800 | Quick overviews |\n| ULTRA | ~60% | ~900 | High token efficiency |\n\n资料来源：[examples/README.md:1-60]()\n\n## Standards Directory (`standards/`)\n\nOfficial OCTAVE format standards defining document schemas.\n\n### L3 Agent Format (`L3-AGENT-FORMAT.oct.md`)\n\nDefines the exact L3 file format for HestAI Agents with:\n\n```mermaid\ngraph LR\n A[YAML_HEADER] --> B[+ OCTAVE_BODY]\n B --> C[===AGENT_DEFINITION===]\n \n C --> D[§0::META]\n C --> E[§1::CONSTITUTIONAL_CORE]\n C --> F[§2::COGNITIVE_FRAMEWORK]\n C --> G[§3::SHANK_OVERLAY]\n C --> H[§4::OPERATIONAL_IDENTITY]\n C --> I[§5::DOMAIN_CAPABILITIES]\n C --> J[§6::OUTPUT_CONFIGURATION]\n \n J --> K[===END===]\n```\n\nRequired YAML header fields:\n- `name`: Agent identifier\n- `description`: One-line summary\n- `allowed-tools`: Tool permissions list\n\n资料来源：[standards/L3-AGENT-FORMAT.oct.md:1-50]()\n\n## Documentation Structure (`docs/`)\n\n| Document | Content |\n|----------|---------|\n| `usage.md` | CLI, MCP, and API usage examples |\n| `api.md` | Python API reference |\n| Configuration | MCP server setup for Claude Code and Claude Desktop |\n\n### MCP Server Setup\n\n**Claude Code Configuration** (`~/.claude.json`):\n```json\n{\n \"mcpServers\": {\n \"octave\": {\n \"command\": \"octave-mcp-server\"\n }\n }\n}\n```\n\n**HTTP Transport:**\n```bash\noctave-mcp-server --transport http --port 8080\n```\n\n资料来源：[README.md:1-60]()\n\n## MCP Tools Reference\n\n| Tool | Function |\n|------|----------|\n| `octave_validate` | Validate against schema, field errors, repair suggestions |\n| `octave_write` | Write files through full validation pipeline |\n| `octave_eject` | Project to different views (canonical, executive, developer, template) |\n| `octave_compile_grammar` | Compile schema constraints to GBNF grammar |\n\n### CLI Commands\n\n```bash\noctave validate document.oct.md\noctave write output.oct.md --stdin\noctave eject document.oct.md --mode executive --format markdown\n```\n\n## Resource Loading Pattern\n\nFor programmatic access to bundled resources:\n\n```python\nfrom importlib.resources import files, as_file\n\n# Read a primer\nprimer_file = files('octave_mcp.resources.primers').joinpath('octave-compression-primer.oct.md')\nwith as_file(primer_file) as path:\n primer_content = path.read_text()\n\n# Read a spec\nspec_file = files('octave_mcp.resources.specs').joinpath('octave-core-spec.oct.md')\n```\n\nAll resources are versioned at v6.0.0 as part of the Universal Anchor release.\n\n## Summary\n\nThe octave-mcp project follows a clear separation of concerns:\n\n1. **Core parsing/validation** in `src/octave_mcp/core/` — language-agnostic processing\n2. **MCP protocol** in `src/octave_mcp/mcp/` — server implementation and tools\n3. **Resources** in `src/octave_mcp/resources/` — distributable specs, primers, and vocabularies\n4. **Utilities** in `tools/` — standalone CLI tools for CI/CD integration\n5. **Examples** in `examples/` — integration demonstrations\n6. **Standards** in `standards/` — official format definitions\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#page-mcp-tools), [CLI Interface](#page-cli-interface)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/core/parser.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/parser.py)\n- [src/octave_mcp/core/grammar_compiler/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/__init__.py)\n- [src/octave_mcp/mcp/grammar_resources.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/grammar_resources.py)\n- [src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)\n- [src/octave_mcp/resources/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/README.md)\n
\n\n# System Architecture\n\n## Overview\n\nOCTAVE-MCP (Olympian Common Text And Vocabulary Engine - Model Context Protocol) is a semantic DSL implementation designed for structured document processing, validation, and LLM integration. The architecture follows a layered approach combining MCP protocol support, grammar-based validation, and integration adapters for various inference backends.\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n CLI[CLI Tools]\n MCP[Claude Desktop / HTTP]\n end\n\n subgraph \"MCP Protocol Layer\"\n Server[MCP Server]\n GrammarResources[Grammar Resources]\n WriteTool[Write Tool]\n ValidateTool[Validate Tool]\n EjectTool[Eject Tool]\n end\n\n subgraph \"Core Processing Layer\"\n Parser[Parser]\n GrammarCompiler[Grammar Compiler]\n Validator[Validator]\n end\n\n subgraph \"Integration Layer\"\n LLM[LLM Integrations]\n end\n\n subgraph \"Resource Layer\"\n Specs[Specifications]\n Primers[Primers]\n Skills[Skills]\n end\n\n CLI --> Server\n MCP --> Server\n Server --> GrammarResources\n Server --> WriteTool\n Server --> ValidateTool\n Server --> EjectTool\n GrammarResources --> GrammarCompiler\n WriteTool --> Parser\n WriteTool --> Validator\n EjectTool --> Parser\n GrammarCompiler --> Specs\n Parser --> Validator\n Specs --> LLM\n```\n\n## MCP Server Architecture\n\n### Server Initialization\n\nThe MCP server (`octave-mcp-server`) provides the primary interface for OCTAVE document operations. It initializes with configuration options supporting both Claude Desktop and HTTP transport modes.\n\n**Configuration Methods:**\n\n| Method | Configuration Location | Example |\n|--------|----------------------|---------|\n| Claude Desktop | `~/.claude.json` | `mcpServers.octave.command` |\n| Claude Code | `.claude.json` | Same structure |\n| HTTP | CLI flags | `--transport http --port 8080` |\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n### Transport Architecture\n\nThe server supports multiple transport mechanisms for flexibility in deployment scenarios:\n\n1. **Standard I/O**: Default mode for CLI and Claude Desktop integration\n2. **HTTP Transport**: Scalable deployment option with port configuration\n\n```mermaid\ngraph LR\n A[Claude Desktop] -->|stdio| B[octave-mcp-server]\n C[HTTP Client] -->|HTTP| D[--transport http]\n B --> E[Core Parser]\n D --> E\n```\n\n## Core Processing Components\n\n### Parser Module\n\nThe parser (`src/octave_mcp/core/parser.py`) handles OCTAVE document parsing with support for:\n\n- **Document Envelope Detection**: Identifies `===NAME===` markers for document boundaries\n- **META Block Parsing**: Extracts metadata including TYPE, VERSION, and custom fields\n- **Grammar Sentinel Support**: Recognizes `OCTAVE::VERSION` patterns for grammar versioning\n- **Byte Offset Tracking**: Records `start_byte` and `end_byte` positions for each document region\n\n**Parser Features:**\n\n| Feature | Description | Implementation |\n|---------|-------------|----------------|\n| Envelope Detection | Required document markers | `ENVELOPE_START` token type |\n| META Region | Structured metadata section | `meta_start_byte` / `meta_end_byte` tracking |\n| Grammar Sentinel | Version identification | `GRAMMAR_SENTINEL` token |\n| Inferred Envelope | Single-document support | Default name: \"INFERRED\" |\n\n资料来源：[src/octave_mcp/core/parser.py:50-80](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/parser.py)\n\n### Grammar Compiler\n\nThe grammar compiler (`src/octave_mcp/core/grammar_compiler/__init__.py`) generates GBNF (Greibach Normal Form) grammars for constrained generation and validation.\n\n**Public API:**\n\n```python\nfrom octave_mcp.core.grammar_compiler import (\n compile_document_grammar,\n emit_grammar_for_schema,\n)\n```\n\n**Compilation Features:**\n\n| Function | Purpose |\n|----------|---------|\n| `compile_document_grammar` | Main entry point for grammar generation |\n| `emit_grammar_for_schema` | Schema-specific grammar emission |\n\n资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/__init__.py)\n\n### Grammar Resources\n\nThe grammar resources module (`src/octave_mcp/mcp/grammar_resources.py`) provides MCP resources for dynamic grammar access:\n\n- **Resource Templates**: Dynamic grammar retrieval via `octave://grammars/{schema_name}`\n- **Caching**: In-memory cache for compiled grammars\n- **Schema Resolution**: Loads schemas from builtin registry or search paths\n\n**Resource URI Pattern:**\n```\noctave://grammars/{schema_name}\n```\n\n资料来源：[src/octave_mcp/mcp/grammar_resources.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/grammar_resources.py)\n\n## MCP Tools\n\n### Validate Tool\n\nPerforms schema-based validation with detailed error reporting:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| document | string | OCTAVE content to validate |\n| schema | string | Schema name for validation |\n| profile | string | Validation profile (protocol, hestai-agent, etc.) |\n\n### Write Tool\n\nThe write tool (`src/octave_mcp/mcp/write.py`) provides file writing with full validation pipeline:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| target_path | string | File path to write |\n| content | string | Full content for new files |\n| changes | dict | Field updates for existing files |\n| schema | string | Optional schema name |\n| format_style | string | Output mode: preserve, expanded, compact |\n\n**Format Style Modes:**\n\n| Mode | Behavior | Deprecation Note |\n|------|----------|-------------------|\n| `preserve` | Span-aware preserve mode | Recommended for future |\n| `expanded` | Full canonical re-emit | Explicit opt-in for legacy behavior |\n| `compact` | Minimal output | Default in v1.14.0+ |\n\n资料来源：[src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)\n\n### Eject Tool\n\nProjects documents to different views for various audiences:\n\n- **canonical**: Full document structure\n- **executive**: Summary view for decision-makers\n- **developer**: Implementation-focused perspective\n- **template**: Blank template for new documents\n\n## Resource Organization\n\n```mermaid\ngraph TD\n subgraph \"Resources\"\n subgraph \"Specs\"\n Core[octave-core-spec.oct.md]\n Agents[octave-agents-spec.oct.md]\n Skills[octave-skills-spec.oct.md]\n Data[octave-data-spec.oct.md]\n Schema[octave-schema-spec.oct.md]\n end\n\n subgraph \"Primers\"\n Mastery[octave-mastery-primer]\n Compression[octave-compression-primer]\n Ultra[octave-ultra-mythic-primer]\n end\n\n subgraph \"Skills\"\n CompressionSkill[octave-compression]\n end\n end\n```\n\n### Specifications Structure\n\n| Category | Purpose | Version |\n|----------|---------|---------|\n| Core Spec | Syntax, operators, type system | v6.0.0 |\n| Agents Spec | Agent architecture patterns | v6.0.0 |\n| Skills Spec | Skill document format | v6.0.0 |\n| Data Spec | Compression tiers and patterns | v6.0.0 |\n| Schema Spec | Validation framework | v6.0.0 |\n\n资料来源：[src/octave_mcp/resources/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/README.md)\n\n## Validation Profiles\n\nThe system supports multiple validation profiles for different use cases:\n\n| Profile | YAML Frontmatter | Default Behavior |\n|---------|------------------|------------------|\n| `protocol` | Optional | Warning on missing |\n| `hestai-agent` | Required | Hard fail if missing |\n| `hestai-skill` | Required | Hard fail if missing |\n| `hestai-pattern` | Optional | Warning on missing |\n\n**Profile Configuration:**\n```bash\noctave validate document.oct.md --profile hestai-agent --require-frontmatter\n```\n\n资料来源：[tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)\n\n## Document Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Server\n participant Validator\n participant Parser\n participant GrammarCompiler\n\n Client->>Server: octave_write(document)\n Server->>Parser: parse_document(content)\n Parser->>Validator: validate(parsed_doc, schema)\n Validator->>GrammarCompiler: compile_grammar(schema)\n GrammarCompiler-->>Validator: GBNF grammar\n Validator-->>Server: validation_result\n Server-->>Client: write_response\n\n Note over Client,GrammarCompiler: Round-trip: OCTAVE → JSON → OCTAVE\n```\n\n## Integration Points\n\n### CLI Integration\n\n```bash\n# Validate a document\noctave validate document.oct.md\n\n# Write with validation\noctave write output.oct.md --stdin\n\n# Eject to different view\noctave eject document.oct.md --mode executive --format markdown\n```\n\n### MCP Tool Integration\n\n| Tool | Function |\n|------|----------|\n| `octave_validate` | Validate against schema with repair suggestions |\n| `octave_write` | Write files through full validation pipeline |\n| `octave_eject` | Project to different views |\n| `octave_compile_grammar` | Compile schema to GBNF |\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n## Architectural Principles\n\n1. **Separation of Concerns**: MCP protocol layer is isolated from core processing\n2. **Profile-Based Validation**: Different profiles support various document types\n3. **Grammar-Driven Validation**: GBNF grammars ensure structured output\n4. **Round-Trip Fidelity**: OCTAVE ↔ JSON conversion preserves document semantics\n5. **Extensible Resources**: Primers and skills provide domain-specific guidance\n\n## File Organization\n\n```\nsrc/octave_mcp/\n├── core/\n│ ├── parser.py # Document parsing\n│ └── grammar_compiler/ # GBNF generation\n├── mcp/\n│ ├── server.py # MCP server\n│ ├── http_transport.py # HTTP transport\n│ ├── grammar_resources.py # Dynamic grammars\n│ └── write.py # Write tool\n├── integrations/ # LLM backend adapters\n└── resources/\n ├── specs/ # OCTAVE specifications\n ├── primers/ # Learning primers\n └── skills/ # Skill definitions\n\n---\n\n\n\n## Canonical Normalization\n\n### 相关页面\n\n相关主题：[Schema Validation](#page-schema-validation), [Compression System](#page-compression-system)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/core/lexer.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/lexer.py)\n- [src/octave_mcp/core/parser.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/parser.py)\n- [src/octave_mcp/core/emitter.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/emitter.py)\n- [src/octave_mcp/core/grammar/tier_normalize.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar/tier_normalize.py)\n- [src/octave_mcp/core/grammar/cst.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar/cst.py)\n
\n\n# Canonical Normalization\n\nCanonical Normalization is the process by which OCTAVE documents are validated, transformed, and written in a standardized format. It ensures consistency across documents by enforcing syntax rules, resolving dialect variations, and producing output that conforms to the OCTAVE specification. The normalization pipeline is a core component of the write workflow, operating between parsing and emission.\n\n## Overview\n\nOCTAVE (Olympian Common Text And Vocabulary Engine) is a semantic DSL designed for LLMs. When documents pass through the system—either during editing, compression, or cross-agent transfer—syntax variations can accumulate. Canonical Normalization addresses this by providing a deterministic transformation that produces a consistent \"canonical\" form.\n\nThe normalization system is governed by ADR-0006 (Writer/Reader Symmetry Programme), which defines a phased rollout of behavior changes across multiple milestones.\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Input OCTAVE] --> B[Lexer]\n B --> C[Parser]\n C --> D[Concrete Syntax Tree CST]\n D --> E[Tier Normalization]\n E --> F[Semantic Validation]\n F --> G[Emitter]\n G --> H[Canonical Output]\n \n E --> E1[warnings list]\n F --> F1[Field Errors]\n F --> F2[Repair Suggestions]\n \n style E fill:#f9f,stroke:#333\n style H fill:#9f9,stroke:#333\n```\n\n## Phases of Normalization\n\n### Phase 1: Lexical Analysis\n\nThe lexer (`src/octave_mcp/core/lexer.py`) performs initial tokenization, handling:\n\n- Standard identifiers and operators\n- Angle bracket annotations (`NAME`)\n- Comma-separated qualifier lists\n\n**Qualifier List Support (GH#320)**\n\nThe lexer supports comma-separated qualifier lists in angle bracket annotations:\n\n```\nNEVER[PEDANTIC,DISMISSIVE,VAGUE]\n```\n\nThis is parsed by consuming valid identifier characters, then checking for commas followed by subsequent segments. 资料来源：[src/octave_mcp/core/lexer.py:lexer-impl]()()\n\n### Phase 2: Parsing\n\nThe parser (`src/octave_mcp/core/parser.py`) builds a Concrete Syntax Tree (CST) from token streams. Key features include:\n\n| Feature | Description |\n|---------|-------------|\n| `start_byte` / `end_byte` | Byte offsets for document and META region (ADR-0006 SR2-T2) |\n| Grammar Sentinel | Parses `OCTAVE::VERSION` pattern |\n| Envelope Detection | Handles explicit `===NAME===` and inferred envelopes |\n\n资料来源：[src/octave_mcp/core/parser.py:parse_document-90-115]()(ADR-0006 SR2-T2)\n\n### Phase 3: Tier Normalization\n\nThe tier normalization module (`src/octave_mcp/core/grammar/tier_normalize.py`) applies compression-tier-specific transformations:\n\n| Tier | Target Fidelity | Preserved | Dropped |\n|------|------------------|-----------|---------|\n| LOSSLESS | 100% | Everything | Nothing |\n| CONSERVATIVE | 85-90% | Explanatory depth | Redundancy |\n| AGGRESSIVE | 70% | Core thesis | Edge cases |\n| ULTRA | Minimal | Key semantics | Most detail |\n\n资料来源：[src/octave_mcp/core/grammar/tier_normalize.py]()()\n\n### Phase 4: CST Representation\n\nThe CST module (`src/octave_mcp/core/grammar/cst.py`) provides the intermediate representation:\n\n```mermaid\nclassDiagram\n class Document {\n +str name\n +int start_byte\n +int end_byte\n +str grammar_version\n +MetaBlock? meta\n +list~Section~ sections\n }\n class MetaBlock {\n +int meta_start_byte\n +int meta_end_byte\n +dict fields\n }\n class Section {\n +str identifier\n +str content\n +list annotations\n }\n \n Document *-- MetaBlock\n Document *-- Section\n```\n\n资料来源：[src/octave_mcp/core/grammar/cst.py]()()\n\n### Phase 5: Emission\n\nThe emitter (`src/octave_mcp/core/emitter.py`) writes the canonical form:\n\n```python\nwarnings = []\ncanonical = emitter.emit(cst, normalize=True)\n# warnings contains list of normalization changes applied\n```\n\n资料来源：[src/octave_mcp/core/emitter.py]()()\n\n## Behavior Timeline\n\nPer ADR-0006, normalization behavior evolves across milestones:\n\n```mermaid\ngraph LR\n T1[TODAY
SR1] --> T2[AFTER_SR1_T4
SR1 Milestone] --> T3[AFTER_SR3_T2
SR3 Milestone]\n \n T1:::today\n T2:::milestone1\n T3:::milestone3\n \n classDef today fill:#ff6b6b,color:#fff\n classDef milestone1 fill:#feca57,color:#000\n classDef milestone3 fill:#48dbfb,color:#000\n \n T1 -->|\"normalize on write\"| T1a[\"warnings: []
source was already canonical\"]\n T2 -->|\"NO-OP normalization
warnings enumerate what
WOULD have changed\"| T2a[\"warnings: []
no normalization attempted
≠ canonicality guarantee\"]\n T3 -->|\"octave_fmt for canonicalization
octave_write for persistence\"| T3a[\"Separate concerns
Two distinct calls\"]\n```\n\n### Timeline Details\n\n| Phase | Behavior | `warnings: []` Meaning |\n|-------|----------|------------------------|\n| **TODAY** | `octave_write` normalizes on every write | Source was already canonical |\n| **AFTER_SR1_T4** | Default becomes NO-OP normalization | No normalization attempted (not a canonicality guarantee) |\n| **AFTER_SR3_T2** | Canonicalization moves to `octave_fmt` tool | Separate persist vs canonicalize calls |\n\n资料来源：[src/octave_mcp/resources/skills/octave-literacy/SKILL.md:§6a::TIMELINE]()(ADR-0006)\n\n## Normalization Rules\n\n### Syntax Normalization\n\n| Rule | Before | After |\n|------|--------|-------|\n| Indentation | Mixed (1, 3, 4 spaces) | 2-space multiples |\n| Assignment spacing | `KEY:: VALUE` | `KEY::VALUE` |\n| List formatting | Trailing commas allowed | Trailing commas forbidden |\n| Bracket balance | All brackets must balance | Enforced at parse time |\n\n### Semantic Normalization\n\n- **Operator resolution**: Alias operators mapped to canonical forms (`⇌` vs `<->`)\n- **Quoted strings**: Preserved verbatim with original quotes\n- **Blank lines**: Tracked for round-trip fidelity\n\n### META Sanity Checks\n\nMinimal validation of META section:\n\n| Field | Required | Validation |\n|-------|----------|------------|\n| TYPE | Yes | Must be valid document type |\n| VERSION | Yes | Semantic version format |\n\n## MCP Tool Integration\n\nThe normalization system integrates with MCP tools:\n\n| Tool | Mode | Behavior |\n|------|------|----------|\n| `octave_write` | normalize | Dry-run, returns warnings |\n| `octave_write` | persist | Apply normalization, return warnings |\n| `octave_validate` | — | Validate against schema, provide repair suggestions |\n| `octave_eject` | — | Project to different views (canonical, executive, developer) |\n\n资料来源：[README.md:MCP Tools]()()\n\n## CLI Usage\n\n```bash\n# Validate document (implicit normalization check)\noctave validate document.oct.md\n\n# Write with dry-run normalization\noctave write output.oct.md --mode normalize\n\n# Canonical format ejection\noctave eject document.oct.md --mode canonical --format markdown\n```\n\n## Round-Trip Fidelity\n\nThe normalization system guarantees round-trip fidelity:\n\n```mermaid\ngraph LR\n A[OCTAVE] -->|octave-to-json| B[JSON]\n B -->|json-to-octave| C[OCTAVE']\n A -->|diff| C\n \n C -->|identical| A\n```\n\nWhen a document passes through JSON serialization and back:\n\n```bash\npython3 octave-to-json.py input.oct.md | python3 json-to-octave.py > output.oct.md\ndiff input.oct.md output.oct.md # Should produce no differences\n```\n\nPreserved elements during round-trip:\n- Blank lines\n- Quoted strings\n- Semantic operators (`⊕`, `⇌`, `§`)\n- Section identifiers\n\n资料来源：[tools/README.md:Round-Trip Example]()()\n\n## Error Handling\n\nNormalization produces structured warnings:\n\n```json\n{\n \"warnings\": [\n \"Indentation normalized: 4 spaces → 2 spaces\",\n \"Trailing comma removed in list [a, b, c,]\",\n \"Operator alias <-> → ⇌\"\n ]\n}\n```\n\nEmpty `warnings` array indicates no normalization changes were needed.\n\n## See Also\n\n- [ADR-0006: Writer/Reader Symmetry Programme](docs/adr/ADR-0006-writer-reader-symmetry.md)\n- [OCTAVE Data Specification](src/octave_mcp/resources/specs/octave-data-spec.oct.md)\n- [Usage Guide](docs/usage.md)\n- [API Reference](docs/api.md)\n\n---\n\n\n\n## Schema Validation\n\n### 相关页面\n\n相关主题：[Canonical Normalization](#page-canonical-normalization), [MCP Tools Reference](#page-mcp-tools)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/core/validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/validator.py)\n- [src/octave_mcp/core/schema_extractor.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/schema_extractor.py)\n- [tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)\n- [src/octave_mcp/resources/primers/octave-mastery-primer.oct.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/primers/octave-mastery-primer.oct.md)\n- [src/octave_mcp/mcp/validate.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/validate.py)\n- [src/octave_mcp/resources/skills/octave-compression/SKILL.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/skills/octave-compression/SKILL.md)\n
\n\n# Schema Validation\n\n## Overview\n\nSchema Validation in OCTAVE-MCP is the core mechanism that ensures OCTAVE documents conform to defined structural rules, type constraints, and semantic policies. The validation system operates on parsed AST (Abstract Syntax Tree) representations of documents, providing comprehensive error reporting with field-level precision.\n\nThe validation framework is designed to:\n- Validate documents against predefined schema definitions\n- Enforce required fields and type constraints\n- Support enum validation with prefix matching and ambiguity detection\n- Detect unknown fields based on policy settings\n- Evaluate constraint chains for complex validation logic\n- Support target routing with audit trails for policy enforcement\n\n资料来源：[src/octave_mcp/core/validator.py:1-30]()\n\n## Architecture\n\nThe validation system follows a layered architecture with clear separation of concerns:\n\n```mermaid\ngraph TD\n A[OCTAVE Document] --> B[Parser]\n B --> C[Document AST]\n C --> D[Validator]\n D --> E{Schema Definition}\n E -->|Built-in| F[META, SKILL, AGENT]\n E -->|Custom| G[User Schemas]\n D --> H[Validation Errors]\n H --> I[Repair Suggestions]\n \n J[Schema Loader] --> E\n K[Schema Extractor] --> E\n```\n\n### Core Components\n\n| Component | Location | Purpose |\n|-----------|----------|---------|\n| `Validator` | `core/validator.py` | Main validation surface - structural visitor pattern |\n| `SchemaDefinition` | `core/schema.py` | Schema data model |\n| `FieldDefinition` | `core/schema.py` | Field constraint definitions |\n| `SchemaExtractor` | `core/schema_extractor.py` | Extract schemas from OCTAVE documents |\n| `SchemaLoader` | `schemas/loader.py` | Load built-in and custom schemas |\n\n资料来源：[src/octave_mcp/core/validator.py:50-100]()\n\n## The Validator Class\n\nThe `Validator` class is the primary entry point for schema validation, implementing the visitor pattern for AST traversal:\n\n```python\nfrom octave_mcp import Validator\n\nvalidator = Validator(schema=schema_def)\nerrors = validator.validate(doc, strict=False)\n```\n\n### Validation Flow\n\n```mermaid\ngraph LR\n A[validate doc] --> B[_prepare_document_validation]\n B --> C[_validate_sections_recursive]\n C --> D{nested blocks?}\n D -->|yes| C\n D -->|no| E[section_schemas defined?]\n E -->|yes| F[validate_frontmatter]\n E -->|no| G[return errors]\n F --> G\n```\n\n### Key Validation Features\n\n1. **Required Field Checking** - Ensures mandatory fields are present\n2. **Type Validation** - Validates field values against defined types\n3. **Enum Validation** - Supports prefix matching and ambiguity detection\n4. **Regex Pattern Validation** - Validates string formats against regex\n5. **Unknown Field Detection** - Policy-driven detection of unexpected fields\n6. **Constraint Chain Evaluation** - Processes complex validation rules\n7. **Target Routing** - Validates routing targets with audit trail\n\n资料来源：[src/octave_mcp/core/validator.py:100-150]()\n\n## Schema Definition\n\nSchemas define the structure and constraints for OCTAVE documents. They consist of:\n\n### Schema Structure\n\n| Section | Purpose |\n|---------|---------|\n| `POLICY` | Version, UNKNOWN_FIELDS handling, default targets |\n| `FIELDS` | Field definitions with constraints |\n| `FRONTMATTER` | YAML frontmatter field definitions |\n\n### Policy Settings\n\nThe `POLICY` block controls validation behavior:\n\n```octave\nPOLICY:\n VERSION::\"1.0\"\n UNKNOWN_FIELDS::REJECT # REJECT, WARN, or ALLOW\n```\n\n**UNKNOWN_FIELDS Policy Options:**\n- `REJECT` - Validation fails on unknown fields\n- `WARN` - Unknown fields are reported but don't fail validation\n- `ALLOW` - Unknown fields are ignored\n\n资料来源：[src/octave_mcp/core/schema_extractor.py:50-80]()\n\n## Schema Extraction\n\nThe `extract_schema_from_document()` function parses OCTAVE documents and builds `SchemaDefinition` objects:\n\n```python\nfrom octave_mcp.core.schema_extractor import extract_schema_from_document\n\nschema = extract_schema_from_document(doc)\n# Returns SchemaDefinition with:\n# - name from document envelope\n# - version from META block\n# - policy settings\n# - field definitions\n# - frontmatter definitions\n```\n\n### Extraction Process\n\n```mermaid\ngraph TD\n A[parse OCTAVE document] --> B[extract name from envelope]\n B --> C[extract VERSION from META]\n C --> D[_extract_policy]\n D --> E[extract FIELDS block]\n E --> F[extract FRONTMATTER block]\n F --> G[build SchemaDefinition]\n G --> H[return with warnings]\n```\n\n资料来源：[src/octave_mcp/core/schema_extractor.py:80-150]()\n\n## Validation Profiles\n\nThe CLI tool supports multiple validation profiles for different document types:\n\n| Profile | YAML Frontmatter | META.TYPE Requirement |\n|---------|------------------|----------------------|\n| `protocol` | Forbidden | Any |\n| `hestai-agent` | Recommended (warning) | `AGENT_DEFINITION` |\n| `hestai-skill` | Recommended (warning) | `SKILL` |\n| `hestai-pattern` | Forbidden | `PATTERN` |\n\n### CLI Usage\n\n```bash\n# Validate single file\npython tools/octave-validator.py document.oct.md\n\n# Validate with specific schema\npython tools/octave-validator.py document.oct.md --schema META\n\n# Directory scan\npython tools/octave-validator.py --path .hestai-sys/library/ --profile hestai-agent\n\n# Require frontmatter (fail on missing)\npython tools/octave-validator.py document.oct.md --require-frontmatter\n```\n\n资料来源：[tools/octave-validator.py:1-50]()\n\n## MCP Tool Integration\n\nThe `octave_validate` MCP tool provides programmatic validation access:\n\n### Tool Interface\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `content` | string | OCTAVE document content |\n| `schema` | string | Schema name to validate against (optional) |\n| `strict` | boolean | Enable strict validation mode |\n\n### Return Structure\n\n```json\n{\n \"valid\": true,\n \"validation_status\": \"VALIDATED\",\n \"validation_errors\": []\n}\n```\n\nOn validation failure:\n```json\n{\n \"valid\": false,\n \"validation_status\": \"INVALID\",\n \"validation_errors\": [\n {\"code\": \"E_REQUIRED_FIELD\", \"message\": \"...\", \"field\": \"META.VERSION\"}\n ],\n \"grammar_hint\": {\"format\": \"gbnf\", \"grammar\": \"...\"}\n}\n```\n\n资料来源：[src/octave_mcp/mcp/validate.py:1-50]()\n\n## Error Codes\n\n| Code | Description |\n|------|-------------|\n| `E_REQUIRED_FIELD` | Mandatory field is missing |\n| `E_TYPE_MISMATCH` | Field value type doesn't match schema |\n| `E_ENUM_INVALID` | Value not in allowed enum values |\n| `E_REGEX_MISMATCH` | String doesn't match pattern |\n| `E_UNKNOWN_FIELD` | Field not defined in schema (when UNKNOWN_FIELDS=REJECT) |\n| `E_CONSTRAINT_VIOLATION` | Constraint chain evaluation failed |\n| `E_FRONTEMATTER_INVALID` | YAML frontmatter validation failed |\n| `E_AST_CYCLE` | Cyclic structure detected |\n\n## Validation Workflow\n\n```mermaid\ngraph TD\n A[Input OCTAVE] --> B[Parse Document]\n B --> C{Parse Success?}\n C -->|No| D[Parser Error]\n C -->|Yes| E[Load Schema]\n E --> F{Schema Found?}\n F -->|No| G[UNVALIDATED]\n F -->|Yes| H[Create Validator]\n H --> I[Run Validation]\n I --> J{Validation Errors?}\n J -->|Yes| K[Report INVALID]\n J -->|No| L[Report VALIDATED]\n \n K --> M[Generate Error Details]\n M --> N[Optional: Grammar Hint]\n L --> O[Optional: Validation Success]\n```\n\n## Best Practices\n\n1. **Always specify schema** - Provides precise error messages and repair suggestions\n2. **Use strict mode for CI/CD** - Catches all violations early\n3. **Leverage profile validation** - Ensures documents match their intended type\n4. **Handle validation errors gracefully** - Provide meaningful feedback to users\n5. **Use grammar hints for generation** - Guide LLM output toward valid structures\n\n资料来源：[src/octave_mcp/core/validator.py:150-200]()\n\n## Related Documentation\n\n- [Usage Guide](docs/usage.md) - CLI, MCP, and API examples\n- [API Reference](docs/api.md) - Python API documentation\n- [Schema Specification](../resources/specs/octave-schema-spec.oct.md) - Schema format specification\n\n---\n\n\n\n## Compression System\n\n### 相关页面\n\n相关主题：[Canonical Normalization](#page-canonical-normalization)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/core/holographic.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/holographic.py)\n- [src/octave_mcp/core/sealer.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/sealer.py)\n- [src/octave_mcp/core/repair.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/repair.py)\n- [src/octave_mcp/resources/skills/octave-compression/SKILL.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/skills/octave-compression/SKILL.md)\n- [src/octave_mcp/resources/skills/octave-mythology/SKILL.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/skills/octave-mythology/SKILL.md)\n- [examples/compression-comparisons/octave-vs-llmlingua-compression-comparison-2026.md](https://github.com/elevanaltd/octave-mcp/blob/main/examples/compression-comparisons/octave-vs-llmlingua-compression-comparison-2026.md)\n
\n\n# Compression System\n\nThe OCTAVE Compression System is a semantic compression framework that transforms prose into structured OCTAVE (Olympian Common Text And Vocabulary Engine) documents. Unlike traditional text compression that destroys structural relationships, OCTAVE compression preserves semantic invariants while achieving significant token reduction, making documents both machine-executable and LLM-legible.\n\n## Overview\n\nOCTAVE compression serves as the bridge between natural language prose and semantic DSL (Domain-Specific Language) representations. The system operates on a tiered fidelity model where operators specify exactly what is preserved and what is lost at each compression level.\n\nThe core principle is **mythological semantic compression** — leveraging pre-trained mythological vocabulary as functional semantic binding for LLM audiences. This approach achieves 60-70% token reduction while maintaining 88-96% cross-model zero-shot comprehension.\n\n资料来源：[src/octave_mcp/resources/skills/octave-mythology/SKILL.md:1-15]()\n\n## Compression Tiers\n\nOCTAVE defines four standardized compression tiers, each with explicit loss profiles:\n\n| Tier | Target Fidelity | Preserved | Dropped | Use Cases |\n|------|-----------------|-----------|---------|-----------|\n| **LOSSLESS** | 100% | Everything | Nothing | Critical reasoning, legal documents, safety analysis, audit trails |\n| **CONSERVATIVE** | 85-90% | Explanatory depth, tradeoff reasoning | Redundancy, verbose transitions | Research summaries, design decisions, technical analysis |\n| **AGGRESSIVE** | 70% | Core thesis, landscape | Explanatory depth, execution narratives | Overview documents, quick references |\n| **ULTRA** | 50-60% | Semantic invariants | All narrative prose | High-density summaries, token-constrained contexts |\n\n资料来源：[src/octave_mcp/resources/skills/octave-compression/SKILL.md:15-30]()\n\n### Tier Selection Flow\n\n```mermaid\ngraph TD\n A[Start: Source Document] --> B{Document Type?}\n B -->|Critical/Legal| C[LOSSLESS]\n B -->|Research/Design| D{Critical Details?}\n B -->|Overview/Summary| E[AGGRESSIVE]\n B -->|Token-Constrained| F[ULTRA]\n D -->|Yes| G[CONSERVATIVE]\n D -->|No| E\n C --> H[0% Loss]\n G --> I[10-15% Loss]\n E --> J[~30% Loss]\n F --> K[40-50% Loss]\n```\n\n## Core Architecture\n\n### Holographic Patterns\n\nThe foundational unit of OCTAVE compression is the **HolographicPattern**, which encodes constraints and validation rules alongside semantic content. Each field in a compressed document carries its own holographic metadata.\n\n```python\nclass HolographicPattern:\n example: Optional[str] # Concrete example value\n constraints: List[str] # Validation constraints\n target: Optional[str] # Routing/execution target\n```\n\n资料来源：[src/octave_mcp/core/holographic.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/holographic.py)\n\n### Literal Zone Audit\n\nThe `LiteralZoneAudit` system tracks zones that should be preserved verbatim during compression. These zones represent semantic invariants that must survive any transformation:\n\n- Schema definitions\n- Contract specifications\n- Routing declarations\n- Required structural elements\n\n```mermaid\ngraph LR\n A[Input Document] --> B[Zone Scanner]\n B --> C{Literal Zone?}\n C -->|Yes| D[Seal for Preservation]\n C -->|No| E[Compressible Zone]\n D --> F[Output: SEALED content]\n E --> G[Compression Engine]\n G --> H[Output: Compressed content]\n```\n\n资料来源：[src/octave_mcp/core/sealer.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/sealer.py)\n\n## Semantic Operators\n\nOCTAVE compression uses specialized operators that maintain semantic relationships during transformation:\n\n| Operator | Symbol | Meaning | Example |\n|----------|--------|---------|---------|\n| Synthesis | `⊕` | Combining elements | `teaches_format ⊕ validates_rules ⊕ routes_data` |\n| Tension | `⇌` | Tradeoff/balance | `downtime ⇌ parallel_work` |\n| Flow | `→` | Routing/execution | `REQ → INDEXER` |\n| Constraint | `∧` | Required conjunction | `valid ∧ processed` |\n| Disjunction | `∨` | Optional alternatives | `CREATE ∨ UPDATE ∨ DELETE` |\n| Definition | `::` | Maps to/assignment | `PURPOSE::\"Master OCTAVE\"` |\n\n资料来源：[src/octave_mcp/resources/primers/octave-mastery-primer.oct.md:15-25]()\n\n## Mythological Compression\n\nThe Mythological Compression Principle treats mythology as OCTAVE's native compression dialect. Mythological domains provide pre-trained semantic binding that activates rich probability distributions in LLMs.\n\n### Domain Categories\n\n| Domain | Mythological Name | Semantic Load | Example |\n|--------|------------------|---------------|---------|\n| Eternal Tasks | SISYPHEAN | Futile repetition | `SISYPHEAN::loop_detected` |\n| Precision Targeting | ARTEMIS | Focused accuracy | `ARTEMIS::targeted_optimization` |\n| Time Pressure | CHRONOS | Temporal constraints | `CHRONOS::q4_deadline` |\n| Resource Limits | DEMETER | Budget/budget exhaustion | `DEMETER::60%_burned` |\n| Forbidden Knowledge | PROMETHEAN | Risk of revelation | `PROMETHEAN::sensitive_exposure` |\n\n资料来源：[src/octave_mcp/resources/skills/octave-mythology/SKILL.md:30-50]()\n\n### How Mythological Compression Works\n\nMythology terms function as **semantic zip files** — compressed meaning already present in model weights. No training required:\n\n1. LLM recognizes domain term (e.g., `ODYSSEAN`)\n2. Automatically loads psychological/operational context (grueling long-term journey)\n3. Maintains distinct categorical boundaries (CHRONOS vs DEMETER)\n4. Preserves causal graph (the \"Why\") rather than just the \"What\"\n\n资料来源：[examples/compression-comparisons/octave-vs-llmlingua-compression-comparison-2026.md:50-70]()\n\n## Repair and Validation\n\nThe repair subsystem (`repair.py`) provides schema validation with specific field errors and repair suggestions. Every transformation passes through the validation pipeline:\n\n```mermaid\ngraph TD\n A[Compressed OCTAVE] --> B[Schema Validator]\n B --> C{Valid?}\n C -->|Yes| D[Schema Valid]\n C -->|No| E[Repair Engine]\n E --> F[Field Errors]\n E --> G[Repair Suggestions]\n F --> H[Repair Receipt]\n G --> H\n H --> I[Normalized Output]\n```\n\n资料来源：[src/octave_mcp/core/repair.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/repair.py)\n\n### Validation Checks\n\nDocuments compressed with OCTAVE must pass these checks:\n\n| Check | Requirement | Purpose |\n|-------|-------------|---------|\n| `valid_OCTAVE` | Valid syntax | Grammar compliance |\n| `preserve_§_names_verbatim` | Section names unchanged | Structural integrity |\n| `patterns_applied` | Semantic operators used correctly | Semantic preservation |\n| `archetypes_used` | Valid archetype selection | Compression fidelity |\n| `holographic_valid` | Field-level holograms intact | Constraint preservation |\n\n资料来源：[src/octave_mcp/resources/primers/octave-mastery-primer.oct.md:30-35]()\n\n## Workflow: Prose to OCTAVE\n\n```mermaid\ngraph TD\n A[Prose Document] --> B[Tier Selection]\n B --> C[Phase 1: Field Extraction]\n C --> D[Identify semantic atoms]\n D --> E[Phase 2: Mythology Mapping]\n E --> F[Map to mythological domains]\n F --> G[Phase 3: Operator Application]\n G --> H[Apply synthesis/tension/flow]\n H --> I[Phase 4: Loss Accounting]\n I --> J[Document LOSS_PROFILE]\n J --> K[OCTAVE Document]\n K --> L[Validation]\n L --> M{Valid?}\n M -->|No| N[Repair & Retry]\n N --> C\n M -->|Yes| O[Output with receipt]\n```\n\n## Compression Example\n\n### Original Prose (5600 tokens)\n> \"The quarterly budget analysis shows significant resource constraints. Downtime from the migration creates tension with the need for parallel work on the new system. Specifically targeted optimization efforts have burned through 60% of the quarterly allocation for this migration alone.\"\n\n### CONSERVATIVE Compression (4800 tokens)\n```octave\nCONFLICT::downtime ⇌ parallel_work\n→ MIGRATION[Q4_window]\nSISYPHEAN::eternal_repetition[this_migration_alone]\nARTEMIS::specifically_targeted_optimization\nDEMETER::60%_quarterly_burned[this_migration_alone]\n```\n\n### AGGRESSIVE Compression (1800 tokens)\n```octave\nMIGRATION::SISYPHEAN[Q4] ⊕ CHRONOS[deadline]\n→ DEMETER::60%_quarterly_burned\n```\n\n## Loss Profiles\n\nEvery compressed document declares its `LOSS_PROFILE`, enabling auditable transformation:\n\n```octave\nMETA:\n COMPRESSION_TIER::CONSERVATIVE\n LOSS_PROFILE::redundancy ⊕ verbose_transitions\n NARRATIVE_DEPTH::maintained[tradeoff_reasoning_inline,execution_strategies_explained]\n```\n\n| Tier | Loss Profile | Narrative Impact |\n|------|--------------|------------------|\n| LOSSLESS | `none` | Fully preserved |\n| CONSERVATIVE | `redundancy ⊕ verbose_transitions` | Tradeoffs explained inline |\n| AGGRESSIVE | `explanatory_depth ⊕ execution_narratives` | Core thesis preserved |\n| ULTRA | `all_narrative` | Semantic invariants only |\n\n资料来源：[examples/survey-octave-5-conservative.oct.md:1-15]()\n\n## Integration Points\n\n### With Claude Code\n```bash\nrepomix --style xml --output context.xml\npython octave_enhance_targeted.py context.xml enhanced.xml\n# Paste enhanced.xml into Claude Code session\n```\n\n### With MCP Tools\n\n| Tool | Compression Use |\n|------|-----------------|\n| `octave_validate` | Validates compressed documents against schema |\n| `octave_write` | Writes with normalization and repair receipts |\n| `octave_compile_grammar` | Compiles constraints to GBNF for generation |\n\n## Best Practices\n\n1. **Select tier before reading source** — Tier drives all transformation decisions\n2. **Preserve literal zones** — Seal schema/contract zones before compression\n3. **Apply mythology selectively** — Use domain terms for repeated concepts\n4. **Document loss explicitly** — Always declare `LOSS_PROFILE` in metadata\n5. **Validate after compression** — Run repair pipeline to ensure schema compliance\n\n---\n\n\n\n## Grammar Compilation\n\n### 相关页面\n\n相关主题：[Schema Validation](#page-schema-validation), [System Architecture](#page-system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/core/gbnf_compiler.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/gbnf_compiler.py)\n- [src/octave_mcp/core/grammar_compiler/gbnf.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/gbnf.py)\n- [src/octave_mcp/mcp/grammar_resources.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/grammar_resources.py)\n- [docs/grammar/octave-v1.0-grammar.ebnf](https://github.com/elevanaltd/octave-mcp/blob/main/docs/grammar/octave-v1.0-grammar.ebnf)\n
\n\n# Grammar Compilation\n\nGrammar Compilation is the process of transforming OCTAVE schema definitions into GBNF (Gendered Backus-Naur Form) grammar rules that enable constrained text generation. The octave-mcp project uses this system to provide grammar-level validation and AI-assisted document generation with predictable structure.\n\n## Overview\n\nOCTAVE documents follow a strict hierarchical structure defined by schemas. The grammar compilation subsystem allows:\n\n- **Schema validation**: Compile schemas to verify structural correctness\n- **Constrained generation**: Generate GBNF grammars that LLMs can use to produce valid OCTAVE output\n- **Dynamic compilation**: Compile grammars on-demand for any registered schema\n\n资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py:1-17]()\n\n## Architecture\n\n```mermaid\ngraph TD\n A[OCTAVE Schema Definition] --> B[SchemaDefinition]\n B --> C[GBNFCompiler]\n C --> D[GBNF Grammar Rules]\n D --> E[Constrained LLM Generation]\n \n F[load_schema_by_name] --> B\n G[Contract Field Specs] --> H[parse_contract_field]\n H --> I[HolographicPattern]\n I --> C\n \n J[GBNFCompiler.compile_schema] --> C\n K[compile_document_grammar] --> C\n```\n\n## Core Components\n\n### GBNFCompiler\n\nThe `GBNFCompiler` class is the central component that transforms schema definitions into GBNF grammar strings.\n\n| Method | Purpose |\n|--------|---------|\n| `compile_schema(schema_def, include_envelope=True)` | Compile full schema to GBNF |\n| `emit_grammar_for_schema(schema_name)` | Emit grammar for named schema |\n\n资料来源：[src/octave_mcp/core/grammar_compiler/gbnf.py]()\n资料来源：[src/octave_mcp/mcp/grammar_resources.py:48-76]()\n\n### SchemaDefinition\n\nSchemas define the structure of OCTAVE documents:\n\n```python\nschema = SchemaDefinition(\n name=schema_type,\n version=str(meta.get(\"VERSION\", \"1.0\")),\n)\n```\n\n资料来源：[src/octave_mcp/core/gbnf_compiler.py:42-47]()\n\n### FieldDefinition\n\nIndividual fields within schemas include holographic patterns for constraint representation:\n\n```python\nschema.fields[field_name] = FieldDefinition(\n name=field_name,\n pattern=pattern,\n raw_value=field_spec,\n)\n```\n\n资料来源：[src/octave_mcp/core/gbnf_compiler.py:59-63]()\n\n## Compilation Pipeline\n\n### Step 1: Schema Loading\n\n```mermaid\ngraph LR\n A[Schema Name] --> B[load_schema_by_name]\n B --> C{Found?}\n C -->|Yes| D[Return SchemaDefinition]\n C -->|No| E[Search Paths]\n E --> C\n```\n\nThe `load_schema_by_name` function searches builtin registry and configured search paths:\n\n资料来源：[src/octave_mcp/mcp/grammar_resources.py:48-52]()\n\n```python\nschema_def = load_schema_by_name(schema_name)\nif schema_def is None:\n raise ValueError(f\"Schema '{schema_name}' not found in builtin registry or search paths\")\n```\n\n### Step 2: CONTRACT Parsing\n\nThe CONTRACT field in OCTAVE META sections defines field constraints using holographic notation:\n\n| Constraint Syntax | Meaning |\n|-------------------|---------|\n| `REQ` | Required field |\n| `OPT` | Optional field |\n| `ENUM[values]` | Enumerated values |\n| `FIELD[NAME]::REQ∧ENUM[...]` | Combined constraints |\n\n资料来源：[src/octave_mcp/core/gbnf_compiler.py:30-40]()\n\nThe `parse_contract_field` function extracts field names and constraints from CONTRACT specifications:\n\n```python\nfield_name, constraints = parse_contract_field(field_spec)\npattern = HolographicPattern(\n example=None,\n constraints=constraints,\n target=None,\n)\n```\n\n资料来源：[src/octave_mcp/core/gbnf_compiler.py:53-58]()\n\n### Step 3: Grammar Emission\n\nThe compiler generates GBNF rules from the schema structure:\n\n```python\ncompiler = GBNFCompiler()\ngrammar = compiler.compile_schema(schema_def, include_envelope=True)\n```\n\n资料来源：[src/octave_mcp/mcp/grammar_resources.py:53-55]()\n\n## MCP Integration\n\n### Grammar Resource Provider\n\nThe MCP server exposes grammars through a resource provider:\n\n```mermaid\ngraph TD\n A[MCP Client] --> B[GrammarResources]\n B --> C{Cached?}\n C -->|Yes| D[Return cached GBNF]\n C -->|No| E[_compile_grammar]\n E --> F[GBNFCompiler]\n F --> G[Cache Result]\n G --> D\n```\n\n资料来源：[src/octave_mcp/mcp/grammar_resources.py:43-56]()\n\n### Resource Templates\n\nGrammars are accessible via URI templates:\n\n| Template | Schema |\n|----------|--------|\n| `octave://grammars/{schema_name}` | Any registered schema |\n\n资料来源：[src/octave_mcp/mcp/grammar_resources.py:23-32]()\n\n### Caching\n\nThe grammar compiler uses an in-memory cache to avoid recompilation:\n\n```python\nif schema_name in self._cache:\n return self._cache[schema_name]\n```\n\n资料来源：[src/octave_mcp/mcp/grammar_resources.py:43-44]()\n\n## Public API\n\n### compile_document_grammar\n\nMain entry point for document grammar compilation:\n\n```python\nfrom octave_mcp.core.grammar_compiler import compile_document_grammar\n```\n\n### emit_grammar_for_schema\n\nEmit grammar for a specific schema by name:\n\n```python\nfrom octave_mcp.core.grammar_compiler import emit_grammar_for_schema\n```\n\n资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py:10-11]()\n\n## MCP Tool: octave_compile_grammar\n\nThe MCP server exposes a tool for grammar compilation:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `schema_name` | string | Name of schema to compile |\n| `include_envelope` | boolean | Include document envelope rules (default: true) |\n\n资料来源：[README.md - MCP Tools section]()\n\n## Example Usage\n\n### Compile from META definition\n\n```python\nfrom octave_mcp.core.gbnf_compiler import compile_gbnf_from_meta\n\nmeta = {\n \"TYPE\": \"SESSION_LOG\",\n \"VERSION\": \"1.0\",\n \"CONTRACT\": [\n \"FIELD[STATUS]::REQ∧ENUM[ACTIVE,PAUSED,COMPLETE]\",\n \"FIELD[PRIORITY]::OPT∧ENUM[LOW,MEDIUM,HIGH]\",\n ],\n}\ngbnf = compile_gbnf_from_meta(meta)\n```\n\n资料来源：[src/octave_mcp/core/gbnf_compiler.py:20-35]()\n\n### Access via MCP Resource\n\n```bash\n# Using MCP resource URI\noctave://grammars/META\noctave://grammars/SKILL\n```\n\n## EBNF Grammar Reference\n\nThe base grammar definition for OCTAVE v1.0 is documented in:\n\n- `docs/grammar/octave-v1.0-grammar.ebnf`\n\nThis EBNF defines the fundamental syntax that GBNF grammars must conform to, including:\n- Document envelope markers (`===NAME=== ... ===END===`)\n- Section references (`§N::NAME`)\n- Assignment syntax (`KEY::VALUE`)\n- List and inline map structures\n\n## Architecture Notes\n\n### ADR-0006 Design\n\nThe grammar compilation system was restructured under ADR-0006 to resolve naming conflicts:\n\n- Original: `octave_mcp.core.grammar`\n- Current: `octave_mcp.core.grammar_compiler.gbnf`\n\nThe `octave_mcp.core.grammar` package now serves as a unified front-door for parsing, while grammar compilation lives in the `grammar_compiler` submodule.\n\n资料来源：[src/octave_mcp/core/grammar/__init__.py:1-30]()\n\n### Backward Compatibility\n\nLegacy GBNF exports are available through lazy module loading:\n\n```python\n_DEPRECATED_GBNF_EXPORTS: frozenset[str] = frozenset({\n \"compile_document_grammar\",\n \"emit_grammar_for_schema\",\n})\n```\n\nAccessing deprecated symbols emits a `DeprecationWarning` but returns the correct objects.\n\n资料来源：[src/octave_mcp/core/grammar/__init__.py:48-52]()\n\n## Workflow Summary\n\n```mermaid\ngraph TD\n A[Define OCTAVE Schema] --> B[Register Schema]\n B --> C[MCP Request: compile_grammar]\n C --> D[Load Schema Definition]\n D --> E[Parse CONTRACT Fields]\n E --> F[Generate HolographicPatterns]\n F --> G[GBNFCompiler.compile_schema]\n G --> H[Return GBNF String]\n H --> I[LLM Constrained Generation]\n I --> J[Validate Output]\n```\n\n## See Also\n\n- [OCTAVE Core Specification](../specs/octave-core-spec.oct.md)\n- [Schema Validation Framework](../specs/octave-schema-spec.oct.md)\n- [Holographic Patterns](holographic-patterns.md)\n\n---\n\n\n\n## MCP Tools Reference\n\n### 相关页面\n\n相关主题：[CLI Interface](#page-cli-interface), [Python API Reference](#page-python-api)\n\n
\nRelated Source Files\n\nThe following source files were used to generate this documentation:\n\n- [src/octave_mcp/mcp/validate.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/validate.py)\n- [src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)\n- [src/octave_mcp/mcp/eject.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/eject.py)\n- [src/octave_mcp/mcp/compile_grammar.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/compile_grammar.py)\n- [src/octave_mcp/mcp/base_tool.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/base_tool.py)\n- [docs/mcp-configuration.md](https://github.com/elevanaltd/octave-mcp/blob/main/docs/mcp-configuration.md)\n
\n\n# MCP Tools Reference\n\nThe Model Context Protocol (MCP) tools in Octave-MCP provide a standardized interface for LLM agents to interact with OCTAVE documents. These tools enable validation, writing, transformation, and grammar compilation operations through the MCP protocol, serving as the primary programmatic interface for document-centric workflows.\n\n## Overview\n\nOctave-MCP exposes four core MCP tools that wrap the underlying Python API functions. These tools are designed for documents that pass through multiple agents, tools, or compression steps—including agent/skill files, decision logs, coordination briefs, audit trails, system prompts, and reference documentation where token cost optimization matters.\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n## Architecture\n\nThe MCP tools layer sits atop the core parsing and validation engine, providing an asynchronous interface compatible with the MCP protocol. Each tool inherits from a base class that enforces consistent error handling, logging, and result formatting.\n\n```mermaid\ngraph TD\n A[MCP Client] --> B[Octave-MCP Server]\n B --> C[octave_validate]\n B --> D[octave_write]\n B --> E[octave_eject]\n B --> F[octave_compile_grammar]\n C --> G[Core Validator]\n D --> H[Core Parser + Emitter]\n E --> I[Projection Engine]\n F --> J[GBNF Grammar Compiler]\n G --> K[Schema Registry]\n H --> K\n I --> K\n J --> K\n```\n\n资料来源：[src/octave_mcp/mcp/base_tool.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/base_tool.py)\n\n## MCP Tool Configuration\n\nBefore using the tools, the MCP server must be configured in your client application. Octave-MCP supports two transport mechanisms.\n\n### Claude Code / Claude Desktop\n\nAdd the following to `~/.claude.json` (Claude Code) or `claude_desktop_config.json` (Claude Desktop):\n\n```json\n{\n \"mcpServers\": {\n \"octave\": {\n \"command\": \"octave-mcp-server\"\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n### HTTP Transport\n\nFor HTTP-based deployments, start the server with explicit transport configuration:\n\n```bash\noctave-mcp-server --transport http --port 8080\n```\n\n## Tool Reference\n\n### 1. `octave_validate`\n\nValidates OCTAVE documents against schemas, returning field errors, repair suggestions, and zone coverage analysis.\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `document` | string | Yes | The OCTAVE document content to validate |\n| `schema` | string | No | Schema name to validate against (e.g., META, SKILL, AGENT) |\n| `strict` | boolean | No | If true, reject unknown META fields (default: false) |\n\n#### Returns\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `status` | string | \"VALID\" or \"INVALID\" |\n| `errors` | array | List of validation errors with line numbers |\n| `warnings` | array | List of warnings (e.g., W_META_001, W_META_002) |\n| `suggestions` | array | Auto-correction suggestions for repairable issues |\n\n#### Validation Process\n\nThe validator performs four sequential steps:\n\n1. **Block-target extraction** — Extracts block-level targets from the document AST, enabling feudal inheritance where children inherit parent block targets\n2. **Schema-aware META validation** — Validates META section against schema definitions when a schema is provided\n3. **Schema-independent loss-accounting** — Fires warnings regardless of schema presence\n4. **Duplicate-target detection** — Structural safety net for GH#369 duplicate-target issues\n\n资料来源：[src/octave_mcp/mcp/validate.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/validate.py)\n资料来源：[src/octave_mcp/core/validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/validator.py)\n\n### 2. `octave_write`\n\nWrites files through the full validation pipeline, supporting both creation and modification of OCTAVE documents.\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `target_path` | string | Yes | File path to write to |\n| `content` | string | No | Full content for new files or overwrites |\n| `changes` | object | No | Field updates for existing files (mutually exclusive with content) |\n| `mutations` | object | No | Optional META field overrides |\n| `base_hash` | string | No | SHA-256 hash for CAS consistency check |\n| `schema` | string | No | Schema name for validation |\n| `debug_grammar` | boolean | No | Include compiled grammar in output (default: false) |\n| `format_style` | string | No | Output mode: \"preserve\", \"expanded\", or \"compact\" |\n\n#### Format Style Options\n\n| Mode | Description |\n|------|-------------|\n| `preserve` | Span-aware mode that preserves original formatting (recommended for edits) |\n| `expanded` | Canonical re-emit with full canonical form |\n| `compact` | Minimal whitespace, reduced token count |\n\n#### Response\n\n```json\n{\n \"status\": \"success\",\n \"path\": \"/path/to/document.oct.md\",\n \"canonical_hash\": \"sha256:abc123...\",\n \"corrections\": [\"Fixed trailing whitespace\", \"Balanced brackets\"],\n \"diff\": \"--- a/doc.oct.md\\n+++ b/doc.oct.md\\n@@ ...\",\n \"validation_status\": \"VALIDATED\"\n}\n```\n\n#### Deprecation Note\n\nIn v1.14.0, the default format style will change from canonical re-emit to span-aware `\"preserve\"` mode. To opt in now, explicitly pass `format_style=\"preserve\"`. Omitting the parameter accepts the future default silently without warning.\n\n资料来源：[src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)\n\n### 3. `octave_eject`\n\nProjects OCTAVE documents to different views—canonical, executive summary, developer, or template format.\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `document` | string | Yes | The OCTAVE document to transform |\n| `mode` | string | No | Projection mode (default: canonical) |\n| `format` | string | No | Output format: \"markdown\" or \"json\" (default: markdown) |\n\n#### Projection Modes\n\n| Mode | Description | Use Case |\n|------|-------------|----------|\n| `canonical` | Full document with all sections | Preservation, validation |\n| `executive` | High-level summary with key decisions | Stakeholder review |\n| `developer` | Implementation-focused view | Code generation, testing |\n| `template` | Structure without content | New document scaffolding |\n\n资料来源：[src/octave_mcp/mcp/eject.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/eject.py)\n\n### 4. `octave_compile_grammar`\n\nCompiles schema constraints to GBNF (Greibach Normal Form) grammar for constrained generation.\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `schema` | string | Yes | Schema name to compile (e.g., META, SKILL) |\n| `include_envelope` | boolean | No | Include document envelope markers (default: true) |\n| `debug` | boolean | No | Include debug comments in output (default: false) |\n\n#### Returns\n\nReturns compiled GBNF grammar string suitable for use with constrained decoding libraries.\n\n#### Grammar Access via MCP Resources\n\nThe MCP server also exposes grammar resources at `octave://grammars/{schema_name}`, enabling dynamic grammar access without compilation:\n\n```mermaid\ngraph LR\n A[MCP Client] -->|octave://grammars/META| B[Grammar Resources]\n B --> C{Grammar Cache}\n C -->|cache hit| D[Return Cached]\n C -->|cache miss| E[Compile Schema]\n E --> F[Cache Result]\n F --> D\n```\n\n资料来源：[src/octave_mcp/mcp/compile_grammar.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/compile_grammar.py)\n资料来源：[src/octave_mcp/mcp/grammar_resources.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/grammar_resources.py)\n\n## Base Tool Infrastructure\n\nAll MCP tools inherit from `BaseTool` which provides:\n\n- **Async execution** — All tools support async invocation\n- **Logging integration** — Structured logging with tool context\n- **Error handling** — Consistent error formatting with error codes\n- **Result schema** — Standardized response structure\n\n资料来源：[src/octave_mcp/mcp/base_tool.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/base_tool.py)\n\n## CLI Equivalents\n\nFor command-line usage, the tools are also available as CLI commands:\n\n```bash\noctave validate document.oct.md\noctave write output.oct.md --stdin\noctave eject document.oct.md --mode executive --format markdown\n```\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n## Tool Selection Guide\n\n| Scenario | Recommended Tool |\n|----------|-----------------|\n| Verify document correctness | `octave_validate` |\n| Create new document | `octave_write` with `content` |\n| Modify existing document | `octave_write` with `changes` |\n| Generate summary view | `octave_eject` with `mode: executive` |\n| Prepare for constrained generation | `octave_compile_grammar` |\n| Reformat document | `octave_eject` with `mode: canonical` |\n\n## Error Codes\n\n| Code | Meaning |\n|------|---------|\n| `E_NESTED_INLINE_MAP` | Inner value is an inline map (strict mode error) |\n| `W_NESTED_INLINE_MAP` | Inner value is an inline map (lenient mode warning) |\n| `W_META_001` | Missing recommended META field |\n| `W_META_002` | Unknown META field present |\n| `GH#369` | Duplicate target detected |\n\n## When to Use MCP Tools\n\n**Use MCP tools for:**\n- Documents passing through multiple agents or tools\n- Agent and skill files with YAML discovery headers\n- Decision logs, coordination briefs, and audit trails\n- System prompts where token cost matters\n\n**Do not use for:**\n- Single-step prompts\n- Freeform prose\n- Direct code output without document structure\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n---\n\n\n\n## CLI Interface\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#page-mcp-tools), [Python API Reference](#page-python-api)\n\n
\nRelevant Source Files\n\nThe following source files were used to generate this documentation:\n\n- [src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)\n- [tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)\n- [tools/octave-to-json.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-to-json.py)\n- [tools/json-to-octave.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/json-to-octave.py)\n- [tools/lint-octave.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/lint-octave.py)\n- [README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n
\n\n# CLI Interface\n\nThe CLI (Command Line Interface) for octave-mcp provides a suite of standalone tools for validating, converting, and processing OCTAVE documents outside of the MCP protocol. These tools enable direct file-based workflows, batch processing, and integration with external systems that require OCTAVE content in alternative formats.\n\n## Overview\n\nThe CLI interface consists of two categories of tools:\n\n| Category | Tools | Purpose |\n|----------|-------|---------|\n| **Core CLI** | `octave validate`, `octave write`, `octave eject` | Primary operations via MCP server executable |\n| **Standalone Scripts** | `lint-octave.py`, `octave-to-json.py`, `json-to-octave.py`, `octave-validator.py` | Fast validation and format conversion without server overhead |\n\nThe standalone tools are particularly valuable for build pipelines, CI/CD workflows, and scenarios where spawning an MCP server is impractical.\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"CLI Tools\"\n A[octave CLI] --> B[octave validate]\n A --> C[octave write]\n A --> D[octave eject]\n end\n \n subgraph \"Standalone Tools\"\n E[lint-octave.py] --> F[Fast Syntax Check]\n G[octave-to-json.py] --> H[JSON Conversion]\n I[json-to-octave.py] --> J[OCTAVE Conversion]\n K[octave-validator.py] --> L[Repo Validation]\n end\n \n subgraph \"Core Library\"\n M[octave_mcp.core] --> N[Parser]\n M --> O[Validator]\n M --> P[Emitter]\n end\n \n B --> M\n C --> M\n D --> M\n E --> M\n G --> M\n I --> M\n K --> M\n```\n\n## Installation & Configuration\n\n### Server Installation\n\nInstall the `octave-mcp-server` executable for MCP-based CLI access:\n\n```bash\npip install octave-mcp\n```\n\n### MCP Configuration\n\n#### Claude Code (`~/.claude.json`)\n\n```json\n{\n \"mcpServers\": {\n \"octave\": {\n \"command\": \"octave-mcp-server\"\n }\n }\n}\n```\n\n#### Claude Desktop (`claude_desktop_config.json`)\n\n```json\n{\n \"mcpServers\": {\n \"octave\": {\n \"command\": \"octave-mcp-server\"\n }\n }\n}\n```\n\n#### HTTP Transport\n\nFor remote or containerized deployments:\n\n```bash\noctave-mcp-server --transport http --port 8080\n```\n\n## Core CLI Commands\n\n### `octave validate`\n\nValidates OCTAVE documents against the specification and optional schema.\n\n```bash\noctave validate document.oct.md\n```\n\n**Exit Codes:**\n- `0` - Validation successful\n- `1` - Validation failed (outputs `OCTAVE_INVALID: `)\n\n### `octave write`\n\nWrites files through the full validation pipeline.\n\n```bash\noctave write output.oct.md --stdin\n```\n\nThe `--stdin` flag reads content from standard input, enabling piping from other tools.\n\n### `octave eject`\n\nProjects documents to different views for specialized audiences.\n\n```bash\noctave eject document.oct.md --mode executive --format markdown\n```\n\n**Available Modes:**\n| Mode | Purpose |\n|------|---------|\n| `canonical` | Full OCTAVE format |\n| `executive` | High-level summary for decision-makers |\n| `developer` | Implementation-focused view |\n| `template` | Template with placeholders |\n\n## Standalone Validation Tools\n\n### `lint-octave.py`\n\nFast syntax validation script optimized for rapid feedback.\n\n**Usage:**\n```bash\npython3 lint-octave.py < document.oct.md\n```\n\n**Output:**\n- `OCTAVE_VALID` - Document passes all checks\n- `OCTAVE_INVALID: ` - Document fails with specific reason\n\n**Validation Checks:**\n\n| Check | Description |\n|-------|-------------|\n| Document Markers | Verifies `===NAME===` and `===END===` envelope markers |\n| META Section | Confirms presence of `META:` after optional preface comments |\n| Indentation | Validates 2-space multiples |\n| Assignment Syntax | Ensures `KEY::VALUE` format |\n| Balanced Brackets | Checks `[]` bracket matching |\n| Trailing Commas | Rejects trailing commas in lists |\n\n资料来源：[tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)\n\n### `octave-validator.py`\n\nRepository-level validator that wraps the OCTAVE-MCP core parser/validator. This tool prevents drift between runtime validation and document validation.\n\n**Usage:**\n```bash\n# Single file validation\npython3 octave-validator.py document.oct.md\n\n# Directory scanning\npython3 octave-validator.py --path /path/to/documents\n```\n\n**Command-Line Arguments:**\n\n| Argument | Short | Description | Default |\n|----------|-------|-------------|---------|\n| `--version` | `-v` | OCTAVE version label (informational) | `6.0.0` |\n| `--profile` | `-p` | Validation profile | `protocol` |\n| `--schema` | - | Schema name for validation | None |\n| `--require-frontmatter` | - | Fail on missing YAML frontmatter | False |\n| `--path` | `-d` | Scan directory for `*.oct.md` files | None |\n\n**Validation Profiles:**\n\n| Profile | Description |\n|---------|-------------|\n| `protocol` | Standard OCTAVE protocol validation |\n| `hestai-agent` | Agent document format with YAML frontmatter |\n| `hestai-skill` | Skill document format with YAML frontmatter |\n| `hestai-pattern` | Pattern document format |\n\n```bash\n# Strict validation with required frontmatter\npython3 octave-validator.py agent.oct.md --profile hestai-agent --require-frontmatter\n\n# Schema validation\npython3 octave-validator.py document.oct.md --schema SKILL\n```\n\n资料来源：[tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)\n\n## Format Conversion Tools\n\n### `octave-to-json.py`\n\nConverts OCTAVE documents to JSON for system integration.\n\n**Usage:**\n```bash\npython3 octave-to-json.py document.oct.md > output.json\n```\n\n**Features:**\n- Preserves semantic operators (`synthesis`, `tension`, `progression`)\n- Tracks blank lines for round-trip fidelity\n- Maintains quoted strings\n- Handles nested structures\n\n资料来源：[tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)\n\n### `json-to-octave.py`\n\nConverts JSON back to OCTAVE format, restoring original formatting.\n\n**Usage:**\n```bash\npython3 json-to-octave.py input.json > document.oct.md\n```\n\n**Features:**\n- Restores original formatting including blank lines\n- Reconstructs semantic operators\n- Preserves document structure\n\n## Round-Trip Conversion\n\nThe conversion tools support bidirectional transformation with fidelity preservation:\n\n```mermaid\ngraph LR\n A[OCTAVE] -->|octave-to-json.py| B[JSON]\n B -->|json-to-octave.py| A\n B -->|round-trip| C{Same Content?}\n C -->|Yes| D[Perfect Round-Trip]\n C -->|No| E[Check for Data Loss]\n```\n\n**Verification Example:**\n```bash\n# Convert OCTAVE to JSON and back\npython3 octave-to-json.py input.oct.md | python3 json-to-octave.py > output.oct.md\n\n# Verify perfect round-trip\ndiff input.oct.md output.oct.md\n```\n\n## MCP Tool Interface\n\nThe CLI tools mirror MCP tools available for programmatic access:\n\n### Tool Comparison\n\n| CLI Command | MCP Tool | Function |\n|------------|----------|----------|\n| `octave validate` | `octave_validate` | Validate against schema |\n| `octave write` | `octave_write` | Write files with validation |\n| `octave eject` | `octave_eject` | Project to different views |\n| - | `octave_compile_grammar` | Compile schema constraints to GBNF |\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n### `octave_write` Parameters\n\nThe `octave_write` MCP tool provides comprehensive file writing capabilities:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `target_path` | string | File path to write to |\n| `content` | string | Full content for new files (mutually exclusive with `changes`) |\n| `changes` | object | Field updates for existing files (mutually exclusive with `content`) |\n| `mutations` | object | Optional META field overrides |\n| `base_hash` | string | Optional CAS consistency check hash |\n| `schema` | string | Optional schema name for validation |\n| `debug_grammar` | boolean | Include compiled grammar in output (default: false) |\n| `format_style` | string | Output formatting: `\"preserve\"`, `\"expanded\"`, or `\"compact\"` |\n\n**Return Value Structure:**\n\n| Field | Description |\n|-------|-------------|\n| `status` | `\"success\"` or `\"error\"` |\n| `path` | Written file path (on success) |\n| `canonical_hash` | SHA-256 hash of canonical content (on success) |\n| `corrections` | List of corrections applied |\n| `diff` | Compact diff of changes |\n| `errors` | List of errors (on failure) |\n| `validation_status` | `VALIDATED` or `UNVALID` |\n\n资料来源：[src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)\n\n## Format Style Options\n\nThe `format_style` parameter controls output formatting:\n\n| Style | Description | Use Case |\n|-------|-------------|----------|\n| `preserve` | Maintains original formatting and blank lines | Default (future v1.14.0+) |\n| `expanded` | Canonical re-emit with full structure | Current default, archival |\n| `compact` | Minimizes whitespace | Storage-constrained environments |\n\n**Deprecation Notice:**\n> Passing `format_style=None` explicitly is deprecated. In v1.14.0 the default will change from full canonical re-emit to span-aware `preserve` mode.\n\n资料来源：[src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)\n\n## Workflow Examples\n\n### CI/CD Integration\n\n```bash\n#!/bin/bash\n# Validate all OCTAVE documents in a directory\nfor file in $(find . -name \"*.oct.md\"); do\n python3 octave-validator.py \"$file\" --profile hestai-agent --require-frontmatter\n if [ $? -ne 0 ]; then\n echo \"Validation failed for $file\"\n exit 1\n fi\ndone\necho \"All documents validated successfully\"\n```\n\n### Build Pipeline\n\n```bash\n# 1. Convert source documents to JSON\npython3 octave-to-json.py docs/*.oct.md > build/documents.json\n\n# 2. Process with external tool\nexternal-processor build/documents.json > build/processed.json\n\n# 3. Convert back to OCTAVE\npython3 json-to-octave.py build/processed.json > docs/updated/\n\n# 4. Validate results\npython3 octave-validator.py --path docs/updated/\n```\n\n### Quick Validation Loop\n\n```bash\n# Watch file and validate on change (requires inotifywait)\nwhile inotifywait -e close_write document.oct.md; do\n python3 lint-octave.py < document.oct.md\ndone\n```\n\n## Tool Selection Guide\n\n```mermaid\ngraph TD\n A[Need to process OCTAVE?] --> B{Environment}\n B -->|MCP Server| C[Use octave CLI commands]\n B -->|No MCP| D{Operation Type}\n D -->|Fast Check| E[lint-octave.py]\n D -->|Full Validation| F[octave-validator.py]\n D -->|Format Conversion| G{Which Direction?}\n G -->|OCTAVE to JSON| H[octave-to-json.py]\n G -->|JSON to OCTAVE| I[json-to-octave.py]\n D -->|Batch Processing| J[octave-validator.py --path]\n```\n\n**Decision Matrix:**\n\n| Scenario | Recommended Tool | Reason |\n|----------|-----------------|--------|\n| Quick syntax check during editing | `lint-octave.py` | Fast, no imports required |\n| CI/CD validation pipeline | `octave-validator.py` | Full validation, exit codes |\n| Integration with JSON systems | `octave-to-json.py` / `json-to-octave.py` | Round-trip capable |\n| Claude Desktop/Code integration | MCP tools via server | Full feature set |\n| Batch directory validation | `octave-validator.py --path` | Processes all `.oct.md` files |\n\n## Error Handling\n\n### Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| `0` | Success / Validation passed |\n| `1` | Failure (validation failed, file error, etc.) |\n\n### Validation Error Output Format\n\n```\nOCTAVE_INVALID: \n```\n\nCommon reasons include:\n- Missing envelope markers (`===NAME===`)\n- Invalid META section structure\n- Syntax errors in assignments\n- Schema validation failures\n\n### Verbose Mode\n\nFor debugging validation issues, enable debug grammar output:\n\n```bash\noctave write document.oct.md --debug-grammar\n```\n\nThis includes the compiled GBNF grammar in the output, useful for identifying grammar-level failures.\n\n---\n\n\n\n## Python API Reference\n\n### 相关页面\n\n相关主题：[CLI Interface](#page-cli-interface), [MCP Tools Reference](#page-mcp-tools)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/__init__.py)\n- [src/octave_mcp/core/parser.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/parser.py)\n- [src/octave_mcp/core/emitter.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/emitter.py)\n- [src/octave_mcp/core/repair.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/repair.py)\n- [src/octave_mcp/schemas/loader.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/schemas/loader.py)\n- [docs/api.md](https://github.com/elevanaltd/octave-mcp/blob/main/docs/api.md)\n
\n\n# Python API Reference\n\nThe Python API Reference documents the public programmatic interface of the `octave_mcp` library. This API enables developers to integrate OCTAVE document parsing, validation, emission, and transformation directly into Python applications without relying on CLI commands or MCP tools.\n\n## Overview\n\nThe `octave_mcp` package provides a complete toolkit for working with OCTAVE (Olympian Common Text And Vocabulary Engine) documents. OCTAVE is a semantic DSL designed for structured document representation in LLM workflows.\n\nThe public API exports 51 functions and classes, organized into the following categories:\n\n| Category | Count | Description |\n|----------|-------|-------------|\n| Functions | 9 | Core operations: parse, emit, tokenize, repair, project, hydrate |\n| Classes | 16 | Parser, Validator, TokenType, Token, Document, Block, Assignment, etc. |\n| AST Nodes | 8 | Document, Block, Assignment, Section, ListValue, InlineMap, Absent |\n| Hydration | 3 | HydrationPolicy, VocabularyRegistry, hydrate |\n| Schema | 2 | SchemaDefinition, FieldDefinition |\n| Repair | 4 | RepairLog, RepairEntry, RepairTier, RoutingLog |\n| Exceptions | 8 | VocabularyError, CollisionError, ParserError, LexerError, etc. |\n\n*资料来源：[src/octave_mcp/__init__.py:12-45]()\n\n## Core Functions\n\n### parse()\n\n```python\ndef parse(content: str) -> Document\n```\n\nThe primary parsing function that converts OCTAVE-formatted text into an Abstract Syntax Tree (AST).\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `content` | `str` | OCTAVE document string to parse |\n\n**Returns:** `Document` - The parsed AST representation\n\n**Behavior:**\n- Returns a `Document` object with sections, blocks, and assignments\n- Does not emit warnings; use `parse_with_warnings()` for detailed diagnostics\n- Supports OCTAVE 6.x grammar including grammar sentinel `OCTAVE::VERSION` headers\n\n*资料来源：[src/octave_mcp/__init__.py:27]()\n\n### parse_with_warnings()\n\n```python\ndef parse_with_warnings(content: str) -> tuple[Document, list[WarningEntry]]\n```\n\nExtended parsing that returns both the document and any warnings encountered during parsing.\n\n**Returns:** `tuple[Document, list[WarningEntry]]` - Document and warnings list\n\n**Warning Types:**\n- Missing META section\n- Non-protocol dialect tokens detected\n- Lenient preprocessing applied for HestAI dialect\n\n*资料来源：[src/octave_mcp/core/parser.py:340-350]()\n\n### emit()\n\n```python\ndef emit(doc: Document) -> str\n```\n\nConverts a Document AST back into a canonical OCTAVE-formatted string.\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `doc` | `Document` | The AST document to emit |\n\n**Returns:** `str` - Canonical OCTAVE-formatted output\n\n**Note:** This function is the inverse of `parse()`. Round-trip conversion preserves document structure including blank lines and semantic operators.\n\n*资料来源：[src/octave_mcp/__init__.py:27](), [src/octave_mcp/core/emitter.py]()\n\n### tokenize()\n\n```python\ndef tokenize(content: str) -> list[Token]\n```\n\nBreaks OCTAVE content into a stream of tokens for lexical analysis.\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `content` | `str` | OCTAVE document string |\n\n**Returns:** `list[Token]` - Ordered list of tokens with type and value\n\n**Token Types:**\n- `ENVELOPE_START` / `ENVELOPE_END`\n- `SECTION_KEY`\n- `ASSIGNMENT`\n- `LIST_START` / `LIST_END`\n- `GRAMMAR_SENTINEL`\n- `IDENTIFIER`\n- `STRING`\n\n*资料来源：[src/octave_mcp/__init__.py:27]()\n\n### repair()\n\n```python\ndef repair(content: str) -> tuple[str, RepairLog]\n```\n\nAttempts to automatically fix malformed OCTAVE content.\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `content` | `str` | Potentially malformed OCTAVE content |\n\n**Returns:** `tuple[str, RepairLog]` - Repaired content and log of changes\n\n**Repair Strategies:**\n- Localized salvaging preserves document structure where possible\n- Wraps plain text into BODY: RAW carrier for non-parseable content\n- Marks failing lines with `_PARSE_ERROR_LINE_N` markers\n\n*资料来源：[src/octave_mcp/__init__.py:27](), [src/octave_mcp/core/repair.py]()\n\n### project()\n\n```python\ndef project(doc: Document, mode: str) -> ProjectionResult\n```\n\nTransforms a document into different output views.\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `doc` | `Document` | Source document |\n| `mode` | `str` | Projection mode: canonical, executive, developer, template |\n\n**Returns:** `ProjectionResult` - Transformed document with routing log\n\n*资料来源：[src/octave_mcp/__init__.py:27]()\n\n### hydrate()\n\n```python\ndef hydrate(doc: Document, policy: HydrationPolicy) -> Document\n```\n\nApplies a hydration policy to a document for variable substitution and template expansion.\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `doc` | `Document` | Document to hydrate |\n| `policy` | `HydrationPolicy` | Hydration configuration |\n\n**Returns:** `Document` - Hydrated document with substitutions applied\n\n*资料来源：[src/octave_mcp/__init__.py:27]()\n\n### extract_schema_from_document()\n\n```python\ndef extract_schema_from_document(doc: Document) -> SchemaDefinition\n```\n\nInfers the schema definition from an existing document's structure.\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `doc` | `Document` | Document to analyze |\n\n**Returns:** `SchemaDefinition` - Inferred schema with field definitions\n\n*资料来源：[src/octave_mcp/__init__.py:27]()\n\n### seal_document() / verify_seal()\n\n```python\ndef seal_document(doc: Document) -> Document\ndef verify_seal(doc: Document) -> SealVerificationResult\n```\n\nIntegrity management functions for document sealing.\n\n*资料来源：[src/octave_mcp/__init__.py:27]()\n\n## Core Classes\n\n### Parser\n\nThe `Parser` class provides detailed control over the parsing process.\n\n```python\nclass Parser:\n def __init__(self, content: str)\n def parse(self) -> Document\n def parse_document(self) -> Document\n def current() -> Token\n def advance() -> Token\n```\n\n**Key Methods:**\n\n| Method | Description |\n|--------|-------------|\n| `parse_document()` | Parse complete OCTAVE document with ADR-0006 SR2-T2 support for `start_byte`/`end_byte` |\n| `parse_with_warnings()` | Returns document with META region byte positions |\n\n**Grammar Sentinel Support:**\n- Recognizes `OCTAVE::VERSION` pattern\n- Populates `doc.grammar_version` from lexer\n\n*资料来源：[src/octave_mcp/core/parser.py:150-180]()\n\n### Document\n\nThe AST representation of an OCTAVE document.\n\n```python\n@dataclass\nclass Document:\n name: str\n grammar_version: str | None\n start_byte: int\n end_byte: int\n meta_start_byte: int | None\n meta_end_byte: int | None\n sections: list[Block]\n```\n\n**Attributes:**\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `name` | `str` | Document envelope name (e.g., \"MY_DOC\") or \"INFERRED\" |\n| `grammar_version` | `str \\| None` | Version from grammar sentinel |\n| `start_byte` | `int` | Document start byte offset (always 0 for NFC base) |\n| `end_byte` | `int` | Document end byte offset |\n| `meta_start_byte` | `int \\| None` | META block start (when present) |\n| `meta_end_byte` | `int \\| None` | META block end (when present) |\n| `sections` | `list[Block]` | Parsed section blocks |\n\n*资料来源：[src/octave_mcp/core/parser.py:150-160]()\n\n### Block\n\nRepresents a structural block within a document.\n\n```python\n@dataclass\nclass Block:\n key: str\n children: list[Section | Assignment]\n```\n\n### Assignment\n\nRepresents a key-value assignment.\n\n```python\n@dataclass\nclass Assignment:\n key: str\n value: str | ListValue | InlineMap\n```\n\n### HydrationPolicy\n\nConfiguration for document hydration.\n\n```python\n@dataclass\nclass HydrationPolicy:\n registry: VocabularyRegistry\n strict: bool\n mode: str # \"substitute\", \"expand\", \"validate\"\n```\n\n### SchemaDefinition\n\nSchema definition for validation.\n\n```python\n@dataclass\nclass SchemaDefinition:\n name: str\n fields: list[FieldDefinition]\n```\n\n*资料来源：[src/octave_mcp/__init__.py:30-45]()\n\n## Exception Classes\n\n| Exception | Description |\n|-----------|-------------|\n| `VocabularyError` | Vocabulary-related validation failure |\n| `CollisionError` | Key or name collision detected |\n| `VersionMismatchError` | Grammar version incompatibility |\n| `CycleDetectionError` | Circular dependency in hydration |\n| `SourceUriSecurityError` | Unsafe URI reference detected |\n| `ParserError` | Parsing failure |\n| `LexerError` | Lexical analysis failure |\n| `ValidationError` | Schema validation failure |\n\n*资料来源：[src/octave_mcp/__init__.py:43-45]()\n\n## Repair System\n\n### RepairLog\n\n```python\n@dataclass\nclass RepairLog:\n entries: list[RepairEntry]\n corrections: list[dict[str, Any]]\n```\n\n### RepairTier\n\n| Tier | Description |\n|------|-------------|\n| `LENIENT_PARSE` | Minor fixes that preserve semantics |\n| `MODERATE` | Structural corrections |\n| `STRICT` | Breaking changes required |\n\n### RepairEntry\n\n```python\n@dataclass\nclass RepairEntry:\n code: str\n tier: RepairTier\n message: str\n safe: bool\n semantics_changed: bool\n```\n\n**Common Repair Codes:**\n\n| Code | Tier | Description |\n|------|------|-------------|\n| `W_STRUCT_RAW_WRAP` | LENIENT_PARSE | Wrapped plain text into BODY: RAW carrier |\n\n*资料来源：[src/octave_mcp/core/repair.py]()\n\n## Schema Loading\n\n### load_schema_by_name()\n\n```python\ndef load_schema_by_name(schema_name: str) -> SchemaDefinition | None\n```\n\nLoads a schema definition by name from the builtin registry or search paths.\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `schema_name` | `str` | Schema name (e.g., \"META\", \"SKILL\", \"SESSION_LOG\") |\n\n**Returns:** `SchemaDefinition` or `None` if not found\n\n**Builtin Schemas:**\n- `META` - Document metadata schema\n- `SKILL` - Skill definition schema\n- `SESSION_LOG` - Session logging schema\n\n*资料来源：[src/octave_mcp/schemas/loader.py]()\n\n## Usage Examples\n\n### Basic Parsing\n\n```python\nfrom octave_mcp import parse, emit\n\n# Parse OCTAVE content\ncontent = '''===MY_DOC===\nMETA:\n TYPE::SKILL\n VERSION::\"1.0.0\"\n§1::CONTENT\nKEY::VALUE\n===END===\n'''\n\ndoc = parse(content)\nprint(f\"Document name: {doc.name}\")\nprint(f\"Grammar version: {doc.grammar_version}\")\n```\n\n### Round-Trip Conversion\n\n```python\nfrom octave_mcp import parse, emit\n\ncontent = '''===EXAMPLE===\nMETA:\n TYPE::TEST\n§1::SECTION\nFIELD::VALUE\n===END===\n'''\n\ndoc = parse(content)\noutput = emit(doc)\n# output is canonical OCTAVE\n```\n\n### Validation with Repair\n\n```python\nfrom octave_mcp import repair, parse\n\nmalformed = '''===DOC===\nMETA:\n TYPE::TEST\nINVALID§SYNTAX\n===END===\n'''\n\nrepaired, log = repair(malformed)\nprint(f\"Repaired content: {repaired}\")\nprint(f\"Corrections made: {len(log.corrections)}\")\n```\n\n### Schema Validation\n\n```python\nfrom octave_mcp import parse, Validator\nfrom octave_mcp.schemas import load_schema_by_name\n\ndoc = parse(octave_content)\nschema = load_schema_by_name(\"META\")\nvalidator = Validator(schema)\nresult = validator.validate(doc)\n```\n\n*资料来源：[docs/api.md]()\n\n## Architecture Diagram\n\n```mermaid\ngraph TD\n A[OCTAVE String Input] --> B[Parser]\n B --> C[Document AST]\n C --> D[Validator]\n C --> E[Emitter]\n C --> F[Repair]\n F --> G{Parse Success?}\n G -->|No| H[Localized Salvage]\n G -->|Yes| C\n H --> I[Repaired Content]\n I --> B\n D --> J[ValidationResult]\n E --> K[Canonical OCTAVE Output]\n F --> L[RepairLog]\n C --> M[Projector]\n M --> N[ProjectionResult]\n C --> O[Hydrator]\n O --> P[HydratedDocument]\n \n style A fill:#e1f5fe\n style K fill:#c8e6c9\n style J fill:#fff3e0\n style L fill:#fce4ec\n```\n\n## CLI vs Python API\n\n| Feature | CLI | Python API |\n|---------|-----|------------|\n| Quick validation | ✓ | ✓ via `parse()` |\n| File operations | ✓ | Manual |\n| Streaming | ✓ | ✓ via generators |\n| Custom repair strategies | ✗ | ✓ via `repair()` |\n| AST manipulation | ✗ | ✓ |\n| Integration into Python apps | ✗ | ✓ |\n| MCP tools | ✓ | ✗ |\n\n## Advanced: Grammar Compilation\n\n```python\nfrom octave_mcp.core.grammar_compiler import compile_document_grammar\n\ngrammar = compile_document_grammar(\"META\")\n# Returns GBNF grammar string for schema\n```\n\nThe grammar compiler supports:\n- Schema-based grammar generation\n- Cached compilation for performance\n- Include/exclude envelope markers\n\n*资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py]()\n\n## Best Practices\n\n1. **Use `parse_with_warnings()` during development** to catch non-protocol dialect tokens\n2. **Call `repair()` before `parse()`** when processing untrusted input\n3. **Cache schema definitions** if loading repeatedly\n4. **Use `emit()` for round-trip verification** in tests\n5. **Leverage `HydrationPolicy`** for template-based workflows\n\n## See Also\n\n- [Usage Guide](docs/usage.md) - CLI and integration examples\n- [Specs](../specs/) - OCTAVE specification documents\n- [Primers](../resources/primers/) - Quick-start primers for specific use cases\n\n---\n\n---\n\n## Doramagic Pitfall Log\n\nProject: elevanaltd/octave-mcp\n\nSummary: Found 38 potential pitfall items; 4 are high/blocking. Highest priority: security_permissions - 失败模式：security_permissions: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oc....\n\n## 1. security_permissions · 失败模式：security_permissions: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oc...\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: Developers should check this security_permissions risk before relying on the project: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md\n- User impact: Developers may expose sensitive permissions or credentials: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/elevanaltd/octave-mcp/issues/424\n- Evidence: failure_mode_cluster:github_issue | fmev_22c0329bf698546f57cbd9edd620083f | https://github.com/elevanaltd/octave-mcp/issues/424 | octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md\n\n## 2. security_permissions · 失败模式：security_permissions: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: Developers should check this security_permissions risk before relying on the project: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)\n- User impact: Developers may expose sensitive permissions or credentials: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38). Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/elevanaltd/octave-mcp/issues/420\n- Evidence: failure_mode_cluster:github_issue | fmev_e63e5f9a96f8ad23bef9d32f6c4c13e7 | https://github.com/elevanaltd/octave-mcp/issues/420 | octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)\n\n## 3. security_permissions · 来源证据：bug: octave_write surgical edit primitives unsafe on inline-array top-level entries (APPEND + expanded modes)\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: octave_write surgical edit primitives unsafe on inline-array top-level entries (APPEND + expanded modes)\n- User impact: 可能影响升级、迁移或版本选择。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_75dbe0c2c20b479a9afc619c467acc20 | https://github.com/elevanaltd/octave-mcp/issues/411 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. security_permissions · 来源证据：octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_744a11a12c0340e08087ea951c281000 | https://github.com/elevanaltd/octave-mcp/issues/426 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. installation · 失败模式：installation: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed findin...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks\n- User impact: Developers may fail before the first successful local run: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_8ff9088f7d6c1752dffdf17a7dd320db | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks, failure_mode_cluster:github_issue | fmev_aa61ed66e510ebfae83228fb28ae6e11 | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks, failure_mode_cluster:github_issue | fmev_6046cbe1d9f5946d7c5f3b4a9e75cd5a | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks, failure_mode_cluster:github_issue | fmev_6450b53644007e96c1fa966585fe47ea | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks\n\n## 6. installation · 失败模式：installation: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type doc...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents\n- User impact: Developers may fail before the first successful local run: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_9d395f7455d912516430481376e952e2 | https://github.com/elevanaltd/octave-mcp/issues/425 | octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents\n\n## 7. installation · 来源证据：bug: _find_target_start backslash-run quote-escape mishandling (sibling of cubic P1 on PR #431)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: _find_target_start backslash-run quote-escape mishandling (sibling of cubic P1 on PR #431)\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_8284755b0fa74799b1f881f624677141 | https://github.com/elevanaltd/octave-mcp/issues/432 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. configuration · 失败模式：configuration: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describi...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty)\n- User impact: Developers may misconfigure credentials, environment, or host setup: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty). Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_c368f015439226dbb8b9c45fddf3158d | https://github.com/elevanaltd/octave-mcp/issues/430 | RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty)\n\n## 9. configuration · 失败模式：configuration: bug: emitter normalises backslash counts in string literals (round-trip byte-loss)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: bug: emitter normalises backslash counts in string literals (round-trip byte-loss)\n- User impact: Developers may misconfigure credentials, environment, or host setup: bug: emitter normalises backslash counts in string literals (round-trip byte-loss)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug: emitter normalises backslash counts in string literals (round-trip byte-loss). Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_bbc57f3d1a93f9e5fb48332874044f35 | https://github.com/elevanaltd/octave-mcp/issues/434 | bug: emitter normalises backslash counts in string literals (round-trip byte-loss)\n\n## 10. configuration · 失败模式：configuration: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only pat...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue)\n- User impact: Developers may misconfigure credentials, environment, or host setup: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue). Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_cf23dec47765d23b75fcd69bef5c1332 | https://github.com/elevanaltd/octave-mcp/issues/433 | bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue)\n\n## 11. configuration · 失败模式：configuration: bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say fu...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplicate key (invalid O...\n- User impact: Developers may misconfigure credentials, environment, or host setup: bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplicate key (invalid O...\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplicate key (invalid O.... Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_6420a6baab4269626b43aeca56c0d6c8 | https://github.com/elevanaltd/octave-mcp/issues/443 | bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplicate key (invalid O...\n\n## 12. configuration · 失败模式：configuration: governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate\n- User impact: Developers may misconfigure credentials, environment, or host setup: governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_67bfde22b66b3bde199f59556c21e82d | https://github.com/elevanaltd/octave-mcp/issues/441 | governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate\n\n## 13. configuration · 失败模式：configuration: octave_validate: SKILL schema only validates frontmatter; §-section body uncovered\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: octave_validate: SKILL schema only validates frontmatter; §-section body uncovered\n- User impact: Developers may misconfigure credentials, environment, or host setup: octave_validate: SKILL schema only validates frontmatter; §-section body uncovered\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: octave_validate: SKILL schema only validates frontmatter; §-section body uncovered. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_339fb57ac390e565b548c1bea78abc66 | https://github.com/elevanaltd/octave-mcp/issues/428 | octave_validate: SKILL schema only validates frontmatter; §-section body uncovered, failure_mode_cluster:github_issue | fmev_338bf1f21059e0d238b9fcb8084aea71 | https://github.com/elevanaltd/octave-mcp/issues/428 | octave_validate: SKILL schema only validates frontmatter; §-section body uncovered\n\n## 14. configuration · 来源证据：bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form-preservation gap)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form-preservation gap)\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_6236e7ed154c4976ac4a7deee1e5e95d | https://github.com/elevanaltd/octave-mcp/issues/447 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 15. configuration · 来源证据：octave_validate: DEBATE_TRANSCRIPT STATUS enum missing 'PAUSED' (live false negative)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：octave_validate: DEBATE_TRANSCRIPT STATUS enum missing 'PAUSED' (live false negative)\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_b0ee99f7200a4686b5de382a2c70d9b2 | https://github.com/elevanaltd/octave-mcp/issues/423 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | README/documentation is current enough for a first validation pass.\n\n## 17. runtime · 失败模式：runtime: bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP cr...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this runtime risk before relying on the project: bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock\n- User impact: Developers may hit a documented source-backed failure mode: bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_9022259172bcd98fea3c615e38180f11 | https://github.com/elevanaltd/octave-mcp/issues/440 | bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock\n\n## 18. runtime · 失败模式：runtime: enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this runtime risk before relying on the project: enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement\n- User impact: Developers may hit a documented source-backed failure mode: enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_4667399fae050529c3b6df294209996d | https://github.com/elevanaltd/octave-mcp/issues/439 | enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement\n\n## 19. runtime · 失败模式：runtime: enhancement: validator section-bucket merging may mask path-isolated requirements (raised on...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this runtime risk before relying on the project: enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444)\n- User impact: Developers may hit a documented source-backed failure mode: enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444). Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_d71a3524d919da6f5900dcc0df04304b | https://github.com/elevanaltd/octave-mcp/issues/445 | enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444)\n\n## 20. runtime · 来源证据：bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_2512797d818a4840822d948795de8588 | https://github.com/elevanaltd/octave-mcp/issues/440 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 21. runtime · 来源证据：bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_a8d2b9e12cb2477499d2ada52aed438e | https://github.com/elevanaltd/octave-mcp/issues/436 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 22. runtime · 来源证据：enhancement: octave_validate ENUM constraint non-enforcement (PARTIAL → IMPLEMENTED)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：enhancement: octave_validate ENUM constraint non-enforcement (PARTIAL → IMPLEMENTED)\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_c9882e67c42642b0864690256d8258e6 | https://github.com/elevanaltd/octave-mcp/issues/435 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 23. runtime · 来源证据：enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_ed6a5fd931ec45489d58f2763b403513 | https://github.com/elevanaltd/octave-mcp/issues/439 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 24. runtime · 来源证据：enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444)\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_28e0ef9cb32e4e918dafd0e22960d639 | https://github.com/elevanaltd/octave-mcp/issues/445 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 25. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | last_activity_observed missing\n\n## 26. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | no_demo; severity=medium\n\n## 27. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | no_demo; severity=medium\n\n## 28. security_permissions · 来源证据：DECISION_LOG schema v1.1 conformance: reference DECISIONS.oct.md reports 68 STRICT validation_errors\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：DECISION_LOG schema v1.1 conformance: reference DECISIONS.oct.md reports 68 STRICT validation_errors\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_8d4d0aa8843f448b8151f98bb89a5d32 | https://github.com/elevanaltd/octave-mcp/issues/448 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 29. security_permissions · 来源证据：bug: emitter normalises backslash counts in string literals (round-trip byte-loss)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: emitter normalises backslash counts in string literals (round-trip byte-loss)\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_2c50ae54a6ed47aa92320c3c9a40fdc2 | https://github.com/elevanaltd/octave-mcp/issues/434 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 30. security_permissions · 来源证据：bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-o…\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplic…\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_694f815fe5af49db82e637268c4346ca | https://github.com/elevanaltd/octave-mcp/issues/443 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 31. security_permissions · 来源证据：governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_6d91773d5074499aa595b7e38bddbb0d | https://github.com/elevanaltd/octave-mcp/issues/441 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 32. security_permissions · 来源证据：octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_7c17465d2f4a474e8516a911c69b6427 | https://github.com/elevanaltd/octave-mcp/issues/424 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 33. security_permissions · 来源证据：octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_86500177a232460e83ffd2da0f3bf682 | https://github.com/elevanaltd/octave-mcp/issues/420 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 34. capability · 失败模式：capability: bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this capability risk before relying on the project: bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)\n- User impact: Developers may hit a documented source-backed failure mode: bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only). Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_5da92869a244d36ecaf3e556113dc916 | https://github.com/elevanaltd/octave-mcp/issues/436 | bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)\n\n## 35. capability · 失败模式：conceptual: bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form...\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this conceptual risk before relying on the project: bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form-preservation gap)\n- User impact: Developers may hit a documented source-backed failure mode: bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form-preservation gap)\n- Suggested check: 复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_7310a80e89468fb4bd5c6e61aadaa05b | https://github.com/elevanaltd/octave-mcp/issues/447 | bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form-preservation gap)\n\n## 36. capability · 失败模式：conceptual: octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed/enforced\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this conceptual risk before relying on the project: octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed/enforced\n- User impact: Developers may hit a documented source-backed failure mode: octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed/enforced\n- Suggested check: 复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_8978c0e787312f231a947da5f5c4e156 | https://github.com/elevanaltd/octave-mcp/issues/427 | octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed/enforced, failure_mode_cluster:github_issue | fmev_ea0f8b5de25b570660810c386051af8e | https://github.com/elevanaltd/octave-mcp/issues/427 | octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed/enforced\n\n## 37. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | issue_or_pr_quality=unknown\n\n## 38. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | release_recency=unknown\n\n\n", "summary": "DeepWiki/Human Wiki output with a Doramagic pitfall appendix.", "title": "Human Manual" }, "pitfall_log": { "asset_id": "pitfall_log", "filename": "PITFALL_LOG.md", "markdown": "# Pitfall Log\n\nProject: elevanaltd/octave-mcp\n\nSummary: Found 38 potential pitfall items; 4 are high/blocking. Highest priority: security_permissions - 失败模式：security_permissions: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oc....\n\n## 1. security_permissions · 失败模式：security_permissions: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oc...\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: Developers should check this security_permissions risk before relying on the project: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md\n- User impact: Developers may expose sensitive permissions or credentials: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/elevanaltd/octave-mcp/issues/424\n- Evidence: failure_mode_cluster:github_issue | fmev_22c0329bf698546f57cbd9edd620083f | https://github.com/elevanaltd/octave-mcp/issues/424 | octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md\n\n## 2. security_permissions · 失败模式：security_permissions: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: Developers should check this security_permissions risk before relying on the project: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)\n- User impact: Developers may expose sensitive permissions or credentials: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38). Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/elevanaltd/octave-mcp/issues/420\n- Evidence: failure_mode_cluster:github_issue | fmev_e63e5f9a96f8ad23bef9d32f6c4c13e7 | https://github.com/elevanaltd/octave-mcp/issues/420 | octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)\n\n## 3. security_permissions · 来源证据：bug: octave_write surgical edit primitives unsafe on inline-array top-level entries (APPEND + expanded modes)\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: octave_write surgical edit primitives unsafe on inline-array top-level entries (APPEND + expanded modes)\n- User impact: 可能影响升级、迁移或版本选择。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_75dbe0c2c20b479a9afc619c467acc20 | https://github.com/elevanaltd/octave-mcp/issues/411 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. security_permissions · 来源证据：octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_744a11a12c0340e08087ea951c281000 | https://github.com/elevanaltd/octave-mcp/issues/426 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. installation · 失败模式：installation: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed findin...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks\n- User impact: Developers may fail before the first successful local run: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_8ff9088f7d6c1752dffdf17a7dd320db | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks, failure_mode_cluster:github_issue | fmev_aa61ed66e510ebfae83228fb28ae6e11 | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks, failure_mode_cluster:github_issue | fmev_6046cbe1d9f5946d7c5f3b4a9e75cd5a | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks, failure_mode_cluster:github_issue | fmev_6450b53644007e96c1fa966585fe47ea | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks\n\n## 6. installation · 失败模式：installation: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type doc...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents\n- User impact: Developers may fail before the first successful local run: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_9d395f7455d912516430481376e952e2 | https://github.com/elevanaltd/octave-mcp/issues/425 | octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents\n\n## 7. installation · 来源证据：bug: _find_target_start backslash-run quote-escape mishandling (sibling of cubic P1 on PR #431)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: _find_target_start backslash-run quote-escape mishandling (sibling of cubic P1 on PR #431)\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_8284755b0fa74799b1f881f624677141 | https://github.com/elevanaltd/octave-mcp/issues/432 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. configuration · 失败模式：configuration: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describi...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty)\n- User impact: Developers may misconfigure credentials, environment, or host setup: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty). Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_c368f015439226dbb8b9c45fddf3158d | https://github.com/elevanaltd/octave-mcp/issues/430 | RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty)\n\n## 9. configuration · 失败模式：configuration: bug: emitter normalises backslash counts in string literals (round-trip byte-loss)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: bug: emitter normalises backslash counts in string literals (round-trip byte-loss)\n- User impact: Developers may misconfigure credentials, environment, or host setup: bug: emitter normalises backslash counts in string literals (round-trip byte-loss)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug: emitter normalises backslash counts in string literals (round-trip byte-loss). Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_bbc57f3d1a93f9e5fb48332874044f35 | https://github.com/elevanaltd/octave-mcp/issues/434 | bug: emitter normalises backslash counts in string literals (round-trip byte-loss)\n\n## 10. configuration · 失败模式：configuration: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only pat...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue)\n- User impact: Developers may misconfigure credentials, environment, or host setup: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue). Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_cf23dec47765d23b75fcd69bef5c1332 | https://github.com/elevanaltd/octave-mcp/issues/433 | bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue)\n\n## 11. configuration · 失败模式：configuration: bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say fu...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplicate key (invalid O...\n- User impact: Developers may misconfigure credentials, environment, or host setup: bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplicate key (invalid O...\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplicate key (invalid O.... Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_6420a6baab4269626b43aeca56c0d6c8 | https://github.com/elevanaltd/octave-mcp/issues/443 | bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplicate key (invalid O...\n\n## 12. configuration · 失败模式：configuration: governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate\n- User impact: Developers may misconfigure credentials, environment, or host setup: governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_67bfde22b66b3bde199f59556c21e82d | https://github.com/elevanaltd/octave-mcp/issues/441 | governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate\n\n## 13. configuration · 失败模式：configuration: octave_validate: SKILL schema only validates frontmatter; §-section body uncovered\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: octave_validate: SKILL schema only validates frontmatter; §-section body uncovered\n- User impact: Developers may misconfigure credentials, environment, or host setup: octave_validate: SKILL schema only validates frontmatter; §-section body uncovered\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: octave_validate: SKILL schema only validates frontmatter; §-section body uncovered. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_339fb57ac390e565b548c1bea78abc66 | https://github.com/elevanaltd/octave-mcp/issues/428 | octave_validate: SKILL schema only validates frontmatter; §-section body uncovered, failure_mode_cluster:github_issue | fmev_338bf1f21059e0d238b9fcb8084aea71 | https://github.com/elevanaltd/octave-mcp/issues/428 | octave_validate: SKILL schema only validates frontmatter; §-section body uncovered\n\n## 14. configuration · 来源证据：bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form-preservation gap)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form-preservation gap)\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_6236e7ed154c4976ac4a7deee1e5e95d | https://github.com/elevanaltd/octave-mcp/issues/447 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 15. configuration · 来源证据：octave_validate: DEBATE_TRANSCRIPT STATUS enum missing 'PAUSED' (live false negative)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：octave_validate: DEBATE_TRANSCRIPT STATUS enum missing 'PAUSED' (live false negative)\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_b0ee99f7200a4686b5de382a2c70d9b2 | https://github.com/elevanaltd/octave-mcp/issues/423 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | README/documentation is current enough for a first validation pass.\n\n## 17. runtime · 失败模式：runtime: bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP cr...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this runtime risk before relying on the project: bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock\n- User impact: Developers may hit a documented source-backed failure mode: bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_9022259172bcd98fea3c615e38180f11 | https://github.com/elevanaltd/octave-mcp/issues/440 | bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock\n\n## 18. runtime · 失败模式：runtime: enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this runtime risk before relying on the project: enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement\n- User impact: Developers may hit a documented source-backed failure mode: enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_4667399fae050529c3b6df294209996d | https://github.com/elevanaltd/octave-mcp/issues/439 | enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement\n\n## 19. runtime · 失败模式：runtime: enhancement: validator section-bucket merging may mask path-isolated requirements (raised on...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this runtime risk before relying on the project: enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444)\n- User impact: Developers may hit a documented source-backed failure mode: enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444). Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_d71a3524d919da6f5900dcc0df04304b | https://github.com/elevanaltd/octave-mcp/issues/445 | enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444)\n\n## 20. runtime · 来源证据：bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_2512797d818a4840822d948795de8588 | https://github.com/elevanaltd/octave-mcp/issues/440 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 21. runtime · 来源证据：bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_a8d2b9e12cb2477499d2ada52aed438e | https://github.com/elevanaltd/octave-mcp/issues/436 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 22. runtime · 来源证据：enhancement: octave_validate ENUM constraint non-enforcement (PARTIAL → IMPLEMENTED)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：enhancement: octave_validate ENUM constraint non-enforcement (PARTIAL → IMPLEMENTED)\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_c9882e67c42642b0864690256d8258e6 | https://github.com/elevanaltd/octave-mcp/issues/435 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 23. runtime · 来源证据：enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_ed6a5fd931ec45489d58f2763b403513 | https://github.com/elevanaltd/octave-mcp/issues/439 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 24. runtime · 来源证据：enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444)\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_28e0ef9cb32e4e918dafd0e22960d639 | https://github.com/elevanaltd/octave-mcp/issues/445 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 25. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | last_activity_observed missing\n\n## 26. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | no_demo; severity=medium\n\n## 27. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | no_demo; severity=medium\n\n## 28. security_permissions · 来源证据：DECISION_LOG schema v1.1 conformance: reference DECISIONS.oct.md reports 68 STRICT validation_errors\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：DECISION_LOG schema v1.1 conformance: reference DECISIONS.oct.md reports 68 STRICT validation_errors\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_8d4d0aa8843f448b8151f98bb89a5d32 | https://github.com/elevanaltd/octave-mcp/issues/448 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 29. security_permissions · 来源证据：bug: emitter normalises backslash counts in string literals (round-trip byte-loss)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: emitter normalises backslash counts in string literals (round-trip byte-loss)\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_2c50ae54a6ed47aa92320c3c9a40fdc2 | https://github.com/elevanaltd/octave-mcp/issues/434 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 30. security_permissions · 来源证据：bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-o…\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplic…\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_694f815fe5af49db82e637268c4346ca | https://github.com/elevanaltd/octave-mcp/issues/443 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 31. security_permissions · 来源证据：governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_6d91773d5074499aa595b7e38bddbb0d | https://github.com/elevanaltd/octave-mcp/issues/441 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 32. security_permissions · 来源证据：octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_7c17465d2f4a474e8516a911c69b6427 | https://github.com/elevanaltd/octave-mcp/issues/424 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 33. security_permissions · 来源证据：octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_86500177a232460e83ffd2da0f3bf682 | https://github.com/elevanaltd/octave-mcp/issues/420 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 34. capability · 失败模式：capability: bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this capability risk before relying on the project: bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)\n- User impact: Developers may hit a documented source-backed failure mode: bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only). Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_5da92869a244d36ecaf3e556113dc916 | https://github.com/elevanaltd/octave-mcp/issues/436 | bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)\n\n## 35. capability · 失败模式：conceptual: bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form...\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this conceptual risk before relying on the project: bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form-preservation gap)\n- User impact: Developers may hit a documented source-backed failure mode: bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form-preservation gap)\n- Suggested check: 复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_7310a80e89468fb4bd5c6e61aadaa05b | https://github.com/elevanaltd/octave-mcp/issues/447 | bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form-preservation gap)\n\n## 36. capability · 失败模式：conceptual: octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed/enforced\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this conceptual risk before relying on the project: octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed/enforced\n- User impact: Developers may hit a documented source-backed failure mode: octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed/enforced\n- Suggested check: 复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_8978c0e787312f231a947da5f5c4e156 | https://github.com/elevanaltd/octave-mcp/issues/427 | octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed/enforced, failure_mode_cluster:github_issue | fmev_ea0f8b5de25b570660810c386051af8e | https://github.com/elevanaltd/octave-mcp/issues/427 | octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed/enforced\n\n## 37. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | issue_or_pr_quality=unknown\n\n## 38. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | release_recency=unknown\n", "summary": "Identity, installation, configuration, runtime, and safety pitfalls before user trial.", "title": "Pitfall Log" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# octave-mcp - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for elevanaltd/octave-mcp.\n\nProject:\n- Name: octave-mcp\n- Repository: https://github.com/elevanaltd/octave-mcp\n- Summary: OCTAVE MCP Server\n- Host target: mcp_host\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: OCTAVE MCP Server\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-project-introduction: Project Introduction. Produce one small intermediate artifact and wait for confirmation.\n2. page-system-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n3. page-canonical-normalization: Canonical Normalization. Produce one small intermediate artifact and wait for confirmation.\n4. page-schema-validation: Schema Validation. Produce one small intermediate artifact and wait for confirmation.\n5. page-compression-system: Compression System. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/elevanaltd/octave-mcp#readme\n- src/octave_mcp/resources/skills/octave-compression/SKILL.md\n- src/octave_mcp/resources/skills/octave-literacy/SKILL.md\n- src/octave_mcp/resources/skills/octave-mastery/SKILL.md\n- src/octave_mcp/resources/skills/octave-mythology/SKILL.md\n- src/octave_mcp/resources/skills/octave-ultra-mythic/SKILL.md\n- README.md\n- src/octave_mcp/__init__.py\n- AGENTS.oct.md\n- src/octave_mcp/mcp/server.py\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start\n\nProject: elevanaltd/octave-mcp\n\n## Official Entry Points\n\n### Python / pip · 官方安装入口\n\n```bash\npip install octave-mcp\n```\n\nSource：https://github.com/elevanaltd/octave-mcp#readme\n\n## Sources\n\n- docs: https://github.com/elevanaltd/octave-mcp#readme\n", "summary": "Entry points extracted from official README or installation documentation.", "title": "Quick Start" } }, "validation_id": "dval_7f39a25a30e541f2b9056def84f066e7" }