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

package/assets/ZH_CN/TRANSLATION_GLOSSARY.md

@@ -0,0 +1,72 @@
+# 翻译术语表 — 治理术语（EN ↔ 中文）
+
+> English version: [TRANSLATION_GLOSSARY.md](../EN/TRANSLATION_GLOSSARY.md)
+
+治理层文档（`assets/` 下六份冻结文档及其官方译本、以及由它们驱动的流程记录）翻译与一致性审校的统一基准。翻译或审校任何治理材料时使用下列对应关系；新增行须说明理由，并保持表格按英文术语排序。
+
+| English                           | 中文                               | 语境/备注                                                            |
+|:----------------------------------|:-----------------------------------|:---------------------------------------------------------------------|
+| Human-Agent Paradigm (HAP)        | 人机协作范式 / 人与 Agent 协作范式 | 专有名词；产品名                                                     |
+| constitution                      | 宪法                               | 唯一权威文档：`assets/ZH_CN/HUMAN_AGENT_PARADIGM.md`                 |
+| derived specification             | 派生规范                           | `DERIVED_SPECIFICATION`                                              |
+| conformance self-check checklist  | 符合性自检清单                     | `CONFORMANCE_CHECKLIST`                                              |
+| contract                          | 契约                               | 已签署的 C1–C10 契约                                                 |
+| contract template                 | 契约模板                           | `CONTRACT_TEMPLATE`                                                  |
+| decision request                  | 决策请求                           | `DECISION_REQUEST_TEMPLATE`（Part A）                                |
+| necessary information request     | 必要信息补全请求                   | 同一模板（Part B）                                                   |
+| delivery report                   | 交付报告                           | `DELIVERY_REPORT_TEMPLATE`                                           |
+| Owner                             | 人（所有者）/ 所有者               | 也称 “the human”；不译作“owner-company”                              |
+| Agent                             | Agent                              | 全责公司；中文语境保留 “Agent”                                       |
+| decision-maker                    | 决策者                             | 人的角色                                                             |
+| mandatory file                    | 强制文件                           | P0–P7 阶段记录                                                       |
+| hard gate                         | 硬门                               | 阻止推进的机器或人工门禁                                             |
+| record                            | 记录                               | 流程产物，如 P0_intent.md                                            |
+| evidence                          | 证据                               | 可独立复核的证明                                                     |
+| evidence package                  | 证据包                             | 交付用证据集                                                         |
+| multi-view review                 | 多视角审视                         | 下述四个视角                                                         |
+| product perspective               | 产品视角                           | P6 视角词                                                            |
+| user perspective                  | 用户视角                           | P6 视角词                                                            |
+| engineering perspective           | 工程视角                           | P6 视角词                                                            |
+| adversarial review / perspective  | 对抗性（审查）视角                 | P6 视角词                                                            |
+| five excellence dimensions        | 优秀五维度                         | 6.1–6.5（见下）                                                      |
+| sound design                      | 设计合理                           | 维度 6.1                                                             |
+| complete functionality            | 功能完备                           | 维度 6.2                                                             |
+| elegant implementation            | 实现优雅                           | 维度 6.3                                                             |
+| perfect experience                | 体验完美                           | 维度 6.4                                                             |
+| excellent performance             | 性能优异                           | 维度 6.5                                                             |
+| autonomy budget                   | 自治预算                           | 契约 C7                                                              |
+| decision point                    | 决策点                             | 流程术语                                                             |
+| proposal                          | 提案                               | 可决策材料（P2）                                                     |
+| intent                            | 意图                               | P0 对象                                                              |
+| definition of done (DoD)          | 完成定义                           | 契约 C4                                                              |
+| acceptance                        | 验收                               | P7 活动                                                              |
+| owner signature / signing         | 签署                               | 以用户语言副本为准                                                   |
+| reliability                       | 可靠                               | 硬性要求一                                                           |
+| excellence                        | 优秀                               | 硬性要求二                                                           |
+| safety and compliance bottom line | 安全与合规底线                     | 宪法底线                                                             |
+| assets                            | 资产                               | 沉淀的可复用成果                                                     |
+| product DNA                       | 产品 DNA                           | 沉淀的人偏好与价值观                                                 |
+| run                               | run / 流程实例                     | `.hap/runs/<run-id>/`；中文记录中与 SKILL.md 一致使用 “run/流程实例” |
+| governance root                   | 治理根                             | `.hap/` 目录                                                         |
+| bilingual pair                    | 双语成对                           | 用户语言（无后缀）                                                   |
+
+## 规则
+
+1. P0–P7、C1–C10、A1–A7…J1–J7、★ 标记与版本串一律不翻译。
+2. 冻结文档正文内的文件名引用指向同一语言目录下的同名文件（例如 `assets/EN/DERIVED_SPECIFICATION.md` 内引用
+   `HUMAN_AGENT_PARADIGM`）；冻结中文原文正文内嵌的规范小写文件名引用保持原样（内容冻结不可改），工具复制到 `.hap/docs/`
+   时使用规范小写名。
+3. 已随代码注释、README（EN）与注入契约文本发布的既有英文措辞优先（如 “hard requirement”、“multi-view review”、“owner-decision
+   contract”）。
+4. 记录的双语副本同轮书写同一事实——事实与 ID 必须一致，措辞可随语言调整； **英文副本供 Agent 读取与推理（Agent 读取记录事实一律读
+   `records/EN/`）**，中文副本供用户（所有者）审批阅读与签署。
+
+## 语言目录与新增语言
+
+仓库语言文档按语言分目录，语言码大写、复合码用下划线：`assets/ZH_CN/`（冻结中文原文）、`assets/EN/`（英文译本）、`docs/EN/`、
+`docs/ZH_CN/`——目录内文件名为纯 `<NAME>.md`（大写+下划线连接，无语言后缀）。
+
+新增语言：
+
+1. 在 `assets/` 下建立同名语言目录（如 `JA/`；复合码用下划线），把文档译为目录内纯 `<NAME>.md`；
+2. 使用前在本术语表与 README「语言规则」节登记。

package/package.json

@@ -1,36 +1,27 @@
 {
   "name": "@hap-labs/human-agent-paradigm",
-  "version": "0.1.0",
-  "description": "Human-Agent Paradigm (HAP) governance content package: the Constitution, the Derived Specification, the Conformance Checklist, and the Contract / Decision-Request / Delivery-Report templates in Simplified Chinese (ZH_CN) and English (EN), plus the governance-document structural self-check tool.",
+  "version": "0.2.0",
+  "description": "Human-Agent Paradigm (HAP) content package: the Constitution, the Derived Specification, the Conformance Checklist, and the Contract / Decision-Request / Delivery-Report templates in Simplified Chinese (ZH_CN) and English (EN).",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/hap-labs/human-agent-paradigm-governance.git"
+    "url": "https://github.com/hap-labs/human-agent-paradigm.git"
   },
   "files": [
     "assets",
-    "scripts/python/repo_governance_check",
     "README.md",
     "README.zh-CN.md",
-    "CHANGELOG.md",
-    "!**/__pycache__",
-    "!**/__pycache__/**",
-    "!**/*.pyc"
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public"
   },
   "keywords": [
-    "hap",
+    "constitution",
     "ai",
     "agent",
-    "governance",
-    "constitution",
-    "bilingual"
+    "governance"
   ],
-  "scripts": {
-    "check": "python3 -m scripts.python.repo_governance_check --root . --out-dir reports"
-  },
   "packageManager": "pnpm@11.25.0",
   "engines": {
     "node": ">=18"

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