bookwright-cli 0.2.0__py3-none-any.whl

bookwright/indexers/rdflib_indexer.py

@@ -0,0 +1,89 @@
+"""``RdflibIndexer`` — the v0 default engine (wraps :class:`rdflib.Graph`).
+
+Owns Turtle serialization and prefix binding so FR-015 (short prefixes) holds
+regardless of which engine the manifest selects (R5). The build command feeds
+``entity.to_triples()`` through :meth:`add_triple`; ``graph query`` runs SPARQL
+through :meth:`query`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+from rdflib import Graph
+from rdflib.query import ResultRow
+from rdflib.term import Literal, URIRef
+
+from bookwright.golem.namespaces import bind_prefixes
+
+from .errors import GraphLoadError, InvalidQueryError
+
+
+class RdflibIndexer:
+    """An :class:`~bookwright.indexers.base.Indexer` backed by ``rdflib``."""
+
+    def __init__(self, graph: Graph | None = None) -> None:
+        self._graph = graph if graph is not None else Graph()
+        bind_prefixes(self._graph)
+
+    # --- ingestion ----------------------------------------------------------
+
+    def add_triple(
+        self,
+        s: URIRef | str,
+        p: URIRef | str,
+        o: URIRef | Literal | str | int | float,
+    ) -> None:
+        """Add one triple. IRI-like ``str`` subjects/predicates coerce to ``URIRef``;
+        objects that are already rdflib terms pass through, scalars become literals."""
+        subject = s if isinstance(s, URIRef) else URIRef(s)
+        predicate = p if isinstance(p, URIRef) else URIRef(p)
+        if isinstance(o, (URIRef, Literal)):
+            obj: URIRef | Literal = o
+        else:
+            obj = Literal(o)
+        self._graph.add((subject, predicate, obj))
+
+    # --- persistence --------------------------------------------------------
+
+    def load(self, ttl_path: Path) -> None:
+        """Parse the Turtle at ``ttl_path`` into the engine's graph.
+
+        A malformed file raises :class:`GraphLoadError` (a clean envelope) rather
+        than letting an rdflib parse error escape as a raw traceback.
+        """
+        try:
+            self._graph.parse(str(ttl_path), format="turtle")
+        except Exception as exc:  # rdflib raises a variety of parse errors
+            raise GraphLoadError(str(ttl_path), str(exc)) from exc
+
+    def save(self, ttl_path: Path) -> None:
+        """Serialize the graph to Turtle (short prefixes), creating parent dirs."""
+        ttl_path.parent.mkdir(parents=True, exist_ok=True)
+        self._graph.serialize(destination=str(ttl_path), format="turtle")
+
+    # --- querying -----------------------------------------------------------
+
+    def query(self, sparql: str) -> Iterable[dict[str, Any]]:
+        """Run a SELECT/ASK; return one dict per row (projected var → ``str``).
+
+        The result is fully materialized inside the ``try`` so a malformed query
+        raises :class:`InvalidQueryError` with **no partial rows** yielded first
+        (FR-016).
+        """
+        try:
+            result = self._graph.query(sparql)
+            rows: list[dict[str, Any]] = [
+                {str(var): str(value) for var, value in row.asdict().items()}
+                for row in result
+                if isinstance(row, ResultRow)
+            ]
+        except Exception as exc:  # rdflib raises a variety of parse errors
+            raise InvalidQueryError(str(exc)) from exc
+        return rows
+
+    def count(self) -> int:
+        """Return the number of triples currently held."""
+        return len(self._graph)

bookwright/integrations/__init__.py

@@ -0,0 +1,155 @@
+"""Public API for the ``bookwright.integrations`` layer (iteration 3).
+
+Importing this package eagerly populates ``INTEGRATION_REGISTRY`` via
+``_register_builtins()`` (FR-002). Downstream consumers (iteration 4's
+``bookwright init``, iteration 9's skills materializer) need only::
+
+    from bookwright.integrations import get, list_keys, parse_options
+
+The public surface (re-exported in ``__all__``) is contractual; renaming
+any symbol below is a breaking change for iterations 4+.
+"""
+
+from __future__ import annotations
+
+from bookwright.integrations.base import SkillsIntegration
+from bookwright.integrations.claude import ClaudeIntegration
+from bookwright.integrations.constants import (
+    SKILL_DESCRIPTION_MAX_LENGTH,
+    SKILL_NAME_MAX_LENGTH,
+    SKILL_PLACEHOLDER_MARKER_NAME,
+)
+from bookwright.integrations.errors import (
+    DuplicateRegistrationError,
+    InvalidIntegrationError,
+    InvalidOptionDeclarationError,
+    MalformedOptionError,
+    SkillLintError,
+    SkillMaterializationError,
+    UnknownIntegrationError,
+    UnknownOptionError,
+)
+from bookwright.integrations.generic import GenericIntegration
+from bookwright.integrations.options import IntegrationOption, parse_options
+
+INTEGRATION_REGISTRY: dict[str, type[SkillsIntegration]] = {}
+
+
+def _fqcn(cls: type) -> str:
+    """Fully-qualified class name, used in DuplicateRegistrationError payloads."""
+
+    return f"{cls.__module__}.{cls.__qualname__}"
+
+
+def _register(cls: type[SkillsIntegration]) -> None:
+    """Register one integration class under its declared ``cls.key``.
+
+    Re-registering the same class is a no-op (FR-002 idempotency under
+    ``importlib.reload``). Registering a *different* class under an
+    existing key raises ``DuplicateRegistrationError`` naming both
+    classes (FR-005, research R5). Registering a class whose ``key``
+    is empty (the base-class sentinel) raises ``InvalidIntegrationError``
+    (R13) — subclasses MUST override ``key`` with a non-empty string.
+    Registering a class whose ``default_skills_dir`` is empty raises
+    ``InvalidIntegrationError`` (R25) for the same reason: an empty
+    default would surface as a misleading ``resolves_to_project_root``
+    error in ``setup()`` because ``Path("")`` collapses to ``Path(".")``.
+    """
+
+    new_fqcn = _fqcn(cls)
+    if not cls.key:
+        raise InvalidIntegrationError(rule="empty_key", value=new_fqcn)
+    if not cls.default_skills_dir:
+        # R25 — symmetric guard to R13. Without this, a forgetful subclass
+        # that overrides `key` but leaves `default_skills_dir` at the
+        # base sentinel ("") would register successfully and then fail
+        # at setup() time with `resolves_to_project_root` (because
+        # `Path("") == Path(".")` collapses to project_root), pointing
+        # the author at the wrong layer.
+        raise InvalidIntegrationError(rule="empty_default_skills_dir", value=new_fqcn)
+
+    existing = INTEGRATION_REGISTRY.get(cls.key)
+    if existing is None:
+        INTEGRATION_REGISTRY[cls.key] = cls
+        return
+
+    # R12 — compare by fully-qualified class name, not by identity. After
+    # `importlib.reload(bookwright.integrations.claude)` the reloaded
+    # `ClaudeIntegration` is a NEW class object with different identity
+    # from the one already in the registry; relying on `is` would raise
+    # DuplicateRegistrationError spuriously, breaking the FR-002 reload
+    # idempotency promise. FQCN equality preserves the duplicate guard
+    # for genuinely different classes (different module/qualname) that
+    # collide on `key`.
+    # R27 — compute existing FQCN once and reuse for both the equality
+    # check and the error payload, instead of recomputing on each call
+    # site.
+    existing_fqcn = _fqcn(existing)
+    if existing is cls or existing_fqcn == new_fqcn:
+        INTEGRATION_REGISTRY[cls.key] = cls  # rebind to the reloaded class
+        return
+    raise DuplicateRegistrationError(
+        value=cls.key,
+        existing=existing_fqcn,
+        new=new_fqcn,
+    )
+
+
+def _register_builtins() -> None:
+    """Populate ``INTEGRATION_REGISTRY`` with the two v0 built-ins.
+
+    Future contributors add a single ``_register(NewIntegration)`` line
+    here (per quickstart "Adding a new integration"). No edit to
+    ``base.py``, ``claude/``, or ``generic/`` is permitted — this is
+    enforced mechanically by ``tests/integrations/test_plugin_contract.py``
+    (FR-031).
+    """
+
+    _register(ClaudeIntegration)
+    _register(GenericIntegration)
+
+
+def get(key: str) -> type[SkillsIntegration]:
+    """Look up an integration class by its short key (FR-003)."""
+
+    cls = INTEGRATION_REGISTRY.get(key)
+    if cls is None:
+        raise UnknownIntegrationError(value=key, valid=list_keys())
+    return cls
+
+
+def list_keys() -> list[str]:
+    """Return registered integration keys, alphabetically sorted (FR-004)."""
+
+    return sorted(INTEGRATION_REGISTRY.keys())
+
+
+_register_builtins()
+
+
+__all__ = [
+    # NOTE: `INTEGRATION_REGISTRY` is intentionally NOT exposed in __all__
+    # (R17). The dict remains importable from the module namespace for
+    # the in-tree test snapshot fixture and the registry-mutation guard
+    # tests, but external consumers MUST go through `get`, `list_keys`,
+    # and `_register` — direct dict assignment bypasses FR-005's
+    # duplicate-detection guard and the R13 empty-key guard.
+    "SKILL_DESCRIPTION_MAX_LENGTH",
+    "SKILL_NAME_MAX_LENGTH",
+    "SKILL_PLACEHOLDER_MARKER_NAME",
+    "ClaudeIntegration",
+    "DuplicateRegistrationError",
+    "GenericIntegration",
+    "IntegrationOption",
+    "InvalidIntegrationError",
+    "InvalidOptionDeclarationError",
+    "MalformedOptionError",
+    "SkillLintError",
+    "SkillMaterializationError",
+    "SkillsIntegration",
+    "UnknownIntegrationError",
+    "UnknownOptionError",
+    "get",
+    "list_keys",
+    "parse_options",
+]

bookwright/integrations/base.py

@@ -0,0 +1,117 @@
+"""``SkillsIntegration`` — the single operative v0 base class for integrations.
+
+Subclasses live under ``bookwright.integrations.<key>/`` and override:
+    - ``key``, ``config``, ``default_skills_dir`` (always),
+    - ``supports_*`` flags (when the agent supports the capability),
+    - ``options()`` (when the integration declares ``--integration-options``
+      flags), and
+    - ``resolve_skills_dir()`` (when the resolved dir depends on
+      ``parsed_options``).
+
+``setup()`` is implemented once here; no v0 subclass overrides it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from types import MappingProxyType
+from typing import TYPE_CHECKING, ClassVar
+
+from bookwright.integrations.errors import MalformedOptionError
+from bookwright.integrations.materialize import generate_skill_md, iter_command_sources
+from bookwright.integrations.options import IntegrationOption
+from bookwright.io.fs import NullLedger, mkdir_tracked
+
+if TYPE_CHECKING:
+    from bookwright.core.manifest import Manifest
+    from bookwright.io.fs import FileLedger
+
+
+class SkillsIntegration:
+    """Base contract every Bookwright v0 integration implements."""
+
+    # Sentinel defaults — every concrete subclass MUST override `key`,
+    # `config`, and `default_skills_dir`. The empty-string sentinel on
+    # `key` is caught by `_register` (R13). `config`'s default is a
+    # frozen `MappingProxyType` (R19) so a forgetful subclass that
+    # accidentally writes `cls.config['x'] = 'y'` raises TypeError
+    # instead of silently mutating the shared base dict and polluting
+    # every other forgetful subclass.
+    key: ClassVar[str] = ""
+    config: ClassVar[Mapping[str, str | bool]] = MappingProxyType({})
+    default_skills_dir: ClassVar[str] = ""
+
+    supports_dynamic_context: ClassVar[bool] = False
+    supports_subagents: ClassVar[bool] = False
+    supports_tool_restrictions: ClassVar[bool] = False
+
+    @classmethod
+    def options(cls) -> list[IntegrationOption]:
+        """Return the integration's declared ``--integration-options`` flags.
+
+        Default: empty list (FR-013). Override to declare flags.
+        """
+
+        return []
+
+    def resolve_skills_dir(
+        self,
+        parsed_options: Mapping[str, object] | None = None,
+    ) -> Path:
+        """Return the project-relative skills directory for this integration.
+
+        Default implementation returns ``Path(self.default_skills_dir)`` and
+        ignores ``parsed_options`` (FR-023). Subclasses that declare options
+        affecting the resolved directory (e.g., ``GenericIntegration``'s
+        ``--skills-dir``) MUST override.
+
+        ``Mapping`` (not ``dict``) is used in the signature so callers may
+        pass the narrower ``dict[str, str | bool]`` returned by
+        ``parse_options`` without an explicit cast (``dict`` is invariant).
+        """
+
+        del parsed_options
+        return Path(self.default_skills_dir)
+
+    def setup(
+        self,
+        project_root: Path,
+        manifest: Manifest,
+        parsed_options: Mapping[str, object] | None = None,
+        *,
+        ledger: FileLedger | None = None,
+    ) -> None:
+        """Materialize one ``SKILL.md`` per source command under the resolved dir.
+
+        Shared by every v0 integration (no subclass overrides it — the only
+        per-integration variation is already behind ``resolve_skills_dir`` and
+        the capability flags). For each packaged source command, delegate to
+        ``generate_skill_md``; idempotent per-``SKILL.md`` (FR-014); never writes
+        outside the resolved dir (FR-017).
+
+        ``ledger`` is the rollback-recording ``FileLedger`` (``init`` passes its
+        live ``BackupLedger``); when omitted it defaults to a ``NullLedger`` so
+        ``setup()`` is standalone-callable. Every materialized path is recorded
+        through it (FR-019). A ``SkillLintError``/``SkillMaterializationError``
+        from any command propagates, aborting this integration (FR-016).
+        """
+
+        # `manifest` is part of the iteration-9 contract; unused in v0 body.
+        del manifest
+
+        ledger = ledger or NullLedger()
+        resolved = self.resolve_skills_dir(parsed_options)
+        target = (project_root / resolved).resolve()
+        root = project_root.resolve()
+        if target == root:
+            # `--skills-dir=`, `--skills-dir .`, `--skills-dir ./`, etc. all
+            # collapse the target into project_root itself. Rejected as a
+            # separate rule from `escapes_project_root` so the JSON envelope
+            # can distinguish "lands AT root" from "lands OUTSIDE root" (R6).
+            raise MalformedOptionError(rule="resolves_to_project_root", value=str(resolved))
+        if not target.is_relative_to(root):
+            raise MalformedOptionError(rule="escapes_project_root", value=str(resolved))
+        mkdir_tracked(target, ledger)
+        for command_path in iter_command_sources():
+            generate_skill_md(command_path, target, self, ledger=ledger)

bookwright/integrations/claude/__init__.py

@@ -0,0 +1,29 @@
+"""``ClaudeIntegration`` — Claude Code integration (FR-007, FR-010, FR-013)."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from bookwright.integrations.base import SkillsIntegration
+
+
+class ClaudeIntegration(SkillsIntegration):
+    """Integration for the Claude Code agent (.claude/skills layout).
+
+    Inherits the base ``setup()`` body and the base ``resolve_skills_dir``
+    (which already returns ``Path(default_skills_dir)``); no overrides are
+    necessary in v0.
+    """
+
+    key: ClassVar[str] = "claude"
+    default_skills_dir: ClassVar[str] = ".claude/skills"
+    config: ClassVar[dict[str, str | bool]] = {
+        "name": "Claude Code",
+        "install_url": "https://docs.claude.com/claude-code",
+        "requires_cli": True,
+        "context_file": "CLAUDE.md",
+    }
+
+    supports_dynamic_context: ClassVar[bool] = True
+    supports_subagents: ClassVar[bool] = True
+    supports_tool_restrictions: ClassVar[bool] = True

bookwright/integrations/constants.py

@@ -0,0 +1,38 @@
+"""Agent Skills (agentskills.io) compliance constants for the integrations layer.
+
+Single source of truth for the numeric caps, the inherited default license,
+and the dynamic-context injection allowlist consumed by iteration 9's
+``SKILL.md`` materializer and linter (FR-003, FR-005, FR-013, FR-015).
+
+Structural invariant from FR-003 — *the directory name MUST equal the
+``name`` field inside its ``SKILL.md``* — is not numeric and therefore is not
+encoded as a constant; it is enforced by iteration 9's materializer/linter and
+documented here so future readers do not duplicate the rule.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+SKILL_NAME_MAX_LENGTH: Final[int] = 64
+SKILL_DESCRIPTION_MAX_LENGTH: Final[int] = 1024
+
+#: Tier-2 ``SKILL.md`` body budget (R6/FR-015). Bodies are copied unchanged from
+#: already-budget-passing iteration-8 sources, so this is a regression guard.
+SKILL_BODY_MAX_TOKENS: Final[int] = 5000
+
+#: License inherited by a materialized skill when its source declares no
+#: ``license`` (FR-005/A-002). The single source of truth for the design default.
+DEFAULT_SKILL_LICENSE: Final[str] = "Apache-2.0"
+
+#: Deny-by-default allowlist of project-file *read* commands permitted inside a
+#: `` !`…` `` dynamic-context injection (the FR-013 invariant). File-read only —
+#: ``ls``/``find`` (which *list*, not *read a file*) are deliberately excluded to
+#: stay faithful to FR-013 ("reads a project file").
+INJECTION_READ_COMMANDS: Final[frozenset[str]] = frozenset({"cat", "head", "tail"})
+
+#: DEPRECATED (iteration 9): the iteration-3 placeholder-marker filename. The
+#: marker is **no longer written** — ``setup()`` now materializes real
+#: ``SKILL.md`` files. Retained only so the deprecated symbol stays importable
+#: for the legacy-cleanup tests; do not write this file in new code.
+SKILL_PLACEHOLDER_MARKER_NAME: Final[str] = ".bookwright-skills-placeholder"

bookwright/integrations/descriptions.py

@@ -0,0 +1,48 @@
+"""Authoritative `SKILL.md` `description` table (R1/R3, FR-004).
+
+A pure, dependency-free data module: `SKILL_DESCRIPTIONS` maps each command name
+to its bilingual ES/EN trigger-bearing description, and `get_description` is the
+single authoritative lookup (with source-frontmatter fallback) where the
+1024-char cap is asserted in **one** place.
+
+In v0 the table mirrors the iteration-8 source frontmatter `description` verbatim
+under a CI equality gate (SC-009): the dict is the authoritative read seam (where
+the cap lives and where future per-skill tuning would land), while the gate makes
+any divergence from the source an explicit, reviewed change — never silent drift.
+"""
+
+from __future__ import annotations
+
+from bookwright.integrations.constants import SKILL_DESCRIPTION_MAX_LENGTH
+
+SKILL_DESCRIPTIONS: dict[str, str] = {
+    "bookwright-constitution": 'Define la constitución narrativa del libro: voz, tono, pacto con el lector, líneas rojas e invariantes de coherencia — el paso de configuración que va ANTES de la biblia. Build the book\'s narrative constitution: voice, tone, reader pact, red lines and coherence invariants — the setup step BEFORE the bible. Úsalo cuando el autor quiera fijar el tono, la voz o las reglas de su obra ("define el tono", "set the tone/voice", "establece las bases"). NO genera fichas de personajes ni localizaciones: eso es bookwright-bible, que va después.',
+    "bookwright-bible": 'Genera la biblia del proyecto en una sola pasada: fichas de personajes, escenarios y localizaciones, cronología, relaciones, temas, glosario y subtramas — DESPUÉS de tener la constitución. Build the project bible in a single pass: character, setting and location sheets, timeline, relationships, themes, glossary and subplots — AFTER the constitution exists. Úsalo cuando el autor pida "fichas de mis personajes y localizaciones" / "character and location sheets", "puebla la biblia" / "build the bible". NO sirve para definir el tono o la voz: eso es bookwright-constitution, que va antes.',
+    "bookwright-outline": 'Construye el esqueleto narrativo de la obra: arcos de personaje, estructura por actos y capítulos, y una sinopsis inicial, a partir de la constitución y la biblia. Build the book\'s narrative skeleton: character arcs, act/chapter structure and an initial synopsis, from the constitution and bible. Úsalo cuando el autor quiera "estructurar la trama", "diseñar los arcos" / "outline the plot", "design the arcs and structure". Trabaja al nivel de capítulos y arcos, no de escenas concretas (eso es bookwright-scenes).',
+    "bookwright-scenes": 'Desglosa la estructura en una lista de escenas concretas, cada una con su función narrativa, personajes presentes, lugar y beats. Break the structure into a concrete scene list, each carrying its narrative function, characters present, location and beats. Úsalo cuando el autor quiera "desglosar los capítulos en escenas", "preparar la lista de escenas" / "break chapters into scenes", "plan the scene list" antes de redactar. Planifica escenas; NO redacta su prosa (eso es bookwright-draft).',
+    "bookwright-draft": 'Redacta la prosa de una escena concreta (indicada por su scene_id) en el capítulo correcto del manuscrito, respetando la voz, la focalización y las restricciones de la constitución y la biblia. Draft the prose of a specific scene (given by its scene_id) into the correct manuscript chapter, honoring the voice, focalization and constraints from the constitution and bible. Úsalo cuando el autor diga "escribe/redacta la escena X" / "draft/write scene X". Es el único comando que produce prosa de manuscrito.',
+    "bookwright-synopsis": 'Actualiza la sinopsis del proyecto: una versión corta (250–350 palabras) y una larga (1000–2000 palabras) que reflejan el estado actual de la trama. Update the project synopsis: a short version (250–350 words) and a long one (1000–2000 words) reflecting the current state of the plot. Úsalo cuando el autor pida "actualiza/genera la sinopsis", "resume la novela" / "update/write the synopsis", "summarize the plot". Regenera ambos resúmenes en cualquier momento del proyecto.',
+    "bookwright-clarify": 'Revisa los artefactos del proyecto y devuelve una lista de preguntas abiertas que el autor debería resolver antes de seguir. Review the project artifacts and return a list of open questions the author should resolve before continuing. Úsalo cuando el autor pregunte "¿qué me falta por aclarar antes de seguir?", "¿qué dudas quedan?" / "what\'s still unclear?", "what do I need to decide next?". Es de solo lectura. Pregunta por DUDAS abiertas, NO comprueba la completitud de un artefacto concreto (eso es bookwright-checklist).',
+    "bookwright-analyze": 'Revisa la consistencia cruzada PRE-redacción entre constitución, biblia, outline y escenas, y reporta contradicciones antes de empezar a escribir. Check PRE-draft cross-artifact consistency among constitution, bible, outline and scenes, reporting contradictions before any prose is written. Úsalo cuando el autor pregunte "¿es coherente mi planificación antes de redactar?" / "is my planning consistent before I start drafting?". Es de solo lectura y trabaja en fase PRE-draft. NO compara el manuscrito con la biblia (eso es post-draft: bookwright-continuity).',
+    "bookwright-continuity": 'Revisa la consistencia POST-redacción del manuscrito frente a la biblia: cumplimiento de la biblia, coherencia de los arcos de personaje y de la línea de tiempo. Check POST-draft continuity of the manuscript against the bible: bible compliance, character-arc consistency and timeline coherence. Úsalo cuando el autor pida "revisa si mi manuscrito es coherente con la biblia" / "check my manuscript against the bible". Es de solo lectura y trabaja en fase POST-draft. NO revisa la planificación antes de redactar (eso es pre-draft: bookwright-analyze).',
+    "bookwright-checklist": 'Comprueba si UN artefacto concreto está completo: todas sus secciones presentes, sin marcadores [PENDING: …] sin resolver y sin placeholders vacíos. Check whether ONE named artifact is complete: all sections present, no unresolved [PENDING: …] markers, no empty placeholders. Úsalo cuando el autor pregunte "¿está completa mi constitución / esta ficha?" / "is this artifact complete?". Es de solo lectura. Mide COMPLETITUD de un artefacto, NO recoge las dudas abiertas del proyecto (eso es bookwright-clarify).',
+    "bookwright-research": 'Investiga un tema del mundo real y lo documenta como hallazgos con procedencia completa (fuentes, citas en lengua original, fiabilidad) en bible/research/, marcando qué hallazgos son anclas que restringen la ficción. Research a real-world topic and document it as findings with full provenance (sources, original-language quotes, reliability) under bible/research/, marking which findings are binding anchors on the fiction. Úsalo cuando el autor pida "investiga <tema>", "documenta <tema> con fuentes", "preséntame fuentes sobre <tema>" / "research <topic>", "find sources on <topic>". NO verifica prosa ya escrita contra sus fuentes (eso es bookwright-verify, posterior) ni puebla fichas de personajes o localizaciones (eso es bookwright-bible).',
+    "bookwright-verify": 'Verifica el manuscrito ya redactado contra las anclas de investigación: detecta pasajes que contradicen lo investigado — anacronismos, errores de procedimiento (algo ilegal o imposible en la ambientación) e inexactitudes culturales o lingüísticas. Verify the drafted manuscript against the research anchors: flag passages that contradict the research — anachronisms, procedural errors (something illegal or impossible in the setting) and cultural or linguistic inaccuracies. Úsalo cuando el autor pida "verifica si mi manuscrito contradice lo investigado" / "check my manuscript against my research". Es de solo lectura y trabaja en fase POST-draft. NO compara el manuscrito con la biblia (eso es bookwright-continuity) ni audita la integridad estructural de las anclas (eso es el validator factual_anchor).',
+}
+
+
+def get_description(name: str, fallback: str) -> str:
+    """Authoritative lookup with source-frontmatter fallback (R3, FR-004).
+
+    Returns `SKILL_DESCRIPTIONS[name]` when present, else `fallback` (the source
+    frontmatter description). The 1024-char cap is *enforced* at runtime by
+    ``lint_skill_md`` Rule 3 (which survives ``python -O``); the ``assert`` below
+    is only a developer-time tripwire on the static table — over-cap is a coding
+    error caught by tests (the SC-009 equality gate), never a user-data case.
+    """
+
+    result = SKILL_DESCRIPTIONS.get(name, fallback)
+    assert len(result) < SKILL_DESCRIPTION_MAX_LENGTH, (
+        f"description for {name!r} is {len(result)} chars, >= cap {SKILL_DESCRIPTION_MAX_LENGTH}"
+    )
+    return result

bookwright/integrations/errors.py

@@ -0,0 +1,170 @@
+"""Structured exception family for the integrations layer (FR-035, FR-036).
+
+Every public error inherits from the private `_IntegrationError` base — which now
+inherits the shared `BookwrightError` — and exposes:
+    - a class-level ``code: str`` (immutable identifier),
+    - a ``message: str`` attribute (human-readable, also passed to
+      ``Exception.__init__``),
+    - the structured fields under the canonical envelope's ``details`` (the
+      single ``to_json()`` is owned by `BookwrightError`; see
+      ``specs/018-unified-error-envelope/contracts/error-envelope.md``).
+
+The ``init --json`` / ``integration use --json`` consumers read the canonical
+``to_json()`` body; renaming any ``details`` field below is a breaking change.
+"""
+
+from __future__ import annotations
+
+from bookwright.errors import BookwrightError
+
+
+class _IntegrationError(BookwrightError):
+    """Private base for all structured errors raised by the integrations layer.
+
+    Subclasses MUST set a non-empty class-level ``code`` and assign their
+    structured fields on ``self`` in ``__init__`` (e.g., ``self.rule``,
+    ``self.value``), then end ``__init__`` with
+    ``super().__init__(message, {<public attrs>})`` so the inherited
+    ``BookwrightError.to_json()`` emits the canonical envelope. The base is
+    abstract: it declares no ``code`` and is never serialized directly.
+    """
+
+
+class UnknownIntegrationError(_IntegrationError):
+    """Raised by ``get(key)`` when ``key`` is not in ``INTEGRATION_REGISTRY``."""
+
+    code = "unknown_integration"
+
+    def __init__(self, *, value: str | None, valid: list[str]) -> None:
+        self.value = value
+        self.valid = list(valid)
+        message = f"unknown integration: {value!r}; valid: [{', '.join(self.valid)}]"
+        super().__init__(message, {"value": value, "valid": self.valid})
+
+
+class UnknownOptionError(_IntegrationError):
+    """Raised by ``parse_options`` for a flag the integration does not declare."""
+
+    code = "unknown_option"
+
+    def __init__(self, *, integration: str, value: str, valid: list[str]) -> None:
+        self.integration = integration
+        self.value = value
+        self.valid = list(valid)
+        message = (
+            f"unknown option {value} for integration {integration!r}; "
+            f"valid: [{', '.join(self.valid)}]"
+        )
+        super().__init__(
+            message,
+            {"integration": integration, "value": value, "valid": self.valid},
+        )
+
+
+class MalformedOptionError(_IntegrationError):
+    """Raised by ``parse_options`` on a structural rule violation in user input."""
+
+    code = "malformed_option"
+
+    def __init__(self, *, rule: str, value: str) -> None:
+        self.rule = rule
+        self.value = value
+        message = f"malformed option {value!r}: {rule}"
+        super().__init__(message, {"rule": rule, "value": value})
+
+
+class DuplicateRegistrationError(_IntegrationError):
+    """Raised by ``_register`` when a *different* class is bound to an existing key."""
+
+    code = "duplicate_registration"
+
+    def __init__(self, *, value: str, existing: str, new: str) -> None:
+        self.value = value
+        self.existing = existing
+        self.new = new
+        message = (
+            f"duplicate integration registration for key {value!r}: "
+            f"already registered as {existing}, refusing to replace with {new}"
+        )
+        super().__init__(message, {"value": value, "existing": existing, "new": new})
+
+
+class InvalidOptionDeclarationError(_IntegrationError):
+    """Raised when an ``IntegrationOption`` descriptor itself is malformed.
+
+    Programming-error guard for FR-015: surfaced the first time
+    ``parse_options`` introspects an integration's ``options()``. Never
+    user-facing — the offending integration class needs to be fixed.
+    """
+
+    code = "invalid_option_declaration"
+
+    def __init__(self, *, rule: str, value: str) -> None:
+        self.rule = rule
+        self.value = value
+        message = (
+            f"invalid option declaration ({rule}): {value!r}; "
+            "this is a programming error in the integration's options()"
+        )
+        super().__init__(message, {"rule": rule, "value": value})
+
+
+class InvalidIntegrationError(_IntegrationError):
+    """Raised by ``_register`` when an integration class is malformed.
+
+    Programming-error guard (R13): catches integrations that forgot to
+    override the base ``SkillsIntegration`` sentinel defaults
+    (e.g., ``cls.key = ""``). Never user-facing — the offending
+    integration class needs to be fixed.
+    """
+
+    code = "invalid_integration"
+
+    def __init__(self, *, rule: str, value: str) -> None:
+        self.rule = rule
+        self.value = value
+        message = (
+            f"invalid integration ({rule}): {value!r}; "
+            "this is a programming error in the integration class"
+        )
+        super().__init__(message, {"rule": rule, "value": value})
+
+
+class SkillLintError(_IntegrationError):
+    """Raised by ``lint_skill_md`` on the first agentskills.io violation (FR-015).
+
+    Post-write: a freshly generated skill is linted right after it is written, and
+    ``generate_skill_md`` deletes the offending skill dir before this error escapes
+    (FR-016 — "no invalid SKILL.md on disk"). Note that ``generate_skill_md`` does
+    NOT re-lint a *pre-existing* ``SKILL.md``: idempotency (FR-014) skips it
+    untouched, so re-validation of hand-edited skills is the job of the standalone
+    ``lint_skill_md`` call (and the iteration-11 validation system that reuses it),
+    not of ``setup()``.
+    """
+
+    code = "skill_lint_failed"
+
+    def __init__(self, *, skill: str, rule: str, detail: str) -> None:
+        self.skill = skill
+        self.rule = rule
+        self.detail = detail
+        message = f"skill {skill!r} failed lint rule {rule!r}: {detail}"
+        super().__init__(message, {"skill": skill, "rule": rule, "detail": detail})
+
+
+class SkillMaterializationError(_IntegrationError):
+    """Raised by ``generate_skill_md`` on a pre-write authoring error (FR-010/FR-020).
+
+    ``rule`` ∈ {``dangling_reference``, ``name_frontmatter_mismatch``,
+    ``residual_token``}. All are detected *before* the first filesystem write, so a
+    rejected source leaves **zero** on-disk state (nothing to clean up).
+    """
+
+    code = "skill_materialization_failed"
+
+    def __init__(self, *, skill: str, rule: str, detail: str) -> None:
+        self.skill = skill
+        self.rule = rule
+        self.detail = detail
+        message = f"skill {skill!r} materialization failed ({rule}): {detail}"
+        super().__init__(message, {"skill": skill, "rule": rule, "detail": detail})