Files
Jyotisha/scripts/workspace_governance_audit.py
T
ClaudeandClaude Opus 5.5 6a57faacdb feat(consult): run the astrologer's upstream skill in full (BUG-1696, BUG-1697, BUG-1698)
- root SKILL.md is her upstream file (body byte-identical to the 5fb8379c mirror; description quoted so YAML parses and Mastra can load the skill)
- chat binds the whole SKILL.md plus references/product_runtime_contract.md (safety-only) instead of a ~477-character excerpt
- every turn carries her full strict-workflow-router (synced to upstream) and the domain's event-judgment file; product lists follow as an extra layer
- import her 10 sub-skills, family router, interpretation status contract, technique ontology and the 54 files her method names
- tests/test_upstream_skill_parity.py (in the quick gate) fails whenever her skill and ours drift
- 18 frontend guards that locked the excerpt design updated with 原值/新值/原因 notes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DbBXoyn7Hj3LCW3BUs5bZ8
2026-11-07 14:02:26 +08:00

403 lines
16 KiB
Python

#!/usr/bin/env python3
"""Audit workspace hygiene, authority files, and external JH8 reference status."""
from __future__ import annotations
import argparse
import json
import subprocess
from collections import Counter
from datetime import datetime, timezone
from pathlib import Path
from typing import Any
ROOT = Path(__file__).resolve().parents[1]
DEFAULT_JH8_ROOT = Path(
"local-source-untracked/Library/Containers/com.tencent.xinWeChat/Data/Documents/"
"xwechat_files/wxid_ef1allun5xa612_cf0c/msg/file/2026-09/JH8_FULL_20260905"
)
STAMP = datetime.now().strftime("%Y_%m_%d")
JSON_OUT = ROOT / f"docs/research/workspace_governance_audit_{STAMP}.json"
MD_OUT = ROOT / f"docs/research/workspace_governance_audit_{STAMP}.md"
SELF_OUTPUTS = {
"docs/research/workspace_governance_audit_2026_09_14.json",
"docs/research/workspace_governance_audit_2026_09_14.md",
f"docs/research/workspace_governance_audit_{STAMP}.json",
f"docs/research/workspace_governance_audit_{STAMP}.md",
}
def _run(args: list[str], *, cwd: Path = ROOT, timeout: int = 30) -> tuple[int, str, str]:
try:
proc = subprocess.run(args, cwd=cwd, text=True, capture_output=True, timeout=timeout, check=False)
except FileNotFoundError:
return 127, "", f"{args[0]}: command not found"
except subprocess.TimeoutExpired as exc:
return 124, "", str(exc)
return proc.returncode, proc.stdout, proc.stderr
def _lines(text: str) -> list[str]:
return [line.rstrip() for line in text.splitlines() if line.strip()]
def _git_status() -> dict[str, Any]:
code, out, err = _run(["git", "status", "--short", "--branch"])
lines = _lines(out)
dirty = [
line
for line in lines
if not line.startswith("## ")
and line[3:] not in SELF_OUTPUTS
]
return {
"ok": code == 0,
"branch_line": lines[0] if lines else "",
"dirty_count": len(dirty),
"dirty_paths": dirty,
"stderr": err.strip(),
}
def _changed_paths() -> dict[str, Any]:
"""Group current changes for review without staging or mutating them.
Git records state and paths, not the authoring window. These groups are
therefore review batches, never ownership claims or staging approval.
"""
commands = {
"staged": ["git", "diff", "--cached", "--name-only"],
"unstaged": ["git", "diff", "--name-only"],
"untracked": ["git", "ls-files", "--others", "--exclude-standard"],
}
paths_by_state: dict[str, list[str]] = {}
for state, command in commands.items():
code, out, _ = _run(command)
paths_by_state[state] = [path for path in _lines(out) if path not in SELF_OUTPUTS] if code == 0 else []
def category(path: str) -> str:
if path.startswith("references/open_source_sources/"):
return "third_party_mirror_license_review"
if path.startswith("scripts/") or path.startswith("jyotish-app/"):
return "implementation_and_runtime_tests"
if path.startswith("tests/"):
return "regression_tests"
if path.startswith("skills/"):
return "workflow_contracts"
if path.startswith(("docs/", "references/")):
return "research_or_evidence_receipts"
return "root_or_other_review"
batches: list[dict[str, Any]] = []
for state, paths in paths_by_state.items():
grouped: dict[str, list[str]] = {}
for path in paths:
grouped.setdefault(category(path), []).append(path)
for name, members in sorted(grouped.items()):
batches.append({
"state": state,
"category": name,
"count": len(members),
"paths": sorted(members),
"approval": "review_required_no_automatic_stage",
})
return {
"schema": "jyotish.workspace_change_batches.v1",
"boundary": (
"Batches are derived from current Git state and paths only. They do not identify an author, "
"prove formula correctness, clear privacy review, or approve a commit."
),
"state_counts": {state: len(paths) for state, paths in paths_by_state.items()},
"batches": batches,
}
def _remote_head(branch: str) -> dict[str, Any]:
ref = f"refs/heads/{branch}"
code, out, err = _run(["git", "ls-remote", "git@github.com:732642856/yinduzhanxing.git", ref], timeout=45)
parts = out.strip().split()
return {
"ok": code == 0 and len(parts) >= 2,
"branch": branch,
"sha": parts[0] if parts else "",
"stderr": err.strip(),
}
def _worktrees() -> dict[str, Any]:
code, out, err = _run(["git", "worktree", "list", "--porcelain"])
records: list[dict[str, str]] = []
current: dict[str, str] = {}
for line in out.splitlines():
if not line.strip():
if current:
records.append(current)
current = {}
continue
key, _, value = line.partition(" ")
current[key] = value
if current:
records.append(current)
prunable = [row for row in records if "prunable" in row]
workbuddy = [row for row in records if "/.workbuddy/" in row.get("worktree", "")]
auxiliary = [row for row in records if row.get("worktree") != str(ROOT)]
return {
"ok": code == 0,
"count": len(records),
"auxiliary_count": len(auxiliary),
"prunable_count": len(prunable),
"workbuddy_count": len(workbuddy),
"records": records,
"stderr": err.strip(),
"boundary": ".workbuddy and auxiliary worktrees are audit context only; they are not runtime source roots.",
}
def _file_counts() -> dict[str, Any]:
tracked_code, tracked_out, _ = _run(["git", "ls-files"])
untracked_code, untracked_out, _ = _run(["git", "ls-files", "--others", "--exclude-standard"])
rg_code, rg_out, rg_err = _run(["rg", "--files"])
tracked = _lines(tracked_out) if tracked_code == 0 else []
untracked = [
path
for path in (_lines(untracked_out) if untracked_code == 0 else [])
if path not in SELF_OUTPUTS
]
if rg_code == 0:
file_inventory = _lines(rg_out)
file_inventory_source = "rg --files"
file_inventory_warning = ""
else:
# Some deployment hosts do not have ripgrep. Governance should remain
# usable and explicit rather than reporting an unexplained zero count.
file_inventory = sorted(set(tracked + untracked))
file_inventory_source = "git ls-files fallback"
file_inventory_warning = (rg_err or "rg --files failed").strip()
top = Counter(path.split("/", 1)[0] for path in tracked)
return {
"tracked_count": len(tracked),
"untracked_count": len(untracked),
"rg_file_count": len(file_inventory),
"file_inventory_source": file_inventory_source,
"file_inventory_warning": file_inventory_warning,
"tracked_top_level": dict(sorted(top.items())),
"untracked_paths": untracked[:50],
}
def _ignored_recent_summary() -> dict[str, Any]:
code, out, _ = _run(["git", "status", "--short", "--ignored=matching"])
ignored = [line[3:] for line in out.splitlines() if line.startswith("!! ")]
buckets = Counter(path.split("/", 1)[0] for path in ignored)
return {
"ok": code == 0,
"ignored_count": len(ignored),
"ignored_top_level": dict(sorted(buckets.items())),
"notable_ignored": [
path
for path in ignored
if path in {"output/", "scratch/", "tmp/", "jyotish-app/dist/", "uv.lock"}
or path.startswith("references/oracle/artifacts/")
][:40],
}
def _authority_files() -> dict[str, Any]:
paths = [
"docs/research/current_report_authority_snapshot_2026_09_14.md",
"references/oracle/current_report_authority_snapshot_2026_09_14.json",
"docs/research/report_staleness_audit_2026_09_14.md",
"references/oracle/report_staleness_audit_2026_09_14.json",
"docs/research/pl9_final_diff_matrix_2026_09_13.md",
"references/oracle/pl9_final_diff_matrix_2026_09_13.json",
]
return {
"paths": [
{
"path": path,
"exists": (ROOT / path).exists(),
"tracked": _run(["git", "ls-files", "--error-unmatch", path])[0] == 0,
}
for path in paths
]
}
def _jh8_reference(root: Path) -> dict[str, Any]:
from scripts.jh8_golden_fixture_hash_queue_producer import redact_root
display_root = redact_root(root)
if not root.exists():
return {
"available": False,
"path": display_root,
"absorbed_as": "blocked_missing_external_package",
"engine_admission_status": "blocked",
"engine_admission_reason": "JH8 package path is unavailable in this workspace.",
"copy_private_text_allowed": False,
}
files = [path for path in root.rglob("*") if path.is_file()]
rels = [path.relative_to(root).as_posix() for path in files]
tests = [path for path in rels if "/tests/" in f"/{path}" and path.endswith(".py")]
docs = [path for path in rels if path.startswith("references/project_docs/")]
core = [path for path in rels if path.startswith("core/") and path.endswith(".py")]
feature_registry = root / "references/feature_registry.json"
feature_count = None
if feature_registry.exists():
try:
data = json.loads(feature_registry.read_text(encoding="utf-8"))
if isinstance(data, dict):
features = data.get("features") or data.get("items") or data.get("rows")
feature_count = len(features) if isinstance(features, list) else len(data)
except Exception:
feature_count = None
return {
"available": True,
"path": display_root,
"file_count": len(files),
"core_python_count": len(core),
"test_count": len(tests),
"project_doc_count": len(docs),
"feature_registry_exists": feature_registry.exists(),
"feature_registry_observed_count": feature_count,
"absorbed_as": "external_product_pattern_reference_only",
"engine_admission_status": "not_admitted",
"engine_admission_reason": (
"JH8 is an external private package with useful product/governance patterns, "
"but it is not a licensed, stable, machine-replayed same-chart truth engine."
),
"engine_admission_requirements": [
"explicit permission and source/license boundary for adapter use",
"stable executable entrypoint with deterministic inputs",
"machine-readable raw output contract",
"same-chart replay against local/PyJHora/VedAstro/jyotishganit fields",
"tests that keep JH8 as black-box observation unless admission passes",
],
"copy_private_text_allowed": False,
"truth_source_allowed": False,
"signals": [
"formal_contract_gate",
"native_dasha_formula_tests",
"electional_event_surface_tests",
"transit_closed_loop_package",
"feature_registry_sync",
"source_truth_hardening",
],
}
def build(jh8_root: Path | None = None) -> dict[str, Any]:
from scripts.jh8_golden_fixture_hash_queue_producer import resolve_jh8_root
jh8_root = resolve_jh8_root(str(jh8_root) if jh8_root is not None else None)
status = _git_status()
branch = status["branch_line"].split("...", 1)[0].replace("## ", "")
payload = {
"schema": "jyotish.workspace_governance_audit.v1",
"generated_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
"root": ".", # repo-relative: the absolute root identifies the build machine
"status": "pass",
"git": {
"status": status,
"remote": _remote_head(branch),
"clean": status["dirty_count"] == 0,
},
"worktrees": _worktrees(),
"files": _file_counts(),
"change_batches": _changed_paths(),
"ignored": _ignored_recent_summary(),
"authority": _authority_files(),
"jh8_external_reference": _jh8_reference(jh8_root),
"boundaries": [
"Ignored output/scratch/dist/cache artifacts are not release source unless promoted through tracked docs/json.",
"External JH8 is used for structural product-pattern comparison only; do not copy private prose or treat it as truth oracle.",
"JH8 is not a fourth truth engine until an explicit black-box engine admission gate passes.",
"A clean main worktree does not imply auxiliary worktree branches have been merged.",
],
}
failures = []
if not payload["git"]["clean"]:
failures.append("main_worktree_dirty")
if payload["worktrees"]["prunable_count"]:
failures.append("prunable_worktree_metadata")
if not payload["git"]["remote"]["ok"]:
failures.append("remote_head_unverified")
if any(not item["exists"] or not item["tracked"] for item in payload["authority"]["paths"]):
failures.append("authority_receipt_missing_or_untracked")
payload["failures"] = failures
payload["status"] = "pass" if not failures else "review"
return payload
def render_markdown(payload: dict[str, Any]) -> str:
git = payload["git"]
worktrees = payload["worktrees"]
files = payload["files"]
jh8 = payload["jh8_external_reference"]
lines = [
"# Workspace Governance Audit",
"",
f"- Status: `{payload['status']}`",
f"- Root: `{payload['root']}`",
f"- Branch: `{git['status']['branch_line']}`",
f"- Remote SHA: `{git['remote']['sha'] or 'unverified'}`",
f"- Dirty paths: `{git['status']['dirty_count']}`",
f"- Tracked files: `{files['tracked_count']}`",
f"- Untracked files: `{files['untracked_count']}`",
f"- File inventory source: `{files.get('file_inventory_source', 'unknown')}`",
f"- Worktrees: `{worktrees['count']}` total, `{worktrees['auxiliary_count']}` auxiliary, `{worktrees['prunable_count']}` prunable",
f"- Change batches: `{len(payload['change_batches']['batches'])}` (review-only)",
f"- Ignored artifacts: `{payload['ignored']['ignored_count']}` entries",
"",
"## Authority Receipts",
"",
]
for item in payload["authority"]["paths"]:
lines.append(f"- `{item['path']}`: exists={item['exists']} tracked={item['tracked']}")
lines.extend([
"",
"## JH8 External Reference",
"",
f"- Available: `{jh8['available']}`",
f"- Path: `{jh8['path']}`",
f"- File count: `{jh8.get('file_count', 0)}`",
f"- Core Python files: `{jh8.get('core_python_count', 0)}`",
f"- Tests: `{jh8.get('test_count', 0)}`",
f"- Project docs: `{jh8.get('project_doc_count', 0)}`",
f"- Feature registry exists: `{jh8.get('feature_registry_exists', False)}`",
f"- Admission: `{jh8['absorbed_as']}`",
f"- Engine admission: `{jh8.get('engine_admission_status', 'not_admitted')}`",
f"- Copy private text allowed: `{jh8['copy_private_text_allowed']}`",
"",
"## Boundaries",
"",
])
for boundary in payload["boundaries"]:
lines.append(f"- {boundary}")
lines.extend(["", "## Current Change Batches", ""])
for batch in payload["change_batches"]["batches"]:
lines.append(f"- `{batch['state']}` / `{batch['category']}`: `{batch['count']}` files; `{batch['approval']}`")
lines.extend(["", payload["change_batches"]["boundary"]])
if payload["failures"]:
lines.extend(["", "## Review Items", ""])
for failure in payload["failures"]:
lines.append(f"- `{failure}`")
return "\n".join(lines) + "\n"
def main() -> int:
parser = argparse.ArgumentParser()
parser.add_argument("--jh8-root")
parser.add_argument("--write", action="store_true")
args = parser.parse_args()
payload = build(Path(args.jh8_root) if args.jh8_root else None)
if args.write:
JSON_OUT.parent.mkdir(parents=True, exist_ok=True)
JSON_OUT.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8", newline="\n")
MD_OUT.write_text(render_markdown(payload), encoding="utf-8", newline="\n")
print(json.dumps(payload, ensure_ascii=False, indent=2))
return 0 if payload["status"] == "pass" else 1
if __name__ == "__main__":
raise SystemExit(main())