@hunter-harness/workflow-harness 0.2.8 → 0.2.9

package/harness/bundles/general/codex/scripts/harness_events.py

@@ -43,6 +43,7 @@ EVENT_TYPES = frozenset(
 )
 
 SCHEMA_VERSION = 3
+_NOTE_FALLBACK_MAXLEN = 60
 HEADER_LINE = (
     "本文件由 harness_events.py 自动渲染，请勿手工编辑；事实源为 events.ndjson"
 )
@@ -316,6 +317,8 @@ def build_event(args: argparse.Namespace, existing: list[dict[str, Any]]) -> dic
 def status_symbol(status: Any, reason: Any = None) -> str:
     text = str(status or "").strip().lower()
     reason_text = str(reason or "").strip()
+    if not text:
+        return "—"
     ok_set = {"ok", "passed", "pass", "success", "green", "✅", "✅ok"}
     warn_set = {"warn", "warning", "yellow", "skipped", "skip", "🟡", "🟡warn"}
     fail_set = {"fail", "failed", "error", "red", "blocked", "❌", "❌fail"}
@@ -327,7 +330,7 @@ def status_symbol(status: Any, reason: Any = None) -> str:
         return f"❌FAIL({reason_text})" if reason_text else "❌FAIL"
     if reason_text:
         return f"{status}({reason_text})"
-    return str(status or "unknown")
+    return str(status)
 
 
 def severity_symbol(severity: Any, message: Any = None) -> str:
@@ -339,7 +342,10 @@ def severity_symbol(severity: Any, message: Any = None) -> str:
         return f"🟡WARN({msg})" if msg else "🟡WARN"
     if text in {"info", "ok", "note"}:
         return f"✅OK({msg})" if msg else "✅OK"
-    return f"{severity}: {msg}" if msg else str(severity or "issue")
+    # Empty/unknown severity: never emit literal "issue"/"None".
+    if not text:
+        return ""
+    return f"{severity}: {msg}" if msg else str(severity)
 
 
 def format_duration(ms: int | None) -> str:
@@ -440,35 +446,54 @@ def phase_duration_ms(phase_events: list[dict[str, Any]]) -> int | None:
 def render_command_block(commands: list[dict[str, Any]]) -> list[str]:
     if not commands:
         return []
+
+    def command_display(event: dict[str, Any]) -> str:
+        cmd = str(event.get("command") or "").strip()
+        if cmd:
+            return cmd
+        return str(event.get("note") or "").strip()
+
     if len(commands) == 1:
         event = commands[0]
-        cmd = event.get("command") or ""
+        display = command_display(event)
+        if not display:
+            return []
         exit_code = event.get("exit_code")
         exit_text = "?" if exit_code is None else str(exit_code)
         duration = format_duration(
             int(event["duration_ms"]) if isinstance(event.get("duration_ms"), int) else None
         )
         note = str(event.get("note") or "").strip()
-        parts = [f"- command: `{cmd}`", f"exit={exit_text}", f"duration={duration}"]
-        if note:
+        parts = [f"- command: `{display}`", f"exit={exit_text}", f"duration={duration}"]
+        # Avoid duplicating note when it was already used as the display text.
+        if note and note != display:
             parts.append(f"note={note}")
         return [" · ".join(parts)]
 
-    lines = [
-        "",
-        "| 命令 | exit | duration | note |",
-        "| --- | ---: | ---: | --- |",
-    ]
+    rows: list[str] = []
     for event in commands:
-        cmd = str(event.get("command") or "").replace("|", "\\|")
+        display = command_display(event)
+        if not display:
+            continue
+        cmd = display.replace("|", "\\|")
         exit_code = event.get("exit_code")
         exit_text = "?" if exit_code is None else str(exit_code)
         duration = format_duration(
             int(event["duration_ms"]) if isinstance(event.get("duration_ms"), int) else None
         )
         note = str(event.get("note") or "").replace("|", "\\|")
-        lines.append(f"| `{cmd}` | {exit_text} | {duration} | {note} |")
-    lines.append("")
+        # If note was promoted to the command cell, leave the note column empty.
+        note_cell = "" if note == display else note
+        rows.append(f"| `{cmd}` | {exit_text} | {duration} | {note_cell} |")
+    if not rows:
+        return []
+    lines = [
+        "",
+        "| 命令 | exit | duration | note |",
+        "| --- | ---: | ---: | --- |",
+        *rows,
+        "",
+    ]
     return lines
 
 
@@ -491,23 +516,37 @@ def render_event_line(event: dict[str, Any]) -> list[str]:
         suffix = f" — {note}" if note else ""
         return [f"- phase.end @ {event.get('timestamp', '')}{suffix}"]
     if etype == "verification":
-        name = event.get("name") or "(unnamed)"
-        symbol = status_symbol(event.get("status"), event.get("reason") or event.get("note"))
+        note = str(event.get("note") or "").strip()
+        name = str(event.get("name") or "").strip() or (
+            note[:_NOTE_FALLBACK_MAXLEN] if note else ""
+        )
+        if not name:
+            return []
+        symbol = status_symbol(event.get("status"), event.get("reason"))
         return [f"- verification: {name} → {symbol}"]
     if etype == "decision":
-        decision = event.get("decision") or ""
-        reason = event.get("reason") or event.get("note") or ""
+        decision = str(event.get("decision") or "").strip()
+        reason = str(event.get("reason") or event.get("note") or "").strip()
+        if not decision:
+            return [f"- decision: {reason}"] if reason else []
         if reason:
             return [f"- decision: {decision} — {reason}"]
         return [f"- decision: {decision}"]
     if etype == "issue":
-        symbol = severity_symbol(event.get("severity"), event.get("message"))
+        note = str(event.get("note") or "").strip()
+        message = str(event.get("message") or "").strip() or note
+        symbol = severity_symbol(event.get("severity"), message)
+        if not symbol:
+            return [f"- issue: {note}"] if note else []
         code = event.get("code")
         prefix = f"[{code}] " if code else ""
         return [f"- issue: {prefix}{symbol}"]
     if etype == "artifact":
-        path = event.get("path") or ""
+        path = str(event.get("path") or "").strip()
+        note = str(event.get("note") or "").strip()
         kind = event.get("kind")
+        if not path:
+            return [f"- artifact: {note}"] if note else []
         if kind:
             return [f"- artifact: `{path}` ({kind})"]
         return [f"- artifact: `{path}`"]
@@ -653,6 +692,18 @@ def cmd_append(args: argparse.Namespace) -> int:
     # new_event_id 用完整 uuid，无需扫描去重。锁覆盖 atomic_append_line 的
     # open/write/flush/fsync 全过程。
     event = build_event(args, [])
+    # Semantic hints (non-fatal): guide agents toward required fields.
+    if args.type == "issue" and not args.severity:
+        event["severity"] = "info"
+        print(
+            "warning: issue without --severity, defaulted to info",
+            file=sys.stderr,
+        )
+    if args.type == "verification" and (not args.name or not args.status):
+        print(
+            "warning: verification missing --name or --status",
+            file=sys.stderr,
+        )
     line = json.dumps(event, ensure_ascii=False, separators=(",", ":"))
     try:
         with event_file_lock(lock_path):

package/harness/bundles/general/codex/scripts/harness_gate.py

@@ -149,7 +149,8 @@ def checkpoint_status(checkpoints: dict[str, Any] | None, checkpoint_id: str) ->
 def foundation_gate_blocks(task_number: int | None, change_dir: Path) -> dict[str, Any] | None:
     checkpoints = load_checkpoints(change_dir)
     status = checkpoint_status(checkpoints, "foundation-gate")
-    if status == "approved":
+    # missing = checkpoint not enabled for this change (no file / no entry).
+    if status in {"approved", "missing"}:
         return None
     if task_number is None:
         return {
@@ -174,8 +175,25 @@ def foundation_gate_blocks(task_number: int | None, change_dir: Path) -> dict[st
     }
 
 
-def validate_ledger_entry_v2(entry: dict[str, Any], verification: str) -> list[str]:
+def is_degraded_ledger_entry(entry: dict[str, Any]) -> bool:
+    """NOT_RUN + evidence starting with 'DEGRADED: <non-empty reason>'."""
+    if entry.get("status") != "NOT_RUN":
+        return False
+    evidence = str(entry.get("evidence") or "").strip()
+    if not evidence.startswith("DEGRADED:"):
+        return False
+    reason = evidence.split(":", 1)[1].strip()
+    return bool(reason)
+
+
+def validate_ledger_entry_v2(entry: dict[str, Any], verification: str) -> tuple[list[str], bool]:
+    """Internal helper for ledger close validation (not a public API).
+
+    Returns ``(missing_fields, degraded_ok)`` where ``degraded_ok`` is True only when
+    the entry is a valid DEGRADED NOT_RUN record with no other missing fields.
+    """
     missing: list[str] = []
+    degraded = is_degraded_ledger_entry(entry)
     for field in LEDGER_V2_REQUIRED_ENTRY_FIELDS:
         value = entry.get(field)
         if field == "inputsFiles":
@@ -184,7 +202,7 @@ def validate_ledger_entry_v2(entry: dict[str, Any], verification: str) -> list[s
             elif verification == "unitTestFull" and not value:
                 missing.append("inputsFiles(non-empty)")
         elif field == "status":
-            if value != "OK":
+            if value != "OK" and not degraded:
                 missing.append("status=OK")
         elif not (isinstance(value, str) and value.strip()):
             missing.append(field)
@@ -192,7 +210,7 @@ def validate_ledger_entry_v2(entry: dict[str, Any], verification: str) -> list[s
             missing.append("coverage(valid)")
         elif field == "algorithmVersion" and str(value).strip() != hl.LEDGER_VERSION:
             missing.append("algorithmVersion(harness-ledger-2)")
-    return missing
+    return missing, degraded and not missing
 
 
 def validate_ledger_for_phase_close(
@@ -225,6 +243,7 @@ def validate_ledger_for_phase_close(
         }
 
     problems: list[dict[str, Any]] = []
+    degraded: list[str] = []
     for verification in required:
         entry = validations.get(verification)
         if not isinstance(entry, dict):
@@ -236,7 +255,7 @@ def validate_ledger_for_phase_close(
                 }
             )
             continue
-        missing = validate_ledger_entry_v2(entry, verification)
+        missing, is_degraded = validate_ledger_entry_v2(entry, verification)
         if missing:
             code = (
                 "MISSING_V2_FIELDS"
@@ -258,6 +277,8 @@ def validate_ledger_for_phase_close(
                     "code": code,
                 }
             )
+        elif is_degraded:
+            degraded.append(verification)
 
     if problems:
         return {
@@ -269,6 +290,15 @@ def validate_ledger_for_phase_close(
             "ledgerPath": str(ledger_path) if ledger_path else None,
             "detail": "natural-language override is not permitted",
         }
+    if degraded:
+        return {
+            "ok": True,
+            "code": "LEDGER_OK_DEGRADED",
+            "phase": phase,
+            "validated": required,
+            "degraded": degraded,
+            "ledgerPath": str(ledger_path) if ledger_path else None,
+        }
     return {
         "ok": True,
         "code": "LEDGER_OK",
@@ -417,7 +447,11 @@ def change_code_root(change_dir: Path) -> Path:
     return project
 
 
-def classify_risk(change_dir: Path, stage: str) -> dict[str, Any]:
+def classify_risk(
+    change_dir: Path,
+    stage: str,
+    workflow: dict[str, Any] | None = None,
+) -> dict[str, Any]:
     tier = "full"
     source = "default-full"
     plan_path = change_dir / "plans"
@@ -484,7 +518,31 @@ def classify_risk(change_dir: Path, stage: str) -> dict[str, Any]:
             tier = observed
         source = f"{source}+post-run"
     main_project = change_dir.parents[2]
-    workflow = _load_workflow_policy(project=main_project)
+    if workflow is None:
+        workflow = _load_workflow_policy(project=main_project)
+    tier_policy = workflow["riskTiers"][tier]
+    unique_signals = sorted(set(signals))
+    payload = {
+        "ok": True,
+        "code": "CLASSIFIED",
+        "stage": stage,
+        "tier": tier,
+        "source": source,
+        "changeId": change_dir.name,
+        "signals": unique_signals,
+        "defaultPhases": list(tier_policy["defaultPhases"]),
+        "requiredValidations": list(tier_policy["requiredValidations"]),
+        "conditionalStages": list(tier_policy["conditionalStages"]),
+        "stageDecisions": _stage_decisions_for_tier(workflow, tier, unique_signals),
+    }
+    if stage == "post-run":
+        _write_json(change_dir / "meta" / "risk-classification.json", payload)
+    return payload
+
+
+def _stage_decisions_for_tier(
+    workflow: dict[str, Any], tier: str, signals: list[str]
+) -> dict[str, dict[str, Any]]:
     tier_policy = workflow["riskTiers"][tier]
     unique_signals = sorted(set(signals))
     stage_decisions: dict[str, dict[str, Any]] = {}
@@ -501,22 +559,66 @@ def classify_risk(change_dir: Path, stage: str) -> dict[str, Any]:
             ),
             "matchedSignals": matched,
         }
-    payload = {
+    return stage_decisions
+
+
+def apply_tier_override(
+    payload: dict[str, Any],
+    workflow: dict[str, Any],
+    *,
+    tier: str,
+    override_by: str,
+) -> dict[str, Any]:
+    """Rebind payload to an explicit tier override (source=override)."""
+    tier_policy = workflow["riskTiers"][tier]
+    now = hc.now_iso()
+    signals = list(payload.get("signals") or [])
+    payload = dict(payload)
+    payload["tier"] = tier
+    payload["source"] = "override"
+    payload["defaultPhases"] = list(tier_policy["defaultPhases"])
+    payload["requiredValidations"] = list(tier_policy["requiredValidations"])
+    payload["conditionalStages"] = list(tier_policy["conditionalStages"])
+    payload["stageDecisions"] = _stage_decisions_for_tier(workflow, tier, signals)
+    payload["tierOverride"] = {"tier": tier, "by": override_by, "at": now}
+    return payload
+
+
+def gate_policy_document(payload: dict[str, Any]) -> dict[str, Any]:
+    """Cross-change contract: meta/gate-policy.json (schemaVersion=1)."""
+    return {
+        "schemaVersion": 1,
+        "tier": payload["tier"],
+        "source": payload["source"],
+        "defaultPhases": list(payload.get("defaultPhases") or []),
+        "requiredValidations": list(payload.get("requiredValidations") or []),
+        "classifiedAt": payload.get("classifiedAt") or hc.now_iso(),
+        "tierOverride": payload.get("tierOverride"),
+    }
+
+
+def classify_defaults(
+    workflow: dict[str, Any],
+    *,
+    change_id: str,
+    stage: str,
+) -> dict[str, Any]:
+    tier = "full"
+    source = "default-full"
+    tier_policy = workflow["riskTiers"][tier]
+    return {
         "ok": True,
         "code": "CLASSIFIED",
         "stage": stage,
         "tier": tier,
         "source": source,
-        "changeId": change_dir.name,
-        "signals": unique_signals,
+        "changeId": change_id,
+        "signals": [],
         "defaultPhases": list(tier_policy["defaultPhases"]),
         "requiredValidations": list(tier_policy["requiredValidations"]),
         "conditionalStages": list(tier_policy["conditionalStages"]),
-        "stageDecisions": stage_decisions,
+        "stageDecisions": _stage_decisions_for_tier(workflow, tier, []),
     }
-    if stage == "post-run":
-        _write_json(change_dir / "meta" / "risk-classification.json", payload)
-    return payload
 
 
 def lint_skill_tree(skills_root: Path) -> dict[str, Any]:
@@ -823,6 +925,14 @@ def cmd_close(args: argparse.Namespace) -> int:
             extra={k: v for k, v in ledger_result.items() if k not in {"ok", "message", "code"}},
         )
 
+    close_status = args.status
+    close_code = "PHASE_CLOSED"
+    if ledger_result.get("code") == "LEDGER_OK_DEGRADED":
+        close_code = "CLOSED_DEGRADED"
+        # Degraded close: phase.end status must not exceed WARN (OK → WARN).
+        if close_status == "OK":
+            close_status = "WARN"
+
     guard_result = None
     if args.phase in {"run", "test"}:
         project_root = args.project or str(project)
@@ -839,7 +949,7 @@ def cmd_close(args: argparse.Namespace) -> int:
         change_dir,
         phase=args.phase,
         type_="phase.end",
-        status=args.status,
+        status=close_status,
         note=args.note or "",
         run_id=run_id,
     ) if not _phase_event_exists(change_dir, args.phase, "phase.end", run_id) else {
@@ -862,9 +972,9 @@ def cmd_close(args: argparse.Namespace) -> int:
 
     payload = {
         "ok": True,
-        "code": "PHASE_CLOSED",
+        "code": close_code,
         "phase": args.phase,
-        "status": args.status,
+        "status": close_status,
         "changeId": resolved["changeId"],
         "ledger": ledger_result,
         "testGuard": guard_result,
@@ -878,19 +988,56 @@ def cmd_close(args: argparse.Namespace) -> int:
 def cmd_classify(args: argparse.Namespace) -> int:
     as_json = bool(args.json)
     project = hc.resolve_main_project_root()
+    try:
+        workflow = _load_workflow_policy(project=project)
+    except (OSError, ValueError, hwp.PolicyValidationError) as exc:
+        return emit_error("POLICY_LOAD_FAILED", str(exc), as_json=as_json)
+
     resolved = hc.resolve_change(project, args.change)
-    if not resolved.get("ok"):
-        return emit_error(
-            str(resolved.get("code", "RESOLVE_FAILED")),
-            str(resolved.get("message", "change resolve failed")),
-            as_json=as_json,
-            extra={k: v for k, v in resolved.items() if k not in {"ok", "message"}},
+    change_dir: Path | None = None
+    change_id = str(args.change or "")
+    if resolved.get("ok"):
+        change_dir = Path(resolved["changeDir"])
+        change_id = str(resolved.get("changeId") or change_dir.name)
+        if not change_dir.is_dir():
+            change_dir = None
+
+    if change_dir is not None:
+        payload = classify_risk(change_dir, args.stage, workflow=workflow)
+    else:
+        payload = classify_defaults(workflow, change_id=change_id or "unknown", stage=args.stage)
+        if not resolved.get("ok"):
+            payload["resolveCode"] = resolved.get("code")
+
+    tier_override = getattr(args, "tier_override", None)
+    if tier_override:
+        payload = apply_tier_override(
+            payload,
+            workflow,
+            tier=str(tier_override),
+            override_by=str(getattr(args, "override_by", None) or "user"),
         )
-    payload = classify_risk(Path(resolved["changeDir"]), args.stage)
+    else:
+        payload.setdefault("tierOverride", None)
+
+    classified_at = hc.now_iso()
+    payload["classifiedAt"] = classified_at
+
+    if change_dir is not None and change_dir.is_dir():
+        policy_doc = gate_policy_document(payload)
+        policy_path = change_dir / "meta" / "gate-policy.json"
+        _write_json(policy_path, policy_doc)
+        payload["policyPersisted"] = True
+        payload["policyPath"] = str(policy_path)
+    else:
+        payload["policyPersisted"] = False
+        payload["warning"] = (
+            "change directory does not exist; gate-policy.json not written"
+        )
+
     emit(payload, as_json=as_json)
     return 0
 
-
 def cmd_checkpoint(args: argparse.Namespace) -> int:
     as_json = bool(args.json)
     project = hc.resolve_main_project_root()
@@ -1012,6 +1159,12 @@ def build_parser() -> argparse.ArgumentParser:
     p_classify = sub.add_parser("classify", parents=[shared])
     p_classify.add_argument("--change", default=None)
     p_classify.add_argument("--stage", required=True, choices=["plan", "post-run"])
+    p_classify.add_argument(
+        "--tier-override",
+        default=None,
+        choices=["fast", "standard", "full"],
+    )
+    p_classify.add_argument("--override-by", default="user")
     p_classify.set_defaults(func=cmd_classify)
 
     p_checkpoint = sub.add_parser("checkpoint", parents=[shared])

package/harness/bundles/general/codex/scripts/harness_ledger.py

@@ -816,6 +816,18 @@ def cmd_record(args: argparse.Namespace) -> int:
                 "finishedAt": now_iso(),
             }
         )
+        metrics_raw = getattr(args, "metrics_json", None)
+        if metrics_raw is not None and str(metrics_raw).strip() != "":
+            try:
+                metrics_obj = json.loads(str(metrics_raw))
+            except json.JSONDecodeError:
+                return emit_error("invalid --metrics-json", as_json=as_json)
+            if not isinstance(metrics_obj, dict):
+                return emit_error("invalid --metrics-json", as_json=as_json)
+            entry["metrics"] = metrics_obj
+        elif "metrics" in entry:
+            # Fresh record without metrics must not keep stale metrics from prev.
+            entry.pop("metrics", None)
         if args.scope is not None and str(args.scope).strip():
             entry["scope"] = str(args.scope).strip()
         # No default scope: recording an incremental run as broad "module" scope
@@ -1014,6 +1026,11 @@ def build_parser() -> argparse.ArgumentParser:
         default=None,
         help="package: prior verifications reused when testsExecuted=false",
     )
+    p_record.add_argument(
+        "--metrics-json",
+        default=None,
+        help='structured counts, e.g. \'{"run":155,"failures":0}\' or \'{"total":3,"passed":3}\'',
+    )
     p_record.set_defaults(func=cmd_record)
 
     p_diff = sub.add_parser(

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "cursor",
-  "coreHash": "7bc40a6254c830f4"
+  "coreHash": "4788a7abe108becd"
 }

package/harness/bundles/general/cursor/contracts/workflow-policy.json

@@ -2,21 +2,21 @@
   "schemaVersion": 1,
   "riskTiers": {
     "fast": {
-      "description": "Low-risk docs/comments/non-behavioral config; no API/DB/security/concurrency.",
+      "description": "Low-risk docs/comments/non-behavioral config; no API/DB/security/concurrency. Policy notes: checkpointRules apply only when meta/implementation-checkpoints.json defines the entry for this change; missing file/entry = disabled (gate must not require --task).",
       "defaultPhases": ["plan", "run", "submit", "archive"],
       "requiredValidations": ["unitTest"],
       "conditionalStages": ["review", "package", "apidoc"],
       "upgradeTriggers": ["api-change", "security", "migration", "concurrency", "breaking-contract"]
     },
     "standard": {
-      "description": "Ordinary production code and non-breaking API/features.",
+      "description": "Ordinary production code and non-breaking API/features. Policy notes: requiredValidations may close DEGRADED when ledger status=NOT_RUN and evidence starts with 'DEGRADED: <reason>' (close code CLOSED_DEGRADED, phase status <= WARN); do not fake OK with unrelated tests.",
       "defaultPhases": ["plan", "run", "test", "submit", "archive"],
       "requiredValidations": ["compile", "unitTest", "unitTestFull"],
       "conditionalStages": ["review", "package", "apidoc"],
       "upgradeTriggers": ["auth", "security", "delete", "migration", "concurrency", "artifact-protocol", "shared-state", "breaking-api"]
     },
     "full": {
-      "description": "Auth/security/delete/migration/concurrency/service protocol/shared state/breaking contracts.",
+      "description": "Auth/security/delete/migration/concurrency/service protocol/shared state/breaking contracts. Policy notes: (1) DEGRADED close — ledger status=NOT_RUN and evidence 'DEGRADED: <reason>' → CLOSED_DEGRADED with phase <= WARN; never fake OK with unrelated tests. (2) checkpointRules — only when plan created meta/implementation-checkpoints.json entry; missing file/entry = not enabled, gate must not require --task.",
       "defaultPhases": ["plan", "run", "test", "review", "submit", "archive"],
       "requiredValidations": ["compile", "unitTest", "unitTestFull", "apiTest"],
       "conditionalStages": ["package", "apidoc"],

package/harness/bundles/general/cursor/harness-archive/SKILL.md

@@ -3,7 +3,7 @@ name: harness-archive
 description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到
   .harness/archive/，含归档元数据和可视化最终总结。使用场景：归档、完成归档、收尾、打包产出物
 ---
-<!-- generated by harness_deploy.py; core=7bc40a6254c830f4; overlay=none; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=4788a7abe108becd; overlay=none; agent=cursor; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -86,8 +86,8 @@ AskUserQuestion 让用户确认归档操作。**用户拒绝 → 终止流程，
 ### Phase 3：执行归档
 
 1. 运行 `python <skills-root>/scripts/harness_archive.py status --change-dir ".harness/changes/<change-name>" --json` 前置检查。
-2. 如需维护者结论，在移动前补全 `meta/archive-meta.md`；不得在 finalize 后修改已校验的归档文件。
-3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ".harness/changes/<change-name>" --archive-root ".harness/archive" --json`；读 JSON（事件、移动、collect、render、validate、manifest 比对）。finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，调用者不得重复追加。**finalize 不再同步执行知识维护**（§8.2）：它写一个 `pending` maintenance-outbox 项即返回，`knowledgeMaintenance=QUEUED`；写 outbox 失败时 `NOT_QUEUED`（warning，不回滚 archive，总状态 CONDITIONAL）。后续由 `harness-sync` / `harness_knowledge.py maintain` 异步推进 outbox。**finalize 失败或 validate 报错时不删除原目录**。
+2. `meta/archive-meta.md` **由 `harness_archive.py finalize` 自动生成**（与 summary-data `finalStatus` 同源）；**禁止 agent 手写**该文件，手写视为数据丢失。维护者结论写入 events（decision/issue）即可，finalize 会汇总到 summary / archive-meta。
+3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ".harness/changes/<change-name>" --archive-root ".harness/archive" --json`；读 JSON（cleanup、事件、移动、collect、render、validate、manifest 比对、archive-meta）。finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，调用者不得重复追加。**finalize 不再同步执行知识维护**（§8.2）：它写一个 `pending` maintenance-outbox 项即返回，`knowledgeMaintenance=QUEUED`；写 outbox 失败时 `NOT_QUEUED`（warning，不回滚 archive，总状态 CONDITIONAL）。后续由 `harness-sync` / `harness_knowledge.py maintain` 异步推进 outbox。**finalize 失败或 validate 报错时不删除原目录**。
 
 - **Read `reference.md`** — finalize 输出字段、archive-meta 格式、CONDITIONAL_OK 规则
 - **Read `templates/summary-data-template.json`** — summary-data 数据结构

package/harness/bundles/general/cursor/harness-archive/reference.md

@@ -11,7 +11,7 @@ description: harness-archive 的归档流程、manifest、summary-data、final-s
 - **Phase 2 确认归档（强制阻断）**：AskUserQuestion 确认，拒绝即终止。
 - **Phase 3 执行归档**：
   1. 运行 `python <skills-root>/scripts/harness_archive.py status --change-dir ... --json` 做前置检查。
-  2. 需要维护者结论时，在移动前补全 `meta/archive-meta.md` 的 `maintenanceNotes` / `knownRisks` / `manualActions`；finalize 后不再修改归档内容。
+  2. `meta/archive-meta.md` 由 finalize 生成（与 summary `finalStatus` 同源）；禁止手写。维护者结论写入 events 即可。finalize 在 before-manifest 前执行 cleanup（删除 lock/pid/launcher/credential，截断超大日志）。
   3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ... --archive-root ".harness/archive" --json`；读 JSON 结果。finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，调用者不得重复追加。**finalize 报错或 validate 失败时不删除原 changes 目录**。
 - **Phase 4 验证与提示**：见 `checklist.md` 归档后验证项。
 
@@ -70,18 +70,26 @@ powershell.exe -NoProfile -Command "& '<node-path>' 'harness-skills/harness-arch
 
 ## archive-meta.md 模板
 
+由 `harness_archive.py finalize` 生成（手写视为数据丢失）。frontmatter 与 summary-data 同源：
+
 ```markdown
-# Archive Meta — <change-name>
-
-- archivedAt: YYYY-MM-DD HH:mm
-- finalCommit: <hash>
-- sourceDir: .harness/changes/<change-name>
-- archiveDir: .harness/archive/YYYY-MM-DD-<change-name>
-- movedFiles: <from manifest>
-- generatedFiles: archive-meta.md, summary-data.json, final-summary.html, manifests
-- totalArchiveFiles: <from after manifest>
+---
+archive-id: YYYY-MM-DD-<change-name>
+change-name: <change-name>
+archived-at: YYYY-MM-DD HH:mm
+final-commit: <hash>
+base-commit: <hash>
+final-status: <OK|WARN|CONDITIONAL_OK|FAIL>   # 与 summary-data.finalStatus 同源
+source: harness-archive
+---
+# 归档元数据 — <change-name>
+## 阶段状态
+## 变更文件
+## 已知风险
 ```
 
+cleanup 步骤（before-manifest 前）：删除 `events.ndjson.lock`、`runtime/*.pid`、launcher、credential/token/secret 文件名；截断 `logs/**/*.log` 超过 64KB 的尾部保留。
+
 ## 目录结构与最终状态规则
 
 - 默认渲染器：`templates/render-summary.mjs`，输入 `reports/final/summary-data.json`，输出 `reports/final/final-summary.html`。