frontface-proofit 1.0.0__py3-none-any.whl

frontface_proofit-1.0.0.dist-info/METADATA

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: frontface-proofit
+Version: 1.0.0
+Summary: Fail-closed linter for locked-down runbooks: ten rules of workflow discipline as code
+Author: Ryan Wesley Hitchcock
+License: MIT
+Project-URL: Homepage, https://github.com/ohpersonperson/frontface
+Keywords: linter,runbook,workflow,technical-writing,validation
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# proofit — fail-closed linter for locked-down runbooks
+
+A runbook is a step-by-step procedure written so tightly that two different
+people following it do the same thing and get the same result. proofit checks
+a runbook draft against ten rules of workflow discipline — and **rejects the
+draft if any rule is violated**. No warnings, no advisories. Fail-closed:
+exit 1 until it's fixed, exit 0 when it's locked down.
+
+It checks the runbook's **shape, not its truth**: it can tell you a step is
+missing its verification block, not whether the verification would actually
+work. A fully-specified unwise workflow passes; a wise but sloppy one doesn't.
+That distinction is the whole product — see the FAQ.
+
+No prerequisites. You don't need to know anything about this project's
+history or any framework. The mechanism is the whole product.
+
+*(Lineage: this is the front-facing conversion of the `proofit` skill from
+Ryan's skill-suite, MIT. What changed in the conversion is documented in
+CHANGELOG.md.)*
+
+## What it does
+
+You write the runbook as Markdown in the template shape
+(`templates/runbook-template.md` — or print it with `python -m proofit
+template`):
+
+- **Ground Rules & Prerequisites** — baseline, routing specs per service,
+  tools/items, expected outcome
+- **Step-by-Step Directives** — numbered steps, each with **Do:** /
+  **Look for:** / **Verify:** / **If wrong:** / **Fix:**
+- **Validation & Closure** — success condition plus consistency checkpoints
+
+The linter parses that shape and runs ten checks:
+
+| # | Rule | How it's checked |
+|---|------|------------------|
+| 1 | Remove every assumption | Heuristic: flags bare unlabeled directives ("Press Continue") and claims of automatic behavior ("is done automatically"). Narrow by design — see below. |
+| 2 | All prerequisites upfront | Structure: the section must exist before step 1 and cover all eight fields (hardware, software, accounts, permissions, files, internet access, free-tier limits, starting state). |
+| 3 | One action per step | Structure: each `Do:` holds exactly one verb-led action; steps numbered 1..N. |
+| 4 | Concrete references | Flags bare UI nouns ("the button") and vague references ("open the file") with no visible label. Qualified nouns ("a confirmation dialog") don't fire. |
+| 5 | Explain technical terms | Convention: where a glossary exists, every entry must match `Term (definition)`. Detecting undefined jargon *without* a glossary is out of scope — stated, not pretended. |
+| 6 | Verification after every milestone | Structure: every step ends with a `Verify:` block in observable language ("displays", "exists", "contains"). |
+| 7 | Immediate recovery | Structure: every step carries `If wrong:` + `Fix:`. |
+| 8 | Never skip state changes | Heuristic: a `Do:` starting with a state-changing verb (open, close, install, …) must describe the resulting state in transition language ("a dialog appears"). Narrow by design. |
+| 9 | Routing decisions upfront | Schema: per named service — when to use, free-tier limits, verbatim prompt, expected output format — plus rate-limit handling and error paths. |
+| 10 | Finish with full validation | Structure: the document ends with Validation & Closure (never a step), with a success condition and a checklist. |
+
+## Why it works
+
+Most workflow failures are specification failures, not execution failures.
+Someone improvises mid-stream because the routing decision was never written
+down. Someone skips a prerequisite because it was revealed in step 9. Someone
+combines two actions in one step and does them in the wrong order. The ten
+rules attack exactly these failure modes, and the linter makes them
+mechanical: the rules that can be checked as structure *are* checked as
+structure, so compliance isn't a matter of discipline — it's a matter of
+passing the gate.
+
+Two rules (1 and 8) are phrase-list heuristics — tripwires, not proof. Under
+fail-closed they still block, so they are deliberately narrow: they fire only
+on clear hits. A foolproof gate that misfires on good drafts isn't foolproof,
+it's a tax. The narrowness is documented in the code and tested.
+
+## Quickstart
+
+Zero dependencies beyond Python 3.10+.
+
+```bash
+cd proofit
+PYTHONPATH=src python3 -m unittest discover -s tests   # 65 offline tests
+```
+
+Lint a draft:
+
+```bash
+PYTHONPATH=src python3 -m proofit lint my-runbook.md
+# violations listed as RULE n [location] ERROR — message + fix
+# exit 1: REJECTED — fix and re-run
+# exit 0: PASS — the runbook is locked down
+```
+
+Print the blank template:
+
+```bash
+PYTHONPATH=src python3 -m proofit template > my-runbook.md
+```
+
+Or use it as a library:
+
+```python
+from proofit import lint_text
+
+result = lint_text(open("my-runbook.md").read())
+if not result.passed:
+    for v in result.violations:
+        print(v.render())
+```
+
+See `examples/run_local.py` for the full cycle (broken draft rejected,
+fixed draft passes).
+
+## Inputs, outputs
+
+- **Input:** a runbook draft in Markdown following the template shape
+  (`templates/runbook-template.md`, or print it with `python -m proofit
+  template`). Freeform Markdown is out of scope **by design, not by
+  accident**: the linter parses the template's sections, so a document that
+  isn't in the template shape fails wholesale on missing sections rather
+  than producing meaningful per-rule violations. Write it in the template,
+  get it checked — anything else isn't a bad runbook to proofit, it's not
+  a runbook at all.
+- **Output:** a list of violations (`RULE n [location] ERROR — message`
+  plus a `fix:` line), and an exit code: 1 if any violation exists, 0 if
+  clean. Fail-closed — there is no warning level.
+
+## Worked example
+
+`examples/example-1-lint-cycle.md` — the same workflow as a broken draft
+(18 violations, rejected) and a fixed draft (passes). The fixture files
+`examples/broken-runbook.md` and `examples/fixed-runbook.md` are the
+actual inputs; the test suite asserts the broken one yields exactly 18
+violations across all ten rules and the fixed one yields zero.
+
+## FAQ
+
+**Does it check whether the runbook is *correct*?** No. It checks the
+runbook's shape, not its truth — it can't tell whether a stated rate limit
+is right or a recovery path works. It guarantees the workflow is fully
+specified, not that it is wise.
+
+**What if a heuristic fires on a good draft?** Rules 1 and 8 are narrow by
+design, but false positives are possible (documented in `checks.py`). If
+one blocks a draft you believe is correct, the honest move is to reword past
+the tripwire — the rewording is usually clearer anyway — not to fork the
+linter.
+
+**Why fail-closed instead of warnings?** Because the skill's promise is
+"unbreakable, zero-assumption directive." A warning you can ignore is the
+opposite of idiot-proof. The gate is the product.
+
+**Single-service workflow — do I need the routing section?** No. Rule 9 is
+vacuous when no services are named. Delete the Routing Architecture section
+and the check passes silently.
+
+## License
+
+MIT. See LICENSE.

frontface_proofit-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+frontface_proofit-1.0.0.dist-info/licenses/LICENSE,sha256=Zx_XafyZDq7qBexUb7tER9kYlBZ0rCVaAwKuqMCfxLE,1078
+proofit/__init__.py,sha256=u6VfGkv38hyNB1wSdtQqsYDZeLD8PtQIfHRdPf4vXTo,351
+proofit/__main__.py,sha256=chyGF0o_zRGXzpfsPXXfNFfEPJZo9yMB0vxt_2z37dk,4439
+proofit/checks.py,sha256=GCmTxU0OAFskLHKkl68Yr6NEICyWDdjqGHNGNpaNWSU,21443
+proofit/ledger.py,sha256=x8TH2et1Jt_UTzLMn49R8YKEiMMykYTW6UoMz-l8qCU,4245
+proofit/linter.py,sha256=ecu2ZDJZh57lSzwV9R5v7ZuCalJMRBINbqeTwKyyEPU,734
+proofit/model.py,sha256=UUI0AYD8YzhRLRUtlfrjivyIPvaQX0QDeJHDmivcZK4,2994
+proofit/parser.py,sha256=Hc59xsoGbbDx0nFgzNdjbefjo0ICYsbaQ_bGTzi1TLc,5500
+frontface_proofit-1.0.0.dist-info/METADATA,sha256=qeU5CuJyMvaDTbhhxqrg7f_NDyMT5RxbBW1cvrzSaNY,7597
+frontface_proofit-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+frontface_proofit-1.0.0.dist-info/entry_points.txt,sha256=lq8bTPZnHRhEdpIW2oT0ZwxGnTkrpBKYEnNpqoeZ8_M,50
+frontface_proofit-1.0.0.dist-info/top_level.txt,sha256=yDyoKQj29kURcq-c6TQr4fkTPJu7uaJRCZf-7uBL_xg,8
+frontface_proofit-1.0.0.dist-info/RECORD,,

frontface_proofit-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

frontface_proofit-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+proofit = proofit.__main__:main

frontface_proofit-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Wesley Hitchcock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

frontface_proofit-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+proofit

proofit/__init__.py

@@ -0,0 +1,16 @@
+"""proofit — fail-closed linter for locked-down runbooks."""
+from .linter import lint_file, lint_text
+from .model import LintResult, Runbook, Step, Violation
+from .parser import parse
+
+__version__ = "1.0.0"
+__all__ = [
+    "lint_file",
+    "lint_text",
+    "parse",
+    "LintResult",
+    "Runbook",
+    "Step",
+    "Violation",
+    "__version__",
+]

proofit/__main__.py

@@ -0,0 +1,130 @@
+"""CLI: python -m proofit lint runbook.md | python -m proofit template
+
+Fail-closed on ERRORs: any structural violation rejects the draft (exit 1).
+WARNINGs (heuristic/convention rules) are listed but don't fail the draft —
+unless --strict is passed, which restores fail-on-anything.
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+from . import __version__, lint_file
+from .ledger import Ledger
+
+
+def _template_path() -> str:
+    here = os.path.dirname(os.path.abspath(__file__))
+    return os.path.normpath(os.path.join(here, "..", "..", "templates", "runbook-template.md"))
+
+
+def cmd_lint(path: str, *, strict: bool = False) -> int:
+    try:
+        result = lint_file(path, strict=strict)
+    except FileNotFoundError:
+        print(f"error: file not found: {path}", file=sys.stderr)
+        return 2
+    except OSError as e:
+        print(f"error: cannot read {path}: {e}", file=sys.stderr)
+        return 2
+    _record_lint(path, result)
+    for v in result.violations:
+        print(v.render())
+    if not result.passed:
+        # errors, or (strict mode and warnings)
+        n = len(result.violations)
+        print(f"\nREJECTED: {n} violation{'s' if n != 1 else ''} — fix and re-run.")
+        return 1
+    if result.warnings:
+        n = len(result.warnings)
+        print(f"\nWARNINGS: {n} warning{'s' if n != 1 else ''} — pass "
+              f"(warnings don't fail the draft; use --strict to fail on them).")
+        return 0
+    print("PASS: no violations — the runbook is locked down.")
+    return 0
+
+
+def _record_lint(path: str, result) -> None:
+    """Append one lint record. Digest of the draft, never the draft."""
+    try:
+        with open(path, encoding="utf-8") as f:
+            content = f.read()
+    except OSError:
+        content = None
+    by_rule: dict[int, int] = {}
+    for v in result.violations:
+        by_rule[v.rule] = by_rule.get(v.rule, 0) + 1
+    Ledger("proofit").record(
+        "lint",
+        {
+            "passed": result.passed,
+            "violations": len(result.violations),
+            "by_rule": by_rule,
+        },
+        input_text=content,
+    )
+
+
+def cmd_ledger(argv: list[str]) -> int:
+    led = Ledger("proofit")
+    s = led.summary()
+    print(f"proofit ledger: {s['records']} records "
+          f"({led.path})")
+    for ev, n in sorted(s["events"].items()):
+        print(f"  {ev}: {n}")
+    if s["records"]:
+        print(f"  first: {s['first']}")
+        print(f"  last:  {s['last']}")
+        try:
+            limit = int(argv[0]) if argv else 5
+        except ValueError:
+            limit = 5
+        print(f"  recent {limit}:")
+        for r in led.read(limit=limit):
+            sm = r["summary"]
+            print(f"    {r['ts']} lint "
+                  f"passed={sm['passed']} violations={sm['violations']} "
+                  f"by_rule={sm['by_rule']}")
+    return 0
+
+
+def cmd_template() -> int:
+    path = _template_path()
+    try:
+        with open(path, encoding="utf-8") as f:
+            sys.stdout.write(f.read())
+    except OSError as e:
+        print(f"error: template not found at {path}: {e}", file=sys.stderr)
+        return 2
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    if not argv or argv[0] in ("-h", "--help", "help"):
+        print(f"proofit {__version__} — fail-closed runbook linter")
+        print("usage:")
+        print("  python -m proofit lint [--strict] <runbook.md>")
+        print("      check a draft; ERRORs reject (exit 1), WARNINGs pass unless --strict")
+        print("  python -m proofit template            print the blank runbook template")
+        print("  python -m proofit ledger [n]          show the local lint ledger (last n, default 5)")
+        return 0
+    if argv[0] == "lint" and len(argv) in (2, 3):
+        args = argv[1:]
+        strict = "--strict" in args
+        paths = [a for a in args if a != "--strict"]
+        if len(paths) != 1:
+            print("usage: python -m proofit lint [--strict] <runbook.md>",
+                  file=sys.stderr)
+            return 2
+        return cmd_lint(paths[0], strict=strict)
+    if argv[0] == "template" and len(argv) == 1:
+        return cmd_template()
+    if argv[0] == "ledger":
+        return cmd_ledger(argv[1:])
+    print(f"usage: python -m proofit (lint <file> | template | ledger [n])", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

proofit/checks.py

@@ -0,0 +1,490 @@
+"""The ten proofit rules as code.
+
+Each check takes a parsed Runbook and returns a list of Violations.
+Under fail-closed semantics every violation is an ERROR: any one of them
+rejects the draft.
+
+Implementation status per rule:
+  full check : R2, R3, R4, R6, R7, R9, R10  (mechanical structure/schema)
+  heuristic  : R1, R8                     (narrow phrase lists — tripwires)
+  convention : R5                         (enforces the Term (definition)
+                                           pattern where a glossary exists;
+                                           detecting undefined jargon without
+                                           a glossary is out of scope)
+"""
+from __future__ import annotations
+
+import re
+
+from .model import Runbook, Violation
+
+
+def _has_label(text: str) -> bool:
+    """Does the line name a visible label (bold, quotes, or code)?"""
+    return bool(
+        re.search(r"\*\*.+?\*\*|\"[^\"]+\"|'[^']+'|`[^`]+`", text)
+    )
+
+
+def _strip_labels(text: str) -> str:
+    text = re.sub(r"\*\*(.+?)\*\*", " ", text)
+    text = re.sub(r'"[^"]+"', " ", text)
+    text = re.sub(r"'[^']+'", " ", text)
+    text = re.sub(r"`[^`]+`", " ", text)
+    return text
+
+
+def _word_in(text: str, words: list[str]) -> bool:
+    t = text.lower()
+    return any(re.search(r"\b" + re.escape(w) + r"\b", t) for w in words)
+
+
+# ---------------------------------------------------------------------------
+# R1 — Remove every assumption (heuristic, narrow)
+# ---------------------------------------------------------------------------
+# Fires only on clear hits: bare unlabeled directives ("Press Continue"),
+# and claims that something happens on its own ("is done automatically").
+# It cannot prove completeness — a linter can't know which assumptions the
+# author silently held. Kept narrow on purpose: under fail-closed a
+# false positive blocks a good draft.
+R1_BARE_DIRECTIVES = [
+    "press continue",
+    "click continue",
+    "select the option",
+    "click ok",
+    "press ok",
+]
+# "is generated automatically" / "are handled automatically" — a claim that
+# something happens on its own. Deliberately requires is/are/was/were so that
+# plain state-change descriptions ("the download begins") don't trip it.
+R1_AUTOMATICITY_RE = re.compile(
+    r"\b(is|are|was|were)\b[^.\n]{0,40}\bautomatically\b", re.IGNORECASE
+)
+
+
+def check_r1_assumptions(rb: Runbook) -> list[Violation]:
+    out: list[Violation] = []
+    for step in rb.steps:
+        for field_name in ("do", "look_for"):
+            line = getattr(step, field_name)
+            if not line:
+                continue
+            low = line.lower()
+            if R1_AUTOMATICITY_RE.search(line):
+                out.append(Violation(
+                    rule=1,
+                    location=f"Step {step.number} ({field_name})",
+                    message=f'assumes automatic behavior: "{line.strip()}"',
+                    fix="state the condition explicitly instead of assuming it happens on its own",
+                ))
+                continue
+            if not _has_label(line):
+                for phrase in R1_BARE_DIRECTIVES:
+                    if phrase in low:
+                        out.append(Violation(
+                            rule=1,
+                            location=f"Step {step.number} ({field_name})",
+                            message=f'unlabeled directive assumes the reader knows where/what: "{line.strip()}"',
+                            fix="name the exact visible label, e.g. the blue **Continue** button in the bottom-right corner",
+                        ))
+                        break
+    return out
+
+
+# ---------------------------------------------------------------------------
+# R2 — Define every requirement before starting (structure)
+# ---------------------------------------------------------------------------
+PREREQ_FIELDS: list[tuple[str, list[str]]] = [
+    ("hardware", ["hardware", "computer", "laptop", "device", "machine"]),
+    ("software", ["software", "browser", "app", "apps", "application", "program"]),
+    ("accounts", ["account", "accounts"]),
+    ("permissions", ["permission", "permissions", "admin", "access level"]),
+    ("files", ["file", "files"]),
+    ("internet access", ["internet", "wi-fi", "wifi", "online", "connection"]),
+    ("free-tier limits", ["limit", "limits", "quota", "rate limit",
+                         "per day", "per month", "per hour"]),
+    ("starting state", ["starting state", "baseline", "precondition", "preconditions",
+                        "starting condition"]),
+]
+
+
+def check_r2_prerequisites(rb: Runbook) -> list[Violation]:
+    out: list[Violation] = []
+    if not rb.prereq_present:
+        out.append(Violation(
+            rule=2,
+            location="document",
+            message="no Ground Rules & Prerequisites section found",
+            fix="add a Ground Rules & Prerequisites section before the first step, covering all eight required fields",
+        ))
+        return out
+    kinds = [k for k, _, _ in rb.section_order]
+    if "steps" in kinds and kinds.index("prereq") > kinds.index("steps"):
+        out.append(Violation(
+            rule=2,
+            location="document",
+            message="prerequisites section comes after the steps — requirements must be defined before step 1",
+            fix="move Ground Rules & Prerequisites above Step-by-Step Directives",
+        ))
+    for field_name, keywords in PREREQ_FIELDS:
+        # Free-tier limits may live in the per-service routing specs, which
+        # are part of the prerequisites section — count those too.
+        haystack = rb.prereq_text
+        if field_name == "free-tier limits":
+            haystack += " " + " ".join(s.body for s in rb.services)
+        if not _word_in(haystack, keywords):
+            out.append(Violation(
+                rule=2,
+                location="Ground Rules & Prerequisites",
+                message=f"required prerequisite field missing: {field_name}",
+                fix=f"state the {field_name} requirement explicitly (never reveal new prerequisites mid-guide)",
+            ))
+    return out
+
+
+# ---------------------------------------------------------------------------
+# R3 — One action per step (structure — the strongest check)
+# ---------------------------------------------------------------------------
+ACTION_VERBS = [
+    "open", "click", "press", "select", "type", "enter", "copy", "paste",
+    "save", "run", "launch", "close", "download", "upload", "install",
+    "uninstall", "delete", "create", "rename", "move", "wait", "check",
+    "read", "write", "send", "start", "stop", "restart", "log", "sign",
+    "navigate", "go", "scroll", "drag", "drop", "choose", "pick", "set",
+    "change", "fill", "submit", "confirm", "cancel", "switch", "export", "load",
+    "import", "print", "refresh",
+]
+_SPLIT_RE = re.compile(r"\s+and\s+|\s*,\s*then\s+|\s+then\s+|\s*;\s*")
+
+
+def _verb_led(fragment: str) -> bool:
+    words = re.findall(r"[A-Za-z']+", fragment)
+    if not words:
+        return False
+    # crude stemming so "clicks" matches "click" ("go" keeps its form)
+    stem = words[0].lower()
+    if stem.endswith("s") and stem[:-1] in ACTION_VERBS:
+        stem = stem[:-1]
+    return stem in ACTION_VERBS
+
+
+def _count_actions(do_text: str) -> int:
+    fragments = [f for f in _SPLIT_RE.split(do_text) if f.strip()]
+    return sum(1 for f in fragments if _verb_led(f))
+
+
+def check_r3_one_action(rb: Runbook) -> list[Violation]:
+    out: list[Violation] = []
+    if not rb.steps:
+        out.append(Violation(
+            rule=3,
+            location="Step-by-Step Directives",
+            message="no steps found — the directives section is missing or empty",
+            fix="write the workflow as numbered steps, one action each",
+        ))
+        return out
+    numbers = [s.number for s in rb.steps]
+    if numbers != list(range(1, len(numbers) + 1)):
+        out.append(Violation(
+            rule=3,
+            location="Step-by-Step Directives",
+            message=f"step numbers are not sequential 1..{len(numbers)}: {numbers}",
+            fix="renumber steps sequentially starting at 1",
+        ))
+    for step in rb.steps:
+        if not step.do.strip():
+            out.append(Violation(
+                rule=3,
+                location=f"Step {step.number}",
+                message="step has no Do: field — zero actions is not one action",
+                fix="write exactly one action in a Do: field",
+            ))
+            continue
+        n = _count_actions(step.do)
+        if n > 1:
+            out.append(Violation(
+                rule=3,
+                location=f"Step {step.number}",
+                message=f'{n} actions in one Do: "{step.do.strip()}"',
+                fix="split into separate steps, one action each",
+            ))
+    return out
+
+
+# ---------------------------------------------------------------------------
+# R4 — Use concrete references (phrase + format)
+# ---------------------------------------------------------------------------
+# Fires only on BARE nouns — "the button", "the dialog" — the skill's own
+# bad examples. A noun with a qualifier ("a confirmation dialog", "the VS
+# Code window", "the blue Publish button") names something distinguishable
+# and does not fire. "window"/"screen" are excluded: they almost always
+# carry a product name ("the Settings window").
+UI_NOUNS = ["button", "link", "menu", "tab", "dialog", "field", "icon",
+            "dropdown", "checkbox", "option"]
+_BARE_UI_RE = re.compile(
+    r"\b(the|a|an)\s+(button|link|menu|tab|dialog|field|icon|dropdown|checkbox|option)\b",
+    re.IGNORECASE,
+)
+_QUALIFIED_UI_RE = re.compile(
+    r"\b(the|a|an)\s+[A-Za-z]+\s+(button|link|menu|tab|dialog|field|icon|dropdown|checkbox|option)\b",
+    re.IGNORECASE,
+)
+R4_VAGUE = ["select the file", "open the file"]
+
+
+def check_r4_concrete_refs(rb: Runbook) -> list[Violation]:
+    out: list[Violation] = []
+    for step in rb.steps:
+        for field_name in ("do", "look_for"):
+            line = getattr(step, field_name)
+            if not line:
+                continue
+            low = line.lower()
+            if _has_label(line):
+                continue
+            if _BARE_UI_RE.search(line) and not _QUALIFIED_UI_RE.search(line):
+                out.append(Violation(
+                    rule=4,
+                    location=f"Step {step.number} ({field_name})",
+                    message=f'UI element named without a visible label: "{line.strip()}"',
+                    fix="quote or bold the exact visible label, e.g. the **Save** button",
+                ))
+                continue
+            for phrase in R4_VAGUE:
+                if phrase in low and "named" not in low:
+                    out.append(Violation(
+                        rule=4,
+                        location=f"Step {step.number} ({field_name})",
+                        message=f'vague reference with no label: "{line.strip()}"',
+                        fix="name the exact item, e.g. the file named **report.xlsx**",
+                    ))
+                    break
+    return out
+
+
+# ---------------------------------------------------------------------------
+# R5 — Explain unavoidable technical terms (convention)
+# ---------------------------------------------------------------------------
+# Enforces the `Term (definition)` pattern where a glossary exists.
+# Detecting undefined jargon WITHOUT a glossary needs a glossary or a
+# model — that judgment is explicitly out of scope (see README).
+TERM_DEF_RE = re.compile(r"^\s*[-*]?\s*.+\([^)]+\)\s*$")
+
+
+def check_r5_terms(rb: Runbook) -> list[Violation]:
+    out: list[Violation] = []
+    if not rb.glossary_present:
+        return out
+    for i, line in enumerate(rb.glossary_text.splitlines(), start=1):
+        s = line.strip()
+        if not s or s.startswith("#"):
+            continue
+        if not TERM_DEF_RE.match(s):
+            out.append(Violation(
+                rule=5,
+                location=f"glossary (line {i})",
+                message=f'term without an inline definition: "{s}"',
+                fix="use the Term (definition) pattern, e.g. Repository (a folder that stores the project's files and history)",
+            ))
+    return out
+
+
+# ---------------------------------------------------------------------------
+# R6 — Verification after every milestone (structure)
+# ---------------------------------------------------------------------------
+OBSERVABLE = ["display", "displays", "appear", "appears", "exist", "exists",
+              "contain", "contains", "show", "shows", "return", "returns",
+              "match", "matches", "visible", "checkmark", "present",
+              "created", "saved", "opens"]
+
+
+def check_r6_verification(rb: Runbook) -> list[Violation]:
+    out: list[Violation] = []
+    for step in rb.steps:
+        if not step.verify.strip():
+            out.append(Violation(
+                rule=6,
+                location=f"Step {step.number}",
+                message="step ends without a Verify: block",
+                fix="describe exactly what should be observed, e.g. Verify: the file now exists at ~/backup/",
+            ))
+        elif not _word_in(step.verify, OBSERVABLE):
+            out.append(Violation(
+                rule=6,
+                location=f"Step {step.number} (Verify)",
+                message=f'verification is not objectively checkable: "{step.verify.strip()}"',
+                fix="describe something observable — what the screen displays, what exists, what the output contains",
+            ))
+    return out
+
+
+# ---------------------------------------------------------------------------
+# R7 — Include immediate recovery (structure)
+# ---------------------------------------------------------------------------
+def check_r7_recovery(rb: Runbook) -> list[Violation]:
+    out: list[Violation] = []
+    for step in rb.steps:
+        if not step.if_wrong.strip():
+            out.append(Violation(
+                rule=7,
+                location=f"Step {step.number}",
+                message="step has no If wrong: block — the most likely mistake is unstated",
+                fix="add If wrong: describing the most likely mistake for this step",
+            ))
+        if not step.fix.strip():
+            out.append(Violation(
+                rule=7,
+                location=f"Step {step.number}",
+                message="step has no Fix: block — no recovery path",
+                fix="add Fix: with the shortest recovery path (resume the guide, don't restart, when possible)",
+            ))
+    return out
+
+
+# ---------------------------------------------------------------------------
+# R8 — Never skip state changes (heuristic, narrow)
+# ---------------------------------------------------------------------------
+# A linter cannot know what state changes a step *causes* — that needs the
+# author or a model. This is a tripwire: when the Do: line starts with a
+# state-changing verb, the Look for:/Verify: text must describe the resulting
+# state in transition language. Narrow by design.
+STATE_VERBS = ["open", "close", "launch", "start", "restart", "install",
+               "uninstall", "delete", "download", "upload", "submit",
+               "refresh", "navigate", "log", "sign"]
+TRANSITIONS = ["opens", "appears", "closes", "begins", "starts", "dialog",
+               "new tab", "window", "confirmation", "downloads", "downloaded",
+               "installed", "deleted", "submitted", "refreshed", "logged in",
+               "logged out", "signed in", "signed out"]
+
+
+def check_r8_state_changes(rb: Runbook) -> list[Violation]:
+    out: list[Violation] = []
+    for step in rb.steps:
+        words = re.findall(r"[A-Za-z']+", step.do)
+        if not words:
+            continue
+        first = words[0].lower()
+        if first not in STATE_VERBS:
+            continue
+        observed = (step.look_for + " " + step.verify).lower()
+        if not any(t in observed for t in TRANSITIONS):
+            out.append(Violation(
+                rule=8,
+                location=f"Step {step.number}",
+                message=f'state-changing action with no described state change: "{step.do.strip()}"',
+                fix="describe what the software visibly does — a new tab opens, a dialog appears, the window closes",
+            ))
+    return out
+
+
+# ---------------------------------------------------------------------------
+# R9 — Specify routing decisions upfront (schema)
+# ---------------------------------------------------------------------------
+SERVICE_ITEMS: list[tuple[str, list[str]]] = [
+    ("when to use", ["when to use", "use when", "trigger", "condition", "route to", "use for"]),
+    ("free-tier limits", ["limit", "limits", "quota", "rate limit", "context window"]),
+    ("verbatim prompt", ["prompt"]),
+    ("expected output format", ["output format", "expected output", "schema", "response format"]),
+]
+
+
+def check_r9_routing(rb: Runbook) -> list[Violation]:
+    out: list[Violation] = []
+    if not rb.services:
+        return out  # single-service workflow: routing spec is vacuous
+    for svc in rb.services:
+        for item_name, keywords in SERVICE_ITEMS:
+            if not _word_in(svc.body, keywords):
+                out.append(Violation(
+                    rule=9,
+                    location=f"Routing / {svc.name}",
+                    message=f"service spec missing: {item_name}",
+                    fix=f"specify {item_name} for {svc.name} — no improvisation mid-workflow",
+                ))
+    if not _word_in(rb.prereq_text, ["rate limit handling", "when hitting", "quota exhaust"]):
+        out.append(Violation(
+            rule=9,
+            location="Routing Architecture",
+            message="no rate-limit handling — what to do when a free-tier limit is hit is unstated",
+            fix="add rate limit handling: wait time, fallback service, or graceful degradation",
+        ))
+    if not _word_in(rb.prereq_text, ["error path", "error paths", "if any service fails",
+                                   "unexpected data", "service fails"]):
+        out.append(Violation(
+            rule=9,
+            location="Routing Architecture",
+            message="no error paths — what to do if a service fails or returns unexpected data is unstated",
+            fix="add error paths per service",
+        ))
+    return out
+
+
+# ---------------------------------------------------------------------------
+# R10 — Finish with full validation (structure)
+# ---------------------------------------------------------------------------
+def check_r10_validation(rb: Runbook) -> list[Violation]:
+    out: list[Violation] = []
+    if not rb.validation_present:
+        out.append(Violation(
+            rule=10,
+            location="document",
+            message="no Validation & Closure section — the document never describes the completed state",
+            fix="end with Validation & Closure: a Success Condition plus consistency checkpoints",
+        ))
+        return out
+    kinds = [k for k, _, _ in rb.section_order]
+    # A trailing glossary is fine — the rule is "never end on an action".
+    if kinds and kinds[-1] not in ("validation", "glossary"):
+        out.append(Violation(
+            rule=10,
+            location="document",
+            message="document does not end with Validation & Closure — it ends on an action",
+            fix="move Validation & Closure to the end; never end with the final action",
+        ))
+    # A Step N heading placed after the validation section means the
+    # document ends on an action even if a validation section exists.
+    val_pos = None
+    for m in re.finditer(r"^#{1,6}\s+.*$", rb.raw, re.M):
+        if re.search(r"valid|closure|success condition|consistency", m.group(0), re.I):
+            val_pos = m.start()
+    if val_pos is not None:
+        for m in re.finditer(r"^#{1,6}\s+step\s+\d+", rb.raw, re.M | re.I):
+            if m.start() > val_pos:
+                out.append(Violation(
+                    rule=10,
+                    location="document",
+                    message="a step appears after Validation & Closure — the document ends on an action",
+                    fix="move all steps above Validation & Closure",
+                ))
+                break
+    if not _word_in(rb.validation_text, ["success condition"]):
+        out.append(Violation(
+            rule=10,
+            location="Validation & Closure",
+            message="no Success Condition — the exact final state is undescribed",
+            fix="describe the exact final state so success is certain, not hoped for",
+        ))
+    has_checklist = bool(re.search(r"^\s*-\s*\[[ xX]\]", rb.validation_text, re.M))
+    has_list = bool(re.search(r"^\s*(?:-\s+|\*\s+|\d+\.\s+)\S", rb.validation_text, re.M))
+    if not has_checklist and not has_list:
+        out.append(Violation(
+            rule=10,
+            location="Validation & Closure",
+            message="no consistency checklist — nothing to check the workflow against",
+            fix="add consistency checkpoints: inputs met spec, prompts correct, outputs matched format",
+        ))
+    return out
+
+
+ALL_CHECKS = [
+    check_r1_assumptions,
+    check_r2_prerequisites,
+    check_r3_one_action,
+    check_r4_concrete_refs,
+    check_r5_terms,
+    check_r6_verification,
+    check_r7_recovery,
+    check_r8_state_changes,
+    check_r9_routing,
+    check_r10_validation,
+]

proofit/ledger.py

@@ -0,0 +1,132 @@
+"""Append-only local ledger. Vendored per tool; stdlib only.
+
+CANONICAL COPY: edit this file, then re-vendor with vendor.sh.
+Do not edit the vendored copies in place.
+
+Privacy rule (non-negotiable): the ledger NEVER stores raw input text.
+Records carry SHA-256 digests of inputs plus structural summaries
+(counts, verdicts, deltas). What happened, and what kind — never the words.
+
+Location: ~/.frontface/<tool>/ledger.jsonl
+  override: FRONTFACE_LEDGER_DIR=<dir>   (ledgers go to <dir>/<tool>/)
+  disable:  FRONTFACE_NO_LEDGER=1         (record() becomes a silent no-op)
+
+The ledger must never break the tool it serves: record() swallows OSError
+and returns False instead of raising.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+from datetime import datetime, timezone
+
+try:
+    import fcntl
+except ImportError:  # pragma: no cover — Windows has no fcntl
+    fcntl = None  # type: ignore[assignment]
+
+
+def _base_dir() -> str:
+    return os.environ.get("FRONTFACE_LEDGER_DIR") or os.path.join(
+        os.path.expanduser("~"), ".frontface"
+    )
+
+
+def _disabled() -> bool:
+    return os.environ.get("FRONTFACE_NO_LEDGER") == "1"
+
+
+class Ledger:
+    """One JSONL ledger per tool. Cheap to construct; construct per use."""
+
+    def __init__(self, tool: str) -> None:
+        self.tool = tool
+        self.dir = os.path.join(_base_dir(), tool)
+        self.path = os.path.join(self.dir, "ledger.jsonl")
+
+    @property
+    def version(self) -> str:
+        """The owning package's __version__, resolved lazily."""
+        try:
+            pkg = sys.modules.get(__package__ or "")
+            return str(getattr(pkg, "__version__", "unknown"))
+        except Exception:
+            return "unknown"
+
+    @staticmethod
+    def digest(text: str) -> str:
+        return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+    def record(
+        self,
+        event: str,
+        summary: dict,
+        *,
+        input_text: str | None = None,
+    ) -> bool:
+        """Append one record. Returns False when disabled or on I/O error.
+
+        Never raises. Never stores raw input text — only its digest.
+        """
+        if _disabled():
+            return False
+        rec: dict = {
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "tool": self.tool,
+            "tool_version": self.version,
+            "event": event,
+            "summary": summary,
+        }
+        if input_text is not None:
+            rec["input_digest"] = self.digest(input_text)
+        try:
+            os.makedirs(self.dir, exist_ok=True)
+            with open(self.path, "a", encoding="utf-8") as f:
+                if fcntl is not None:
+                    fcntl.flock(f, fcntl.LOCK_EX)
+                    try:
+                        f.write(json.dumps(rec) + "\n")
+                        f.flush()
+                        os.fsync(f.fileno())
+                    finally:
+                        fcntl.flock(f, fcntl.LOCK_UN)
+                else:
+                    f.write(json.dumps(rec) + "\n")
+        except OSError:
+            return False
+        return True
+
+    def read(self, limit: int | None = None) -> list[dict]:
+        """All records, oldest first. Empty list when there's no ledger."""
+        try:
+            with open(self.path, encoding="utf-8") as f:
+                lines = f.read().splitlines()
+        except OSError:
+            return []
+        recs = []
+        for line in lines:
+            line = line.strip()
+            if line:
+                try:
+                    recs.append(json.loads(line))
+                except ValueError:
+                    continue  # never let a corrupt line kill the read
+        return recs[-limit:] if limit else recs
+
+    def summary(self) -> dict:
+        """Counts by event plus first/last timestamps."""
+        recs = self.read()
+        by_event: dict[str, int] = {}
+        for r in recs:
+            ev = str(r.get("event", "?"))
+            by_event[ev] = by_event.get(ev, 0) + 1
+        return {
+            "tool": self.tool,
+            "records": len(recs),
+            "events": by_event,
+            "first": recs[0]["ts"] if recs else None,
+            "last": recs[-1]["ts"] if recs else None,
+        }

proofit/linter.py

@@ -0,0 +1,21 @@
+"""Orchestrator: parse a runbook draft, run all ten rule checks, collect violations."""
+from __future__ import annotations
+
+from .checks import ALL_CHECKS
+from .model import LintResult
+from .parser import parse
+
+
+def lint_text(markdown: str, *, strict: bool = False) -> LintResult:
+    runbook = parse(markdown)
+    violations = []
+    for check in ALL_CHECKS:
+        violations.extend(check(runbook))
+    # deterministic order: rule number, then location
+    violations.sort(key=lambda v: (v.rule, v.location))
+    return LintResult(violations=violations, strict=strict)
+
+
+def lint_file(path: str, *, strict: bool = False) -> LintResult:
+    with open(path, encoding="utf-8") as f:
+        return lint_text(f.read(), strict=strict)

proofit/model.py

@@ -0,0 +1,104 @@
+"""Core data model for the proofit runbook linter."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Step:
+    number: int
+    name: str
+    do: str = ""
+    look_for: str = ""
+    verify: str = ""
+    if_wrong: str = ""
+    fix: str = ""
+    line_no: int = 0
+
+
+@dataclass
+class ServiceSpec:
+    name: str
+    body: str = ""
+    line_no: int = 0
+
+
+@dataclass
+class Runbook:
+    """A runbook draft parsed from Markdown following the proofit template shape."""
+
+    raw: str = ""
+    # (kind, title, line_no) for top-level sections, in document order.
+    # kind is one of: prereq, steps, validation, glossary, other
+    section_order: list = field(default_factory=list)
+    prereq_text: str = ""
+    prereq_present: bool = False
+    steps: list = field(default_factory=list)  # list[Step]
+    steps_present: bool = False
+    validation_text: str = ""
+    validation_present: bool = False
+    glossary_text: str = ""
+    glossary_present: bool = False
+    services: list = field(default_factory=list)  # list[ServiceSpec]
+
+
+# PARAM-PROOFIT-001: rule -> severity. Structural rules are ERROR
+# (fail-closed); heuristic (R1, R8) and convention (R5) are WARNING
+# (listed, never fail the draft unless --strict).
+ERROR = "ERROR"
+WARNING = "WARNING"
+SEVERITY_BY_RULE = {
+    1: WARNING,   # heuristic: assumptions
+    2: ERROR,     # structural: prerequisites
+    3: ERROR,     # structural: one action
+    4: ERROR,     # structural: concrete refs
+    5: WARNING,   # convention: terms
+    6: ERROR,     # structural: verification
+    7: ERROR,     # structural: recovery
+    8: WARNING,   # heuristic: state changes
+    9: ERROR,     # structural: routing
+    10: ERROR,   # structural: validation
+}
+
+
+@dataclass
+class Violation:
+    rule: int
+    location: str
+    message: str
+    fix: str
+    # Severity is derived from the rule, not passed — the map above is
+    # the adjudicated spec. An explicit value wins if ever given.
+    severity: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.severity:
+            self.severity = SEVERITY_BY_RULE.get(self.rule, ERROR)
+
+    def render(self) -> str:
+        lines = [f"RULE {self.rule} [{self.location}] {self.severity} \u2014 {self.message}"]
+        if self.fix:
+            lines.append(f"  fix: {self.fix}")
+        return "\n".join(lines)
+
+
+@dataclass
+class LintResult:
+    violations: list = field(default_factory=list)  # list[Violation]
+    # PARAM-PROOFIT-001: strict mode restores the old fail-on-anything
+    # behavior (the --strict CLI flag). Default is fail-closed on ERRORs.
+    strict: bool = False
+
+    @property
+    def errors(self) -> list:
+        return [v for v in self.violations if v.severity == ERROR]
+
+    @property
+    def warnings(self) -> list:
+        return [v for v in self.violations if v.severity == WARNING]
+
+    @property
+    def passed(self) -> bool:
+        if self.strict:
+            return not self.violations
+        return not self.errors

proofit/parser.py

@@ -0,0 +1,153 @@
+"""Template-shaped Markdown parser for runbook drafts.
+
+This is not a general Markdown parser. It understands exactly one document
+shape: the proofit runbook template (see templates/runbook-template.md),
+which mirrors the skill's own Output Format section:
+
+  Ground Rules & Prerequisites / Step-by-Step Directives / Validation & Closure
+
+Steps are `### Step N: name` headings with **Do:** / **Look for:** /
+**Verify:** / **If wrong:** / **Fix:** fields. Service routing specs are
+`### <service name>` headings inside the prerequisites section.
+"""
+from __future__ import annotations
+
+import re
+
+from .model import Runbook, ServiceSpec, Step
+
+HEADING_RE = re.compile(r"^(#{1,6})\s+(.*?)\s*$")
+FIELD_RE = re.compile(
+    r"^\s*\*{0,2}(Do|Look for|Verify|If wrong|Fix)\s*:\*{0,2}\s*(.*)$",
+    re.IGNORECASE,
+)
+STEP_RE = re.compile(r"^step\s+(\d+)\s*:?\s*(.*)$", re.IGNORECASE)
+
+# Subsection headings inside Ground Rules & Prerequisites that are NOT services.
+KNOWN_PREREQ_SUBSECTIONS = [
+    r"required baseline",
+    r"starting state",
+    r"precondition",
+    r"routing architecture",
+    r"input spec",
+    r"rate limit",
+    r"error path",
+    r"needed tools",
+    r"required tools",
+    r"needed items",
+    r"expected outcome",
+]
+
+
+def classify_section(title: str) -> str:
+    t = title.lower()
+    if re.search(r"prereq|ground rules", t):
+        return "prereq"
+    if re.search(r"step.by.step|directives", t):
+        return "steps"
+    if re.search(r"valid|closure|success condition|consistency", t):
+        return "validation"
+    if re.search(r"glossar|\bterms\b|definitions", t):
+        return "glossary"
+    return "other"
+
+
+def _is_known_prereq_subsection(title: str) -> bool:
+    t = title.lower()
+    return any(re.search(p, t) for p in KNOWN_PREREQ_SUBSECTIONS)
+
+
+def _is_step_heading(title: str) -> bool:
+    return bool(STEP_RE.match(title.strip()))
+
+
+def parse(text: str) -> Runbook:
+    rb = Runbook(raw=text)
+    lines = text.splitlines()
+
+    current_section: str | None = None
+    current_step: Step | None = None
+    current_field: str | None = None
+    current_service: ServiceSpec | None = None
+    # raw-text accumulators per top-level section
+    section_texts: dict[str, list[str]] = {}
+
+    def flush_step():
+        nonlocal current_step, current_field
+        if current_step is not None:
+            rb.steps.append(current_step)
+            current_step = None
+            current_field = None
+
+    def flush_service():
+        nonlocal current_service
+        if current_service is not None:
+            rb.services.append(current_service)
+            current_service = None
+
+    for i, line in enumerate(lines, start=1):
+        m = HEADING_RE.match(line)
+        if m:
+            level = len(m.group(1))
+            title = m.group(2).strip()
+            flush_step()
+            flush_service()
+            current_field = None
+            if level <= 2:
+                current_section = classify_section(title)
+                rb.section_order.append((current_section, title, i))
+                section_texts.setdefault(current_section, [])
+            elif current_section == "steps" and _is_step_heading(title):
+                sm = STEP_RE.match(title.strip())
+                current_step = Step(
+                    number=int(sm.group(1)),
+                    name=sm.group(2).strip(),
+                    line_no=i,
+                )
+                rb.steps_present = True
+            elif current_section in ("prereq", "glossary"):
+                if _is_known_prereq_subsection(title):
+                    current_section = "prereq"
+                elif re.search(r"glossar|\bterms\b|definitions", title, re.I):
+                    current_section = "glossary"
+                    rb.section_order.append(("glossary", title, i))
+                    section_texts.setdefault("glossary", [])
+                elif current_section == "prereq":
+                    # A named service routing block.
+                    current_service = ServiceSpec(name=title, line_no=i)
+            # record raw text under the current top-level section
+            if current_section:
+                section_texts.setdefault(current_section, []).append(line)
+            continue
+
+        if current_step is not None:
+            fm = FIELD_RE.match(line)
+            if fm:
+                fname = fm.group(1).lower().replace(" ", "_")
+                current_field = fname
+                setattr(current_step, fname, fm.group(2).strip())
+                continue
+            if current_field and line.strip():
+                # continuation of the current field
+                prev = getattr(current_step, current_field)
+                setattr(current_step, current_field, (prev + " " + line.strip()).strip())
+                continue
+            continue
+
+        if current_service is not None:
+            current_service.body += line + "\n"
+            continue
+
+        if current_section:
+            section_texts.setdefault(current_section, []).append(line)
+
+    flush_step()
+    flush_service()
+
+    rb.prereq_text = "\n".join(section_texts.get("prereq", []))
+    rb.prereq_present = any(k == "prereq" for k, _, _ in rb.section_order)
+    rb.validation_text = "\n".join(section_texts.get("validation", []))
+    rb.validation_present = any(k == "validation" for k, _, _ in rb.section_order)
+    rb.glossary_text = "\n".join(section_texts.get("glossary", []))
+    rb.glossary_present = any(k == "glossary" for k, _, _ in rb.section_order)
+    return rb