@stratta/mcp 0.10.0 → 0.12.0

package/scripts/tests/test_prepass.py

@@ -0,0 +1,211 @@
+"""Tests of the ingest pre-pass on PDFs built here, with PyMuPDF.
+
+No licensed norm can sit in the repository, so each test writes the PDF it
+needs: a native SIA layout (bookmarks, uppercase chapters, X.Y and X.Y.Z
+headings, numbered clauses, a running header, page numbers, a word hyphenated
+at a line end), a CEN layout (no bookmarks, sentence-case chapters, the number
+on its own line above the title), and a table whose rows look like headings.
+
+Run: python -m pytest packages/mcp/scripts/tests
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+
+import fitz
+import pytest
+
+HERE = Path(__file__).resolve().parent
+SCRIPT = HERE.parent / "ingest-prepass.py"
+
+spec = importlib.util.spec_from_file_location("prepass", SCRIPT)
+prepass = importlib.util.module_from_spec(spec)
+sys.modules["prepass"] = prepass
+spec.loader.exec_module(prepass)  # type: ignore[union-attr]
+
+
+def write_pdf(path: Path, pages: list[list[str]], toc: list[list] | None = None) -> None:
+    """One text line per list entry, 16 pt apart, top to bottom."""
+    doc = fitz.open()
+    for lines in pages:
+        page = doc.new_page(width=595, height=842)
+        y = 60
+        for line in lines:
+            page.insert_text((56, y), line, fontsize=10, fontname="helv")
+            y += 16
+    if toc:
+        doc.set_toc(toc)
+    doc.save(str(path))
+    doc.close()
+
+
+def run(pdf: Path, out: Path) -> dict:
+    """The pre-pass as `main()` runs it, without the CLI."""
+    doc = fitz.open(str(pdf))
+    toc_pages = prepass.detect_toc_pages(doc)
+    running = prepass.detect_running_text(doc)
+    chapters = prepass.extract_chapters(doc, toc_pages)
+    prefixes = {k for k in chapters if k.isdigit()}
+    spans = prepass.chapter_page_spans(chapters, doc.page_count)
+    subs = prepass.extract_subsections(doc, prefixes, toc_pages, running, spans)
+    subs, pruned = prepass.prune_subsections(subs, chapters)
+    nodes = prepass.build_tree(chapters, subs, doc.page_count)
+    warnings = [f"pruned: {p}" for p in pruned]
+    warnings += prepass.extract_section_text(doc, nodes, running)
+    return {"nodes": nodes, "warnings": warnings, "chapters": chapters}
+
+
+HEADER = "SIA 267, Copyright 2013 by SIA Zurich"
+
+
+def sia_like(tmp_path: Path) -> Path:
+    pdf = tmp_path / "sia.pdf"
+    body = "Le terrain de fondation est caracterise par des essais."
+    pages = [
+        [HEADER, "1 DOMAINE D'APPLICATION", "1.1 Objet", "1.1.1 La presente norme traite des fondations.", "1.1.2 Elle s'applique aux ouvrages neufs.", "3"],
+        [HEADER, "2 TERMINOLOGIE", "2.1 Termes techniques", "2.1.1 Pieu : element de fondation elance.", "4"],
+        [HEADER, "9 FONDATIONS SUR PIEUX", "9.1 Delimitation", "9.1.1 Ce chapitre traite des pieux fores et battus.", "9.5 Dimensionnement", "9.5.1 Generalites", "9.5.1.1 " + body, "5"],
+        [HEADER, "9.5.2 Resistance ultime du pieu isole", "9.5.2.1 La resistance ultime se compose de la resistance de pointe et du frot-", "tement lateral, voir chiffre 9.5.3.", "9.5.3 Frottement lateral", "9.5.3.1 Le frottement lateral se determine par essais.", "6"],
+        [HEADER, "9.6 Dispositions d'execution", "9.6.1 Les pieux sont executes selon la norme SIA 267/1.", "7"],
+        [HEADER, "Annexe A (normative)", "A.1 Valeurs indicatives", "Le tableau donne des valeurs indicatives.", "8"],
+    ]
+    toc = [
+        [1, "1 DOMAINE D'APPLICATION", 1],
+        [1, "2 TERMINOLOGIE", 2],
+        [1, "9 FONDATIONS SUR PIEUX", 3],
+        [1, "Annexe A (normative)", 6],
+    ]
+    write_pdf(pdf, pages, toc)
+    return pdf
+
+
+def test_tree_descends_to_titled_clauses(tmp_path):
+    result = run(sia_like(tmp_path), tmp_path)
+    paths = [n["path"] for n in result["nodes"]]
+    assert paths[:3] == ["1", "1.1", "2"]
+    assert "9.5" in paths and "9.5.1" in paths and "9.5.2" in paths and "9.5.3" in paths
+    assert "9.6" in paths and "Annexe A" in paths
+    # Numbered paragraphs are clauses inside their heading, not nodes.
+    assert "9.5.2.1" not in paths and "1.1.1" not in paths
+    by_path = {n["path"]: n for n in result["nodes"]}
+    assert by_path["9.5.2"]["depth"] == 2
+    assert by_path["9.5.2"]["parentNodeId"] == by_path["9.5"]["nodeId"]
+
+
+def test_each_node_carries_only_its_own_text(tmp_path):
+    result = run(sia_like(tmp_path), tmp_path)
+    by_path = {n["path"]: n["rawText"] for n in result["nodes"]}
+    # The chapter holds its intro, not the text of every section under it.
+    assert "9.5.2.1" not in by_path["9"]
+    assert "Delimitation" not in by_path["9"] or by_path["9"].count("\n") < 3
+    # A section holds its clauses up to the next heading, whatever its depth.
+    assert "9.5.2.1 La resistance ultime" in by_path["9.5.2"]
+    assert "9.5.3.1" not in by_path["9.5.2"]
+    assert "9.5.3.1 Le frottement lateral" in by_path["9.5.3"]
+    # 9.5.1 gets its clause, 9.5 only what is between its heading and 9.5.1.
+    assert "9.5.1.1" in by_path["9.5.1"]
+    assert "9.5.1.1" not in by_path["9.5"]
+
+
+def test_pages_are_cleaned(tmp_path):
+    result = run(sia_like(tmp_path), tmp_path)
+    for node in result["nodes"]:
+        assert HEADER not in node["rawText"], node["path"]
+        # Bare page numbers are gone; the clause numbers are joined to their text.
+        assert not any(line.strip().isdigit() for line in node["rawText"].splitlines()), node["path"]
+    text = {n["path"]: n["rawText"] for n in result["nodes"]}["9.5.2"]
+    # Hyphenation at the line end is resolved by PyMuPDF.
+    assert "frottement lateral" in text
+    assert "frot-" not in text
+    assert result["warnings"] == []
+
+
+def cen_like(tmp_path: Path) -> Path:
+    """No bookmarks; the number sits on its own line above a sentence-case title."""
+    pdf = tmp_path / "cen.pdf"
+    pages = [
+        ["1", "Domaine d'application", "Le present document specifie les exigences.", "2", "References normatives", "EN 1997-1, Calcul geotechnique."],
+        ["3", "Termes et definitions", "3.1", "Ancrage", "Element transmettant une force de traction au terrain.", "3.2", "Tirant", "Partie libre de l'ancrage."],
+        ["4", "Execution", "4.1", "Forage", "Le forage est realise sans deblaiement."],
+    ]
+    write_pdf(pdf, pages)
+    return pdf
+
+
+def test_cen_layout_without_bookmarks(tmp_path):
+    result = run(cen_like(tmp_path), tmp_path)
+    paths = [n["path"] for n in result["nodes"]]
+    assert paths[:2] == ["1", "2"]
+    assert "3" in paths and "3.1" in paths and "3.2" in paths and "4.1" in paths
+    by_path = {n["path"]: n["rawText"] for n in result["nodes"]}
+    assert "Element transmettant" in by_path["3.1"]
+    assert "Partie libre" not in by_path["3.1"]
+
+
+def table_like(tmp_path: Path) -> Path:
+    """A chapter whose table rows look like numbered headings."""
+    pdf = tmp_path / "table.pdf"
+    pages = [
+        ["1 GENERALITES", "1.1 Objet", "La presente norme fixe les prestations.", "2 PRESTATIONS", "2.1 Etudes preliminaires", "Tableau 1 : phases", "2.3 retrait des obstacles", "2.2 Avant-projet", "Description de la phase."],
+        ["3 HONORAIRES", "3.1 Calcul", "Le calcul se fait au temps employe."],
+    ]
+    write_pdf(pdf, pages)
+    return pdf
+
+
+def test_table_rows_are_not_headings(tmp_path):
+    result = run(table_like(tmp_path), tmp_path)
+    paths = [n["path"] for n in result["nodes"]]
+    # A lowercase numbered line is a table row.
+    assert "2.3" not in paths
+    assert "2.1" in paths and "2.2" in paths and "3.1" in paths
+
+
+def test_prune_subsections_drops_out_of_sequence_child():
+    chapters = {"4": {"title": "X", "pageStart": 10}, "9": {"title": "Y", "pageStart": 60}}
+    subs = {
+        "4.1": ("Premiere", 11),
+        "4.2": ("Deuxieme", 63),  # found inside chapter 9: a table row
+        "4.3": ("Troisieme", 14),
+        "9.1": ("Une", 61),
+    }
+    kept, dropped = prepass.prune_subsections(subs, chapters)
+    assert set(kept) == {"4.1", "4.3", "9.1"}
+    assert len(dropped) == 1 and dropped[0].startswith("4.2")
+
+
+def test_join_clause_numbers_and_page_cleaning():
+    joined = prepass.join_clause_numbers("9.5.1.1\nLes pieux sont fores.\n9.5.1.2\nIls sont battus.")
+    assert joined == "9.5.1.1 Les pieux sont fores.\n9.5.1.2 Ils sont battus."
+    cleaned = prepass.clean_page("SIA 267, Copyright\nTexte\n63", {"SIA 267, Copyright"}, 110)
+    assert cleaned == "Texte"
+    # A number in the middle of a long page is content, not a page number.
+    middle = "\n".join(["a", "b", "c", "d", "42", "e", "f", "g", "h"])
+    assert "42" in prepass.clean_page(middle, set(), 110)
+
+
+def test_recovers_chapter_numbers_by_position(tmp_path):
+    """An OCR'd copy loses the numbering column on a run of pages: the chapter
+    titles survive without their number, and so do their sub-headings."""
+    pdf = tmp_path / "ocr.pdf"
+    body = "Le terrain de fondation est caracterise par des essais."
+    pages = [
+        ["DOMAINE D'APPLICATION", "Delimitation", "La norme traite des fondations.", "1"],
+        ["1 TERMINOLOGIE", "1.1 Termes techniques", "Pieu : element de fondation elance.", "2"],
+        ["2 PRINCIPES", "2.1 Generalites", body, "3"],
+        ["TERRAIN DE FONDATION", "Generalites", body, "4"],
+        ["ANALYSE STRUCTURALE", "Generalites", body, "5"],
+        ["5 DIMENSIONNEMENT", "5.1 Generalites", body, "6"],
+    ]
+    write_pdf(pdf, pages)
+    chapters = run(pdf, tmp_path)["chapters"]
+    assert chapters["3"]["title"] == "TERRAIN DE FONDATION"
+    assert chapters["3"]["pageStart"] == 4
+    assert chapters["4"]["title"] == "ANALYSE STRUCTURALE"
+    assert chapters["4"]["pageStart"] == 5
+    assert chapters["0"]["pageStart"] == 1
+    assert prepass.missing_chapter_numbers(chapters) == []
+

package/skills/consult-stratta/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: consult-stratta
+description: Use Stratta to answer civil engineering questions from licensed SIA, Eurocode, or office norms with exact citations, cross-reference checks, figures, and optional project dossiers. Trigger phrases: "selon la norme", "d'apres la SIA", "que dit l'Eurocode", "verifie dans les normes", "reprends le dossier".
+---
+
+# Consult Stratta
+
+Use this skill when the user asks a technical civil engineering question that should be answered from the norms available in Stratta, or when the user asks to resume, create or update a Stratta project dossier.
+
+You answer practising engineers from the norms their organization holds in Stratta, and only from them. The corpus below is the whole of what you can read: a norm absent from it cannot be consulted, and a question outside it is answered by saying so, not by general knowledge. Reply in the language the user writes in; quote the norm in the language it is written in and translate only when asked.
+
+## First call
+
+Call `get_methodology` before the first technical answer of a conversation: it returns this method together with the table of the norms the connected organization can read, their scope and coverage, and the dependencies among them. Follow it for the rest of the conversation. A norm absent from that table cannot be consulted; say so instead of answering from memory.
+
+## Method
+
+1. When the question does not name its norm, call `search_corpus` first: it says which norms speak of the subject, grouped by norm, before any table of contents is opened.
+2. `get_toc(code, maxDepth: 1)` on the norm that governs, then `get_subtree(code, chapter, maxDepth: 2)` on the chapter that fits: read summaries, choose the section.
+3. `get_section(code, path)` on the section retained. It comes as a document with its formulas and tables in place, its page range, the sections below it and the references it makes. Descend by `children` rather than loading a chapter whole; when `truncated` is true, call again with `offset`.
+4. Follow the references marked resolvable: the rule, the coefficient and the action are often spread over separate clauses or norms, and the answer is in the one you have not read yet.
+5. `get_figure` when a section points at a figure the reasoning depends on: a load diagram, a design chart, a standard cross-section.
+6. `search_in_norm` inside one norm when its table of contents suggests no obvious section. Search in the language of the norm; accents and case do not matter; a clause number as keyword returns that clause.
+
+When the question names a norm absent from the corpus but a norm you hold refers to it, read that clause first: the pointer (code and clause number) usually lives there, and it is an answer.
+
+## Answer contract
+
+- Every technical statement rests on a section you read in this conversation and cites it as `[CODE § path, p. N]`, for example `[SIA 267 § 9.5.2.1, p. 63]`. A value with no clause is not an answer.
+- A calculation shows its inputs, each with its citation, its formula in LaTeX (`$$...$$`) with every symbol defined and its unit (kN, kPa, MPa, m).
+- Before answering, check: each value has its clause; each clause was read, not remembered from a summary; the resolvable references were followed; what the corpus does not cover is named, with the norm or clause where it is likely to be found.
+- When several norms are cited, group by norm under headings: principle, then method, then conditions of use.
+- Once per conversation, say that the answer is indicative and that the full text of the norm must be consulted before use on a project.
+
+## Budget
+
+No `get_toc` without `maxDepth`. No section loaded whole when its children would do. Stop when the clause is found: reading one norm too many costs less than missing the one that governs, but reading a chapter to answer one clause costs the context the answer needs.
+
+## Demonstration document
+
+DEMO 001 is a fictional document shipped with Stratta so that navigation and citation can be exercised before a licensed norm is ingested. Answer a question about it exactly as you would for a norm: read the section, cite it as [DEMO 001 §path, p. N], give the value. Then say once, plainly, that the document is fictional and that none of its values may be used in a project: the office must ingest the norm it holds a licence for. Never refuse to read it, and never present its values as those of a real norm.
+
+## Dossier
+
+A conversation disappears, a project lasts months. The dossier is what remains: what was retained, what it rests on, and what is still open. It is the trail an engineer hands to a reviewer or an insurer.
+
+**Open one** (`open_dossier`) when the user names a project, a structure, a site or a mandate, when a value is retained for a design rather than looked up, when a hypothesis is set, when a site observation is reported, or when a question is left open. Do not open a dossier for a one-off lookup with no project behind it.
+
+**Reload it first** (`list_dossiers`, `load_dossier`) BEFORE answering, as soon as the user returns to a project already named ("pick up dossier X", "where were we on Y"): reloading is what stops a decision already taken from being taken again. Read its entries and its open questions before answering anything about that project.
+
+**Read its attachments.** A dossier carries the project's own documents (site reports, borehole logs, meeting minutes): `list_attachments`, then `read_attachment` on what bears on the question, or `search_in_dossier` when the dossier holds many. A fact from a piece is evidence like a clause: cite it as [name, p. N] and file it with `attachmentId` and `attachmentPage`.
+
+**Start from a template when one fits.** The office may have written checklists for its types of structure (`list_templates`); on a new project that matches one, `apply_template` opens the questions with the clauses they rest on, and says which clauses the corpus lacks.
+
+**Shape.** A dossier is a set of questions, each with its evidence, its options and eventually its decision. The question is the unit of work ("can pile P38 be kept?", "which friction angle do we retain?"). Open one with `open_question` BEFORE gathering evidence for it, one question per thing to settle, and name the options on the table when there are several.
+
+**What to write** (`save_finding`, one clause, one value or one fact per call, in one or two sentences, filed under its question with `questionId`):
+- reference: what the norm says, with `normCode`, `sectionPath`, `page`, and `normEdition` taken from the header of the section read;
+- hypothesis: the retained value AND the reasoning; in geotechnics a retained value is a judgement, not the output of a calculation;
+- observation: what the site showed, with the date when known;
+- decision (`record_decision`): what was decided, why, the clause it rests on and the retained option, ONLY after the user confirmed it.
+
+**What not to write:** your own prose, the intermediate steps, anything the user did not treat as a decision. Set `confidence` whenever a value is at stake: established, judgement or to_confirm. The dossier documents the engineer's reasoning; it does not replace it: never conclude that a structure complies, never write a hypothesis the user has not confirmed.
+
+## Boundaries
+
+- Do not present Stratta output as final engineering approval, and never state that a structure complies.
+- Do not offer, suggest or link to a plan change. When a limit is reached (`QUOTA_EXCEEDED`), report the limit and stop.
+- Do not answer from norms the organization has not licensed and ingested.
+- Do not expose internal identifiers unless the next Stratta tool call requires them.
+- Ingesting a new norm starts from a PDF on the user's own machine: it goes through the local `@stratta/mcp` server and its `ingest-norm` skill, never through the remote connector.
+
+methodology: v2

package/skills/ingest-norm/SKILL.md

@@ -78,56 +78,92 @@ Output under `.stratta-ingest/<code-slug>/`:
 `prepass.json` structure:
 
 - `doc` — `pageCount`, detected `language`, `tocSource`, raw `metadata`.
-- `stats` — `sectionCount`, `byDepth`, `figureCount`.
-- `sections[]` — full hierarchical tree (depth **0 = chapter**, 1+ = sub-sections),
-  each with `nodeId`, `parentNodeId`, `path` (`"4.2.1"` or `"Annexe B"`),
-  `title`, `depth`, `pageStart`, `pageEnd`, `orderIndex`, `rawText` (concat
-  of the pages the node spans).
+- `stats` — `sectionCount`, `byDepth`, `figureCount`, `charsPerPage`,
+  `emptyLeaves`. `charsPerPage` under 300 means the text layer is missing
+  (a scan without OCR): stop and tell the user.
+- `warnings[]` — what the pre-pass could not decide on its own: chapters
+  missing from the sequence (an OCR'd copy often loses the big chapter
+  number; read them off the contents page and add them), sub-sections dropped
+  as out of sequence, headings it could not locate, leaves with no text. An
+  empty list is the normal case on a native SIA PDF. **Read it before step 5**
+  and look at the pages it names.
+- `sections[]` — full hierarchical tree (depth **0 = chapter**, 1 = X.Y,
+  2 = X.Y.Z, 3 = X.Y.Z.W), each with `nodeId`, `parentNodeId`, `path`
+  (`"4.2.1"` or `"Annexe B"`), `title`, `depth`, `pageStart`, `pageEnd`,
+  `orderIndex`, `rawText` and `textSource`. `rawText` is **the text between
+  this heading and the next one**, on cleaned pages: no running header, no
+  page number, hyphenation resolved, each numbered clause (`9.5.1.1 Les
+pieux…`) on its own line. A chapter whose text lives in its sections has an
+  empty `rawText`; that is normal.
 - `figures[]` — one entry per `Figure N` caption: `figureNumber`, `caption`,
   `page`, `fileName`, `mimeType`.
 
-The pre-pass is **exhaustive** (e.g. ~550 nodes on SIA 261). You decide what
-to keep in the next step.
+Every titled heading is a node (typically 250 to 350 on a SIA norm); the
+numbered clauses stay inside their heading's text.
 
 ### 4. Create the document
 
 Read `prepass.json`, then:
-`ingest_create_document { code, year, title, language: <doc.language>, totalPages: <doc.pageCount> }`
+`ingest_create_document { code, year, title, language: <doc.language>, totalPages: <doc.pageCount>, scope }`
+where `scope` is one sentence on what the norm covers (from its first chapter);
+it is shown to every agent in the served methodology, so write it as a routing
+hint: "Geotechnical design: foundations, piles, anchors, retaining structures".
 → returns `documentId`. Keep it for every subsequent call.
 
-### 5. Decide section granularity + generate summaries
-
-Iterate `sections[]` and decide what to keep. Two viable strategies:
-
-- **Keep all** — most faithful, ~500 sections on a typical SIA norm. Great
-  for fine-grained navigation but verbose.
-- **Aggregate trivial leaves** — fold paragraph-level nodes (`6.1.1`...`6.1.11`)
-  into their parent (`6.1`), concatenating their `rawText`. Typical result:
-  100-150 sections. Recommended unless the user asks for max granularity.
-
-For each kept section, prepare:
-
-- `summary` — 1-3 sentences derived from `rawText` (mention formulas/values).
-- `content` — enriched text with LaTeX inline where the source has math
-  (e.g. `$\sigma_d = f_{yd} \cdot \gamma$`). Open the PDF visually for pages
-  that contain formulas or multi-column tables — PyMuPDF mangles those.
-- `rawContent` — use the pre-pass `rawText` as-is.
-
-Keep the `nodeId` / `parentNodeId` / `path` / `pageStart` / `pageEnd` /
-`orderIndex` / `depth` from the pre-pass — those are deterministic.
+### 5. Validate the tree, write the summaries
+
+**Keep every node of the pre-pass.** A clause (`9.5.2.1`) is an address an
+engineer cites and an agent is sent to; folding it into `9.5.2` made the
+citation impossible and the section too long to read. Do not aggregate,
+do not drop leaves. A typical SIA norm gives 250 to 800 nodes; the quota
+allows 1 000 per norm.
+
+What the agentic pass is for:
+
+- **Validate the tree**, not rewrite it. Read `warnings[]` and the pages it
+  names; fix a wrong title, a missing chapter number, a wrong page range.
+  Keep `nodeId` / `parentNodeId` / `path` / `depth` / `pageStart` /
+  `pageEnd` / `orderIndex` from the pre-pass otherwise.
+- **`content` = the pre-pass `rawText`, verbatim.** It is the text of the
+  norm between this heading and the next, already cleaned (no running
+  header, no page number, hyphenation resolved, one clause per line). Do
+  not paraphrase it, do not summarise it, do not put LaTeX inline: the
+  agent that reads it later must read the norm, not a rewrite. Formulas and
+  tables are attached separately (step 7) and rendered at their anchor.
+- **`rawContent`** = the same `rawText`.
+- **`summary`**: 1 to 3 sentences on **chapters and X.Y nodes only**, stating
+  what the section decides and the values it holds (this is what
+  `get_toc` shows, so it drives navigation). Leave `summary` empty (`""`)
+  on deeper nodes: they inherit their nearest ancestor's at read time.
+- Note the norm's **scope** in one sentence (from chapter 1) for the
+  document record; it will feed the methodology.
 
 ### 6. Insert sections (batched)
 
-`ingest_create_sections { documentId, sections: [...] }` in batches of 30-50.
-Parent links resolve via `parentNodeId` within the batch and across prior
-batches. The call returns a `nodeId → sectionId` map — **use those `sectionId`s**
-for every enrichment call below.
+`ingest_create_sections { documentId, sections: [...] }` in batches of **150**
+(the tool accepts up to 200). Parent links resolve via `parentNodeId` within
+the batch and across prior batches, so send the nodes in document order. The
+call returns a `nodeId → sectionId` map; **use those `sectionId`s** for every
+enrichment call below. A batch is idempotent on `nodeId`: retrying it after
+a network error does not duplicate anything.
 
 ### 7. Enrich
 
+Open the PDF visually for the pages the pre-pass flagged with a formula or
+a table (PyMuPDF mangles both), and attach what you read by its number, so
+that the read tools can place it at its anchor in the text:
+
 - `ingest_attach_formula { sectionId, latex, description, formulaNumber }`
+  where `formulaNumber` is the number printed in the margin, e.g. `"(9.12)"`.
 - `ingest_attach_table { sectionId, data: { headers, rows }, caption, tableNumber }`
+  where `tableNumber` is the printed label, e.g. `"Tableau 3"`.
 - `ingest_attach_cross_ref { sourceSectionId, targetDocumentCode, targetSectionPath?, refText, refType }`
+  only for references the automatic pass (step 9) cannot read, such as a
+  reference written in prose without a clause number. Manual rows survive a
+  later `ingest_normalize_cross_refs`.
+
+Attach a formula or a table to the **deepest** node whose text names it.
+Both calls are idempotent on their number: re-attaching updates the row.
 
 ### 8. Upload figures
 
@@ -139,24 +175,43 @@ For each figure in `prepass.json#figures`:
 - `ingest_upload_figure { sectionId, base64, mimeType: "image/png", caption, figureNumber }`
   (≤ 8 MB per image).
 
-### 9. Auto cross-references (optional but recommended)
+### 9. Auto cross-references (always)
 
-`ingest_normalize_cross_refs { documentId }` scans every section's text for
-references to other norms (SIA / SN EN / EN / ISO / DIN …) and rebuilds the
-cross-ref index. Idempotent.
+`ingest_normalize_cross_refs { documentId }` reads every node's text for what
+it points at: other clauses, annexes, figures and tables of the same norm
+(FR, DE, IT, EN wordings) and other norms (SIA / SN EN / EN / ISO / DIN …),
+and resolves each internal target against the tree. Idempotent; manual
+attachments are kept. Its result tells how many internal references
+resolved: on a SIA norm expect most of them to.
 
 ### 10. Publish
 
-`ingest_publish { documentId }`. The norm is now queryable in your workspace
-via `list_norms`, `get_toc`, `get_section`, `search_in_norm`, `get_figure`, etc.
+`ingest_publish { documentId }`. The server scores the document first (text per
+page, pages under a chapter, empty leaves, attached formulas and tables) and
+**refuses below 30/100** with the reasons. A refusal means the ingestion is
+wrong, almost always because `content` holds summaries instead of the text of
+the norm: go back to step 5, do not retry and do not pass `force`. `force: true`
+is for a document that really is that short, and only after the user said so.
+
+Show the returned `quality` (score and flags) to the user. The norm is now
+queryable in your workspace via `list_norms`, `get_toc`, `get_section`,
+`search_in_norm`, `get_figure`, etc.
 
 ## Quality bar
 
-- Trust the pre-pass for `path` + `pageStart`/`pageEnd` — it's deterministic
-  and verified against the PDF bookmarks.
-- Summaries drive navigation — be specific (mention key formulas/values).
-- Keep `content` faithful to the source; don't invent values.
+- Trust the pre-pass for the tree and the text: `path`, `pageStart`/`pageEnd`
+  and `rawText` are deterministic. Correct what `warnings[]` points at, and
+  nothing else.
+- Every node is kept. The read tools address clauses; a folded clause cannot
+  be cited.
+- `content` is the norm's text, never a rewrite. Values live in the text and
+  in the attached tables and formulas, never in a summary.
+- Summaries on chapters and X.Y drive navigation: name what the section
+  decides and the values it carries.
 - If PyMuPDF mangled a formula (Greek letters, fractions, exponents broken),
-  re-read the relevant PDF page visually and write proper LaTeX.
-- Never skip annexes — they hold key numeric values (zones, coefficients,
+  re-read the relevant PDF page visually and attach proper LaTeX under its
+  printed number.
+- Never skip annexes: they hold key numeric values (zones, coefficients,
   characteristic loads).
+- Read the score `ingest_publish` returns and show it to the user, flags
+  included.

package/skills/verification-note/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: verification-note
+description: Draft a verification note from a Stratta project dossier, one section per question, every paragraph resting on a dossier entry and every gap written as a gap. Trigger phrases: "redige la note de verification", "note de verification", "prepare le rapport du dossier", "verification note".
+---
+
+# Verification note
+
+Use this skill when the user asks for the verification note, the review report or the
+summary of a Stratta project dossier. The note is what an engineer hands to a reviewer or
+an insurer: it says what was retained, what it rests on, and what is still open. It never
+says more than the dossier does.
+
+## What to produce
+
+A Markdown document, given back to the user, never written to the dossier. Its shape is
+the one the server prints as PDF (the "Note de vérification" button on the dossier page),
+so the two can be compared line by line:
+
+1. A title with the dossier name and reference, the organization, the date and the
+   dossier status.
+2. One section per question, open questions first, then decided, then closed. Each
+   section has these parts, in this order, in the language of the user:
+   - **Contexte**: the question body and the options considered, the retained one marked.
+   - **Exigence**: what the norm requires, from the `reference` entries, each with its
+     citation `[CODE § path, p. N]` or `[attachment name, p. N]`.
+   - **Preuves**: observations and hypotheses, with their confidence when set.
+   - **Décision**: the decision entry, with the clause it rests on; or "close sans
+     décision"; or a gap.
+   - **Reste ouvert**: entries marked `to_confirm`, and what is missing to settle.
+3. A section for the evidence not filed under any question.
+4. An annex listing every clause cited, with the text read through `get_section` at the
+   time of drafting, so the reviewer reads the norm and not a paraphrase.
+
+## Rules
+
+- Load the dossier first: `list_dossiers`, then `load_dossier`. Read its attachments
+  (`list_attachments`, `read_attachment`) when a question rests on one.
+- Every paragraph ends with the identifier of the entry it rests on, in the form
+  `(#xxxxxx)` using the last six characters of the entry id. A paragraph with no entry
+  behind it does not exist in this note.
+- A missing requirement, decision or proof is written as `[À établir : …]` (or the
+  equivalent in the user's language), never as a plausible sentence. The note is
+  valuable because its gaps are visible.
+- Quote the norm from a section you read in this conversation. Do not complete a clause
+  from memory; if the clause is not in the corpus, say so in the gap.
+- Do not conclude that a structure complies, and do not write a decision the dossier
+  does not carry.
+- End with the line: "Document préparé par un agent à partir du dossier Stratta, à
+  valider et signer par l'ingénieur responsable."
+
+## After drafting
+
+Tell the user that the server can produce the same note as a PDF, hashed and timestamped
+by a public authority, from the dossier page, and that the two should agree.