diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9bad97df7..306f4d0e5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -81,6 +81,8 @@ jobs: run: python tools/mirrors_index_check.py - name: Certificate source bindings still match the tree, and the index names them run: python tools/pinned_sources_check.py + - name: An asserted operator directive cites its source (presence of sourcing, not truth) + run: python tools/operator_directive_check.py - name: Drive source map is queryable run: python tools/drive_index.py stats - name: Scoped Drive coverage and exact packed-byte reconstruction diff --git a/docs/RESEARCH_MAP.md b/docs/RESEARCH_MAP.md index edde6757b..c30c498fa 100644 --- a/docs/RESEARCH_MAP.md +++ b/docs/RESEARCH_MAP.md @@ -677,11 +677,15 @@ below is quoted from those bytes. promotion." The Board's OPERATOR PACKAGE DECISION of 2026-07-24 is the one operator sentence in the corpus about a Git repository: "REPOSITORY ROUTING: private Git repository creation and exact-history push are approved when - platform access becomes available." (Dylan subsequently authorized public - visibility on 2026-09-20; unauthenticated access was verified that day. - Public visitors have no write access. This later visibility decision does - not change the quoted historical routing, Drive sharing, or scientific - gates — see `governance/GIT_ADAPTATION.md`.) + platform access becomes available." (This repository is public, checked + 2026-09-26; the visibility decision is the owner's, and the only sourced record + in this tree about it is the 2026-09-18 execution handoff + `drive/deltas/2026-09-18/DG-EXEC-20260918-49291487/DRIVE_GITHUB_EXECUTION_HANDOFF.md`, + which records the owner asking to restrict who works in the repository, not + to hide it — see `governance/GIT_ADAPTATION.md`, which withdraws an unsourced + directive that this passage previously asserted in the opposite direction. The + quoted historical routing, Drive sharing and scientific gates are unchanged by + visibility either way.) * `14_COORDINATION_AUTOMATION_SPINE` (170) — the live registers (`04.1_LIVE_REGISTERS`: the GP-REG-032-v1.2 workbook, its leaf card, the deletion log), the automation lineage (GP-AUTO-034: **R0.4 current diff --git a/governance/GIT_ADAPTATION.md b/governance/GIT_ADAPTATION.md index f8c726f73..e2d3248ef 100644 --- a/governance/GIT_ADAPTATION.md +++ b/governance/GIT_ADAPTATION.md @@ -45,10 +45,44 @@ paragraph called the Board's sentence the only one; the restatements are GP/CL-line records of the same decision.) It approves a *private* repository as the formalization, source-control, reproducibility and CI-handoff system of record and, in the same decision, "NOT APPROVED: blanket terminalization or mathematical promotion -of any included claim." Dylan subsequently directed that the repository remain -private until publication is explicitly authorized. The authenticated GitHub -API confirmed private visibility on 2026-09-20 UTC. Private draft work may -continue; this does not authorize public publication or mathematical promotion. +of any included claim." This repository is **public** — checked on 2026-09-26 two ways: the +GitHub API reports `private=false`, and the account's repository listing reports +`visibility=public`. The one *sourced* record in this tree about that visibility +is `drive/deltas/2026-09-18/DG-EXEC-20260918-49291487/DRIVE_GITHUB_EXECUTION_HANDOFF.md`: +"The repository was public at inspection. Preserve that visibility: the owner +asked to restrict who works in it, not to hide the existing public record" +(that file, line 17, cited path `drive/deltas/2026-09-18/DG-EXEC-20260918-49291487/DRIVE_GITHUB_EXECUTION_HANDOFF.md`). +Whether to keep it so remains the owner's to decide. Private draft work may +continue; nothing in this paragraph authorizes public publication or mathematical +promotion. + +**Withdrawn on 2026-09-26, and recorded rather than deleted.** Until that date +this paragraph and `docs/RESEARCH_MAP.md` each asserted an operator directive +about repository visibility, with no source anywhere in this tree, and the two +contradicted each other. Quoted verbatim so the withdrawal is checkable — as +transcription, not as assertion; **no operator directive is asserted here:** + +```text +governance/GIT_ADAPTATION.md + "Dylan subsequently directed that the repository remain private until + publication is explicitly authorized. The authenticated GitHub API confirmed + private visibility on 2026-09-20 UTC." + +docs/RESEARCH_MAP.md + "Dylan subsequently authorized public visibility on 2026-09-20; + unauthenticated access was verified that day." +``` + +They cannot both be true, they are dated the same day, and neither cites a Drive +id, an artifact id, or any record in `registers/` or `drive/`. The status half of +the first is also false: the repository is public. And the first is not merely +unsourced but **contradicted by a sourced record already in the tree** — the +2026-09-18 execution handoff cited above says to preserve public visibility and +restrict who works in the repository, not to hide it. Which, if either, reflects an +actual decision is the operator's to say and nobody else's — this note asserts +only that neither was sourced and that both could not hold. +`tools/operator_directive_check.py`, added in the same commit, refuses either +shape from now on. | Drive construct (protocol) | Repository equivalent | Notes on guarantees | |---|---|---| diff --git a/governance/README.md b/governance/README.md index 82af947ae..772ddd106 100644 --- a/governance/README.md +++ b/governance/README.md @@ -99,7 +99,7 @@ about which protocol governs. **Scope note on OP-PROT-012.** The Drive object this reading copy comes from (`1hBQR7Pa10DpVeOxTCLv1qIozLT-bU_hgZKo6ksODCuo`) carries the title *"HISTORICAL OP-PROT-012 — APPROVAL ROUTING SUPERSEDED BY R17"* (retitled 2026-09-17). The -register says what R17 retired: `autonomy_control` AUTONOMOUS_DECISION_BUDGET = +register `registers/json/autonomy_control.json` says what R17 retired: AUTONOMOUS_DECISION_BUDGET = "RETIRED — R17 evidence predicates" ("Current owner-authorized operations have no 50-decision counter gate"), and CONTROL_PLANE_VERSION = "R17 supersedes R16 operational entry/budget/provider locks. Scientific predicates and exact frozen diff --git a/tests/test_operator_directive.py b/tests/test_operator_directive.py new file mode 100644 index 000000000..e0080a146 --- /dev/null +++ b/tests/test_operator_directive.py @@ -0,0 +1,368 @@ +"""Negative controls for tools/operator_directive_check.py. + +The checker exists because a third-party branch asserted, in +``governance/GIT_ADAPTATION.md``, that "Dylan subsequently directed that the +repository remain private until publication is explicitly authorized" -- with +no source anywhere in the tree, deleting a sourced sentence that said the +opposite, and alongside a present-tense status claim that was false. Every +checker in the repository passed. + +Each control runs the checker through its CLI against a synthetic document, so +a path or a pattern bound at import time cannot silently re-check the real +tree. The last two controls run it against the real offending text and against +the real repository. +""" +from __future__ import annotations + +import os +import subprocess +import sys + +ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +CHECKER = os.path.join(ROOT, "tools", "operator_directive_check.py") + +sys.path.insert(0, os.path.join(ROOT, "tools")) +import operator_directive_check as ODC # noqa: E402 + +# The sentence as the branch actually wrote it, with the sentence that followed. +REAL_OFFENDER = ( + "Dylan subsequently directed that the repository remain private until " + "publication is explicitly authorized. The authenticated GitHub API " + "confirmed private visibility on 2026-09-20 UTC. Private draft work may " + "continue; this does not authorize public publication or mathematical " + "promotion.\n" +) + + +def run(root, *docs): + args = [sys.executable, CHECKER, "--root", root] + for d in docs: + args += ["--doc", d] + return subprocess.run(args, capture_output=True, text=True) + + +def write(tmp_path, name, body): + path = tmp_path / name + path.write_text(body, encoding="utf-8") + return str(tmp_path), name + + +def test_the_real_offending_sentence_is_refused(tmp_path): + root, name = write(tmp_path, "GOVERNED.md", REAL_OFFENDER) + out = run(root, name) + assert out.returncode != 0, out.stdout + assert "asserts an operator directive with no source" in out.stdout + # It must name the directive, not some neighbouring run-on chunk. + assert "Dylan subsequently directed" in out.stdout + + +def test_the_noun_form_is_refused(tmp_path): + """"by Dylan's subsequent explicit instruction" asserts just as plainly.""" + root, name = write(tmp_path, "GOVERNED.md", + "This repository is now private by Dylan's subsequent " + "explicit instruction; public publication requires his " + "explicit authorization.\n") + out = run(root, name) + assert out.returncode != 0, out.stdout + + +def test_a_bare_date_is_not_a_citation(tmp_path): + root, name = write(tmp_path, "GOVERNED.md", + "The operator approved the change on 2026-09-20 UTC, " + "confirmed at 17:46 the same day.\n") + out = run(root, name) + assert out.returncode != 0, out.stdout + + +def test_a_drive_id_in_the_same_sentence_is_accepted(tmp_path): + root, name = write(tmp_path, "GOVERNED.md", + "The operator approved it (Drive " + "`10o4YRYOr8a2fB6rtnFnzMn7HkQMfv9-FZ5Mh0L-KF_o`).\n") + out = run(root, name) + assert out.returncode == 0, out.stdout + + +def test_a_citation_in_the_following_sentence_is_accepted(tmp_path): + root, name = write(tmp_path, "GOVERNED.md", + "The operator approved the routing. See OP-PROT-012 for " + "the decision as recorded.\n") + out = run(root, name) + assert out.returncode == 0, out.stdout + + +def test_a_cross_reference_to_a_governed_file_is_accepted(tmp_path): + """docs/RESEARCH_MAP.md cites by pointing at the file holding the id.""" + (tmp_path / "governance").mkdir() + (tmp_path / "governance" / "GIT_ADAPTATION.md").write_text("# id here\n", encoding="utf-8") + root, name = write(tmp_path, "GOVERNED.md", + "The Board's decision of 2026-07-24 is the one operator " + "sentence about a Git repository. (The visibility " + "decision is the owner's -- see " + "`governance/GIT_ADAPTATION.md`.)\n") + out = run(root, name) + assert out.returncode == 0, out.stdout + + +def test_a_cross_reference_to_a_missing_file_is_refused(tmp_path): + """`docs/NOTHING_HERE.md` has the shape of a citation and cites nothing.""" + root, name = write(tmp_path, "GOVERNED.md", + "The operator approved the routing; see " + "`docs/NOTHING_HERE.md` for the decision.\n") + out = run(root, name) + assert out.returncode == 1, out.stdout + assert "does not exist under the checked root" in out.stdout + assert "docs/NOTHING_HERE.md" in out.stdout + + +def test_a_commit_sha_is_not_a_drive_id(tmp_path): + """A 40-hex sha beginning 0 or 1 has a Drive id's shape and opens nothing.""" + root, name = write(tmp_path, "GOVERNED.md", + "The operator approved it in " + "0123456789abcdef0123456789abcdef01234567.\n") + out = run(root, name) + assert out.returncode == 1, out.stdout + assert "no source" in out.stdout + + +def test_the_owner_asked_phrasing_is_a_directive(tmp_path): + """The handoff record's own wording, restated without its source.""" + for body in ("The owner asked that the repository be made private.\n", + "The owner directed that the mirror be removed.\n", + "Dylan requested a private repository.\n"): + root, name = write(tmp_path, "GOVERNED.md", body) + out = run(root, name) + assert out.returncode == 1, body + out.stdout + assert "no source" in out.stdout + root, name = write(tmp_path, "GOVERNED.md", + "The owner asked to restrict who works in it " + "(OP-PROT-012).\n") + assert run(root, name).returncode == 0 + + +def test_the_explicit_disclaimer_opts_a_paragraph_out(tmp_path): + root, name = write(tmp_path, "GOVERNED.md", + "A reader might think the operator approved this; no " + "operator directive is asserted here.\n") + out = run(root, name) + assert out.returncode == 0, out.stdout + + +def test_prose_with_no_directive_is_untouched(tmp_path): + """The control cannot pass by refusing everything.""" + root, name = write(tmp_path, "GOVERNED.md", + "The lane holds 449 native Google Docs. None of them is " + "certified, and the premises remain OPEN.\n") + out = run(root, name) + assert out.returncode == 0, out.stdout + assert "directives=0" in out.stdout + + +def test_authority_does_not_rub_off_from_a_neighbouring_citation(tmp_path): + """The defect the first version of this checker missed. + + An uncited directive appended to a long, heavily cited paragraph about a + different decision. Paragraph-granularity passed it; sentences do not. + """ + root, name = write(tmp_path, "GOVERNED.md", + "The Board's OPERATOR PACKAGE DECISION of 2026-07-24 " + "(Drive `10o4YRYOr8a2fB6rtnFnzMn7HkQMfv9-FZ5Mh0L-KF_o`) " + "approved private repository creation. " + REAL_OFFENDER) + out = run(root, name) + assert out.returncode != 0, out.stdout + assert "Dylan subsequently directed" in out.stdout + + +def test_the_repository_passes(): + out = run(ROOT) + assert out.returncode == 0, out.stdout + assert "problems=0" in out.stdout + + +# --------------------------------------------------------------------------- +# Fenced code blocks are not prose +# +# README.md's "What CI enforces" block lists `tools/operator_directive_check.py`. +# That filename contains both "operator" and "directive", so the first version +# of this checker counted it as an asserted operator directive -- and PASSED +# it, because the same block names `registers/`, which counts as a citation. A +# false positive that passes is worse than one that fails: it inflates the +# count and teaches a reader to ignore it. +# --------------------------------------------------------------------------- + +def test_a_filename_in_a_bash_block_is_not_a_directive(tmp_path): + root, name = write(tmp_path, "GOVERNED.md", + "## What CI enforces\n\n```bash\n" + "python3 tools/operator_directive_check.py # cites its source\n" + "python3 tools/registers_check.py\n```\n") + out = run(root, name) + assert out.returncode == 0, out.stdout + assert "directives=0" in out.stdout + + +def test_a_tilde_fence_is_stripped_too(tmp_path): + root, name = write(tmp_path, "GOVERNED.md", + "~~~\nthe operator directed everything here\n~~~\n") + out = run(root, name) + assert out.returncode == 0, out.stdout + assert "directives=0" in out.stdout + + +def test_prose_after_a_fence_is_still_read(tmp_path): + """Stripping must not swallow the rest of the document.""" + root, name = write(tmp_path, "GOVERNED.md", + "```bash\npython3 tools/operator_directive_check.py\n```\n\n" + "Dylan subsequently directed that the repository remain private.\n") + out = run(root, name) + assert out.returncode != 0, out.stdout + assert "Dylan subsequently directed" in out.stdout + + +def test_line_numbers_survive_the_stripping(tmp_path): + """Blanked fences keep their newlines, so a report still points at the line.""" + body = ("```bash\n" + "echo hello\n" * 8 + "```\n\n" + "The operator approved the routing with no source at all.\n") + root, name = write(tmp_path, "GOVERNED.md", body) + out = run(root, name) + assert out.returncode != 0, out.stdout + assert f"{name}:12:" in out.stdout, out.stdout + + +def test_the_real_readme_block_no_longer_counts(): + """The live tree passes with every counted directive in prose, none from a + code block. The exact count is not pinned: it moves whenever a governed + document is edited, and a control that fails on an edit without a defect + teaches readers to ignore it.""" + out = run(ROOT) + assert out.returncode == 0, out.stdout + directives = int(out.stdout.split("directives=")[1].split()[0]) + assert directives >= 1 + fenced_only = os.path.join(ROOT, "README.md") + with open(fenced_only, encoding="utf-8") as handle: + stripped = ODC.strip_code_fences(handle.read()) + assert "operator_directive_check.py" not in stripped or \ + not any(ODC.DIRECTIVE.search(s) for _, s in ODC.sentences(stripped) + if "operator_directive_check.py" in s) + + +# --------------------------------------------------------------------------- +# A checker whose coverage can fall to nothing is not enforcing anything +# +# This tool used to skip a governed document that was absent. With the whole +# set gone it printed `docs=0 directives=0 problems=0` and exited 0; deleting +# any one of the six dropped the count by one and still passed. CI invokes it +# bare, so nothing else would have noticed. +# --------------------------------------------------------------------------- + +def test_an_empty_root_is_refused(tmp_path): + out = run(str(tmp_path)) + assert out.returncode != 0, out.stdout + assert "docs=0" in out.stdout + assert out.stdout.count("governed document is missing") == 6 + + +def test_one_missing_governed_document_is_refused(tmp_path): + """Copy the real governed set, drop one, and the checker must object.""" + import shutil + # Cited repository paths must resolve under the checked root, so the + # records the governed set cites travel with it as empty stand-ins. + for rel in ODC.GOVERNED_DOCS: + src = os.path.join(ROOT, rel) + dst = os.path.join(str(tmp_path), rel) + os.makedirs(os.path.dirname(dst), exist_ok=True) + shutil.copyfile(src, dst) + with open(src, encoding="utf-8", errors="replace") as handle: + for cited in ODC.CITED_PATH.findall(ODC.strip_code_fences(handle.read())): + target = os.path.join(str(tmp_path), cited.rstrip("/")) + if os.path.exists(os.path.join(ROOT, cited.rstrip("/"))) and not os.path.exists(target): + os.makedirs(os.path.dirname(target), exist_ok=True) + open(target, "w", encoding="utf-8").close() + out = run(str(tmp_path)) + assert out.returncode == 0, out.stdout + assert "docs=6" in out.stdout + + os.remove(os.path.join(str(tmp_path), ODC.GOVERNED_DOCS[0])) + out = run(str(tmp_path)) + assert out.returncode != 0, out.stdout + assert ODC.GOVERNED_DOCS[0] in out.stdout + assert "docs=5" in out.stdout + + +def test_the_governed_set_is_explicit_and_all_of_it_is_in_the_tree(): + for rel in ODC.GOVERNED_DOCS: + assert os.path.isfile(os.path.join(ROOT, rel)), rel + assert len(ODC.GOVERNED_DOCS) == 6 + + +# ------------- the pair of contradictory directives this branch withdrew ------- +# The tree carried BOTH of these, unsourced, on the same date and in opposite +# directions: governance/GIT_ADAPTATION.md said the operator directed the +# repository stay private, docs/RESEARCH_MAP.md said he authorized it public. The +# controls above already pin the first shape, because it is the edit this checker +# was written for. These pin the second, and pin the mechanism the withdrawal note +# relies on. + +WITHDRAWN_PUBLIC_DIRECTIVE = ( + "Dylan subsequently authorized public visibility on 2026-09-20; " + "unauthenticated access was verified that day.\n") + + +def test_the_opposite_unsourced_directive_is_also_refused(tmp_path): + """Refusing only the "remain private" wording would leave the mirror image of + the same defect live, which is exactly what happened.""" + doc = tmp_path / "docs" / "RESEARCH_MAP.md" + doc.parent.mkdir(parents=True, exist_ok=True) + doc.write_text("# Map\n\n" + WITHDRAWN_PUBLIC_DIRECTIVE, encoding="utf-8") + out = run(str(tmp_path), os.path.join("docs", "RESEARCH_MAP.md")) + assert out.returncode == 1, out.stdout + assert "no source" in out.stdout, out.stdout + + +def test_a_verbatim_quotation_inside_a_fence_is_not_an_assertion(tmp_path): + """The mechanism governance/GIT_ADAPTATION.md's withdrawal note depends on. + + The note quotes both withdrawn sentences so the withdrawal is checkable. In + prose that reads as asserting them -- the disclaimer only covers a sentence + and the one after it, and the quotation is longer than that -- so the + transcription sits in a fenced block, which this checker strips because a + fence holds text, not a claim about anybody. If fences ever stopped being + stripped, the note would fail and the real prose would be edited to appease + it, which is the wrong repair. + """ + doc = tmp_path / "README.md" + doc.write_text("# R\n\nWithdrawn, quoted verbatim below.\n\n```text\n" + + WITHDRAWN_PUBLIC_DIRECTIVE + "```\n", encoding="utf-8") + out = run(str(tmp_path), "README.md") + assert out.returncode == 0, out.stdout + assert "directives=0" in out.stdout, out.stdout + + +def test_the_same_quotation_outside_a_fence_is_still_refused(tmp_path): + """So the control above is not licensing a way to assert a directive by + calling it a quotation.""" + doc = tmp_path / "README.md" + doc.write_text("# R\n\nWithdrawn, quoted verbatim below.\n\n" + + WITHDRAWN_PUBLIC_DIRECTIVE, encoding="utf-8") + out = run(str(tmp_path), "README.md") + assert out.returncode == 1, out.stdout + + +def test_the_real_tree_has_no_unsourced_operator_directive(): + out = run(ROOT) + assert out.returncode == 0, out.stdout + assert "problems=0" in out.stdout, out.stdout + + +def test_the_withdrawal_note_cites_the_record_that_contradicts_it(): + """The withdrawn "remain private" directive is not merely unsourced: a sourced + record in the tree says the opposite. The note must cite it, or the reader has + only my word for the contradiction.""" + with open(os.path.join(ROOT, "governance", "GIT_ADAPTATION.md"), + encoding="utf-8") as handle: + text = handle.read() + cited = ("drive/deltas/2026-09-18/DG-EXEC-20260918-49291487/" + "DRIVE_GITHUB_EXECUTION_HANDOFF.md") + assert cited in text, "the withdrawal note does not cite the contradicting record" + with open(os.path.join(ROOT, cited), encoding="utf-8") as handle: + record = handle.read() + assert "Preserve that visibility" in record, "the cited record does not say that" + assert "restrict who works in it" in record diff --git a/tools/operator_directive_check.py b/tools/operator_directive_check.py new file mode 100644 index 000000000..93b2342a9 --- /dev/null +++ b/tools/operator_directive_check.py @@ -0,0 +1,244 @@ +#!/usr/bin/env python3 +"""An operator directive asserted in this repository must cite its source. + +Dylan Roy is the single final authority for canonical promotion, external +release, permanent deletion and machine-root replacement. This repository +records his decisions; it does not make them, and it must never be the only +place one of them exists. The convention the corpus already follows is that +every operator decision is quoted with its source: a Drive id, an artifact id +(``OP-PROT-012``, ``GP-AUD-187``), or a path under ``registers/`` or +``drive/``. + +Nothing enforced that. Commit c7219af (author-dated 2026-09-19, subject "Add +exact SIDE24 density-window bound and bounded research automation") rewrote the +repository-visibility paragraph of ``governance/GIT_ADAPTATION.md`` to read +"Dylan subsequently directed that the repository remain private until +publication is explicitly authorized", replacing a sourced sentence that said +the opposite ("the 2026-09-18 execution-contract draft records the owner asking +to restrict who works in it, not to hide it"). No source for the directive existed anywhere in the tree, and +the accompanying present-tense status claim was false: the repository is +public. Every checker passed, because none of them was looking at governance +prose for invented authority. + +WHAT THIS CHECKS. In each governed document, a SENTENCE asserting that the +operator directed / instructed / decided / authorised / approved / ordered / +ruled something must carry a citation in that sentence or the one after it. + +Sentence granularity is the point, and it was learned the hard way: the first +version of this checker worked per paragraph and did not catch the very edit +it was written for. The invented directive had been appended to a long, +heavily cited paragraph about a different, real decision, so the paragraph +contained citations and passed. Authority does not rub off on the sentence +next to it. + +A bare date is NOT a citation: "confirmed on 2026-09-20 UTC" is an observation +someone made, not a record anyone else can look up. + +Fenced code blocks are removed before sentences are cut. A filename is not an +assertion about anybody, and `tools/operator_directive_check.py` listed in a +bash block contains both "operator" and "directive". + +WHAT THIS DOES NOT ESTABLISH. That a cited directive is real, that it says +what the paragraph says it says, that the citation resolves, or that an +uncited paragraph is false. This is a presence check on sourcing, not on +truth. It reads no claim, grades nothing, moves no gate, and a pass here +authorizes nothing. Only the operator decides what the operator decided. +""" +from __future__ import annotations + +import argparse +import os +import re +import sys + +ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + +#: Prose in which an operator directive carries weight. Explicit, so that +#: adding a file is a deliberate act a reviewer can see in the diff. +GOVERNED_DOCS = ( + os.path.join("governance", "GIT_ADAPTATION.md"), + os.path.join("governance", "README.md"), + os.path.join("docs", "RESEARCH_MAP.md"), + os.path.join("docs", "OPEN_PROBLEMS.md"), + os.path.join("docs", "FINDINGS_2026-09-18.md"), + "README.md", +) + +#: "the operator did X" -- the subject and the verb in one sentence. "Owner" +#: is a subject because the sourced handoff record itself says "the owner asked +#: to restrict who works in it", and "asked / requested" are verbs because that +#: is the phrasing an unsourced restatement of such a record would use. +#: Hyphenated compounds ("OPERATOR-APPROVED", "owner-authorized operations") +#: still count: a quoted status field asserts the same thing, and the sentence +#: quoting it must say which register or record it comes from. +DIRECTIVE = re.compile( + r"\b(?:Dylan(?:\s+Roy)?(?:'s)?|the\s+operator(?:'s)?|operator(?:'s)?" + r"|the\s+owner(?:'s)?|owner(?:'s)?)\b" + r"[^.!?]{0,140}?" + r"\b(?:directed|instructed|decided|authorised|authorized|approved|ordered|ruled" + r"|asked|requested|instruction|directive|direction|request)\b", + re.IGNORECASE) + +#: What counts as a source someone else can go and read. Deliberately NOT a +#: date: a date is when a thing was observed, not a record of it. +CITATION = re.compile( + # A Drive file id. A 40-hex commit sha beginning 0 or 1 has the same shape + # and is not a record anyone can open, so pure-hex strings are excluded. + r"\b(?![0-9a-f]{40}\b)[01][A-Za-z0-9_-]{25,}\b" + r"|\b(?:OP-PROT|OP-GDN|OP-CNS|OD-OP)-\d" # operator protocol / decision + r"|\b(?:GP|CL|LS|S2|AO48|TRC|EC|PKG|DQ)-[A-Z]{2,4}-\d" # artifact id + r"|registers/|drive/mirrors/|drive/deltas/|claims/" + # A cross-reference to the governed file where the id lives is a + # citation too: docs/RESEARCH_MAP.md quotes the Board decision verbatim + # and points at governance/GIT_ADAPTATION.md for its Drive id, which is + # sourcing, not hand-waving. Requiring the id inline everywhere would + # push noise into prose to satisfy a regex. + r"|governance/[A-Za-z0-9_.-]+\.md|docs/[A-Za-z0-9_.-]+\.md") + +#: A cited repository path must exist under the root being checked. A path +#: that resolves to nothing is the citation shape without the citation, and the +#: first version of this checker accepted `docs/NOTHING_HERE.md` as a source. +CITED_PATH = re.compile( + r"\b((?:registers|drive/mirrors|drive/deltas|claims|governance|docs)/" + r"[A-Za-z0-9_./-]*[A-Za-z0-9_-])") + +#: A paragraph may opt out by saying, in the same paragraph, that it is NOT +#: reporting a directive. The phrase is fixed so the exemption is greppable. +DISCLAIMER = "no operator directive is asserted here" + + +#: End of sentence: . ! or ? then whitespace then a capital or a quote. Not +#: perfect English, and it does not need to be -- a split that occasionally +#: joins two sentences only makes the check more permissive, never less. +SENTENCE_END = re.compile(r"(?<=[.!?])[)\]\"'\u201d`*]*\s+(?=[\"“(*`A-Z])") + + +#: A fenced code block. Its contents are commands and filenames, not prose, and +#: a filename is not an assertion about anybody. `README.md`'s "What CI +#: enforces" block lists `tools/operator_directive_check.py`, which contains +#: both "operator" and "directive" and was read as an operator directive by +#: this checker's first version -- passing only because the same block names +#: `registers/`, which counts as a citation. A false positive that passes is +#: worse than one that fails: it inflates the directive count and teaches a +#: reader to ignore it. Blocks are removed before sentences are cut, with their +#: newlines kept so reported line numbers stay right. +CODE_FENCE = re.compile(r"^(?P```+|~~~+).*?^(?P=fence)[ \t]*$", + re.S | re.M) + + +def strip_code_fences(text: str) -> str: + """Blank out fenced blocks, preserving line count.""" + def blank(m): + return "\n" * m.group(0).count("\n") + return CODE_FENCE.sub(blank, text) + + +def sentences(text: str): + """(1-based line of the sentence, sentence text) over the whole document. + + Line numbers are approximate to the line the sentence starts on, which is + all a reader needs to find it. + """ + out = [] + line_no = 1 + buf, start = [], 1 + for raw in text.splitlines(): + if not buf and not raw.strip(): + # A blank line before any content of the next sentence. Skipping it + # is what lets `start` advance past a paragraph break -- and past a + # blanked-out code fence, whose lines are all blank. Without this, + # every sentence in a document that opens with a fence is reported + # at line 1. + line_no += 1 + continue + if not buf: + start = line_no + buf.append(raw) + joined = " ".join(" ".join(buf).split()) + parts = SENTENCE_END.split(joined) + if len(parts) > 1: + for part in parts[:-1]: + out.append((start, part)) + buf, start = [parts[-1]], line_no + line_no += 1 + tail = " ".join(" ".join(buf).split()) + if tail: + out.append((start, tail)) + return out + + +def audit(root: str, docs=None): + """Return (documents scanned, directive sentences, problems).""" + docs = GOVERNED_DOCS if docs is None else tuple(docs) + scanned = directives = 0 + problems = [] + for rel in docs: + path = os.path.join(root, rel) + if not os.path.isfile(path): + # Skipping silently was a hole in this checker: with the whole + # governed set absent it printed `docs=0 directives=0 problems=0` + # and exited 0, and deleting any one governed document dropped the + # count by one and still passed. A checker whose coverage can fall + # to nothing without failing is not enforcing anything. The set is + # explicit at the top of this file precisely so a change to it is a + # visible edit; a file vanishing is not that edit. + problems.append( + f"{rel}: governed document is missing. It is named in " + f"GOVERNED_DOCS, so either restore it or remove it from that " + f"tuple in the same commit -- a governed document that is " + f"merely absent makes this checker pass by scanning less") + continue + scanned += 1 + with open(path, encoding="utf-8", errors="replace") as handle: + text = handle.read() + items = sentences(strip_code_fences(text)) + for index, (start, sentence) in enumerate(items): + if not DIRECTIVE.search(sentence): + continue + window = sentence + if index + 1 < len(items): + # A citation that trails into the next sentence still counts. + window += " " + items[index + 1][1] + if DISCLAIMER in " ".join(window.lower().split()): + continue + directives += 1 + hit = DIRECTIVE.search(sentence) + lo = max(0, hit.start() - 30) + excerpt = ("..." if lo else "") + sentence[lo:hit.end() + 90] + if not CITATION.search(window): + problems.append( + f"{rel}:{start}: asserts an operator directive with no source in the " + f"sentence or the one after it. Quote it with its Drive id or artifact " + f"id, or say {DISCLAIMER!r}: {excerpt}") + continue + missing = sorted({cited for cited in CITED_PATH.findall(window) + if not os.path.exists(os.path.join(root, cited.rstrip("/")))}) + if missing: + problems.append( + f"{rel}:{start}: asserts an operator directive and cites a repository " + f"path that does not exist under the checked root: " + f"{', '.join(missing)}. A path that resolves to nothing is not a " + f"source: {excerpt}") + return scanned, directives, problems + + +def main(argv=None) -> int: + parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + parser.add_argument("--root", default=None) + parser.add_argument("--doc", action="append", default=[], + help="check this document instead of the governed set") + args = parser.parse_args(argv) + root = args.root if args.root is not None else ROOT + scanned, directives, problems = audit(root, args.doc or None) + for item in problems: + print(item) + print(f"operator_directive_check: docs={scanned} directives={directives} " + f"problems={len(problems)}") + print("A pass here means a directive names a source, not that the directive is real, " + "says what the paragraph says, or authorizes anything. Only the operator decides " + "what the operator decided.") + return 1 if problems else 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/run_checks.py b/tools/run_checks.py index 5884983f4..50942e0ad 100644 --- a/tools/run_checks.py +++ b/tools/run_checks.py @@ -68,6 +68,7 @@ "python tools/mirror_quotes_check.py", "python tools/mirrors_index_check.py", "python tools/pinned_sources_check.py", + "python tools/operator_directive_check.py", "python tools/drive_index.py stats", "python tools/drive_coverage.py --json", "python tools/hermite_envelope_report.py --check research/bands/candidates/hermite_gaussian_20260919.json",