@hap-labs/human-agent-paradigm 0.1.0

package/scripts/python/repo_governance_check/checks.py

@@ -0,0 +1,359 @@
+"""G01-G08 governance checks.
+
+Every rule receives a CheckContext and returns a list of Finding objects.
+Rules never modify files and only read files declared in the config.
+"""
+
+from dataclasses import dataclass
+import re
+from pathlib import Path
+
+
+ITEM_RE = re.compile(r"^\|\s*([A-Z]\d+)\s*(★)?\s*\|")
+SEPARATOR_CELL_RE = re.compile(r"^:?-{1,}:?$")
+
+
+@dataclass(frozen=True)
+class Finding:
+    rule_id: str
+    severity: str
+    file: str
+    line: int
+    message: str
+    evidence: str
+
+    def to_dict(self):
+        return {
+            "rule_id": self.rule_id,
+            "severity": self.severity,
+            "file": self.file,
+            "line": self.line,
+            "message": self.message,
+            "evidence": self.evidence,
+        }
+
+
+def _upper_name(filename):
+    """Language directories store documents under uppercase underscore names;
+    consumer copies keep the canonical lowercase names."""
+    stem, dot, ext = filename.rpartition(".")
+    return stem.replace("-", "_").upper() + dot + ext
+
+
+class CheckContext:
+    def __init__(self, root, config, docs_dir=None):
+        self.root = Path(root)
+        self.config = config
+        self.docs_dir = Path(docs_dir) if docs_dir else self.root
+
+    def doc_file(self, filename):
+        """First existing document path under docs_dir (canonical or
+        uppercase-underscore form); falls back to the canonical path."""
+        direct = self.docs_dir / filename
+        if direct.is_file():
+            return direct
+        upper = self.docs_dir / _upper_name(filename)
+        return upper if upper.is_file() else direct
+
+
+def _read_lines(ctx, filename):
+    try:
+        return ctx.doc_file(filename).read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return None
+
+
+def _headings(lines):
+    for number, raw in enumerate(lines, 1):
+        stripped = raw.strip()
+        if stripped.startswith("#"):
+            yield number, stripped.lstrip("#").strip()
+
+
+def _finding(ctx, rule_id, filename, line, message, evidence):
+    return Finding(rule_id, "error", filename, line, message, evidence)
+
+
+def _table_blocks(lines):
+    blocks = []
+    current = []
+    for number, raw in enumerate(lines, 1):
+        if raw.strip().startswith("|"):
+            current.append((number, raw.strip()))
+        elif current:
+            blocks.append(current)
+            current = []
+    if current:
+        blocks.append(current)
+    return blocks
+
+
+def _cell_count(row):
+    return max(row.count("|") - 1, 0)
+
+
+def _is_separator(row):
+    cells = [cell.strip() for cell in row.strip("|").split("|")]
+    if not cells:
+        return False
+    return all(SEPARATOR_CELL_RE.fullmatch(cell) for cell in cells)
+
+
+def check_required_files(ctx):
+    findings = []
+    for filename in ctx.config["required_files"]:
+        checked = ctx.doc_file(filename)
+        if not checked.is_file():
+            findings.append(
+                _finding(
+                    ctx,
+                    "G01",
+                    filename,
+                    0,
+                    f"required file is missing: {filename}",
+                    f"checked path: {checked}",
+                )
+            )
+    return findings
+
+
+def check_upstream_references(ctx):
+    findings = []
+    for filename, expected in ctx.config["upstream_references"].items():
+        lines = _read_lines(ctx, filename)
+        if lines is None:
+            continue
+        content = "\n".join(lines)
+        for ref in expected:
+            if ref not in content:
+                findings.append(
+                    _finding(
+                        ctx,
+                        "G02",
+                        filename,
+                        0,
+                        f"missing upstream reference: {ref!r}",
+                        "full-file substring check",
+                    )
+                )
+    return findings
+
+
+def check_required_headings(ctx):
+    findings = []
+    for filename, expected in ctx.config["required_headings"].items():
+        lines = _read_lines(ctx, filename)
+        if lines is None:
+            continue
+        present = {heading for _, heading in _headings(lines)}
+        for heading in expected:
+            if heading not in present:
+                findings.append(
+                    _finding(
+                        ctx,
+                        "G03",
+                        filename,
+                        0,
+                        f"missing required heading: {heading}",
+                        "heading text parsed from markdown heading lines",
+                    )
+                )
+    return findings
+
+
+def check_markdown_tables(ctx):
+    findings = []
+    for filename in ctx.config["required_files"]:
+        lines = _read_lines(ctx, filename)
+        if lines is None:
+            continue
+        for block in _table_blocks(lines):
+            first_line, _ = block[0]
+            if len(block) < 2 or not _is_separator(block[1][1]):
+                findings.append(
+                    _finding(
+                        ctx,
+                        "G04",
+                        filename,
+                        first_line,
+                        "table has no valid separator row as its second row",
+                        f"table starts at line {first_line}",
+                    )
+                )
+                continue
+            expected_columns = _cell_count(block[1][1])
+            for line_number, row in block:
+                if _cell_count(row) != expected_columns:
+                    findings.append(
+                        _finding(
+                            ctx,
+                            "G04",
+                            filename,
+                            line_number,
+                            "table row column count differs from separator row",
+                            f"expected {expected_columns} columns, row has {_cell_count(row)}",
+                        )
+                    )
+    return findings
+
+
+def _checklist_missing_sections(ctx, headings):
+    findings = []
+    checklist_config = ctx.config["checklist"]
+    for section in checklist_config["sections"]:
+        if section not in headings:
+            findings.append(
+                _finding(
+                    ctx,
+                    "G05",
+                    "conformance_checklist.md",
+                    0,
+                    f"missing checklist section heading: {section}",
+                    "heading inventory",
+                )
+            )
+    final_section = checklist_config["final_section"]
+    if final_section not in headings:
+        findings.append(
+            _finding(
+                ctx,
+                "G05",
+                "conformance_checklist.md",
+                0,
+                f"missing final section heading: {final_section}",
+                "heading inventory",
+            )
+        )
+    return findings
+
+
+def _checklist_row_metrics(lines):
+    item_count = 0
+    star_count = 0
+    bad_star_rows = []
+    item_ids = []
+    for line_number, raw in enumerate(lines, 1):
+        match = ITEM_RE.match(raw.strip())
+        if not match:
+            continue
+        item_count += 1
+        item_ids.append(match.group(1))
+        if match.group(2):
+            star_count += 1
+            cells = [cell.strip() for cell in raw.strip().strip("|").split("|")]
+            if cells and cells[-1] == "不适用":
+                bad_star_rows.append(line_number)
+    return item_count, star_count, bad_star_rows, item_ids
+
+
+def check_checklist_invariants(ctx):
+    lines = _read_lines(ctx, "conformance_checklist.md")
+    if lines is None:
+        return []
+    headings = {heading for _, heading in _headings(lines)}
+    findings = _checklist_missing_sections(ctx, headings)
+    item_count, star_count, bad_star_rows, item_ids = _checklist_row_metrics(lines)
+    checklist_config = ctx.config["checklist"]
+    prefix_map = checklist_config.get("item_prefixes", {})
+    for section in checklist_config["sections"]:
+        prefix = prefix_map.get(section, section.split(".")[0])
+        if not any(item_id.startswith(prefix) for item_id in item_ids):
+            findings.append(
+                _finding(
+                    ctx,
+                    "G05",
+                    "conformance_checklist.md",
+                    0,
+                    f"checklist section has no item rows: {section}",
+                    f"no item ID starts with prefix {prefix!r}",
+                )
+            )
+    expected_items = checklist_config["expected_items"]
+    if item_count != expected_items:
+        findings.append(
+            _finding(
+                ctx,
+                "G05",
+                "conformance_checklist.md",
+                0,
+                f"checklist item count is {item_count}, expected {expected_items}",
+                "item rows matching the A-Z numbering pattern",
+            )
+        )
+    expected_stars = checklist_config["expected_star_items"]
+    if star_count != expected_stars:
+        findings.append(
+            _finding(
+                ctx,
+                "G05",
+                "conformance_checklist.md",
+                0,
+                f"star item count is {star_count}, expected {expected_stars}",
+                "item rows containing the star marker",
+            )
+        )
+    for line_number in bad_star_rows:
+        findings.append(
+            _finding(
+                ctx,
+                "G05",
+                "conformance_checklist.md",
+                line_number,
+                "star item result column must not contain 不适用",
+                "star item rows may not be exempted in the checklist source",
+            )
+        )
+    return findings
+
+
+def _check_sections(ctx, rule_id, filename, config_key):
+    lines = _read_lines(ctx, filename)
+    if lines is None:
+        return []
+    present = {heading for _, heading in _headings(lines)}
+    findings = []
+    for section in ctx.config[config_key]["required_sections"]:
+        if section not in present:
+            findings.append(
+                _finding(
+                    ctx,
+                    rule_id,
+                    filename,
+                    0,
+                    f"missing required section: {section}",
+                    "heading inventory",
+                )
+            )
+    return findings
+
+
+def check_contract_template_sections(ctx):
+    return _check_sections(ctx, "G06", "contract_template.md", "contract_template")
+
+
+def check_decision_template_sections(ctx):
+    return _check_sections(ctx, "G07", "decision_request_template.md", "decision_request_template")
+
+
+def check_delivery_template_sections(ctx):
+    return _check_sections(ctx, "G08", "delivery_report_template.md", "delivery_report_template")
+
+
+ALL_RULES = (
+    check_required_files,
+    check_upstream_references,
+    check_required_headings,
+    check_markdown_tables,
+    check_checklist_invariants,
+    check_contract_template_sections,
+    check_decision_template_sections,
+    check_delivery_template_sections,
+)
+
+
+def run_all_checks(ctx):
+    findings = []
+    for rule in ALL_RULES:
+        findings.extend(rule(ctx))
+    findings.sort(key=lambda item: (item.file, item.line, item.rule_id))
+    return findings

package/scripts/python/repo_governance_check/cli.py

@@ -0,0 +1,115 @@
+"""Command line entry point for repo_governance_check."""
+
+import argparse
+from datetime import datetime, timezone
+from pathlib import Path
+import time
+
+from .checks import CheckContext, _upper_name, run_all_checks
+from .config import load_config
+from .report import render_console, render_json, render_markdown, result_payload
+
+
+def find_config(root):
+    """Locate the check config: explicit root copy first, then the bundled
+    default that ships next to this package."""
+    candidates = [
+        root / "governance_check_config.json",
+        Path(__file__).resolve().parent / "governance_check_config.json",
+    ]
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def detect_docs_dir(root, config):
+    """Pick the directory holding the governance document set.
+
+    Candidates mirror the repository layouts: the root itself, the package's
+    per-language assets directories (ZH_CN holds the frozen Chinese
+    originals, EN the English translations), the project docs directory, and
+    a consumer workspace's .hap/docs/ directory. Falls back to the root so an
+    explicit --config against arbitrary directories keeps the historical
+    semantics (missing files surface as G01 findings).
+    """
+    candidates = [
+        root,
+        root / "assets" / "ZH_CN",
+        root / "assets" / "EN",
+        root / "assets",
+        root / "vendor" / "governance-snapshot" / "ZH_CN",
+        root / "vendor" / "governance-snapshot" / "EN",
+        root / "vendor" / "governance-snapshot",
+        root / "docs",
+        root / ".hap" / "docs",
+    ]
+
+    def _doc_exists(candidate, name):
+        return (candidate / name).is_file() or (candidate / _upper_name(name)).is_file()
+
+    for candidate in candidates:
+        if all(_doc_exists(candidate, name) for name in config["required_files"]):
+            return candidate
+    return root
+
+
+def parse_args(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="repo_governance_check",
+        description="Check governance documents for structural consistency.",
+    )
+    parser.add_argument("--root", default=".", help="repository root to check")
+    parser.add_argument(
+        "--config",
+        default=None,
+        help="path to governance_check_config.json (default: ROOT or the bundled package copy)",
+    )
+    parser.add_argument(
+        "--out-dir",
+        default="reports",
+        help="directory for generated reports (default: ROOT/reports)",
+    )
+    parser.add_argument(
+        "--format",
+        choices=("json", "markdown", "both"),
+        default="both",
+        help="report format to write",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv=None):
+    args = parse_args(argv)
+    root = Path(args.root).resolve()
+    if args.config:
+        config_path = Path(args.config).resolve()
+    else:
+        config_path = find_config(root)
+        if config_path is None:
+            raise SystemExit(
+                "no governance_check_config.json found under --root "
+                "or next to the package; pass --config explicitly"
+            )
+    out_dir = Path(args.out_dir)
+    if not out_dir.is_absolute():
+        out_dir = root / out_dir
+    config = load_config(config_path)
+    docs_dir = detect_docs_dir(root, config)
+    context = CheckContext(root, config, docs_dir)
+    started = time.perf_counter()
+    findings = run_all_checks(context)
+    elapsed = time.perf_counter() - started
+    run_id = datetime.now(timezone.utc).strftime("RGC-%Y%m%d-%H%M%S")
+    payload = result_payload(run_id, root, config_path, docs_dir, elapsed, findings)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    if args.format in ("json", "both"):
+        (out_dir / "repo_governance_check_report.json").write_text(
+            render_json(payload), encoding="utf-8"
+        )
+    if args.format in ("markdown", "both"):
+        (out_dir / "repo_governance_check_report.md").write_text(
+            render_markdown(payload), encoding="utf-8"
+        )
+    print(render_console(payload))
+    return 1 if payload["summary"]["total_findings"] else 0

package/scripts/python/repo_governance_check/config.py

@@ -0,0 +1,33 @@
+"""Load and validate governance check configuration."""
+
+import json
+from pathlib import Path
+
+
+REQUIRED_KEYS = (
+    "required_files",
+    "upstream_references",
+    "required_headings",
+    "checklist",
+    "contract_template",
+    "decision_request_template",
+    "delivery_report_template",
+)
+
+
+def load_config(path):
+    """Read a JSON config file and return the decoded object.
+
+    The function only performs structural validation. Rule-specific values
+    are consumed by the checks module.
+    """
+    config_path = Path(path)
+    config = json.loads(config_path.read_text(encoding="utf-8"))
+    missing = [key for key in REQUIRED_KEYS if key not in config]
+    if missing:
+        raise ValueError(f"config missing keys: {', '.join(missing)}")
+    if not isinstance(config["required_files"], list):
+        raise ValueError("config 'required_files' must be a list")
+    if not isinstance(config["required_headings"], dict):
+        raise ValueError("config 'required_headings' must be a dict")
+    return config

package/scripts/python/repo_governance_check/governance_check_config.json

@@ -0,0 +1,166 @@
+{
+  "version": 1,
+  "required_files": [
+    "human_agent_paradigm.md",
+    "derived_specification.md",
+    "conformance_checklist.md",
+    "contract_template.md",
+    "decision_request_template.md",
+    "delivery_report_template.md"
+  ],
+  "upstream_references": {
+    "derived_specification.md": [
+      "版本：v1.0",
+      "上级文件：`HUMAN_AGENT_PARADIGM.md` v1.0"
+    ],
+    "conformance_checklist.md": [
+      "版本：v1.0",
+      "配套文件：`DERIVED_SPECIFICATION.md` v1.0"
+    ],
+    "contract_template.md": [
+      "派生规范 `DERIVED_SPECIFICATION.md` v1.0"
+    ],
+    "decision_request_template.md": [
+      "派生规范 `DERIVED_SPECIFICATION.md` v1.0"
+    ],
+    "delivery_report_template.md": [
+      "派生规范 `DERIVED_SPECIFICATION.md` v1.0"
+    ]
+  },
+  "required_headings": {
+    "human_agent_paradigm.md": [
+      "0. 文件地位与效力",
+      "1. 愿景与成功定义",
+      "2. 根本信条（公理）",
+      "3. 两条硬性要求",
+      "4. 角色与行为边界",
+      "5. 协作流程（方向级）",
+      "6. 卓越性方向（优秀的五个维度）",
+      "7. 经济性方向（最低总成本）",
+      "8. 资产与演进（复利飞轮）",
+      "9. 范式的自我治理",
+      "10. 术语定义",
+      "11. 范式级验收判据"
+    ],
+    "derived_specification.md": [
+      "0. 地位、追溯与解释",
+      "1. 通用交付物与记录要求",
+      "2. 契约规范",
+      "3. 协作流程规范（P0–P7）",
+      "4. 决策与沟通规范",
+      "5. 可靠性与证据规范",
+      "6. 优秀与多视角审视规范",
+      "7. 经济性与自治预算规范",
+      "8. 资产与演进规范",
+      "9. 符合性治理",
+      "附录 A：追溯总表",
+      "附录 B：最低记录清单",
+      "修订记录"
+    ],
+    "conformance_checklist.md": [
+      "使用说明",
+      "A. 规范地位与适用性",
+      "B. 可靠（硬性要求一）",
+      "C. 优秀（硬性要求二）",
+      "D. 边界与决策",
+      "E. 流程与契约",
+      "F. 经济性与自治",
+      "G. 资产与演进",
+      "H. 安全与合规底线",
+      "I. 治理与证据",
+      "J. 范式级验收判据（宪法 11）",
+      "最终判定",
+      "修订记录"
+    ],
+    "contract_template.md": [
+      "使用规则",
+      "契约元信息"
+    ],
+    "decision_request_template.md": [
+      "使用规则"
+    ],
+    "delivery_report_template.md": [
+      "使用规则"
+    ]
+  },
+  "checklist": {
+    "expected_items": 89,
+    "expected_star_items": 41,
+    "item_prefixes": {
+      "A. 规范地位与适用性": "A",
+      "B. 可靠（硬性要求一）": "R",
+      "C. 优秀（硬性要求二）": "E",
+      "D. 边界与决策": "D",
+      "E. 流程与契约": "P",
+      "F. 经济性与自治": "C",
+      "G. 资产与演进": "K",
+      "H. 安全与合规底线": "S",
+      "I. 治理与证据": "G",
+      "J. 范式级验收判据（宪法 11）": "J"
+    },
+    "sections": [
+      "A. 规范地位与适用性",
+      "B. 可靠（硬性要求一）",
+      "C. 优秀（硬性要求二）",
+      "D. 边界与决策",
+      "E. 流程与契约",
+      "F. 经济性与自治",
+      "G. 资产与演进",
+      "H. 安全与合规底线",
+      "I. 治理与证据",
+      "J. 范式级验收判据（宪法 11）"
+    ],
+    "final_section": "最终判定"
+  },
+  "contract_template": {
+    "required_sections": [
+      "C1 背景与意图",
+      "C2 范围与非目标",
+      "C3 约束与底线",
+      "C4 可靠标准",
+      "C5 优秀标准（五个维度，逐条可判定）",
+      "C6 多视角审视要求",
+      "C7 自治预算",
+      "C8 交付物与证据清单",
+      "C9 验收方式",
+      "C10 变更、终止与失败处置"
+    ]
+  },
+  "decision_request_template": {
+    "required_sections": [
+      "Part A 决策请求",
+      "A0 元信息",
+      "A1 必要性测试（必填，不通过则不得发送）",
+      "A2 背景摘要",
+      "A3 实质选项",
+      "A4 推荐与理由",
+      "A5 默认选择与逾期处置",
+      "A6 决策影响",
+      "A7 响应窗口",
+      "A8 人的决定与留痕",
+      "Part B 必要信息补全请求（仅限 P0/P1）",
+      "B0 前置校验（不通过则不得发送）",
+      "B1 请求内容",
+      "B2 人的答复与留痕",
+      "发送前自检"
+    ]
+  },
+  "delivery_report_template": {
+    "required_sections": [
+      "1. 元信息",
+      "2. 交付单元清单",
+      "3. 契约对照总表",
+      "4. 可靠证据",
+      "5. 优秀证据（五个维度逐项）",
+      "6. 多视角审视与缺陷",
+      "7. 符合性自检结果",
+      "8. 资产沉淀",
+      "9. 成本台账摘要",
+      "10. 安全与合规",
+      "11. 已知边界与未完成说明",
+      "12. 验收建议（仅自查结论）",
+      "13. 签署与验收",
+      "附：追溯矩阵"
+    ]
+  }
+}