dos-kernel 0.22.0__py3-none-win_amd64.whl

dos/gh4_coverage.py

@@ -0,0 +1,179 @@
+"""GH4 commit-coverage predicates — pure ship-stamp / claim-footprint matching.
+
+Lifted from the job userland's ``scripts/fanout_state.py`` (MQ3X P1, docs/62).
+These three predicates answer two distrust questions the GH4 post-commit
+auto-stamp asks before believing "this commit shipped (plan, phase)":
+
+  * ``claim_covered``          — does any committed path fall inside the claim's
+                                 declared footprint? (explicit glob / explicit
+                                 files / fanout-archive bundle / plan-doc edit)
+  * ``coverage_is_plandoc_only`` — was the claim covered ONLY by a plan-doc edit
+                                 (branch 3b) and none of the stronger footprints?
+                                 The surface of the CRS3 false-stamp (2026-06-02):
+                                 a sibling phase's ship edits the SHARED plan doc
+                                 and would auto-stamp a phase whose deliverable
+                                 was never touched → the picker drops a live phase
+                                 → the lane wedges.
+  * ``subject_matches_stamp``  — does the commit SUBJECT look like the expected
+                                 ship-stamp for this plan?
+
+This module is a ``dos`` Layer-1 leaf in the ``scope`` / ``sibling_scan`` mold:
+**pure** ``(entry, committed_paths, subject)`` → ``bool``, zero fs / git / clock /
+config. All I/O — running ``git show --name-only``, resolving the plan-doc path,
+reading ``STATE_PATH`` — happens in the CALLER (the job adapter's
+``_gh4_scan_claims_after_commit``), which gathers the evidence then calls these.
+That is what lets the whole predicate family be replay-tested on frozen fixtures.
+
+Two impure GH4 siblings (``subject_is_prelaunch_staging_only``,
+``plandoc_only_lacks_deliverable``) deliberately stay job-side: they transitively
+reach ``STATE_PATH`` via ``_gh4_claim_plan_files → _resolve_phase_plan_files →
+_resolve_plan_doc_path`` (the boundary litmus in docs/62 §0). Only these three
+leaf-pure predicates lift.
+
+Function names drop the ``_gh4_`` prefix (the module namespace carries it); the
+job shim re-exports them under their old ``_gh4_*`` names so every existing
+caller resolves unchanged.
+"""
+from __future__ import annotations
+
+import fnmatch
+import re
+
+# A ``dispatched_by: fanout-<TS>`` tag — the claim was dispatched by a fanout run
+# whose archive bundle lives under ``docs/_fanout_runs/<TS>/``.
+FANOUT_TS_RE = re.compile(r"^fanout-(\d{8}T\d{6}Z)$", re.IGNORECASE)
+
+# Commit-subject shapes accepted as a generic ship-stamp (matched against the
+# SUBJECT line only). Permissive on purpose — a false-positive auto-transition is
+# safer than over-routing to the warn queue (a mistaken transition surfaces as a
+# stamp-drift row on the next pre-screen; over-routing buries real signal under
+# noise). The plan-token check is tightened with the actual plan id at match time.
+STAMP_PATTERNS_GENERIC = (
+    re.compile(r"^chore\(working-tree\)", re.IGNORECASE),
+    re.compile(r"^docs/fanout:", re.IGNORECASE),
+    re.compile(r"^docs/dispatch:", re.IGNORECASE),
+    re.compile(r"^docs/_fanout_runs", re.IGNORECASE),
+)
+
+
+def claim_covered(entry: dict, committed: list[str],
+                  plan_doc_path: str | None) -> bool:
+    """Return True iff any committed path is inside the claim's footprint.
+
+    Resolution order:
+      1. Explicit ``path_glob`` on the entry (str): fnmatch any committed path.
+      2. Explicit ``files`` on the entry (list[str]): exact match or prefix match
+         (treat a trailing ``/`` as a directory prefix).
+      3. Fallback (the common case — schema rows today carry NEITHER):
+         a) ``dispatched_by: fanout-<TS>`` AND any committed path is under
+            ``docs/_fanout_runs/<TS>/`` (archive-bundled ship).
+         b) ``plan_doc_path`` resolves and any committed path equals it (a
+            plan-doc edit covering this plan).
+    """
+    if not committed:
+        return False
+    norm_committed = [p.replace("\\", "/") for p in committed if p]
+
+    # 1) explicit path_glob
+    glob = entry.get("path_glob")
+    if isinstance(glob, str) and glob.strip():
+        pat = glob.strip().replace("\\", "/")
+        for p in norm_committed:
+            if fnmatch.fnmatch(p, pat):
+                return True
+
+    # 2) explicit files
+    files = entry.get("files")
+    if isinstance(files, list) and files:
+        explicit = {str(f).replace("\\", "/") for f in files if f}
+        for p in norm_committed:
+            if p in explicit:
+                return True
+            for f in explicit:
+                if f.endswith("/") and p.startswith(f):
+                    return True
+
+    # 3a) fanout-archive bundled commit
+    by = (entry.get("dispatched_by") or "").strip()
+    m = FANOUT_TS_RE.match(by)
+    if m:
+        ts = m.group(1)
+        prefix = f"docs/_fanout_runs/{ts}/"
+        for p in norm_committed:
+            if p.startswith(prefix):
+                return True
+
+    # 3b) plan-doc covered
+    if plan_doc_path:
+        pdp = plan_doc_path.replace("\\", "/")
+        for p in norm_committed:
+            if p == pdp:
+                return True
+
+    return False
+
+
+def coverage_is_plandoc_only(
+    entry: dict, committed: list[str], plan_doc_path: str | None,
+) -> bool:
+    """True iff ``claim_covered`` would pass ONLY via branch 3b (a plan-doc edit)
+    — i.e. the commit touched the plan doc but matched NONE of the stronger
+    footprints (explicit ``path_glob`` / explicit ``files`` / fanout-archive
+    bundle 3a).
+
+    This is the surface of the CRS3 false-stamp (2026-06-02): a real ship commit
+    (``CRS2: …``) edits the SHARED plan doc that holds both CRS2 and CRS3 meta, so
+    3b covers the CRS3 claim even though no CRS3 deliverable was touched; combined
+    with the permissive subject token-match (``\\bCRS3\\b`` in the body) it
+    auto-stamps CRS3 shipped → ship_oracle reads registry→SHIPPED → the picker
+    drops a phase whose deliverable does not exist → every dispatch on that lane
+    WEDGEs. Caller uses this to demand a *deliverable* overlap before stamping such
+    a coverage. Best-effort; pure.
+    """
+    if not committed or not plan_doc_path:
+        return False
+    norm = [p.replace("\\", "/") for p in committed if p]
+    pdp = plan_doc_path.replace("\\", "/")
+    if pdp not in norm:
+        return False  # not covered via 3b at all
+    # Stronger footprints — if ANY of these match, coverage is NOT plan-doc-only.
+    glob = entry.get("path_glob")
+    if isinstance(glob, str) and glob.strip():
+        pat = glob.strip().replace("\\", "/")
+        if any(fnmatch.fnmatch(p, pat) for p in norm):
+            return False
+    files = entry.get("files")
+    if isinstance(files, list) and files:
+        explicit = {str(f).replace("\\", "/") for f in files if f}
+        for p in norm:
+            if p in explicit or any(
+                    f.endswith("/") and p.startswith(f) for f in explicit):
+                return False
+    by = (entry.get("dispatched_by") or "").strip()
+    m = FANOUT_TS_RE.match(by)
+    if m and any(p.startswith(f"docs/_fanout_runs/{m.group(1)}/") for p in norm):
+        return False
+    # Covered, and the ONLY thing that covered it was the plan-doc edit.
+    return True
+
+
+def subject_matches_stamp(subject: str, plan: str) -> bool:
+    """Return True iff the commit ``subject`` looks like the expected ship-stamp
+    for a claim against ``plan``. Permissive — see ``STAMP_PATTERNS_GENERIC``."""
+    if not subject:
+        return False
+    s = subject.strip().splitlines()[0] if subject else ""
+    plan_lc = (plan or "").strip().lower()
+    if plan_lc:
+        # `<plan>:` / `docs/<plan>:` / `<plan>/` / `docs/<plan>-plan` etc.
+        if re.match(rf"^(?:docs/)?{re.escape(plan_lc)}(?:-plan)?[:/]", s,
+                    re.IGNORECASE):
+            return True
+        # Plan id may appear anywhere in the subject as a token (e.g.
+        # `docs/git-hygiene: GH4 — ...` for a GH4 claim).
+        if re.search(rf"\b{re.escape(plan_lc)}\d*\b", s, re.IGNORECASE):
+            return True
+    for pat in STAMP_PATTERNS_GENERIC:
+        if pat.match(s):
+            return True
+    return False

dos/git_delta.py

@@ -0,0 +1,122 @@
+"""git-delta — the "commits since a start SHA" evidence, one shared reader.
+
+`git log <start-sha>..HEAD` is the authoritative *forward-progress delta* for a
+run: how many commits landed on the served workspace since the run began. Two
+callers need exactly this fold and must not drift from each other:
+
+  * `dos.timeline` — Stage 6 of the dispatch handoff view ("N commits since
+    start").
+  * `dos.liveness` (via the `dos liveness` CLI's evidence-gather) — the git rung
+    of the temporal verdict: ≥1 commit since start is the `ADVANCING` floor
+    (docs/82, LVN Phase 1b).
+
+This module is the single home for that read so LVN does not re-implement
+`timeline`'s git rung (the LVN-1b directive). It is **boundary I/O**, not a pure
+verdict: like `pick_oracle`'s gather and `verify`'s git reads, the subprocess
+happens HERE, at the caller boundary, and the already-counted delta is handed to
+the pure classifier. `dos.liveness.classify` itself never calls this — it takes
+`commits_since_start: int` as already-gathered evidence (the arbiter discipline).
+
+The repo root is passed in EXPLICITLY (never read from the process-global active
+config), so a long-lived caller fielding several workspaces — the MCP server, a
+fleet daemon — gets the right tree without mutating global state. Every failure
+mode (no SHA, non-git dir, git missing, timeout, non-zero exit) degrades to an
+empty list: a liveness verdict in a repo with no git history is `0 commits`, the
+honest floor, never a crash (the no-plan / fail-safe discipline).
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+# Cap the git call so a pathological repo can't hang an evidence-gather. Matches
+# the 10s bound `timeline._git_log` has always used.
+_GIT_TIMEOUT_S = 10
+
+
+def commits_since(start_sha: str, *, root: Path | str) -> list[dict[str, str]]:
+    """`git log <start_sha>..HEAD` over ``root``, as ``[{sha, subject}, …]``.
+
+    Newest-first (git's default order). Returns ``[]`` for any of: an empty
+    ``start_sha`` (a run with no recorded start commit), a non-git ``root``, a
+    missing ``git`` binary, a timeout, or a non-zero git exit (e.g. an unknown
+    SHA). The empty list is the safe degrade — a caller reads it as "no forward
+    delta observed," never as an error to propagate.
+    """
+    if not start_sha:
+        return []
+    try:
+        raw = subprocess.run(
+            ["git", "log", f"{start_sha}..HEAD", "--pretty=format:%h%x09%s"],
+            cwd=str(root),
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=_GIT_TIMEOUT_S,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return []
+    if raw.returncode != 0:
+        return []
+    out: list[dict[str, str]] = []
+    for line in raw.stdout.splitlines():
+        if not line.strip():
+            continue
+        parts = line.split("\t", 1)
+        if len(parts) != 2:
+            continue
+        out.append({"sha": parts[0], "subject": parts[1]})
+    return out
+
+
+def count_commits_since(start_sha: str, *, root: Path | str) -> int:
+    """Just the count — the single number `dos.liveness`'s git rung needs.
+
+    A thin fold over `commits_since` so the LVN evidence-gather reads one int
+    without materialising the subject list it does not use.
+    """
+    return len(commits_since(start_sha, root=root))
+
+
+def recent_commits(n: int = 10, *, root: Path | str) -> list[dict[str, str]]:
+    """The last ``n`` commits on ``root``, newest-first, as ``[{sha, subject}, …]``.
+
+    The *unanchored* sibling of `commits_since`: where that answers "what landed
+    since a run's start SHA," this answers "what has landed lately, period" — the
+    one git read `dos top` needs to show real movement in a repo with **no
+    leases and no plan at all** (a freshly-`dos init`'d checkout). Kept here so
+    the kernel's git-evidence reads stay in one home rather than `dispatch_top`
+    spawning its own subprocess.
+
+    Same fail-safe contract as `commits_since`: returns ``[]`` for a non-positive
+    ``n``, a non-git ``root``, a missing ``git`` binary, a timeout, or a non-zero
+    git exit (e.g. a repo with zero commits — `git log` exits non-zero on an
+    unborn HEAD). The empty list is the honest floor — "no history observed,"
+    never an error to propagate. ``root`` is explicit (never the process-global
+    active config), the long-lived-caller discipline `commits_since` set.
+    """
+    if n <= 0:
+        return []
+    try:
+        raw = subprocess.run(
+            ["git", "log", f"-{int(n)}", "--pretty=format:%h%x09%s"],
+            cwd=str(root),
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=_GIT_TIMEOUT_S,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return []
+    if raw.returncode != 0:
+        return []
+    out: list[dict[str, str]] = []
+    for line in raw.stdout.splitlines():
+        if not line.strip():
+            continue
+        parts = line.split("\t", 1)
+        if len(parts) != 2:
+            continue
+        out.append({"sha": parts[0], "subject": parts[1]})
+    return out

dos/guard.py

@@ -0,0 +1,215 @@
+"""dos.guard — the headless-launch wrapper (the argv shim, docs/134 §4).
+
+`dos guard [opts] -- <host-cmd> [host-args]` frames a non-interactive agent
+launch (`claude -p …`, or any host taking the same flags) with the DOS wiring,
+then execs the host command. It injects two things the host already honors:
+
+  * ``--mcp-config '<json>'`` — mounts the DOS MCP server (``dos-mcp``) so the
+    agent *can* call ``dos_verify`` / ``dos_arbitrate`` mid-run. (Works today —
+    ``dos-mcp`` is a shipped console script.)
+  * ``--settings '<json>'`` — carries a ``Stop`` hook (the verify-on-stop
+    binding, docs/134 §2) and/or an ``--append-system-prompt`` instruction.
+    This is the ONLY way to add a hook to a headless run — there is no
+    ``--hooks`` flag (verified against ``claude --help``).
+
+The split is the whole contract: everything after ``--`` is the host command,
+passed through byte-for-byte. DOS computes the two injected flags and appends
+them; an unrecognized host flag is the host's problem, not ours (degrade to
+passthrough). This module is a **layer-3 helper** — it names no host internals
+beyond the two public flags, takes no lease, and computes a plan a test can
+assert without ever launching a subprocess.
+
+Design discipline (mirrors the kernel's "pure core, I/O at the boundary"):
+``build_guard_plan`` is PURE — options in, a ``GuardPlan`` (the injected JSON +
+the final argv) out, no environment read, no process spawned. The CLI verb does
+the one impure thing (``os.execvp`` / ``subprocess``) over the plan the pure
+function returned, and ``--print-config`` dumps the plan without launching.
+
+This is a CONSUMER surface, the MCP server's sibling: it *frames* a host launch,
+it does not get inside the host. The advisory-only boundary (docs/99) is intact —
+nothing here forces a process; the dev typed ``dos guard``, and the host is what
+honors the flags.
+"""
+
+from __future__ import annotations
+
+import json
+import shlex
+from dataclasses import dataclass, field
+
+
+# The console script that serves the DOS syscalls as MCP tools (pyproject
+# [project.scripts]). The wrapper points the host's --mcp-config at it by name;
+# resolution is the host's PATH lookup, same as any MCP stdio server.
+DEFAULT_MCP_COMMAND = "dos-mcp"
+
+# The default Stop-hook command — the docs/134 §2 verify-on-stop binding, now
+# SHIPPED (`cmd_hook_stop`). The hook stays OPT-IN (`--verify-on-stop`), never
+# injected by default, because it changes the launch's stop behavior — that is a
+# decision the dev makes explicitly, not a silent default. (The MCP mount, which
+# only ADDS a callable tool, is the safe default.)
+DEFAULT_STOP_HOOK_COMMAND = "dos hook stop --workspace ."
+
+# The one instruction that makes the docs/134 §2.1 explicit-marker rung reliable:
+# the agent declares what to verify in a form the claim extractor lifts exactly.
+DEFAULT_CLAIM_PROMPT = (
+    "When you complete a unit of work, end your turn with a line of the form "
+    "`DOS-CLAIM: <plan> <phase>` naming the plan and phase you claim shipped, so "
+    "it can be verified against git."
+)
+
+
+@dataclass(frozen=True)
+class GuardPlan:
+    """The pure result of framing a launch: what to inject and the final argv.
+
+    ``argv`` is the complete command to exec (host command + appended DOS flags).
+    ``mcp_config`` / ``settings`` are the JSON objects injected (kept separately
+    so ``--print-config`` can show them legibly and tests can assert on them).
+    ``notes`` carries any honesty caveats surfaced to the user (e.g. the Stop
+    hook targeting a not-yet-built verb).
+    """
+
+    argv: list[str]
+    mcp_config: dict | None
+    settings: dict | None
+    host_command: list[str]
+    notes: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "argv": self.argv,
+            "mcp_config": self.mcp_config,
+            "settings": self.settings,
+            "host_command": self.host_command,
+            "notes": self.notes,
+        }
+
+
+def build_settings(
+    *,
+    verify_on_stop: bool,
+    stop_hook_command: str = DEFAULT_STOP_HOOK_COMMAND,
+    append_prompt: str | None = None,
+) -> dict | None:
+    """Build the ``--settings`` JSON object, or None if nothing to inject.
+
+    Pure. The Stop hook is only present when ``verify_on_stop`` is True — see the
+    DEFAULT_STOP_HOOK_COMMAND note on why it is opt-in.
+    """
+    settings: dict = {}
+    if verify_on_stop:
+        # The host's settings.json hook shape (verified): an event → a list of
+        # matcher-groups, each carrying a list of {type, command} hooks.
+        settings["hooks"] = {
+            "Stop": [
+                {"hooks": [{"type": "command", "command": stop_hook_command}]}
+            ]
+        }
+    if append_prompt:
+        # Carried in settings too — the host merges an appendSystemPrompt setting
+        # the same way the CLI --append-system-prompt flag does. (We pass it via
+        # settings rather than a second flag so the whole injection is two flags
+        # max, and so --print-config shows one legible object.)
+        settings["appendSystemPrompt"] = append_prompt
+    return settings or None
+
+
+def build_mcp_config(
+    *, mount_mcp: bool, mcp_command: str = DEFAULT_MCP_COMMAND
+) -> dict | None:
+    """Build the ``--mcp-config`` JSON object, or None if not mounting.
+
+    Pure. The DOS server is mounted under the key ``dos`` so the agent's tools
+    are ``mcp__dos__verify`` etc.
+    """
+    if not mount_mcp:
+        return None
+    return {"mcpServers": {"dos": {"command": mcp_command}}}
+
+
+def build_guard_plan(
+    host_command: list[str],
+    *,
+    mount_mcp: bool = True,
+    verify_on_stop: bool = False,
+    add_claim_prompt: bool = False,
+    strict_mcp: bool = False,
+    stop_hook_command: str = DEFAULT_STOP_HOOK_COMMAND,
+    mcp_command: str = DEFAULT_MCP_COMMAND,
+) -> GuardPlan:
+    """Frame a host launch with the DOS wiring. PURE — no I/O, no subprocess.
+
+    Returns the complete ``argv`` to exec plus the injected objects. Raises
+    ``ValueError`` only on an empty host command (the one contract error).
+    """
+    # argparse.REMAINDER keeps a literal leading `--` separator in the captured
+    # list; strip one so callers may pass the host command with or without it.
+    if host_command and host_command[0] == "--":
+        host_command = host_command[1:]
+
+    if not host_command:
+        raise ValueError(
+            "dos guard needs a host command after `--` "
+            "(e.g. `dos guard -- claude -p \"...\"`)."
+        )
+
+    notes: list[str] = []
+
+    append_prompt = DEFAULT_CLAIM_PROMPT if add_claim_prompt else None
+    mcp_config = build_mcp_config(mount_mcp=mount_mcp, mcp_command=mcp_command)
+    settings = build_settings(
+        verify_on_stop=verify_on_stop,
+        stop_hook_command=stop_hook_command,
+        append_prompt=append_prompt,
+    )
+
+    # Build the final argv: host command, then the appended DOS flags. We append
+    # (never prepend) so the host's own flags parse first and ours are additive —
+    # and so a host that doesn't recognize a flag fails on OUR flag, legibly,
+    # rather than mangling the user's command.
+    argv = list(host_command)
+    if mcp_config is not None:
+        argv += ["--mcp-config", json.dumps(mcp_config, sort_keys=True)]
+        if strict_mcp:
+            # Only use the servers we injected — the CI-honest form (verified flag).
+            argv += ["--strict-mcp-config"]
+    if settings is not None:
+        argv += ["--settings", json.dumps(settings, sort_keys=True)]
+
+    return GuardPlan(
+        argv=argv,
+        mcp_config=mcp_config,
+        settings=settings,
+        host_command=list(host_command),
+        notes=notes,
+    )
+
+
+def render_plan_human(plan: GuardPlan) -> str:
+    """A legible multi-line dump of what `dos guard` would inject and run."""
+    lines: list[str] = []
+    lines.append("dos guard — launch plan")
+    lines.append("")
+    lines.append("host command (passed through verbatim):")
+    lines.append("  " + " ".join(shlex.quote(a) for a in plan.host_command))
+    lines.append("")
+    if plan.mcp_config is not None:
+        lines.append("injected --mcp-config:")
+        lines.append("  " + json.dumps(plan.mcp_config, sort_keys=True))
+    else:
+        lines.append("injected --mcp-config: (none — MCP mount disabled)")
+    if plan.settings is not None:
+        lines.append("injected --settings:")
+        lines.append("  " + json.dumps(plan.settings, sort_keys=True))
+    else:
+        lines.append("injected --settings: (none)")
+    lines.append("")
+    lines.append("final argv to exec:")
+    lines.append("  " + " ".join(shlex.quote(a) for a in plan.argv))
+    if plan.notes:
+        lines.append("")
+        lines.append("notes:")
+        for n in plan.notes:
+            lines.append("  ! " + n)
+    return "\n".join(lines)