@hunter-harness/workflow-harness 0.3.1 → 0.4.1

package/harness/bundles/general/cursor/scripts/harness_knowledge_candidates.py

@@ -2,17 +2,21 @@
 """Knowledge candidate generation from an archived change's summary-data.json.
 
 The archive workflow has already filtered once: review findings were produced by
-an independent reviewer and then adjudicated, and knownRisks are evidence-derived
-facts. This module turns those two — and only those two — into KnowledgeCandidate
-records for the archive package's ``candidates/knowledge.json``.
+an independent reviewer and then adjudicated, knownRisks are evidence-derived
+facts, and decisions are structured records adopted upstream (plan/execute/
+review). This module turns those three — and only those three — into
+KnowledgeCandidate records for the archive package's ``candidates/knowledge.json``.
 
 Mapping is fixed by docs/superpowers/specs/2026-08-18-three-views-data-flow-design.md
-("知识来源的选定")::
+("知识来源的选定"), extended 2026-08-23 with the decisions source::
 
     disposition = FIXED                      -> pitfall   RED 0.95 / YELLOW 0.85
     disposition = ACCEPTED_RISK | DEFERRED   -> risk      RED 0.95 / YELLOW 0.85
     knownRisks[]                             -> risk      0.85
+    decisions[status=adopted]                -> record's entry_type (decision |
+                                                requirement | api-contract)  0.85
     severity = OK | disposition = NOT_APPLICABLE -> dropped
+    decisions[status != adopted]             -> kept in summary, not knowledge
 
 Dispositions outside the adopted set (OPEN / UNKNOWN) are dropped too: an
 unadjudicated finding is not yet knowledge. maintenanceNotes, finalStatusReasons
@@ -42,6 +46,16 @@ _DISPOSITION_ENTRY_TYPES = {
 _SEVERITY_CONFIDENCE = {"RED": 0.95, "YELLOW": 0.85}
 _KNOWN_RISK_CONFIDENCE = 0.85
 
+# decisions[]（来自 change 的 evidence/decisions.json，经 summary.decisions 传入）
+# 与 findings 的裁决门槛同源：只有已采纳（adopted）的决策才成为候选——
+# proposed/rejected/superseded 留在 summary 里做记录，但不构成知识。
+# entry_type 直接取自记录，取值与 knowledgeCandidateEntryTypeSchema 对齐；
+# source 对应 candidateProvenanceSourceKindSchema 的枚举。
+_DECISION_ENTRY_TYPES = {"decision", "requirement", "api-contract"}
+_DECISION_STATUSES = {"adopted", "proposed", "rejected", "superseded"}
+_DECISION_SOURCE_KINDS = {"plan", "review", "manual", "archive"}
+_DECISION_CONFIDENCE = 0.85
+
 _MAX_KEYWORDS = 32
 _MAX_KEYWORD_CHARS = 80
 _MAX_BODY_CHARS = 20_000
@@ -204,6 +218,86 @@ def _risk_candidate(
     }
 
 
+def _decision_candidate(
+    record: dict[str, Any],
+    *,
+    change_key: str,
+    archive_id: str,
+    producer_version: str,
+    created_at: str,
+) -> dict[str, Any] | None:
+    """Project one adopted design decision / requirement / API contract entry.
+
+    Every field is copied from the record (written upstream by a human or an
+    agent during plan/execute/review); nothing is inferred at archive time.
+    """
+    title = _text(record.get("title"))
+    entry_type = _text(record.get("entry_type"))
+    status = _text(record.get("status")).lower()
+    if not title or entry_type not in _DECISION_ENTRY_TYPES or status != "adopted":
+        return None
+
+    rationale = _text(record.get("rationale"))
+    path = _text(record.get("path"))
+    line = record.get("line")
+    location = _location(path, line)
+    segments = _path_segments(path)
+    record_id = _text(record.get("id"))
+    source = _text(record.get("source"))
+    if source not in _DECISION_SOURCE_KINDS:
+        source = "plan"
+    raw_keywords = record.get("keywords")
+    record_keywords = (
+        [item for item in raw_keywords if isinstance(item, str)]
+        if isinstance(raw_keywords, list)
+        else []
+    )
+
+    body_lines = [title]
+    if rationale:
+        body_lines.append(f"理由：{rationale}")
+    if location:
+        body_lines.append(f"位置：{location}")
+    body_lines.append(f"类型：{entry_type}")
+    body = "\n".join(body_lines)[:_MAX_BODY_CHARS]
+    keywords = _keywords(
+        *record_keywords,
+        segments[-1] if segments else "",
+        segments[-2] if len(segments) >= 2 else "",
+        entry_type,
+    )
+    if path and location != path:
+        source_refs = [f"{path}#L{line}"]
+    elif path:
+        source_refs = [path]
+    else:
+        source_refs = [f"archive:{archive_id}"]
+
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "candidate_id": _candidate_id(
+            change_key, "decision", record_id or f"{title}\0{path}\0{line}"
+        ),
+        "source_change_key": change_key,
+        "source_refs": source_refs,
+        "summary": title,
+        "reusability_scope": segments[0] if segments else "project",
+        "content_hash": _content_hash(entry_type, title, body, keywords),
+        "confidence": _DECISION_CONFIDENCE,
+        "status": "pending",
+        "entry_type": entry_type,
+        "body": body,
+        "keywords": keywords,
+        "provenance": {
+            "source_kind": source,
+            "source_ref": f"archive:{archive_id}#{record_id}" if record_id else f"archive:{archive_id}",
+            "producer": PRODUCER,
+            "producer_version": producer_version,
+            "created_at": created_at,
+        },
+    }
+
+
 def build_knowledge_candidates(
     summary: dict[str, Any],
     *,
@@ -252,6 +346,446 @@ def build_knowledge_candidates(
                     created_at=created_at,
                 ))
 
+    decisions = summary.get("decisions")
+    if isinstance(decisions, list):
+        for record in decisions:
+            if isinstance(record, dict):
+                collect(_decision_candidate(
+                    record,
+                    change_key=change_key,
+                    archive_id=archive_id,
+                    producer_version=producer_version,
+                    created_at=created_at,
+                ))
+
+    return candidates
+
+
+# Dispositions that mean "not yet adjudicated". A finding in this state with a
+# knowledge-carrying severity is dropped by the mapping above — correctly — but
+# the drop must be visible, or an archive with real findings looks identical to
+# an archive with nothing worth keeping (both ship an empty candidates file).
+_UNADJUDICATED_DISPOSITIONS = {"", "OPEN", "UNKNOWN"}
+
+
+def count_unadjudicated_findings(summary: dict[str, Any]) -> int:
+    """Count RED/YELLOW reviewFindings whose disposition is not yet adjudicated.
+
+    These are the findings the mapping table silently drops. Callers use the
+    count to warn when an archive would otherwise show "ready / 0 results"
+    despite carrying real, unprocessed review signal.
+    """
+    if not isinstance(summary, dict):
+        return 0
+    findings = summary.get("reviewFindings")
+    if not isinstance(findings, list):
+        return 0
+    count = 0
+    for finding in findings:
+        if not isinstance(finding, dict):
+            continue
+        severity = _text(finding.get("severity"))
+        disposition = _text(finding.get("disposition")).upper()
+        if severity in _SEVERITIES and disposition in _UNADJUDICATED_DISPOSITIONS:
+            count += 1
+    return count
+
+
+# --- plan/design-derived knowledge candidates ---------------------------------
+#
+# reviewFindings/knownRisks/decisions 只覆盖“经对抗评审的变更”。没有评审的简单
+# 变更（无 RED/YELLOW 发现、无 knownRisks、无 adopted decisions）仍产出了
+# 经用户确认批准的 design/plan/test-scenarios——这些也是值得沉淀的知识。
+# 这里把 plans/*.md（v2 finalize 派生的机器契约）解析回结构化的自然内容，
+# 与 summary 三源并列，但 confidence 略低（机器派生而非独立评审）。
+
+_PLAN_CONFIDENCE = 0.85
+_PLAN_SOURCE_KIND = "plan"
+
+
+def _unescape_markdown(value: str) -> str:
+    """Reverse the renderer's markdown escaping for clean knowledge text.
+
+    harness-plan finalize 的渲染器对自由文本做了反斜杠/实体转义。知识候选存
+    的是自然语言，不需要保留渲染转义。顺序有讲究：先反转义实体，再反转义
+    反斜杠序列（从长到短）。
+    """
+    value = (
+        value.replace("&lt;", "<")
+        .replace("&gt;", ">")
+        .replace("&amp;", "&")
+        .replace("<br>", "\n")
+    )
+    return (
+        value.replace("\\`", "`")
+        .replace("\\#", "#")
+        .replace("\\*", "*")
+        .replace("\\[", "[")
+        .replace("\\]", "]")
+        .replace("\\\\", "\\")
+    )
+
+
+def _markdown_sections(text: str) -> dict[str, list[str]]:
+    """Split a v2 rendered markdown artifact into its ``## Header`` sections.
+
+    Returns ``{header: [lines...]}``. Only the ``##`` level is split; ``###``
+    and ``####`` content stays inside its parent section's lines.
+    """
+    sections: dict[str, list[str]] = {}
+    current: str | None = None
+    for line in text.splitlines():
+        if line.startswith("## ") and not line.startswith("### "):
+            current = line[3:].strip()
+            sections[current] = []
+        elif current is not None:
+            sections[current].append(line)
+    return sections
+
+
+def _plan_source_refs(change_key: str, package_path: str) -> list[str]:
+    """source_refs must exist in the package (core-v1 containment check)."""
+    return [package_path]
+
+
+def _plan_candidate(
+    *,
+    change_key: str,
+    archive_id: str,
+    producer_version: str,
+    created_at: str,
+    kind: str,
+    entry_type: str,
+    summary: str,
+    body: str,
+    keywords: list[str],
+    source_refs: list[str],
+    reusability_scope: str = "project",
+) -> dict[str, Any]:
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "candidate_id": _candidate_id(change_key, kind, summary),
+        "source_change_key": change_key,
+        "source_refs": source_refs,
+        "summary": summary,
+        "reusability_scope": reusability_scope,
+        "content_hash": _content_hash(entry_type, summary, body, keywords),
+        "confidence": _PLAN_CONFIDENCE,
+        "status": "pending",
+        "entry_type": entry_type,
+        "body": body,
+        "keywords": keywords,
+        "provenance": {
+            "source_kind": _PLAN_SOURCE_KIND,
+            "source_ref": f"archive:{archive_id}",
+            "producer": PRODUCER,
+            "producer_version": producer_version,
+            "created_at": created_at,
+        },
+    }
+
+
+def _requirements_from_design(
+    design_text: str,
+    *,
+    change_key: str,
+    archive_id: str,
+    producer_version: str,
+    created_at: str,
+) -> list[dict[str, Any]]:
+    """Parse ``## Requirements`` from design.md into requirement candidates.
+
+    Each line is ``- requirement:sha256:... [kind]: text`` where kind is
+    behavior | invariant | failure_behavior.
+    """
+    sections = _markdown_sections(design_text)
+    lines = sections.get("Requirements", [])
+    out: list[dict[str, Any]] = []
+    for line in lines:
+        stripped = line.strip()
+        if not stripped.startswith("- "):
+            continue
+        prefix = stripped[2:]
+        # kind 位于第一个 `]: ` 之前的方括号内。
+        close_bracket = prefix.find("]")
+        if close_bracket <= 0 or not prefix.startswith("requirement:"):
+            continue
+        kind = prefix[1:close_bracket].strip()
+        if kind not in {"behavior", "invariant", "failure_behavior"}:
+            continue
+        colon = prefix.find(": ", close_bracket + 1)
+        if colon == -1:
+            continue
+        text = _unescape_markdown(prefix[colon + 2:].strip())
+        if not text:
+            continue
+        entry_type = "requirement"
+        body = f"需求类型：{kind}\n{text}"
+        keywords = _keywords(kind, entry_type)
+        out.append(_plan_candidate(
+            change_key=change_key,
+            archive_id=archive_id,
+            producer_version=producer_version,
+            created_at=created_at,
+            kind="requirement",
+            entry_type=entry_type,
+            summary=text,
+            body=body,
+            keywords=keywords,
+            source_refs=_plan_source_refs(change_key, f"plans/{change_key}-design.md"),
+        ))
+    return out
+
+
+def _risks_from_design(
+    design_text: str,
+    *,
+    change_key: str,
+    archive_id: str,
+    producer_version: str,
+    created_at: str,
+) -> list[dict[str, Any]]:
+    """Parse ``## Risks`` (``- risk`` + ``  - Mitigation: ...``) into risk candidates."""
+    sections = _markdown_sections(design_text)
+    lines = sections.get("Risks", [])
+    out: list[dict[str, Any]] = []
+    index = 0
+    while index < len(lines):
+        stripped = lines[index].strip()
+        if not stripped.startswith("- "):
+            index += 1
+            continue
+        risk = _unescape_markdown(stripped[2:].strip())
+        if not risk or risk == "None.":
+            index += 1
+            continue
+        mitigation = ""
+        if index + 1 < len(lines) and lines[index + 1].strip().startswith("- Mitigation:"):
+            mitigation = _unescape_markdown(
+                lines[index + 1].strip()[len("- Mitigation:"):].strip()
+            )
+            index += 1
+        body = risk if not mitigation else f"{risk}\n缓解：{mitigation}"
+        out.append(_plan_candidate(
+            change_key=change_key,
+            archive_id=archive_id,
+            producer_version=producer_version,
+            created_at=created_at,
+            kind="risk",
+            entry_type="risk",
+            summary=risk,
+            body=body,
+            keywords=_keywords("risk"),
+            source_refs=_plan_source_refs(change_key, f"plans/{change_key}-design.md"),
+        ))
+        index += 1
+    return out
+
+
+def _invariants_from_design(
+    design_text: str,
+    *,
+    change_key: str,
+    archive_id: str,
+    producer_version: str,
+    created_at: str,
+) -> list[dict[str, Any]]:
+    """Parse ``## Invariants`` bullet list into requirement candidates."""
+    sections = _markdown_sections(design_text)
+    out: list[dict[str, Any]] = []
+    for line in sections.get("Invariants", []):
+        stripped = line.strip()
+        if not stripped.startswith("- "):
+            continue
+        text = _unescape_markdown(stripped[2:].strip())
+        if not text or text == "None.":
+            continue
+        out.append(_plan_candidate(
+            change_key=change_key,
+            archive_id=archive_id,
+            producer_version=producer_version,
+            created_at=created_at,
+            kind="invariant",
+            entry_type="requirement",
+            summary=text,
+            body=f"需求类型：invariant\n{text}",
+            keywords=_keywords("invariant", "requirement"),
+            source_refs=_plan_source_refs(change_key, f"plans/{change_key}-design.md"),
+        ))
+    return out
+
+
+def _tasks_from_plan(
+    plan_text: str,
+    *,
+    change_key: str,
+    archive_id: str,
+    producer_version: str,
+    created_at: str,
+) -> list[dict[str, Any]]:
+    """Parse ``## Tasks`` from plan.md into implementation candidates.
+
+    Task headings are ``### T1``; the objective is the non-empty text between
+    the heading and the first ``- `` metadata bullet.
+    """
+    sections = _markdown_sections(plan_text)
+    lines = sections.get("Tasks", [])
+    out: list[dict[str, Any]] = []
+    index = 0
+    while index < len(lines):
+        stripped = lines[index].strip()
+        if not stripped.startswith("### "):
+            index += 1
+            continue
+        task_id = stripped[4:].strip()
+        index += 1
+        objective_parts: list[str] = []
+        while index < len(lines):
+            current = lines[index].strip()
+            if current.startswith("### ") or current.startswith("- "):
+                break
+            if current:
+                objective_parts.append(current)
+            index += 1
+        objective = " ".join(objective_parts).strip()
+        if not objective:
+            continue
+        body = f"任务：{task_id}\n{objective}"
+        out.append(_plan_candidate(
+            change_key=change_key,
+            archive_id=archive_id,
+            producer_version=producer_version,
+            created_at=created_at,
+            kind="task",
+            entry_type="implementation",
+            summary=objective,
+            body=body,
+            keywords=_keywords(task_id, "implementation"),
+            source_refs=_plan_source_refs(change_key, f"plans/{change_key}-plan.md"),
+        ))
+    return out
+
+
+def _scenarios_from_test_scenarios(
+    scenarios_text: str,
+    *,
+    change_key: str,
+    archive_id: str,
+    producer_version: str,
+    created_at: str,
+) -> list[dict[str, Any]]:
+    """Parse ``## <id>: <title>`` headings into test-evidence candidates."""
+    out: list[dict[str, Any]] = []
+    for line in scenarios_text.splitlines():
+        stripped = line.strip()
+        if not stripped.startswith("## ") or stripped.startswith("### "):
+            continue
+        heading = stripped[3:].strip()
+        if heading == "Coverage":
+            continue
+        if ":" not in heading:
+            continue
+        scenario_id, title = heading.split(":", 1)
+        title = title.strip()
+        if not title:
+            continue
+        out.append(_plan_candidate(
+            change_key=change_key,
+            archive_id=archive_id,
+            producer_version=producer_version,
+            created_at=created_at,
+            kind="scenario",
+            entry_type="test-evidence",
+            summary=title,
+            body=f"场景：{scenario_id.strip()}\n{title}",
+            keywords=_keywords(scenario_id.strip(), "test-evidence"),
+            source_refs=_plan_source_refs(
+                change_key, f"plans/{change_key}-test-scenarios.md"
+            ),
+        ))
+    return out
+
+
+def build_plan_candidates(
+    archive_dir,
+    *,
+    change_key: str,
+    archive_id: str,
+    producer_version: str,
+    created_at: str,
+) -> list[dict[str, Any]]:
+    """Extract knowledge candidates from the archive's plans/*.md artifacts.
+
+    Complements ``build_knowledge_candidates`` (summary 三源)。没有评审的简单
+    变更仍然产出 plans/*.md；这些是经用户确认批准的结构化真相源，parse 回来
+    就是可沉淀的知识。缺文件/解析失败返回 []（软失败）。
+    """
+    candidates: list[dict[str, Any]] = []
+    seen_ids: set[str] = set()
+
+    def collect(items: list[dict[str, Any]]) -> None:
+        for candidate in items:
+            if candidate["candidate_id"] in seen_ids:
+                continue
+            seen_ids.add(candidate["candidate_id"])
+            candidates.append(candidate)
+
+    design_path = archive_dir / "plans" / f"{change_key}-design.md"
+    if design_path.is_file():
+        try:
+            design_text = design_path.read_text(encoding="utf-8-sig")
+        except OSError:
+            design_text = ""
+        collect(_requirements_from_design(
+            design_text,
+            change_key=change_key,
+            archive_id=archive_id,
+            producer_version=producer_version,
+            created_at=created_at,
+        ))
+        collect(_risks_from_design(
+            design_text,
+            change_key=change_key,
+            archive_id=archive_id,
+            producer_version=producer_version,
+            created_at=created_at,
+        ))
+        collect(_invariants_from_design(
+            design_text,
+            change_key=change_key,
+            archive_id=archive_id,
+            producer_version=producer_version,
+            created_at=created_at,
+        ))
+
+    plan_path = archive_dir / "plans" / f"{change_key}-plan.md"
+    if plan_path.is_file():
+        try:
+            plan_text = plan_path.read_text(encoding="utf-8-sig")
+        except OSError:
+            plan_text = ""
+        collect(_tasks_from_plan(
+            plan_text,
+            change_key=change_key,
+            archive_id=archive_id,
+            producer_version=producer_version,
+            created_at=created_at,
+        ))
+
+    scenarios_path = archive_dir / "plans" / f"{change_key}-test-scenarios.md"
+    if scenarios_path.is_file():
+        try:
+            scenarios_text = scenarios_path.read_text(encoding="utf-8-sig")
+        except OSError:
+            scenarios_text = ""
+        collect(_scenarios_from_test_scenarios(
+            scenarios_text,
+            change_key=change_key,
+            archive_id=archive_id,
+            producer_version=producer_version,
+            created_at=created_at,
+        ))
+
     return candidates
 
 

package/harness/bundles/general/pi/.harness-build.json

@@ -0,0 +1,6 @@
+{
+  "schemaVersion": 1,
+  "overlay": "none",
+  "agent": "pi",
+  "coreHash": "ec59ac2389d9dce9"
+}

package/harness/bundles/general/pi/CONTEXT.md

@@ -0,0 +1,98 @@
+# Harness Skills
+
+Harness Skills 是一组围绕本地变更治理的 agent 工作流。它把外部方法论吸收为原生协议，同时保持 `.harness/changes/<change-name>/` 作为变更过程的唯一真相源。
+
+## Language
+
+**原生协议**:
+Harness skill 内部直接执行的流程约束，作为正式行为契约。原生协议可以吸收外部方法论，但不依赖外部 skill 是否安装。
+_Avoid_: Adapter Mode, 外部 skill 调用
+
+**外部方法论来源**:
+为 harness 规则提供启发的外部 skill 或流程，例如 brainstorming、grill-me、writing-plans、test-driven-development、receiving-code-review。它们是设计来源，不是 harness 的运行时依赖。
+_Avoid_: 外部依赖, 必需插件
+
+**人工参考**:
+不进入正式流程状态机、只供人或后续规则维护者对标的方法、草稿或外部技能。人工参考缺失不产生降级项；若被采用，应先转写为 harness 原生协议或正式产物。
+_Avoid_: 运行时增强, 降级分支, 硬依赖
+
+**变更簇**:
+围绕同一业务行为或同一验证目标的一组任务。变更簇是 `/harness-run` 执行 RED→GREEN→REFACTOR 的基本单位。
+_Avoid_: 小任务, 单步任务
+
+**自适应执行参考**:
+`implementation-detail.md` 的定位。它按变更复杂度提供足够执行上下文，简单变更保持简洁，高风险变更写清顺序、接口、数据、风险和测试策略。
+_Avoid_: 超细步骤文档, 可选详细计划
+
+**Fixback**:
+由 review 阶段把 RED/YELLOW 问题转成的结构化修复反馈。Fixback 指向问题位置、推荐修复和验证方式，但默认不自动阻塞 submit。
+_Avoid_: 修复任务清单, blocking review
+
+**事件唯一源**:
+`events.ndjson` 是变更执行过程的唯一实时记录位置，由 `harness_events.py append` 写入。`execution-log.md` 是它的自动渲染产物，禁止手工编辑。
+_Avoid_: 日志双写, 手写执行日志
+
+**归档终结（finalize）**:
+`harness_archive.py finalize` 在单进程内完成 manifest、移动、collect、渲染、校验、比对、删除原目录的完整归档动作。取代旧的 collect/enrich/validate 三步编排；enrich 不再是有效概念。
+_Avoid_: enrich, 多步归档编排
+
+**知识裁决（judge）**:
+归档收尾时对知识条目的处置流程：脚本规则先消化机械部分（去重、时间序 supersede、stale 重验），模型批量裁决剩余的真语义冲突与 promote，写入可回滚的 decision log。人工退出常规循环。
+_Avoid_: 人工 promote 积压, candidate 待办
+
+**构建档案（build-profile）**:
+`.harness/config/build-profile.json`，项目级持久化的机读构建事实：可用命令模板、工具绝对路径、已知预存错误、服务启动模板。preflight 只做秒级校验，新坑由脚本回写。项目专属硬编码归此文件，不进 skill 文本。
+_Avoid_: 每次重新探测, skill 内硬编码项目参数
+
+**验证指纹（inputsHash）**:
+一项验证（compile/install/unitTest/apiTest）所依赖源文件集合的内容哈希。指纹一致且证据完整才允许 🔁REUSED；无法证明即保守重跑。
+_Avoid_: 仅凭 diffHash 复用, 无证据跳过
+
+**验证图（verification graph）**:
+`evidence/verification-graph.json` 按 canonical identity 持久化验证节点；`can-reuse` 返回 `invalidationCode`（如 `INPUT_CHANGED`）；profile `mergeVerification.requiredOnMerge` 进入 integration verify。详见 ledger / integration 脚本。
+_Avoid_: 冻结后无因重跑全量
+
+**Migration head 单源**:
+消费项目用 `.harness/config/migration-head.json` 声明 canonical head 与联动 sources；`harness_migration_head.py check` 做静态一致性门禁。
+_Avoid_: config/CI/manifest 多处手写 head
+
+**事件批处理**:
+同阶段多事件用 `harness_events.py batch-append`（单锁多行）；`phase.end` 仍走单次 append。
+_Avoid_: 机械事件逐条起进程
+
+**能力级模型路由**:
+任务用 `economy` / `balanced` / `frontier` 表述；禁止在通用 harness 规则硬编码供应商模型名。详见 `protocols/model-routing-protocol.md`。
+_Avoid_: skill 内写死 claude-/gpt- 模型 id
+
+**Overlay 所有权**:
+Bundle 安装目标由安装器管理；项目自有配置放 `.harness/project-overlay/`（或 project.yaml 侧）。`--force-managed` 必须配合 `--yes`/`--confirmed`，冲突 fail closed。
+_Avoid_: 静默 force-managed
+
+**服务会话**:
+`runtime/service-session.json` 记录的 AI 启动服务生命周期。指纹匹配静默复用、不匹配自动重启、归档收尾统一停止；只有用户自启服务占端口才询问。
+_Avoid_: 每轮测试后必杀服务
+
+**交互白名单**:
+每个 skill 显式声明的允许 `blocking user confirmation` 场景清单。白名单外一律取默认值并记 decision 事件。
+_Avoid_: 逐决策点询问
+
+**阻断式用户确认（blocking user confirmation）**:
+宿主无关的审批原语。canonical skill 使用此术语表达"展示完整审批包并等待明确答复"的语义，不绑定具体宿主工具。adapter 按下表映射到宿主具体工具：
+
+| Adapter | 工具 |
+|---------|------|
+| claude-code | AskUserQuestion |
+| codebuddy | AskUserQuestion |
+| codex | request_user_input 或普通对话 |
+| cursor | 普通对话 |
+
+finalizer 只校验 approval receipt/decision 的顺序和内容，不校验交互工具品牌。
+_Avoid_: 硬编码宿主工具名, 跨宿主不可移植
+
+**部署合成**:
+`harness_deploy.py build` 把通用核心 + shared 片段 + overlay 合成为自包含 SKILL.md 后部署。Vault 源头 DRY，运行时单文件。
+_Avoid_: 运行时跨文件拼规则, fork 维护
+
+**Java overlay**:
+`overlays/java/` 中只含"任何 Java 项目通用"的差异段落与独有 skill（apidoc/package）。项目专属值写目标项目的 build-profile。
+_Avoid_: Java fork, UDP 硬编码进 overlay