@hap-labs/human-agent-paradigm 0.1.0 → 0.2.1

package/README.zh-CN.md

@@ -1,52 +0,0 @@
-# hap-governance
-
-人机协作范式（HAP）的 **治理内容包**：六份冻结治理文档与其结构自检工具， 作为独立 npm 包发布，使内容（按人批准节奏演进）与工具（按工程节奏演进）解耦发布。
-
-[English](README.md) | **简体中文**
-
-## 内容
-
-| 路径                                    | 用途                                                                                                                                                                                                                                                    |
-|:----------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `assets/ZH_CN/`                         | 六份治理文档（简体中文原文）：`HUMAN_AGENT_PARADIGM.md`（宪法 v1.0）、`DERIVED_SPECIFICATION.md`（派生规范 v1.0）、`CONFORMANCE_CHECKLIST.md`（符合性清单 v1.0）、`CONTRACT_TEMPLATE.md`、`DECISION_REQUEST_TEMPLATE.md`、`DELIVERY_REPORT_TEMPLATE.md` |
-| `assets/EN/`                            | 同一六份的官方英文译本                                                                                                                                                                                                                                  |
-| `scripts/python/repo_governance_check/` | 文档组结构自检（仅 Python 标准库；自动探测 `assets/ZH_CN` 等）                                                                                                                                                                                          |
-
-## 用法
-
-消费方把 `assets/` 语言目录复制进各自工作区的治理根。独立使用：
-
-```bash
-python3 -m scripts.python.repo_governance_check --root . --out-dir reports
-```
-
-## 版本策略
-
-| 内容版本                   | 包版本             | 触发         |
-|:---------------------------|:-------------------|:-------------|
-| 宪法 v1.0                  | 1.0.0（基线）      | 首发         |
-| 宪法修订（主版本）         | major 递增         | 宪法新版本   |
-| 派生规范 / 清单 / 模板修订 | minor / patch 递增 | 派生家族编辑 |
-
-宪法版本为准，包版本随动。任何内容修订都须在 HAP 流程中经所有者明确批准
-（宪法 §0.4、派生规范 §0.4）。自检工具的工具性改动不改变治理内容。
-
-## 发布
-
-版本经 GitHub Actions（[.github/workflows/publish.yml](.github/workflows/publish.yml)）发布到 npm：推送与 `package.json` 版本一致的 `v*` tag 会触发构建 + `npm publish`；也可用 `workflow_dispatch` 手动触发。
-
-工作流使用 npm **Trusted Publishing（OIDC）**——发布时以 GitHub Actions 的 OIDC token 认证，**本仓库无需存储任何 npm token/密钥**；公开仓库发布时 provenance 自动生成。
-
-首次发布成功前，需在 npmjs.com 完成一次性 Trusted Publisher 配置（包 Settings → Trusted publishing → GitHub Actions）：
-
-- Organization or user：`hap-labs`
-- Repository：`human-agent-paradigm-governance`
-- Workflow filename：`publish.yml`
-- Allowed actions：`npm publish`
-
-首次发布成功后，可进一步加固（包 Settings → Publishing access → 「Require two-factor authentication and disallow tokens」），并吊销不再使用的自动化 token。
-
-## 治理
-
-本仓库受自身内容（HAP 宪法）治理。修订通过 HAP run + 所有者签署完成；
-发布是所有者授权动作。

package/scripts/python/repo_governance_check/__init__.py

@@ -1,3 +0,0 @@
-"""repo_governance_check package."""
-
-__version__ = "1.0.0"

package/scripts/python/repo_governance_check/__main__.py

@@ -1,6 +0,0 @@
-"""Allow ``python -m repo_governance_check``."""
-
-from .cli import main
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/scripts/python/repo_governance_check/checks.py

@@ -1,359 +0,0 @@
-"""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

@@ -1,115 +0,0 @@
-"""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

@@ -1,33 +0,0 @@
-"""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