codec-cortex 0.3.2__py3-none-any.whl

cortex/v2/hcortex_renderer.py

@@ -0,0 +1,450 @@
+r"""HCORTEX v2 renderer — converts SkillIR to canonical HCORTEX Markdown.
+
+Produces human-readable Markdown with:
+  - Header with internal_encoding:HCORTEX
+  - **Perfil: CORTEX-FULL** as first content line
+  - Numbered section headers (# N. Title)
+  - Tables for sigil definitions, attrs, contracts
+  - PUML blocks for DIAG entries
+  - Prose for DESC/AXM entries
+  - Cross-references where applicable
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+from .ir import SkillIR, IREntry
+
+
+# Human-readable sigil names
+SIGIL_NAMES = {
+    "IDN": "Identity", "DOM": "Domain", "KNW": "Knowledge", "REF": "Reference",
+    "TAG": "Tag", "AXM": "Axiom", "CNST": "Constraint", "!": "Rule",
+    "CLAIM": "Claim", "LIM": "Limit", "AUD": "Audit", "RSK": "Risk",
+    "FCS": "Focus", "OBJ": "Objective", "WRK": "Work State", "STP": "Step",
+    "NXT": "Next", "SES": "Session", "LNG": "Lesson", "DIAG": "Diagram",
+    "HDL": "Handler", "PFL": "Pitfall", "DEP": "Dependency",
+    "DESC": "Description", "ERR": "Error",
+}
+
+# Section titles for HCORTEX
+SECTION_TITLES = {
+    "$0": "Glosario cognitivo universal",
+    "$1": "Identidad y dominio",
+    "$2": "Propósito y contexto",
+    "$3": "Operaciones y handlers",
+    "$4": "Reglas de sintaxis y render",
+    "$5": "Restricciones, riesgos y pitfalls",
+    "$6": "Diagramas",
+    "$7": "Contratos mínimos por sigilo",
+    "$8": "Supervivencia y prioridades",
+    "$9": "Perfiles de contexto",
+    "$10": "Política de degradación",
+    "$11": "HCORTEX",
+    "$12": "CORTEX-OUT",
+}
+
+# HCORTEX section number mapping
+CORTEX_TO_HCORTEX_NUM = {
+    "$0": "4", "$1": "0", "$2": "1", "$3": "8", "$4": "5",
+    "$5": "7", "$6": "2", "$7": "6", "$8": "11", "$9": "9.6.3",
+    "$10": "11.5", "$11": "9", "$12": "10",
+}
+
+
+def render_hcortex_v2(ir: SkillIR) -> str:
+    """Render a SkillIR as canonical HCORTEX v2 Markdown."""
+
+    lines: List[str] = []
+
+    # 1. Header
+    lines.append("<!-- CODEC-CORTEX")
+    lines.append("internal_encoding: HCORTEX")
+    if "source_artifact" in ir.header:
+        lines.append(f"source_artifact: {ir.header['source_artifact']}")
+    if "source_version" in ir.header:
+        lines.append(f"source_version: {ir.header['source_version']}")
+    if "status" in ir.header:
+        lines.append(f"status: {ir.header['status']}")
+    lines.append(f'derived_from: {ir.header.get("source_artifact", "skill/cortex/SKILL.md")}')
+    lines.append('-->')
+    lines.append("")
+
+    # 2. Profile
+    lines.append("**Perfil: CORTEX-FULL**")
+    lines.append("")
+    lines.append("---")
+    lines.append("")
+
+    # 3. Render sections
+    for sec_id in sorted(set(e.section for e in ir.entries if e.section), key=lambda x: int(x[1:])):
+        _render_section(lines, ir, sec_id)
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _render_section(lines: List[str], ir: SkillIR, sec_id: str) -> None:
+    """Render a single CORTEX section as HCORTEX."""
+    hcortex_num = CORTEX_TO_HCORTEX_NUM.get(sec_id, sec_id[1:])
+    title = SECTION_TITLES.get(sec_id, sec_id)
+    entries = ir.get_entries(section=sec_id)
+
+    if not entries:
+        return
+
+    lines.append(f"# {hcortex_num}. {title}")
+    lines.append("")
+
+    if sec_id == "$0":
+        _render_glossary(lines, ir, entries)
+    elif sec_id == "$1":
+        _render_identity(lines, ir, entries)
+    elif sec_id == "$2":
+        _render_purpose(lines, ir, entries)
+    elif sec_id == "$3":
+        _render_handlers(lines, ir, entries)
+    elif sec_id == "$4":
+        _render_rules(lines, ir, entries)
+    elif sec_id == "$5":
+        _render_constraints(lines, ir, entries)
+    elif sec_id == "$6":
+        _render_diagrams(lines, ir, entries)
+    elif sec_id == "$7":
+        _render_contracts(lines, ir, entries)
+    elif sec_id == "$8":
+        _render_survival(lines, ir, entries)
+    elif sec_id == "$9":
+        _render_profiles(lines, ir, entries)
+    elif sec_id == "$10":
+        _render_degradation(lines, ir, entries)
+    elif sec_id == "$11":
+        _render_hcortex_directives(lines, ir, entries)
+    elif sec_id == "$12":
+        _render_cortex_out(lines, ir, entries)
+    else:
+        _render_generic(lines, ir, entries)
+
+    lines.append("")
+
+
+def _render_glossary(lines: List[str], ir: SkillIR, entries: List[IREntry]) -> None:
+    """Render $0 glossary as sigil table + types + micro + contracts."""
+    # Sigil declarations
+    sigil_decls = [e for e in entries if e.entry_type == "sigil_decl"]
+    if sigil_decls:
+        lines.append("## Sigilos canónicos")
+        lines.append("")
+        lines.append("| Sigilo | Nombre | Tipo | Riesgo | Capa | Descripción |")
+        lines.append("|---|---|---|:---:|---|---|")
+        for e in sigil_decls:
+            v = e.value
+            lines.append(
+                f"| `{e.sigil}` | {e.name} | `{v.get('type', '')}` | "
+                f"{v.get('risk', '')} | {v.get('cortex', '')} | {v.get('desc', '')} |"
+            )
+        lines.append("")
+
+    # Type declarations
+    type_decls = [e for e in entries if e.sigil == "$0" and e.name.startswith("type_")]
+    if type_decls:
+        lines.append("## Tipos de expansión")
+        lines.append("")
+        lines.append("| Tipo | Regla |")
+        lines.append("|---|---|")
+        for e in type_decls:
+            type_name = e.name.replace("type_", "")
+            lines.append(f"| `{type_name}` | {e.value.get('rule', '')} |")
+        lines.append("")
+
+    # Contract declarations
+    contract_decls = [e for e in entries if e.sigil == "$0" and e.name.startswith("contract_")]
+    if contract_decls:
+        lines.append("## Contratos posicionales")
+        lines.append("")
+        lines.append("| Sigilo | Campos posicionales |")
+        lines.append("|---|---|")
+        for e in contract_decls:
+            sigil_name = e.name.replace("contract_", "").upper()
+            lines.append(f"| `{sigil_name}` | {e.value.get('pos', '')} |")
+        lines.append("")
+
+    # Micro-token declarations
+    micro_decls = [e for e in entries if e.sigil == "$0" and e.name.startswith("micro_")]
+    if micro_decls:
+        lines.append("## Micro-glosario")
+        lines.append("")
+        lines.append("| Token | Expansión |")
+        lines.append("|---|---|")
+        for e in micro_decls:
+            lines.append(f"| `{e.name.replace('micro_', '')}` | {e.value.get('expand', '')} |")
+        lines.append("")
+
+    # Enum declarations
+    enum_decls = [e for e in entries if e.sigil == "$0" and e.name.startswith("enum_")]
+    if enum_decls:
+        lines.append("## Enumeraciones")
+        lines.append("")
+        for e in enum_decls:
+            enum_name = e.name.replace("enum_", "")
+            lines.append(f"**{enum_name}:** {e.value.get('values', '')}")
+            lines.append("")
+
+
+def _render_identity(lines: List[str], ir: SkillIR, entries: List[IREntry]) -> None:
+    """Render $1 identity entries."""
+    for e in entries:
+        if e.sigil == "IDN" and isinstance(e.value, dict):
+            lines.append("## Identidad del proyecto")
+            lines.append("")
+            lines.append("| Campo | Valor |")
+            lines.append("|---|---|")
+            for k, v in e.value.items():
+                lines.append(f"| {k} | {v} |")
+            lines.append("")
+        elif e.sigil == "DOM" and isinstance(e.value, dict):
+            lines.append("## Dominio")
+            lines.append("")
+            lines.append("| Campo | Valor |")
+            lines.append("|---|---|")
+            for k, v in e.value.items():
+                lines.append(f"| {k} | {v} |")
+            lines.append("")
+        elif e.sigil == "REF" and isinstance(e.value, dict):
+            # Group REF entries into a table
+            pass  # Will be handled in a batch
+
+    # Render REF entries as a table
+    ref_entries = [e for e in entries if e.sigil == "REF"]
+    if ref_entries:
+        lines.append("## Artefactos referenciados")
+        lines.append("")
+        lines.append("| Artefacto | Ruta | Rol |")
+        lines.append("|---|---|---|")
+        for e in ref_entries:
+            v = e.value
+            lines.append(f"| `{e.name}` | `{v.get('path', '')}` | {v.get('role', '')} |")
+        lines.append("")
+
+
+def _render_purpose(lines: List[str], ir: SkillIR, entries: List[IREntry]) -> None:
+    """Render $2 purpose/context entries."""
+    for e in entries:
+        if e.entry_type == "cuerpo":
+            if e.sigil == "AXM":
+                # Axioms as blockquotes
+                lines.append(f"> {e.value}")
+                lines.append("")
+            else:
+                # DESC as prose
+                lines.append(e.value)
+                lines.append("")
+        elif e.sigil == "KNW" and isinstance(e.value, dict):
+            lines.append(f"### {e.value.get('topic', e.name)}")
+            lines.append("")
+            lines.append(e.value.get('content', ''))
+            lines.append("")
+
+
+def _render_handlers(lines: List[str], ir: SkillIR, entries: List[IREntry]) -> None:
+    """Render $3 HDL handler entries."""
+    for e in entries:
+        if e.entry_type == "attrs-pos":
+            v = e.value
+            lines.append(f"## {e.name.replace('_', ' ').title()}")
+            lines.append("")
+            lines.append(f"**Operación:** {v.get('operation', '')}  ")
+            lines.append(f"**Estado:** {v.get('status', '')}  ")
+            lines.append(f"**Requiere:** {v.get('requires', '')}")
+            lines.append("")
+            notes = v.get('notes', '')
+            if notes:
+                lines.append(notes)
+                lines.append("")
+
+
+def _render_rules(lines: List[str], ir: SkillIR, entries: List[IREntry]) -> None:
+    """Render $4 ! rule entries as a table."""
+    if entries:
+        lines.append("## Reglas operacionales")
+        lines.append("")
+        lines.append("| Regla | survive |")
+        lines.append("|---|---|")
+        for e in entries:
+            e.value.get('rule', '') if isinstance(e.value, dict) else ''
+            survive = e.value.get('survive', '') if isinstance(e.value, dict) else ''
+            lines.append(f"| `!{e.name}` | {survive} |")
+        lines.append("")
+
+
+def _render_constraints(lines: List[str], ir: SkillIR, entries: List[IREntry]) -> None:
+    """Render $5 constraints, limits, risks, pitfalls."""
+    cnst_entries = [e for e in entries if e.sigil == "CNST"]
+    if cnst_entries:
+        lines.append("## Restricciones")
+        lines.append("")
+        lines.append("| Restricción | Regla | Severidad | survive |")
+        lines.append("|---|---|---|---|")
+        for e in cnst_entries:
+            v = e.value
+            lines.append(f"| `{e.name}` | {v.get('rule', '')} | {v.get('severity', '')} | {v.get('survive', '')} |")
+        lines.append("")
+
+    lim_entries = [e for e in entries if e.sigil == "LIM"]
+    if lim_entries:
+        lines.append("## Límites")
+        lines.append("")
+        lines.append("| Límite | Alcance | Estado |")
+        lines.append("|---|---|---|")
+        for e in lim_entries:
+            v = e.value
+            lines.append(f"| `{e.name}` | {v.get('scope', '')} | {v.get('status', '')} |")
+        lines.append("")
+
+    rsk_entries = [e for e in entries if e.sigil == "RSK"]
+    if rsk_entries:
+        lines.append("## Riesgos")
+        lines.append("")
+        lines.append("| Riesgo | Impacto | Mitigación | Estado |")
+        lines.append("|---|---|---|---|")
+        for e in rsk_entries:
+            v = e.value
+            lines.append(f"| `{e.name}` | {v.get('impact', '')} | {v.get('mitigation', '')} | {v.get('status', '')} |")
+        lines.append("")
+
+    pfl_entries = [e for e in entries if e.sigil == "PFL"]
+    if pfl_entries:
+        lines.append("## Pitfalls")
+        lines.append("")
+        lines.append("| Patrón | Efecto | Prevención |")
+        lines.append("|---|---|---|")
+        for e in pfl_entries:
+            v = e.value
+            lines.append(f"| `{e.name}` | {v.get('effect', '')} | {v.get('prevention', '')} |")
+        lines.append("")
+
+
+def _render_diagrams(lines: List[str], ir: SkillIR, entries: List[IREntry]) -> None:
+    """Render $6 DIAG bloque entries as PUML blocks."""
+    for e in entries:
+        if e.entry_type == "bloque":
+            lines.append(f"## {e.name}")
+            lines.append("")
+            lines.append("```puml")
+            lines.append(e.value.strip())
+            lines.append("```")
+            lines.append("")
+
+
+def _render_contracts(lines: List[str], ir: SkillIR, entries: List[IREntry]) -> None:
+    """Render $7 field contracts as a table."""
+    if entries:
+        lines.append("## Contratos mínimos por sigilo crítico")
+        lines.append("")
+        lines.append("| Sigilo | Campos requeridos | Severidad |")
+        lines.append("|---|---|---|")
+        for e in entries:
+            v = e.value
+            sigil_name = e.name.replace("contract_", "").upper()
+            lines.append(f"| `{sigil_name}` | {v.get('rule', '')} | {v.get('severity', '')} |")
+        lines.append("")
+
+
+def _render_survival(lines: List[str], ir: SkillIR, entries: List[IREntry]) -> None:
+    """Render $8 survival/priorities."""
+    for e in entries:
+        if e.sigil == "KNW" and isinstance(e.value, dict):
+            lines.append(f"### {e.value.get('topic', e.name)}")
+            lines.append("")
+            lines.append(e.value.get('content', ''))
+            lines.append("")
+        elif e.sigil == "!":
+            v = e.value
+            lines.append(f"- **`!{e.name}`**: {v.get('rule', '')}")
+            lines.append("")
+
+
+def _render_profiles(lines: List[str], ir: SkillIR, entries: List[IREntry]) -> None:
+    """Render $9 context profiles."""
+    if entries:
+        lines.append("## Perfiles de contexto")
+        lines.append("")
+        lines.append("| Perfil | Contenido | Estado |")
+        lines.append("|---|---|---|")
+        for e in entries:
+            if isinstance(e.value, dict):
+                v = e.value
+                lines.append(f"| `{e.name}` | {v.get('content', '')} | {v.get('status', '')} |")
+        lines.append("")
+
+
+def _render_degradation(lines: List[str], ir: SkillIR, entries: List[IREntry]) -> None:
+    """Render $10 degradation rules."""
+    for e in entries:
+        v = e.value if isinstance(e.value, dict) else {}
+        lines.append(f"- **`!{e.name}`**: {v.get('rule', '')}")
+        lines.append("")
+
+
+def _render_hcortex_directives(lines: List[str], ir: SkillIR, entries: List[IREntry]) -> None:
+    """Render $11 HCORTEX directives."""
+    for e in entries:
+        if e.entry_type == "cuerpo":
+            lines.append(e.value)
+            lines.append("")
+        elif e.sigil == "KNW" and isinstance(e.value, dict):
+            lines.append(f"### {e.value.get('topic', e.name)}")
+            lines.append("")
+            lines.append(e.value.get('content', ''))
+            lines.append("")
+        elif e.sigil == "!":
+            v = e.value
+            lines.append(f"- **`!{e.name}`**: {v.get('rule', '')}")
+            lines.append("")
+        elif e.sigil == "PFL" and isinstance(e.value, dict):
+            v = e.value
+            lines.append(f"- **{e.name}**: {v.get('pattern', '')} → {v.get('prevention', '')}")
+            lines.append("")
+
+
+def _render_cortex_out(lines: List[str], ir: SkillIR, entries: List[IREntry]) -> None:
+    """Render $12 CORTEX-OUT entries."""
+    for e in entries:
+        if e.entry_type == "cuerpo":
+            lines.append(e.value)
+            lines.append("")
+        elif e.sigil == "AXM":
+            lines.append(f"> {e.value}")
+            lines.append("")
+        elif e.sigil == "!":
+            v = e.value
+            lines.append(f"- **`!{e.name}`**: {v.get('rule', '')}")
+            lines.append("")
+        elif e.sigil == "KNW" and isinstance(e.value, dict):
+            lines.append(f"### {e.value.get('topic', e.name)}")
+            lines.append("")
+            lines.append(e.value.get('content', ''))
+            lines.append("")
+
+
+def _render_generic(lines: List[str], ir: SkillIR, entries: List[IREntry]) -> None:
+    """Generic renderer for unmapped sections."""
+    for e in entries:
+        if e.entry_type == "cuerpo" or e.entry_type == "bloque":
+            lines.append(f"### {e.sigil}:{e.name}")
+            lines.append("")
+            if e.entry_type == "bloque":
+                lines.append("```")
+                lines.append(e.value.strip())
+                lines.append("```")
+            else:
+                lines.append(e.value)
+            lines.append("")
+        elif isinstance(e.value, dict):
+            lines.append(f"### {e.sigil}:{e.name}")
+            lines.append("")
+            lines.append("| Campo | Valor |")
+            lines.append("|---|---|")
+            for k, v in e.value.items():
+                lines.append(f"| {k} | {v} |")
+            lines.append("")

cortex/v2/ir.py

@@ -0,0 +1,223 @@
+r"""SkillIR — Intermediate Representation for bidirectional CORTEX ⇄ HCORTEX.
+
+The IR preserves:
+  - CORTEX entries (sigil, name, type, value, section, raw)
+  - HCORTEX blocks (heading path, kind, raw markdown, source mapping)
+  - Mappings between CORTEX entries and HCORTEX blocks
+  - Human blocks (HCORTEX content not derivable from CORTEX)
+  - Warnings (orphan content, ambiguities, unmapped entries)
+
+The IR is the single source of truth for conversion:
+  CORTEX → parse_cortex_v2 → SkillIR → render_hcortex_v2 → HCORTEX
+  HCORTEX → parse_hcortex_v2 → SkillIR → write_cortex_v2 → CORTEX
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Tuple
+
+from .parser import CortexV2Document, V2Entry, V2Section
+
+
+# ---------------------------------------------------------------------------
+# IR data model
+# ---------------------------------------------------------------------------
+
+@dataclass
+class IREntry:
+    """A CORTEX entry in the IR."""
+    sigil: str
+    name: str
+    entry_type: str  # attrs | attrs-pos | cuerpo | bloque | sigil_decl | meta
+    value: Any
+    section: str = ""
+    raw: str = ""
+    # Mapping to HCORTEX block(s) this entry was rendered into
+    hcortex_blocks: List[str] = field(default_factory=list)  # block IDs
+
+    def to_dict(self) -> dict:
+        return {
+            "sigil": self.sigil, "name": self.name, "type": self.entry_type,
+            "value": self.value, "section": self.section,
+        }
+
+
+@dataclass
+class IRBlock:
+    """An HCORTEX block in the IR."""
+    block_id: str  # unique ID
+    heading_path: str  # e.g. "4.2" or "9.6.1"
+    heading_text: str  # e.g. "Sigilos canónicos"
+    kind: str  # table | prose | puml | list | checklist | code | blockquote
+    raw_markdown: str  # the actual markdown content
+    # Mapping to CORTEX entry(ies) this block was derived from
+    source_entries: List[Tuple[str, str]] = field(default_factory=list)  # [(sigil, name), ...]
+    # Whether this block is derivable from CORTEX or is human-added
+    derivable: bool = True
+
+    def to_dict(self) -> dict:
+        return {
+            "block_id": self.block_id,
+            "heading_path": self.heading_path,
+            "heading_text": self.heading_text,
+            "kind": self.kind,
+            "source_entries": self.source_entries,
+            "derivable": self.derivable,
+        }
+
+
+@dataclass
+class IRWarning:
+    """A warning about content that couldn't be mapped."""
+    code: str
+    message: str
+    severity: str = "warning"  # warning | info
+
+
+@dataclass
+class SkillIR:
+    """Intermediate Representation for bidirectional CORTEX ⇄ HCORTEX.
+
+    This is the single source of truth for conversion.  Both CORTEX
+    and HCORTEX parse into this IR, and both render from it.
+    """
+    header: Dict[str, str] = field(default_factory=dict)
+    entries: List[IREntry] = field(default_factory=list)
+    blocks: List[IRBlock] = field(default_factory=list)
+    warnings: List[IRWarning] = field(default_factory=list)
+    # Section structure: list of (section_id, title) for HCORTEX rendering
+    section_map: List[Tuple[str, str]] = field(default_factory=list)
+
+    def add_entry(self, entry: V2Entry) -> IREntry:
+        ir_entry = IREntry(
+            sigil=entry.sigil, name=entry.name, entry_type=entry.entry_type,
+            value=entry.value, section=entry.section, raw=entry.raw,
+        )
+        self.entries.append(ir_entry)
+        return ir_entry
+
+    def add_block(self, block: IRBlock) -> None:
+        self.blocks.append(block)
+
+    def add_warning(self, code: str, message: str, severity: str = "warning") -> None:
+        self.warnings.append(IRWarning(code=code, message=message, severity=severity))
+
+    def get_entries(self, sigil: str = None, section: str = None) -> List[IREntry]:
+        result = []
+        for e in self.entries:
+            if sigil and e.sigil != sigil:
+                continue
+            if section and e.section != section:
+                continue
+            result.append(e)
+        return result
+
+    def to_dict(self) -> dict:
+        return {
+            "header": dict(self.header),
+            "entries": [e.to_dict() for e in self.entries],
+            "blocks": [b.to_dict() for b in self.blocks],
+            "warnings": [{"code": w.code, "message": w.message, "severity": w.severity} for w in self.warnings],
+            "section_map": self.section_map,
+        }
+
+
+# ---------------------------------------------------------------------------
+# CORTEX → IR
+# ---------------------------------------------------------------------------
+
+def cortex_to_ir(doc: CortexV2Document) -> SkillIR:
+    """Convert a parsed CORTEX v2 document into a SkillIR."""
+    ir = SkillIR()
+    ir.header = dict(doc.header)
+
+    for sec in doc.sections:
+        for entry in sec.entries:
+            ir.add_entry(entry)
+
+    # Build section map for HCORTEX rendering
+    _build_section_map(ir, doc)
+
+    return ir
+
+
+def _build_section_map(ir: SkillIR, doc: CortexV2Document) -> None:
+    """Build the mapping from CORTEX sections to HCORTEX section numbers.
+
+    This mapping is based on the analysis of the canonical SKILL.md ↔ SKILL_HCORTEX.md pair.
+    """
+    # Mapping: CORTEX $N → HCORTEX section number(s)
+    SECTION_MAP = {
+        "$0": [("4", "Glosario cognitivo universal"),
+               ("4.1", "Regla de autoridad y autocontención"),
+               ("4.2", "Sigilos canónicos"),
+               ("4.3", "Tipos de expansión"),
+               ("4.4", "Micro-glosario")],
+        "$1": [("0", "Control del documento"),
+               ("0.1", "Relación con otros artefactos")],
+        "$2": [("1", "Resumen ejecutivo"),
+               ("1.1", "Canon mínimo"),
+               ("1.2", "META-SKILL"),
+               ("1.3", "Problema que resuelve"),
+               ("1.4", "Principio rector"),
+               ("3", "Ontología cognitiva")],
+        "$3": [("8", "Operación de agentes")],
+        "$4": [("5", "Sintaxis .cortex"),
+               ("9.6", "Directrices canónicas de construcción documental HCORTEX")],
+        "$5": [("7", "Reglas de separación de niveles"),
+               ("20", "Pitfalls empresariales")],
+        "$6": [("2.1", "Diagrama canónico"),
+               ("3.1", "Diagrama de capas"),
+               ("8.1", "Secuencia mínima al iniciar"),
+               ("8.3", "Al absorber un paquete Nivel 3"),
+               ("9.4", "Diagrama HCORTEX")],
+        "$7": [("6", "Contratos mínimos por sigilo crítico")],
+        "$8": [("11", "Supervivencia contextual y triaje P0-P5")],
+        "$9": [("9.6.3", "Perfiles de contexto"),
+               ("11.4", "Perfiles")],
+        "$10": [("11.1", "Principio"),
+                ("11.5", "Diagrama de degradación")],
+        "$11": [("9", "HCORTEX"),
+                ("9.6", "Directrices canónicas de construcción documental HCORTEX")],
+        "$12": [("10", "CORTEX-OUT")],
+    }
+
+    for sec in doc.sections:
+        if sec.id in SECTION_MAP:
+            for hcortex_num, hcortex_title in SECTION_MAP[sec.id]:
+                ir.section_map.append((sec.id, hcortex_num, hcortex_title))
+        else:
+            ir.add_warning("UNMAPPED_SECTION", f"section {sec.id} has no HCORTEX mapping")
+
+
+# ---------------------------------------------------------------------------
+# IR → CORTEX
+# ---------------------------------------------------------------------------
+
+def ir_to_cortex(ir: SkillIR) -> CortexV2Document:
+    """Convert a SkillIR back to a CortexV2Document for writing."""
+    doc = CortexV2Document()
+    doc.header = dict(ir.header)
+
+    # Group entries by section
+    sections_map: Dict[str, V2Section] = {}
+    for ir_entry in ir.entries:
+        sec_id = ir_entry.section or "$0"
+        if sec_id not in sections_map:
+            sections_map[sec_id] = V2Section(id=sec_id)
+        v2_entry = V2Entry(
+            sigil=ir_entry.sigil,
+            name=ir_entry.name,
+            entry_type=ir_entry.entry_type,
+            value=ir_entry.value,
+            raw=ir_entry.raw,
+            section=sec_id,
+        )
+        sections_map[sec_id].entries.append(v2_entry)
+
+    # Sort sections by number
+    for sec_id in sorted(sections_map.keys(), key=lambda x: int(x[1:])):
+        doc.sections.append(sections_map[sec_id])
+
+    return doc