shipwright-check 0.1.0__tar.gz

shipwright_check-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may accept and charge a
+      fee for acceptance of support, warranty, indemnity, or other liability
+      obligations and/or rights consistent with this License. However, in
+      accepting such obligations, You may act only on Your own behalf and on
+      Your sole responsibility, not on behalf of any other Contributor, and
+      only if You agree to indemnify, defend, and hold each Contributor
+      harmless for any liability incurred by, or claims asserted against,
+      such Contributor by reason of your accepting any such warranty or
+      additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 StellarRequiem
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

shipwright_check-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: shipwright-check
+Version: 0.1.0
+Summary: Pre-ship reliability check for an AI build's claims, docs, and citations — composes verity, firewall, and grounded over your own project (bring-your-own, consent-first). Checks what your AI ships in text, not its runtime behavior.
+License: Apache-2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Shipwright
+
+**Catch it before your users do.** A pre-ship reliability check for your AI build's **claims, docs, and
+citations** — run it on your own project, privately, before you ship.
+
+It composes three deterministic verification gates over the text your build produces and ships:
+
+| Check | What it catches | Powered by |
+|---|---|---|
+| Doc/output over-claims | factual claims in your README/output that contradict your declared ground truth | `firewall` |
+| Result-claim hygiene | result-claims (accuracy/win-rate) with no sample size, no holdout, or possible leakage | `verity` |
+| Citation grounding | cited claims whose source doesn't actually support them (fabricated/mismatched citations) | `grounded` |
+
+It reports a transparent **1–5 reliability level** and names each unearned point next to the fix.
+
+## Honest scope (what it does and doesn't do)
+Shipwright checks what your build **claims and ships in text**. It does **not** test your code's runtime
+behavior, and a 5/5 means *these specific deterministic checks pass* — not "provably reliable AI." It runs
+**only on the path you give it** and sends nothing anywhere (consent-first). A gate that isn't installed,
+or a check with no matching content, is reported as `n/a` — never a fake pass. MCP/tool *authorization*
+is deliberately **not** a dimension: our `mcp-bench` is a benchmark *of scanners*, not a scanner you point
+at your repo, so claiming an MCP-authz check here would be an over-claim of our own.
+
+## Install
+Shipwright itself has no dependencies. Install it and the three gates (the gates are published from the
+StellarRequiem repos, not under their generic PyPI names):
+
+```sh
+pip install -e .                                              # shipwright (this repo)
+pip install git+https://github.com/StellarRequiem/verity-core \
+            git+https://github.com/StellarRequiem/firewall \
+            git+https://github.com/StellarRequiem/grounded
+```
+
+## Use
+```sh
+shipwright init                         # scaffold a starter truth.yaml + a CI workflow
+shipwright check .                      # check the current project
+shipwright check . --truth truth.yaml   # declare your ground truth for the over-claim check
+```
+Writes `shipwright-report.md` and prints the level. Exit code is CI-gateable: `0` pass · `1` review · `2` refuse.
+Each gap is linked to the lesson that closes it, in the *Building Verifiable Software* course.
+
+Agents can self-check over MCP: `verity-mcp` (installed with verity-core) is a Model Context Protocol
+server — point your agent at it to gate its own claims.
+
+## Status
+Early (v0.1.0), single author, no users yet — the leading hypothesis is that teams ship LLM apps whose
+*claims* outrun what they can support, and there's no cheap, honest, local way to catch that before users
+do. This is the free, local tier; a hosted progress/badge surface is a later build.

shipwright_check-0.1.0/README.md

@@ -0,0 +1,50 @@
+# Shipwright
+
+**Catch it before your users do.** A pre-ship reliability check for your AI build's **claims, docs, and
+citations** — run it on your own project, privately, before you ship.
+
+It composes three deterministic verification gates over the text your build produces and ships:
+
+| Check | What it catches | Powered by |
+|---|---|---|
+| Doc/output over-claims | factual claims in your README/output that contradict your declared ground truth | `firewall` |
+| Result-claim hygiene | result-claims (accuracy/win-rate) with no sample size, no holdout, or possible leakage | `verity` |
+| Citation grounding | cited claims whose source doesn't actually support them (fabricated/mismatched citations) | `grounded` |
+
+It reports a transparent **1–5 reliability level** and names each unearned point next to the fix.
+
+## Honest scope (what it does and doesn't do)
+Shipwright checks what your build **claims and ships in text**. It does **not** test your code's runtime
+behavior, and a 5/5 means *these specific deterministic checks pass* — not "provably reliable AI." It runs
+**only on the path you give it** and sends nothing anywhere (consent-first). A gate that isn't installed,
+or a check with no matching content, is reported as `n/a` — never a fake pass. MCP/tool *authorization*
+is deliberately **not** a dimension: our `mcp-bench` is a benchmark *of scanners*, not a scanner you point
+at your repo, so claiming an MCP-authz check here would be an over-claim of our own.
+
+## Install
+Shipwright itself has no dependencies. Install it and the three gates (the gates are published from the
+StellarRequiem repos, not under their generic PyPI names):
+
+```sh
+pip install -e .                                              # shipwright (this repo)
+pip install git+https://github.com/StellarRequiem/verity-core \
+            git+https://github.com/StellarRequiem/firewall \
+            git+https://github.com/StellarRequiem/grounded
+```
+
+## Use
+```sh
+shipwright init                         # scaffold a starter truth.yaml + a CI workflow
+shipwright check .                      # check the current project
+shipwright check . --truth truth.yaml   # declare your ground truth for the over-claim check
+```
+Writes `shipwright-report.md` and prints the level. Exit code is CI-gateable: `0` pass · `1` review · `2` refuse.
+Each gap is linked to the lesson that closes it, in the *Building Verifiable Software* course.
+
+Agents can self-check over MCP: `verity-mcp` (installed with verity-core) is a Model Context Protocol
+server — point your agent at it to gate its own claims.
+
+## Status
+Early (v0.1.0), single author, no users yet — the leading hypothesis is that teams ship LLM apps whose
+*claims* outrun what they can support, and there's no cheap, honest, local way to catch that before users
+do. This is the free, local tier; a hosted progress/badge surface is a later build.

shipwright_check-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "shipwright-check"
+version = "0.1.0"
+description = "Pre-ship reliability check for an AI build's claims, docs, and citations — composes verity, firewall, and grounded over your own project (bring-your-own, consent-first). Checks what your AI ships in text, not its runtime behavior."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+# No Python dependencies: Shipwright composes the gate CLIs as subprocesses (never re-vendors them).
+# Install the gates separately from the StellarRequiem repos (see README).
+dependencies = []
+
+[project.scripts]
+shipwright = "shipwright.cli:main"
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["shipwright"]

shipwright_check-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

shipwright_check-0.1.0/shipwright/__init__.py

@@ -0,0 +1,7 @@
+"""Shipwright — a pre-ship reliability check for an AI build's claims, docs, and citations.
+
+Composes the verification gates (verity / firewall / grounded) over a path you point it at
+(bring-your-own, consent-first) and reports a transparent 1–5 reliability level. It checks what your
+build *claims and ships in text*, not its runtime code behavior.
+"""
+__version__ = "0.1.0"

shipwright_check-0.1.0/shipwright/cli.py

@@ -0,0 +1,86 @@
+"""shipwright CLI — `shipwright check <path>` runs the reliability check and writes a local report.
+
+Exit code is CI-gateable, mirroring the gates: 0 = pass (or nothing applicable) · 1 = review (warn) ·
+2 = refuse. Consent-first: only ever reads the path you give it.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .core import DIMENSIONS, gate_available, run_check, score
+from .report import render_markdown
+from .scaffold import init_project
+
+_EXIT = {"pass": 0, "warn": 1, "refuse": 2, None: 0}
+
+
+def _cmd_check(args) -> int:
+    root = Path(args.path).expanduser().resolve()
+    if not root.exists():
+        print(f"shipwright: path not found: {root}", file=sys.stderr)
+        return 3
+    truth = Path(args.truth).expanduser().resolve() if args.truth else None
+
+    missing = [cli for _, (_, cli) in DIMENSIONS.items() if not gate_available(cli)]
+    if missing:
+        print(f"shipwright: note — gates not installed: {', '.join(sorted(set(missing)))} "
+              f"(those dimensions report n/a; install from the StellarRequiem repos)", file=sys.stderr)
+
+    results = run_check(root, truth)
+    scored = score(results)
+    report = render_markdown(results, scored, str(root), truth_given=bool(truth))
+
+    out = Path(args.out).expanduser() if args.out else root / "shipwright-report.md"
+    out.write_text(report, encoding="utf-8")
+
+    lvl = scored.get("level")
+    if lvl is None:
+        print(f"Reliability level: n/a — {scored.get('note','')}")
+    else:
+        print(f"Reliability level: {lvl}/5 · {scored['passed']}/{scored['applicable']} applicable checks passed "
+              f"· worst: {scored.get('worst')}")
+    print(f"Report: {out}")
+    return _EXIT.get(scored.get("worst"), 0)
+
+
+def _cmd_init(args) -> int:
+    root = Path(args.path).expanduser().resolve()
+    if not root.exists():
+        print(f"shipwright: path not found: {root}", file=sys.stderr)
+        return 3
+    res = init_project(root, force=args.force)
+    for w in res["wrote"]:
+        print(f"  wrote {w}")
+    for s in res["skipped"]:
+        print(f"  skipped {s} (already exists — use --force to overwrite)")
+    if res["wrote"]:
+        print("Next: edit truth.yaml with your project's real facts, then run "
+              "`shipwright check . --truth truth.yaml`.")
+    return 0
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="shipwright",
+        description="Pre-ship reliability check for your AI build's claims, docs, and citations "
+                    "(composes verity + firewall + grounded; bring-your-own, consent-first).")
+    ap.add_argument("--version", action="version", version=f"shipwright {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    c = sub.add_parser("check", help="run the reliability check over a project path")
+    c.add_argument("path", help="path to your project (read-only; nothing is sent anywhere)")
+    c.add_argument("--truth", help="ground-truth YAML for the doc/output over-claim check")
+    c.add_argument("--out", help="report output path (default: <path>/shipwright-report.md)")
+    c.set_defaults(fn=_cmd_check)
+    i = sub.add_parser("init", help="scaffold a starter truth.yaml + a CI workflow")
+    i.add_argument("path", nargs="?", default=".", help="project path (default: current dir)")
+    i.add_argument("--force", action="store_true", help="overwrite existing files")
+    i.set_defaults(fn=_cmd_init)
+    args = ap.parse_args(argv)
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

shipwright_check-0.1.0/shipwright/core.py

@@ -0,0 +1,186 @@
+"""shipwright.core — compose the verification gates over a project's own claims/docs/citations.
+
+HONEST SCOPE: Shipwright checks the reliability of what an AI build *claims and ships in text* — over-
+claims in docs/output (via the AI-Output Claim Checker, `firewall`), statistically-unsound result-claims
+(via the Claim Verification Gate, `verity`), and fabricated/mismatched citations (via the Citation
+Grounding Checker, `grounded`). It does NOT test runtime code behavior. It runs ONLY on a path you point
+it at (bring-your-own, consent-first) and never sends your code anywhere.
+
+Design: Shipwright COMPOSES the gate CLIs as subprocesses (never re-vendors them) and has zero Python
+dependencies of its own. If a gate isn't installed, that dimension is reported as 'not available' — never
+a fake pass.
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# ── dimensions (plain names) → the gate CLI that powers each ──────────────────
+DIMENSIONS = {
+    "docs_claims": ("Doc/output over-claims", "firewall"),
+    "result_claims": ("Result-claim hygiene", "verity"),
+    "citations": ("Citation grounding", "grounded"),
+}
+_RANK = {"pass": 0, "warn": 1, "refuse": 2}   # worst-wins ordering; na/error sit outside the ladder
+
+
+@dataclass
+class Verdict:
+    dimension: str
+    artifact: str
+    status: str          # pass | warn | refuse | na | error
+    detail: str = ""
+    exit_code: int | None = None
+
+
+@dataclass
+class DimensionResult:
+    key: str
+    label: str
+    cli: str
+    available: bool
+    verdicts: list = field(default_factory=list)
+
+    @property
+    def applicable(self) -> bool:
+        return self.available and bool(self.verdicts)
+
+    @property
+    def status(self) -> str:
+        if not self.available:
+            return "na"            # gate not installed
+        if not self.verdicts:
+            return "na"            # no checkable artifacts of this kind
+        return max((v.status for v in self.verdicts), key=lambda s: _RANK.get(s, 0))
+
+
+def _resolve(cli: str) -> str | None:
+    # Gates are installed in the SAME venv as shipwright (co-located) — check that bin first (running a
+    # venv script directly does NOT put the venv bin on PATH), then fall back to PATH.
+    cand = Path(sys.executable).parent / cli
+    if cand.exists():
+        return str(cand)
+    return shutil.which(cli)
+
+
+def gate_available(cli: str) -> bool:
+    return _resolve(cli) is not None
+
+
+def _run(cmd: list, stdin_path: Path | None = None, timeout: int = 120) -> tuple[int, str]:
+    try:
+        with (open(stdin_path, "rb") if stdin_path else _null()) as fh:
+            p = subprocess.run(cmd, stdin=fh, capture_output=True, text=True, timeout=timeout)
+        return p.returncode, (p.stdout + p.stderr).strip()
+    except FileNotFoundError:
+        return -1, "gate CLI not found"
+    except subprocess.TimeoutExpired:
+        return -1, "gate timed out"
+    except Exception as e:  # noqa: BLE001 — a gate failure must never crash the orchestrator
+        return -1, f"gate error: {str(e)[:160]}"
+
+
+class _null:
+    def __enter__(self): return subprocess.DEVNULL
+    def __exit__(self, *a): return False
+
+
+def _status_from_exit(code: int, verity: bool = False) -> str:
+    # verity documents exit 0/1/2 = PASS/WARN/REFUSE. Other gates: 0 = clean, non-zero = needs review.
+    if code == -1:
+        return "error"
+    if verity:
+        return {0: "pass", 1: "warn", 2: "refuse"}.get(code, "warn")
+    return "pass" if code == 0 else "warn"
+
+
+# ── per-dimension runners ─────────────────────────────────────────────────────
+def run_docs_claims(doc: Path, truth: Path | None) -> Verdict:
+    cmd = [_resolve("firewall") or "firewall"]
+    if truth:
+        cmd += ["--truth", str(truth)]
+    cmd += [str(doc)]
+    code, out = _run(cmd)
+    status = _status_from_exit(code)
+    # A claim that CONTRADICTS your declared truth is the dangerous class — escalate it to refuse.
+    if status != "error" and ("CONTRADICTS" in out or "⛔" in out or "contradict" in out.lower()):
+        status = "refuse"
+    return Verdict("docs_claims", str(doc), status, out[:600], code)
+
+
+def run_result_claims(doc: Path) -> Verdict:
+    code, out = _run([_resolve("verity") or "verity", "verify-markdown", str(doc)])
+    return Verdict("result_claims", str(doc), _status_from_exit(code, verity=True), out[:600], code)
+
+
+def run_citations(doc: Path, no_net: bool = True) -> Verdict:
+    cmd = [_resolve("grounded") or "grounded"] + (["--no-net"] if no_net else []) + [str(doc)]
+    code, out = _run(cmd)
+    return Verdict("citations", str(doc), _status_from_exit(code), out[:600], code)
+
+
+# ── artifact discovery (consent-first: only under the given path) ─────────────
+def _markdown_files(root: Path, limit: int = 200) -> list:
+    out = []
+    for p in sorted(root.rglob("*.md")):
+        if any(seg in {".venv", "node_modules", ".git", "site-packages"} for seg in p.parts):
+            continue
+        out.append(p)
+        if len(out) >= limit:
+            break
+    return out
+
+
+def discover(root: Path) -> dict:
+    """Find the project's own checkable text artifacts. README + docs -> docs_claims; markdown holding
+    ```json claim blocks -> result_claims; markdown with citation/reference markers -> citations."""
+    mds = _markdown_files(root)
+    docs, claims, cites = [], [], []
+    for p in mds:
+        try:
+            text = p.read_text(encoding="utf-8", errors="replace")
+        except Exception:  # noqa: BLE001
+            continue
+        low = p.name.lower()
+        if low == "readme.md" or "/docs/" in str(p).replace("\\", "/").lower():
+            docs.append(p)
+        if "```json" in text:
+            claims.append(p)
+        if "](http" in text or "\n[1]" in text or "references" in text.lower():
+            cites.append(p)
+    return {"docs_claims": docs, "result_claims": claims, "citations": cites}
+
+
+def run_check(root: Path, truth: Path | None = None) -> list:
+    """Run every available dimension over the discovered artifacts. Returns DimensionResults."""
+    found = discover(root)
+    results = []
+    for key, (label, cli) in DIMENSIONS.items():
+        dr = DimensionResult(key=key, label=label, cli=cli, available=gate_available(cli))
+        if dr.available:
+            for art in found.get(key, []):
+                if key == "docs_claims":
+                    dr.verdicts.append(run_docs_claims(art, truth))
+                elif key == "result_claims":
+                    dr.verdicts.append(run_result_claims(art))
+                elif key == "citations":
+                    dr.verdicts.append(run_citations(art))
+        results.append(dr)
+    return results
+
+
+# ── transparent 1–5 reliability level ─────────────────────────────────────────
+def score(results: list) -> dict:
+    """Level = round(1 + 4 * passed/applicable) over APPLICABLE dimensions (a gate that's absent or has no
+    artifacts is 'n/a' and never counted — no fake pass). Returns the level + the inspectable fractions."""
+    applicable = [r for r in results if r.applicable]
+    passed = [r for r in applicable if r.status == "pass"]
+    if not applicable:
+        return {"level": None, "passed": 0, "applicable": 0,
+                "note": "Nothing checkable found — add result-claims, a truth.yaml, or cited reports to get a level."}
+    level = round(1 + 4 * (len(passed) / len(applicable)))
+    worst = max((r.status for r in applicable), key=lambda s: _RANK.get(s, 0))
+    return {"level": max(1, min(5, level)), "passed": len(passed), "applicable": len(applicable), "worst": worst}

shipwright_check-0.1.0/shipwright/report.py

@@ -0,0 +1,67 @@
+"""shipwright.report — render the local reliability report (markdown). No data leaves the machine."""
+from __future__ import annotations
+
+from .core import DimensionResult
+
+_ICON = {"pass": "PASS", "warn": "REVIEW", "refuse": "REFUSE", "na": "n/a", "error": "ERROR"}
+
+# Each gap maps to the lesson that closes it (the teach-at-the-moment loop). Lessons are real lessons in
+# the "Building Verifiable Software" course (StellarRequiem/classroom · courses/verifiable-software).
+_COURSE = "Building Verifiable Software (StellarRequiem/classroom · courses/verifiable-software)"
+_LESSON = {
+    "docs_claims": "l1-claim-vs-proof — state only what your declared truth supports",
+    "result_claims": "l3-tested + l4-calibrated — a result-claim needs a test that can fail, a sample size, and calibration",
+    "citations": "l1-claim-vs-proof — every cited claim must be supported by the source it cites",
+}
+
+
+def render_markdown(results: list, scored: dict, root: str, truth_given: bool = False) -> str:
+    lvl = scored.get("level")
+    lines = ["# Reliability check — " + str(root), ""]
+    if lvl is None:
+        lines += ["**Reliability level: n/a** — " + scored.get("note", ""), ""]
+    else:
+        lines += [f"**Reliability level: {lvl} / 5**  ·  "
+                  f"{scored['passed']} of {scored['applicable']} applicable checks passed"
+                  f"  ·  worst verdict: {_ICON.get(scored.get('worst'),'?')}", ""]
+
+    lines += ["## Dimensions", "", "| Check | Verdict | Artifacts | Powered by |", "|---|---|---|---|"]
+    for r in results:
+        n = len(r.verdicts)
+        powered = f"`{r.cli}`" + ("" if r.available else " — not installed")
+        lines.append(f"| {r.label} | {_ICON.get(r.status,'?')} | {n if r.available else '—'} | {powered} |")
+    lines.append("")
+    docs_dim = next((r for r in results if r.key == "docs_claims"), None)
+    if docs_dim and docs_dim.applicable and not truth_given:
+        lines += ["> Note: the over-claim check ran **without a declared `--truth` file**, so it only compares "
+                  "against the gate's default ground truth — a `PASS` here is weak. Declare your own "
+                  "`truth.yaml` to actually check your project's claims.", ""]
+
+    # named gaps + the lesson that closes each (forward-pointing, never a grade)
+    gaps = [(r, v) for r in results for v in r.verdicts if v.status in ("warn", "refuse")]
+    if gaps:
+        lines += ["## What to look at next (each is an unearned point + its fix)", "",
+                  f"_Lessons are from the course: {_COURSE}._", ""]
+        for r, v in gaps[:40]:
+            lines += [f"- **{r.label}** in `{v.artifact}` → {_ICON.get(v.status)} "
+                      f"({_LESSON.get(r.key,'')})"]
+            if v.detail:
+                snippet = v.detail.splitlines()[0][:140] if v.detail.splitlines() else ""
+                if snippet:
+                    lines.append(f"    - {snippet}")
+        lines.append("")
+
+    lines += [
+        "## How the level is computed (inspect it)",
+        "Level = round(1 + 4 × passed / applicable), over only the dimensions that *apply* to your project "
+        "(a gate that isn't installed, or a check with no matching artifacts, is `n/a` and is never counted — "
+        "there is no fake pass). 5/5 = every applicable check is green.",
+        "",
+        "## What this does NOT check (honest scope)",
+        "Shipwright checks the reliability of what your build **claims and ships in text** — doc/output "
+        "over-claims, result-claim hygiene, and citation grounding. It does **not** test your code's runtime "
+        "behavior, and a 5/5 means *these specific deterministic checks pass*, not 'provably reliable AI'. "
+        "It runs only on the path you gave it and sends nothing anywhere.",
+        "",
+    ]
+    return "\n".join(lines)

shipwright_check-0.1.0/shipwright/scaffold.py

@@ -0,0 +1,61 @@
+"""shipwright.scaffold — `shipwright init` writes a starter truth.yaml + a CI workflow.
+
+Never overwrites an existing file unless --force; reports exactly what it wrote.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+TRUTH_TEMPLATE = """\
+# truth.yaml — your project's declared ground truth, used by the doc/output over-claim check.
+# Each fact declares what is TRUE. Any claim in your README/docs/output that uses a `forbidden_terms`
+# phrase within a matching `domain_keywords` context is flagged as contradicting your ground truth.
+# Edit these to your project and delete the example. (Without this file the over-claim check is weak.)
+facts:
+  - id: capability_honesty
+    severity: HIGH
+    domain_keywords: ["accuracy", "reliable", "fast", "secure", "tested"]
+    canonical_terms: ["measured on a held-out set", "see the benchmark", "as tested"]
+    forbidden_terms: ["100% accurate", "never fails", "perfectly reliable", "always correct", "unhackable"]
+"""
+
+WORKFLOW_TEMPLATE = """\
+name: shipwright reliability check
+on: [pull_request, workflow_dispatch]
+jobs:
+  reliability:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: install shipwright + the verification gates
+        # Gates install from the StellarRequiem repos (not PyPI — the generic names are namesakes).
+        # The shipwright line works once this tool is published; until then, vendor it however you install it.
+        run: |
+          pip install git+https://github.com/StellarRequiem/shipwright \\
+                      git+https://github.com/StellarRequiem/verity-core \\
+                      git+https://github.com/StellarRequiem/firewall \\
+                      git+https://github.com/StellarRequiem/grounded
+      - name: reliability check (fails the PR on a REFUSE)
+        run: shipwright check . --truth truth.yaml
+"""
+
+
+def init_project(root: Path, force: bool = False) -> dict:
+    root = Path(root)
+    targets = {
+        "truth.yaml": root / "truth.yaml",
+        ".github/workflows/shipwright.yml": root / ".github" / "workflows" / "shipwright.yml",
+    }
+    contents = {"truth.yaml": TRUTH_TEMPLATE, ".github/workflows/shipwright.yml": WORKFLOW_TEMPLATE}
+    wrote, skipped = [], []
+    for label, path in targets.items():
+        if path.exists() and not force:
+            skipped.append(label)
+            continue
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(contents[label], encoding="utf-8")
+        wrote.append(label)
+    return {"wrote": wrote, "skipped": skipped}

shipwright_check-0.1.0/shipwright_check.egg-info/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: shipwright-check
+Version: 0.1.0
+Summary: Pre-ship reliability check for an AI build's claims, docs, and citations — composes verity, firewall, and grounded over your own project (bring-your-own, consent-first). Checks what your AI ships in text, not its runtime behavior.
+License: Apache-2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Shipwright
+
+**Catch it before your users do.** A pre-ship reliability check for your AI build's **claims, docs, and
+citations** — run it on your own project, privately, before you ship.
+
+It composes three deterministic verification gates over the text your build produces and ships:
+
+| Check | What it catches | Powered by |
+|---|---|---|
+| Doc/output over-claims | factual claims in your README/output that contradict your declared ground truth | `firewall` |
+| Result-claim hygiene | result-claims (accuracy/win-rate) with no sample size, no holdout, or possible leakage | `verity` |
+| Citation grounding | cited claims whose source doesn't actually support them (fabricated/mismatched citations) | `grounded` |
+
+It reports a transparent **1–5 reliability level** and names each unearned point next to the fix.
+
+## Honest scope (what it does and doesn't do)
+Shipwright checks what your build **claims and ships in text**. It does **not** test your code's runtime
+behavior, and a 5/5 means *these specific deterministic checks pass* — not "provably reliable AI." It runs
+**only on the path you give it** and sends nothing anywhere (consent-first). A gate that isn't installed,
+or a check with no matching content, is reported as `n/a` — never a fake pass. MCP/tool *authorization*
+is deliberately **not** a dimension: our `mcp-bench` is a benchmark *of scanners*, not a scanner you point
+at your repo, so claiming an MCP-authz check here would be an over-claim of our own.
+
+## Install
+Shipwright itself has no dependencies. Install it and the three gates (the gates are published from the
+StellarRequiem repos, not under their generic PyPI names):
+
+```sh
+pip install -e .                                              # shipwright (this repo)
+pip install git+https://github.com/StellarRequiem/verity-core \
+            git+https://github.com/StellarRequiem/firewall \
+            git+https://github.com/StellarRequiem/grounded
+```
+
+## Use
+```sh
+shipwright init                         # scaffold a starter truth.yaml + a CI workflow
+shipwright check .                      # check the current project
+shipwright check . --truth truth.yaml   # declare your ground truth for the over-claim check
+```
+Writes `shipwright-report.md` and prints the level. Exit code is CI-gateable: `0` pass · `1` review · `2` refuse.
+Each gap is linked to the lesson that closes it, in the *Building Verifiable Software* course.
+
+Agents can self-check over MCP: `verity-mcp` (installed with verity-core) is a Model Context Protocol
+server — point your agent at it to gate its own claims.
+
+## Status
+Early (v0.1.0), single author, no users yet — the leading hypothesis is that teams ship LLM apps whose
+*claims* outrun what they can support, and there's no cheap, honest, local way to catch that before users
+do. This is the free, local tier; a hosted progress/badge surface is a later build.

shipwright_check-0.1.0/shipwright_check.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+shipwright/__init__.py
+shipwright/cli.py
+shipwright/core.py
+shipwright/report.py
+shipwright/scaffold.py
+shipwright_check.egg-info/PKG-INFO
+shipwright_check.egg-info/SOURCES.txt
+shipwright_check.egg-info/dependency_links.txt
+shipwright_check.egg-info/entry_points.txt
+shipwright_check.egg-info/top_level.txt
+tests/test_core.py

shipwright_check-0.1.0/shipwright_check.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

shipwright_check-0.1.0/shipwright_check.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+shipwright = shipwright.cli:main

shipwright_check-0.1.0/shipwright_check.egg-info/top_level.txt

@@ -0,0 +1 @@
+shipwright

shipwright_check-0.1.0/tests/test_core.py

@@ -0,0 +1,72 @@
+"""Host-safe unit tests for shipwright.core — discovery + the level math. No gates required."""
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from shipwright.core import DimensionResult, Verdict, discover, score  # noqa: E402
+
+_p = 0
+_f = 0
+
+
+def ok(cond, msg):
+    global _p, _f
+    if cond:
+        _p += 1
+    else:
+        _f += 1
+        print("  FAIL:", msg)
+
+
+def test_discover(tmp: Path):
+    (tmp / "README.md").write_text("# Proj\nThis is fast and reliable.\n")
+    (tmp / "docs").mkdir()
+    (tmp / "docs" / "claims.md").write_text("# Results\n```json\n{\"metric\":\"acc\",\"value\":0.985}\n```\n")
+    (tmp / "report.md").write_text("# R\nThe sky is green [1].\n\n[1] https://example.com\n")
+    (tmp / ".venv").mkdir()
+    (tmp / ".venv" / "junk.md").write_text("```json\n{}\n```\n[1] http://x\n")  # must be ignored
+    d = discover(tmp)
+    ok(any(p.name == "README.md" for p in d["docs_claims"]), "README found as docs_claims")
+    ok(any("claims.md" in str(p) for p in d["result_claims"]), "json-claim md found as result_claims")
+    ok(any("report.md" in str(p) for p in d["citations"]), "cited md found as citations")
+    ok(all(".venv" not in str(p) for v in d.values() for p in v), ".venv excluded from discovery")
+
+
+def test_score():
+    def dim(key, available, statuses):
+        r = DimensionResult(key=key, label=key, cli="x", available=available)
+        r.verdicts = [Verdict(key, "a", s) for s in statuses]
+        return r
+    # all 3 applicable, all pass -> 5
+    s = score([dim("docs_claims", True, ["pass"]), dim("result_claims", True, ["pass"]), dim("citations", True, ["pass"])])
+    ok(s["level"] == 5, f"all-pass -> 5 (got {s.get('level')})")
+    # 1 of 2 applicable pass (third gate absent = n/a, not counted) -> round(1+4*0.5)=3
+    s = score([dim("docs_claims", True, ["pass"]), dim("result_claims", True, ["refuse"]), dim("citations", False, [])])
+    ok(s["applicable"] == 2 and s["level"] == 3, f"1/2 -> level 3 (got {s})")
+    ok(s["worst"] == "refuse", "worst verdict surfaced")
+    # nothing applicable -> n/a, no fake score
+    s = score([dim("docs_claims", False, []), dim("result_claims", True, [])])
+    ok(s["level"] is None, "nothing applicable -> n/a")
+
+
+def test_init(tmp: Path):
+    from shipwright.scaffold import init_project
+    r1 = init_project(tmp)
+    ok("truth.yaml" in r1["wrote"] and ".github/workflows/shipwright.yml" in r1["wrote"], "init writes both files")
+    ok((tmp / "truth.yaml").exists() and (tmp / ".github/workflows/shipwright.yml").exists(), "files on disk")
+    ok("facts:" in (tmp / "truth.yaml").read_text(), "truth.yaml carries the facts schema")
+    r2 = init_project(tmp)
+    ok(r2["wrote"] == [] and len(r2["skipped"]) == 2, "init skips existing files without --force")
+    r3 = init_project(tmp, force=True)
+    ok(len(r3["wrote"]) == 2, "init --force overwrites")
+
+
+if __name__ == "__main__":
+    import tempfile
+    with tempfile.TemporaryDirectory() as t:
+        test_discover(Path(t))
+    with tempfile.TemporaryDirectory() as t:
+        test_init(Path(t))
+    test_score()
+    print(f"--- {_p} passed, {_f} failed ---")
+    sys.exit(1 if _f else 0)