diff --git a/AGENTS.md b/AGENTS.md index 90d60ec0..716cefef 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,6 +12,7 @@ Do not wait for permissions/approvals. Path A or Path B OK for ALIGNED restore - Prefer portable artifacts under `portable/` when this environment cannot push to `main`. - Keep scientific effect **NONE**: never promote, close, or discharge claims, premises, prizes, or lemmas. - After meaningful work: commit, push `cursor/*` branches, land on trial `main` when PR create is 403. +- `idle_no_commit` is terminal. Run `python3 scripts/idle_no_commit.py` before an automation pulse. Exit 0 means source identity and capabilities are unchanged and no substantive defect is present: report that result and return before tracked-file writes. Leave batch headers, `REFRESH_BATCH_TAG` defaults, last-resort fallbacks, `VERIFY.refresh_batch`, schedules, and the release content-hash detector as they are. - Owner land scripts (`owner_land_path_*.sh`) are technical fallback for GitHub App 403 only — not approval gates. - Blocked or need a second pair of hands? Drop a card in [`needs_attention/cards/`](needs_attention/README.md) (schema `needs_attention/v1`; `python3 scripts/needs_attention_check.py`). Helpers cycle that folder with `scripts/needs_attention_scan.py`. Before fixing a repo-wide problem, check the open cards — four agents shipped the same tip-drift fix in parallel (NA-0007). @@ -22,6 +23,12 @@ Do not wait for permissions/approvals. Path A or Path B OK for ALIGNED restore - Enable or claim GitHub scheduled workflows on `main` solely to satisfy R2-06 prose. - Ask Dylan for approval in docs. +## Operations lanes + +- Public-facing **storefront / exhibit / intake** work belongs in `main`: `main/docs/site` (public face) and `main/incoming` (intake). Do not build it here. +- `trial` is the **internal load-test / workbench lane**: probes, smoke checks, portable engineering artifacts, wake/idle automation. It is **not** a public shop and **not** a status register. +- Do not open new trial `Batch NNN` PRs to implement storefront or intake features; route that work to `main`. + ## Start here 1. `README.md` diff --git a/scripts/idle_no_commit.py b/scripts/idle_no_commit.py new file mode 100644 index 00000000..24b4094d --- /dev/null +++ b/scripts/idle_no_commit.py @@ -0,0 +1,280 @@ +#!/usr/bin/env python3 +"""Terminal gate for an automation pulse that has nothing to commit. + +Call this before any tracked-file write. When release-critical source identity +and recorded capabilities are unchanged and no substantive defect is present, +the process prints ``action=idle_no_commit`` and exits 0. The caller returns +immediately. Pulse-only stamps are not source identity and are not a reason to +write: + +- ``print_owner_unblock.sh`` batch header and history echoes +- ``REFRESH_BATCH_TAG`` default in ``refresh_path_c_bundle.sh`` +- last-resort ``return "N"`` fallbacks in the inventory and wake helpers +- ``VERIFY.refresh_batch`` and ``VERIFY.generated_at_utc`` + +A real source change, a capability change, or an explicit substantive defect +exits 1 so the repair can proceed. This gate does not write tracked files, +does not alter schedules, and does not change the release content-hash +detector (that detector still compares raw critical-script bytes). + +Scientific effect: NONE. Never flips lemma_closed. +""" +from __future__ import annotations + +import argparse +import hashlib +import json +import re +import subprocess +import sys +from pathlib import Path +from typing import Mapping + +ROOT = Path(__file__).resolve().parents[1] + +# Files whose pulse stamps were rewritten by idle batches and then flagged +# script_stale by the raw content-hash detector. +SOURCE_FILES = ( + "scripts/refresh_path_c_bundle.sh", + "scripts/refresh_ai_agent_access_inventory.py", + "scripts/post_batch322_wake_comments.py", + "scripts/print_owner_unblock.sh", + "portable/path-c-applied-bundle/VERIFY.json", + "portable/patches/BASE_TIP.txt", +) +INVENTORY = "portable/AI_AGENT_ACCESS_INVENTORY.json" + +_PULSE_COMMENT = re.compile( + r"(?m)^[ \t]*# Batch \d+: last-resort bumped[^\n]*\n?" +) +_FALLBACK_RETURN = re.compile(r'(?m)^[ \t]*return "\d+"\s*$') +_REFRESH_DEFAULT = re.compile(r"REFRESH_BATCH_TAG:-\d+") +_HEADER = re.compile(r"=== Batch \d+") +_ECHO_PULSE = re.compile(r'(?m)^echo " +Batch \d+:[^\n]*\n?') +_VERIFY_REFRESH = re.compile(r'("refresh_batch"\s*:\s*)\d+') +_VERIFY_GENERATED = re.compile( + r'("generated_at_utc"\s*:\s*")[^"]*(")' +) + +_NON_DEFECTS = { + "", + "none", + "no defect", + "no_defect", + "hunt negative", + "hunt_negative", + "idle", + "idle_no_commit", +} + + +def normalize_source(rel: str, text: str) -> str: + """Drop pulse stamps so identity is the remaining source.""" + name = Path(rel).name + if name == "refresh_path_c_bundle.sh": + return _REFRESH_DEFAULT.sub("REFRESH_BATCH_TAG:-0", text) + if name in { + "refresh_ai_agent_access_inventory.py", + "post_batch322_wake_comments.py", + }: + text = _PULSE_COMMENT.sub("", text) + matches = list(_FALLBACK_RETURN.finditer(text)) + if matches: + last = matches[-1] + text = text[: last.start()] + 'return "0"' + text[last.end() :] + return text + if name == "print_owner_unblock.sh": + text = _HEADER.sub("=== Batch 0", text, count=1) + text = _ECHO_PULSE.sub("", text) + return text.rstrip() + "\n" + if name == "VERIFY.json": + text = _VERIFY_REFRESH.sub(r"\g<1>0", text) + return _VERIFY_GENERATED.sub(r"\g<1>0\2", text) + return text + + +def source_identity(files: Mapping[str, str]) -> str: + digest = hashlib.sha256() + for rel in sorted(files): + digest.update(rel.encode()) + digest.update(b"\0") + digest.update(normalize_source(rel, files[rel]).encode()) + digest.update(b"\0") + return digest.hexdigest() + + +def substantive_defect(value: str | None) -> str | None: + if value is None: + return None + text = value.strip() + if text.lower() in _NON_DEFECTS: + return None + return text + + +def capability_fingerprint(inventory: Mapping[str, object]) -> dict: + """Permissions and coverage. Pulse timestamps, batch, and tip shas are omitted.""" + details = [] + raw_details = inventory.get("details") or [] + if isinstance(raw_details, list): + for row in raw_details: + if not isinstance(row, dict): + continue + details.append( + { + "name": row.get("name"), + "push": row.get("push"), + "admin": row.get("admin"), + "write": row.get("write"), + "has_agents": row.get("has_agents"), + "default_branch": row.get("default_branch"), + } + ) + details.sort(key=lambda row: str(row.get("name") or "")) + sandbox = inventory.get("sandbox") + sandbox = sandbox if isinstance(sandbox, dict) else {} + return { + "durable_sibling_coverage": inventory.get("durable_sibling_coverage"), + "durable_writable": inventory.get("durable_writable"), + "main_writable": inventory.get("main_writable"), + "sibling_write_count": inventory.get("sibling_write_count"), + "sandbox": { + "readable": sandbox.get("readable"), + "write": sandbox.get("write"), + "has_agents": sandbox.get("has_agents"), + }, + "details": details, + } + + +def _fingerprint_sha(fingerprint: Mapping[str, object]) -> str: + payload = json.dumps(fingerprint, sort_keys=True, separators=(",", ":")) + return hashlib.sha256(payload.encode()).hexdigest() + + +def decide( + *, + current_files: Mapping[str, str], + baseline_files: Mapping[str, str], + current_inventory: Mapping[str, object], + baseline_inventory: Mapping[str, object], + defect: str | None = None, +) -> dict: + """Return the pulse decision. This function does not write files.""" + missing = sorted( + rel + for rel in SOURCE_FILES + if rel not in current_files or rel not in baseline_files + ) + # Identity is compared on the shared source set. A missing baseline or + # current file is a real difference. + identity_keys = [rel for rel in SOURCE_FILES if rel in current_files or rel in baseline_files] + current_src = {rel: current_files.get(rel, "") for rel in identity_keys} + baseline_src = {rel: baseline_files.get(rel, "") for rel in identity_keys} + present = all(rel in current_files and rel in baseline_files for rel in SOURCE_FILES) + identity_unchanged = present and source_identity(current_src) == source_identity( + baseline_src + ) + current_cap = capability_fingerprint(current_inventory) + baseline_cap = capability_fingerprint(baseline_inventory) + capabilities_unchanged = current_cap == baseline_cap + defect_text = substantive_defect(defect) + reasons: list[str] = [] + if not identity_unchanged: + reasons.append("source_identity") + if not capabilities_unchanged: + reasons.append("capabilities") + if defect_text: + reasons.append("defect") + idle = not reasons + if idle: + action = "idle_no_commit" + elif defect_text and identity_unchanged and capabilities_unchanged: + action = "substantive_defect" + elif not identity_unchanged and capabilities_unchanged and not defect_text: + action = "substantive_source_change" + elif identity_unchanged and not capabilities_unchanged and not defect_text: + action = "substantive_capability_change" + else: + action = "substantive_work" + return { + "action": action, + "write_tracked_files": not idle, + "source_identity_unchanged": identity_unchanged, + "capabilities_unchanged": capabilities_unchanged, + "substantive_defect": defect_text, + "reasons": reasons, + "source_identity": source_identity(current_src), + "capability_fingerprint": _fingerprint_sha(current_cap), + "lemma_closed": False, + "flipped_anything": False, + "scientific_effect": "NONE", + "missing_sources": missing, + } + + +def _git_show(root: Path, rel: str) -> str: + return subprocess.check_output( + ["git", "show", f"HEAD:{rel}"], + cwd=root, + text=True, + ) + + +def evaluate(root: Path, defect: str | None = None) -> dict: + """Compare the worktree to HEAD. Does not write tracked files.""" + current_files = { + rel: (root / rel).read_text(encoding="utf-8") for rel in SOURCE_FILES + } + baseline_files = {rel: _git_show(root, rel) for rel in SOURCE_FILES} + current_inventory = json.loads((root / INVENTORY).read_text(encoding="utf-8")) + baseline_inventory = json.loads(_git_show(root, INVENTORY)) + report = decide( + current_files=current_files, + baseline_files=baseline_files, + current_inventory=current_inventory, + baseline_inventory=baseline_inventory, + defect=defect, + ) + report["baseline"] = "HEAD" + return report + + +def _report_line(report: dict) -> str: + if report.get("action") == "idle_no_commit": + return ( + "idle_no_commit: source identity and capabilities unchanged; " + "no substantive defect; return before tracked-file writes" + ) + reasons = ",".join(report.get("reasons") or []) or "unspecified" + return f"{report.get('action')}: {reasons}; tracked-file writes allowed" + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument( + "--root", + type=Path, + default=ROOT, + help="trial checkout (default: repository root)", + ) + parser.add_argument( + "--defect", + default=None, + help="substantive defect id from the hunt; empty and hunt-negative are idle", + ) + args = parser.parse_args(argv) + try: + report = evaluate(args.root, defect=args.defect) + except (OSError, subprocess.CalledProcessError, json.JSONDecodeError) as exc: + print(f"idle_no_commit: evaluate failed: {exc}", file=sys.stderr) + return 2 + print(_report_line(report), file=sys.stderr) + print(json.dumps(report, indent=2, sort_keys=True)) + if report.get("action") == "idle_no_commit": + return 0 + return 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tests/test_idle_no_commit.py b/tests/test_idle_no_commit.py new file mode 100644 index 00000000..3dbfe0a6 --- /dev/null +++ b/tests/test_idle_no_commit.py @@ -0,0 +1,200 @@ +"""idle_no_commit returns before tracked-file writes.""" +from __future__ import annotations + +import importlib.util +import json +import subprocess +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] + + +def _load(): + path = ROOT / "scripts" / "idle_no_commit.py" + spec = importlib.util.spec_from_file_location("idle_no_commit", path) + assert spec and spec.loader + mod = importlib.util.module_from_spec(spec) + spec.loader.exec_module(mod) + return mod + + +def _pair(): + mod = _load() + files = { + rel: (ROOT / rel).read_text(encoding="utf-8") for rel in mod.SOURCE_FILES + } + inventory = json.loads((ROOT / mod.INVENTORY).read_text(encoding="utf-8")) + return mod, files, inventory + + +def test_unchanged_identity_is_terminal_idle() -> None: + mod, files, inventory = _pair() + report = mod.decide( + current_files=files, + baseline_files=files, + current_inventory=inventory, + baseline_inventory=inventory, + defect="no defect", + ) + assert report["action"] == "idle_no_commit" + assert report["write_tracked_files"] is False + assert report["lemma_closed"] is False + assert report["scientific_effect"] == "NONE" + assert report["reasons"] == [] + + +def test_pulse_stamps_are_not_source_identity() -> None: + import re + + mod, files, inventory = _pair() + current = dict(files) + refresh = current["scripts/refresh_path_c_bundle.sh"] + tag = re.search(r"REFRESH_BATCH_TAG:-(\d+)", refresh) + assert tag is not None + nxt = str(int(tag.group(1)) + 1) + current["scripts/refresh_path_c_bundle.sh"] = refresh.replace( + f"REFRESH_BATCH_TAG:-{tag.group(1)}", + f"REFRESH_BATCH_TAG:-{nxt}", + 1, + ) + for rel in ( + "scripts/refresh_ai_agent_access_inventory.py", + "scripts/post_batch322_wake_comments.py", + ): + text = current[rel] + found = re.search(r'return "(\d+)"', text) + assert found is not None + current[rel] = text.replace( + f'return "{found.group(1)}"', + f'return "{int(found.group(1)) + 1}"', + 1, + ) + unblock = current["scripts/print_owner_unblock.sh"] + header = re.search(r"=== Batch (\d+)", unblock) + assert header is not None + current["scripts/print_owner_unblock.sh"] = unblock.replace( + f"=== Batch {header.group(1)}", + f"=== Batch {int(header.group(1)) + 1}", + 1, + ) + f'\necho " Batch {int(header.group(1)) + 1}: idle_no_commit pulse"\n' + verify = current["portable/path-c-applied-bundle/VERIFY.json"] + stamped = re.search(r'"refresh_batch": (\d+)', verify) + assert stamped is not None + current["portable/path-c-applied-bundle/VERIFY.json"] = verify.replace( + f'"refresh_batch": {stamped.group(1)}', + f'"refresh_batch": {int(stamped.group(1)) + 1}', + 1, + ) + report = mod.decide( + current_files=current, + baseline_files=files, + current_inventory=inventory, + baseline_inventory=inventory, + defect="hunt negative", + ) + assert report["action"] == "idle_no_commit" + assert report["write_tracked_files"] is False + assert report["source_identity_unchanged"] is True + + +def test_real_source_drift_allows_repair() -> None: + mod, files, inventory = _pair() + current = dict(files) + current["scripts/refresh_path_c_bundle.sh"] += "\n# substantive drift marker\n" + report = mod.decide( + current_files=current, + baseline_files=files, + current_inventory=inventory, + baseline_inventory=inventory, + ) + assert report["action"] == "substantive_source_change" + assert report["write_tracked_files"] is True + assert "source_identity" in report["reasons"] + + +def test_base_tip_move_is_source_identity() -> None: + mod, files, inventory = _pair() + current = dict(files) + current["portable/patches/BASE_TIP.txt"] = ( + "chatgpt/drive-github-hardening-20260919 " + "0000000000000000000000000000000000000000\n" + ) + report = mod.decide( + current_files=current, + baseline_files=files, + current_inventory=inventory, + baseline_inventory=inventory, + ) + assert report["write_tracked_files"] is True + assert report["source_identity_unchanged"] is False + + +def test_capability_change_allows_repair() -> None: + mod, files, inventory = _pair() + changed = json.loads(json.dumps(inventory)) + changed["durable_sibling_coverage"] = "0/8" + report = mod.decide( + current_files=files, + baseline_files=files, + current_inventory=changed, + baseline_inventory=inventory, + ) + assert report["action"] == "substantive_capability_change" + assert report["write_tracked_files"] is True + + +def test_explicit_defect_allows_repair() -> None: + mod, files, inventory = _pair() + report = mod.decide( + current_files=files, + baseline_files=files, + current_inventory=inventory, + baseline_inventory=inventory, + defect="living_release_missing_grant_gate", + ) + assert report["action"] == "substantive_defect" + assert report["write_tracked_files"] is True + assert report["substantive_defect"] == "living_release_missing_grant_gate" + + +def test_cli_on_head_is_idle_and_writes_nothing() -> None: + before = subprocess.check_output( + ["git", "status", "--porcelain"], cwd=ROOT, text=True + ) + proc = subprocess.run( + [sys.executable, str(ROOT / "scripts" / "idle_no_commit.py")], + cwd=ROOT, + text=True, + capture_output=True, + check=False, + ) + after = subprocess.check_output( + ["git", "status", "--porcelain"], cwd=ROOT, text=True + ) + assert before == after + assert proc.returncode == 0, proc.stderr + assert "idle_no_commit:" in proc.stderr + assert "return before tracked-file writes" in proc.stderr + report = json.loads(proc.stdout) + assert report["action"] == "idle_no_commit" + assert report["write_tracked_files"] is False + + +def test_content_hash_detector_and_schedule_remain() -> None: + republish = (ROOT / "scripts" / "republish_living_path_c_release.sh").read_text( + encoding="utf-8" + ) + assert "hashlib.sha256()" in republish + assert "if a != b:" in republish + for name in ( + "scripts/refresh_ai_agent_access_inventory.py", + "scripts/print_owner_unblock.sh", + "scripts/post_batch322_wake_comments.py", + "scripts/refresh_path_c_bundle.sh", + ): + assert name in republish + watch = (ROOT / ".github" / "workflows" / "watch-main-alignment.yml").read_text( + encoding="utf-8" + ) + assert 'cron: "0 * * * *"' in watch