govrail 0.1.0__tar.gz

govrail-0.1.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: govrail
+Version: 0.1.0
+Summary: A language-agnostic governance plane for agent-driven development: gates and notes, delivered by the gov CLI.
+Author: govrail
+License: MIT
+Keywords: agent,governance,gates,notes,development
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# govrail
+
+English | [中文](README.zh.md)
+
+A language-agnostic governance plane for agent-driven development: coding
+agents work fast in parallel while machines — not vigilance — hold the quality
+line. The only runtime dependency is Python 3.
+
+The plane ships two mechanisms: **gates** (any promise a command can check
+becomes a mechanical check) and **notes** (every non-trivial change records the
+decision, what it beat, and the consequences). Bilingual pairing keeps the
+external-presentation docs in sync.
+
+## Install
+
+```sh
+pip install .            # or: uv tool install . / pipx install .
+```
+
+This puts the `gov` CLI on your PATH (stdlib only — no third-party
+dependencies). It has one subcommand per action:
+
+```sh
+gov init --project <path>     # inject the plane into an existing project
+gov uninstall --project <path>  # reverse it exactly
+gov run --mode all            # run the project's gate DAG
+gov self-test                 # prove every governance gate can reject
+gov verify-pairing --write    # re-confirm a bilingual pair after editing one side
+gov change-scope --base <ref> # smallest sufficient check set for a diff
+```
+
+`init` is non-invasive and idempotent: it creates `.gov/rules.md`, adds
+`gates.json` and the notes README only when missing, appends one reference line
+to AGENTS.md, and never overwrites the project's own files. `uninstall` reverses
+it exactly.
+
+## What is inside
+
+- `gov/` — the Python package: `gates` (the DAG runner over `gates.json`),
+  `verify_notes` (three required sections), `verify_translation_pairing`
+  (git blob hashes), `change_scope`, `self_test`, `archive_notes`.
+- `gov/templates/` — the rules, default `gates.json`, and notes format that
+  `gov init` injects into a project.
+- `.gov/rules.md` — the single source of truth for the rules.
+- `.agents/notes/` — the decision-record format and lifecycle.
+
+## Origin
+
+The mechanisms are distilled from the DeepSeek Harness repository, whose
+gates-over-prose axiom shaped this template. Kept: the governance plane. Left to
+you: the product plane. The locked design decisions live in
+[docs/decisions.md](docs/decisions.md).

govrail-0.1.0/README.md

@@ -0,0 +1,52 @@
+# govrail
+
+English | [中文](README.zh.md)
+
+A language-agnostic governance plane for agent-driven development: coding
+agents work fast in parallel while machines — not vigilance — hold the quality
+line. The only runtime dependency is Python 3.
+
+The plane ships two mechanisms: **gates** (any promise a command can check
+becomes a mechanical check) and **notes** (every non-trivial change records the
+decision, what it beat, and the consequences). Bilingual pairing keeps the
+external-presentation docs in sync.
+
+## Install
+
+```sh
+pip install .            # or: uv tool install . / pipx install .
+```
+
+This puts the `gov` CLI on your PATH (stdlib only — no third-party
+dependencies). It has one subcommand per action:
+
+```sh
+gov init --project <path>     # inject the plane into an existing project
+gov uninstall --project <path>  # reverse it exactly
+gov run --mode all            # run the project's gate DAG
+gov self-test                 # prove every governance gate can reject
+gov verify-pairing --write    # re-confirm a bilingual pair after editing one side
+gov change-scope --base <ref> # smallest sufficient check set for a diff
+```
+
+`init` is non-invasive and idempotent: it creates `.gov/rules.md`, adds
+`gates.json` and the notes README only when missing, appends one reference line
+to AGENTS.md, and never overwrites the project's own files. `uninstall` reverses
+it exactly.
+
+## What is inside
+
+- `gov/` — the Python package: `gates` (the DAG runner over `gates.json`),
+  `verify_notes` (three required sections), `verify_translation_pairing`
+  (git blob hashes), `change_scope`, `self_test`, `archive_notes`.
+- `gov/templates/` — the rules, default `gates.json`, and notes format that
+  `gov init` injects into a project.
+- `.gov/rules.md` — the single source of truth for the rules.
+- `.agents/notes/` — the decision-record format and lifecycle.
+
+## Origin
+
+The mechanisms are distilled from the DeepSeek Harness repository, whose
+gates-over-prose axiom shaped this template. Kept: the governance plane. Left to
+you: the product plane. The locked design decisions live in
+[docs/decisions.md](docs/decisions.md).

govrail-0.1.0/gov/__init__.py

@@ -0,0 +1,7 @@
+"""govrail — a language-agnostic governance plane for agent-driven development.
+
+The plane ships two mechanisms: gates (mechanical checks) and notes (decision
+records), delivered by the ``gov`` CLI. The only runtime dependency is Python 3.
+"""
+
+__version__ = "0.1.0"

govrail-0.1.0/gov/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

govrail-0.1.0/gov/archive_notes.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+"""Seal the archived-notes manifest: recompute sha256 for every archived note.
+
+Archived notes are frozen (D5); the manifest pins each file's content hash so
+any later edit is detectable. Run this after moving a note into ``archived/``.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+ARCHIVED = Path(".agents/notes/archived")
+
+
+def main() -> int:
+    files: dict[str, dict[str, str]] = {}
+    for p in sorted(ARCHIVED.rglob("*.md")):
+        rel = str(p.relative_to(ARCHIVED))
+        files[rel] = {"sha256": hashlib.sha256(p.read_bytes()).hexdigest()}
+    (ARCHIVED / "manifest.json").write_text(
+        json.dumps({"files": files}, indent=2) + "\n", encoding="utf-8"
+    )
+    print(f"archive_notes: sealed {len(files)} file(s)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

govrail-0.1.0/gov/change_scope.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Report what a change touches, and suggest the smallest gate set.
+
+This is the "check only what changed" hint (rule 9). It does not run gates;
+it maps the touched surfaces to the gates that cover them so a developer
+picks the smallest sufficient set instead of reflexively running everything.
+"""
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+
+SURFACE_GATES = {
+    "governance": ["self-test"],
+    "notes": ["notes"],
+    "docs": ["pairing", "links"],
+    "config": ["self-test"],
+}
+
+
+def _classify(path: str) -> str:
+    if path.startswith(".agents/notes/"):
+        return "notes"
+    if path.endswith(".md"):
+        return "docs"
+    if path in ("gates.json",) or path.startswith(("gates.py", "verify_", "self_test", "gov.py", "change_scope")):
+        return "governance"
+    return "code"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Report touched surfaces since a base ref.")
+    parser.add_argument("--base", default="HEAD~1", help="git ref to diff against")
+    args = parser.parse_args(argv)
+    try:
+        proc = subprocess.run(
+            ["git", "diff", "--name-only", args.base],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+    except subprocess.CalledProcessError as e:
+        print(f"change_scope: git diff failed: {e.stderr.strip()}", file=sys.stderr)
+        return 2
+    files = [f for f in proc.stdout.splitlines() if f]
+    if not files:
+        print(f"change_scope: no changes since {args.base}")
+        return 0
+
+    surfaces = sorted({_classify(f) for f in files})
+    gates = sorted({g for s in surfaces for g in SURFACE_GATES.get(s, [])})
+    print(f"touched surfaces: {', '.join(surfaces)}")
+    for s in surfaces:
+        changed = [f for f in files if _classify(f) == s]
+        print(f"  {s}: {len(changed)} file(s)")
+    print(f"suggested gates: {', '.join(gates) or 'code gates (project toolchain)'}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

govrail-0.1.0/gov/cli.py

@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+"""gov — install, uninstall, run, and self-test the governance plane.
+
+Subcommands delegate to the modules in this package; ``init`` injects the
+templates shipped as package data, and ``uninstall`` reverses it exactly via
+the ``.gov/manifest.json`` it wrote.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import sys
+from importlib.resources import files
+from pathlib import Path
+
+from . import archive_notes, change_scope, gates, self_test
+from . import verify_notes, verify_translation_pairing
+from . import __version__
+
+TEMPLATES = files("gov.templates")
+REFERENCE_MARKER = "<!-- gov:rules -->"
+REFERENCE_LINE = (
+    f"{REFERENCE_MARKER} Read .gov/rules.md and follow it before starting work."
+)
+
+
+def _copy(source, dest: Path) -> None:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    with source.open("rb") as f:
+        dest.write_bytes(f.read())
+
+
+def _remove_empty_dirs(root: Path) -> None:
+    """Remove empty parent dirs, deepest first, stopping at the first non-empty."""
+    p = root
+    while p != p.parent:
+        try:
+            p.rmdir()
+        except OSError:
+            break
+        p = p.parent
+
+
+def init(project: Path) -> int:
+    project = project.resolve()
+    if not project.is_dir():
+        print(f"init: {project} is not a directory", file=sys.stderr)
+        return 2
+    if (project / ".gov" / "manifest.json").exists():
+        print(f"init: {project} is already initialized")
+        return 0
+
+    gov_dir = project / ".gov"
+    created: list[str] = []
+
+    _copy(TEMPLATES.joinpath("rules.md"), gov_dir / "rules.md")
+
+    if not (project / "gates.json").exists():
+        _copy(TEMPLATES.joinpath("gates.json"), project / "gates.json")
+        created.append("gates.json")
+
+    notes_readme = project / ".agents" / "notes" / "README.md"
+    if not notes_readme.exists():
+        _copy(TEMPLATES.joinpath("notes-README.md"), notes_readme)
+        created.append(".agents/notes/README.md")
+
+    ag = project / "AGENTS.md"
+    if ag.exists():
+        text = ag.read_text(encoding="utf-8")
+        if REFERENCE_MARKER not in text:
+            if text and not text.endswith("\n"):
+                text += "\n"
+            ag.write_text(text + REFERENCE_LINE + "\n", encoding="utf-8")
+    else:
+        ag.write_text(REFERENCE_LINE + "\n", encoding="utf-8")
+
+    (gov_dir / "manifest.json").write_text(
+        json.dumps({"version": "0.1.0", "created": created}, indent=2) + "\n",
+        encoding="utf-8",
+    )
+
+    print(f"init: initialized {project}")
+    print("  .gov/rules.md (rules)")
+    if created:
+        print("  " + ", ".join(created) + " (created; project had none)")
+    print("  AGENTS.md reference line")
+    return 0
+
+
+def uninstall(project: Path) -> int:
+    project = project.resolve()
+    manifest = project / ".gov" / "manifest.json"
+    if not manifest.exists():
+        print(f"uninstall: {project} is not initialized", file=sys.stderr)
+        return 2
+    try:
+        data = json.loads(manifest.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as e:
+        print(f"uninstall: corrupt manifest {manifest}: {e}", file=sys.stderr)
+        return 2
+
+    ag = project / "AGENTS.md"
+    if ag.exists():
+        kept = [line for line in ag.read_text(encoding="utf-8").splitlines()
+                if REFERENCE_MARKER not in line]
+        while kept and kept[-1] == "":
+            kept.pop()
+        if kept:
+            ag.write_text("\n".join(kept) + "\n", encoding="utf-8")
+        else:
+            ag.unlink()
+
+    for rel in data.get("created", []):
+        p = project / rel
+        if p.exists():
+            p.unlink()
+            _remove_empty_dirs(p.parent)
+
+    shutil.rmtree(project / ".gov", ignore_errors=True)
+    print(f"uninstall: removed governance from {project}")
+    return 0
+
+
+_COMMANDS = {
+    "init": "inject the plane into a project",
+    "uninstall": "reverse init",
+    "run": "run the project's gate DAG (args forwarded to gates.py)",
+    "self-test": "run governance rejection cases",
+    "verify-notes": "check note format",
+    "verify-pairing": "check bilingual pairing (e.g. --write)",
+    "change-scope": "report touched surfaces (e.g. --base <ref>)",
+    "archive-notes": "seal the archived-notes manifest",
+}
+
+
+def _usage() -> None:
+    print("usage: gov <command> [args]", file=sys.stderr)
+    print("commands:", file=sys.stderr)
+    for name, help_text in _COMMANDS.items():
+        print(f"  {name:<16} {help_text}", file=sys.stderr)
+
+
+_HELP_FLAGS = ("-h", "--help", "help")
+_VERSION_FLAGS = ("-v", "--version", "version")
+# Commands whose args are NOT forwarded to an argparse parser: they must
+# intercept help/version themselves so a trailing flag never runs the action.
+_NO_FORWARD = ("init", "uninstall", "self-test", "verify-notes", "archive-notes")
+
+
+def _init_uninstall_args(args: list[str], what: str) -> Path | None:
+    """Parse the only supported flag ``--project <dir>``; reject the rest."""
+    project = "."
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a == "--project":
+            if i + 1 >= len(args):
+                print(f"gov {what}: --project requires a directory", file=sys.stderr)
+                return None
+            project = args[i + 1]
+            i += 2
+        else:
+            print(f"gov {what}: unexpected argument '{a}'", file=sys.stderr)
+            _usage()
+            return None
+    return Path(project)
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv:
+        _usage()
+        return 2
+    cmd, rest = argv[0], argv[1:]
+
+    if cmd in _HELP_FLAGS:
+        _usage()
+        return 0
+    if cmd in _VERSION_FLAGS:
+        print(f"gov {__version__}")
+        return 0
+    # Subcommand-level help/version: never execute the action as a side effect.
+    if cmd in _NO_FORWARD:
+        if any(a in _HELP_FLAGS for a in rest):
+            _usage()
+            return 0
+        if any(a in _VERSION_FLAGS for a in rest):
+            print(f"gov {__version__}")
+            return 0
+    if cmd == "init":
+        project = _init_uninstall_args(rest, "init")
+        return 2 if project is None else init(project)
+    if cmd == "uninstall":
+        project = _init_uninstall_args(rest, "uninstall")
+        return 2 if project is None else uninstall(project)
+    if cmd == "run":
+        return gates.main(rest)
+    if cmd == "self-test":
+        return self_test.main()
+    if cmd == "verify-notes":
+        return verify_notes.main()
+    if cmd == "verify-pairing":
+        return verify_translation_pairing.main(rest)
+    if cmd == "change-scope":
+        return change_scope.main(rest)
+    if cmd == "archive-notes":
+        return archive_notes.main()
+    print(f"gov: unknown command '{cmd}'", file=sys.stderr)
+    _usage()
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())