@hunter-harness/workflow-harness 0.2.21 → 0.2.23

package/harness/bundles/general/codebuddy/scripts/harness_archive.py

@@ -331,6 +331,811 @@ def load_ci_metrics(change_dir: Path) -> tuple[dict[str, Any] | None, str | None
     return None, None
 
 
+def _legacy_candidate_path(change_dir: Path) -> Path | None:
+    for relative in (
+        "evidence/product-candidate-ci.json",
+        "meta/product-candidate-ci.json",
+        "runtime/product-candidate-ci.json",
+    ):
+        path = change_dir / relative
+        if path.is_file():
+            return path
+    return None
+
+
+def _remote_ci_history_present(change_dir: Path) -> bool:
+    if _legacy_candidate_path(change_dir) is not None:
+        return True
+    ledger = load_ledger(change_dir) or {}
+    if any(key in ledger for key in ("productCandidateCi", "product_candidate_ci")):
+        return True
+    validations = (
+        ledger.get("validations")
+        if isinstance(ledger.get("validations"), dict)
+        else {}
+    )
+    return any(
+        key in validations
+        for key in ("productCandidateCi", "product_candidate_ci", "candidateCi")
+    )
+
+
+def load_product_candidate_ci(change_dir: Path) -> dict[str, Any] | None:
+    """Load platform-neutral candidate evidence, then legacy CI evidence."""
+    for relative in (
+        "evidence/product-candidate-verification.json",
+        "meta/product-candidate-verification.json",
+        "runtime/product-candidate-verification.json",
+    ):
+        path = change_dir / relative
+        if not path.is_file():
+            continue
+        try:
+            data = read_json(path)
+        except (OSError, json.JSONDecodeError):
+            continue
+        if isinstance(data, dict) and data.get("schemaVersion") == 2:
+            return data
+
+    # Legacy schema remains readable so existing projects do not need an
+    # immediate migration. It represents a remote claim, not an attestation.
+    legacy_path = _legacy_candidate_path(change_dir)
+    if legacy_path is not None:
+        try:
+            data = read_json(legacy_path)
+        except (OSError, json.JSONDecodeError):
+            data = None
+        if isinstance(data, dict) and data.get("schemaVersion") == 1:
+            return data
+    ledger = load_ledger(change_dir) or {}
+    for key in ("productCandidateCi", "product_candidate_ci"):
+        value = ledger.get(key)
+        if isinstance(value, dict):
+            return {"schemaVersion": 1, **value}
+    validations = ledger.get("validations") if isinstance(ledger.get("validations"), dict) else {}
+    for key in ("productCandidateCi", "product_candidate_ci", "candidateCi"):
+        value = validations.get(key) if isinstance(validations, dict) else None
+        if isinstance(value, dict):
+            return {"schemaVersion": 1, **value}
+    return None
+
+
+def evaluate_product_ci_gate(change_dir: Path) -> dict[str, Any]:
+    """Evaluate product-candidate evidence independently of CI availability."""
+    evidence = load_product_candidate_ci(change_dir)
+    if evidence is None:
+        return {
+            "ok": False,
+            "code": "PRODUCT_CI_NOT_GREEN",
+            "message": (
+                "missing product-candidate CI evidence "
+                "(need evidence/product-candidate-ci.json with conclusion=success, "
+                "runUrl, commit)"
+            ),
+            "evidence": None,
+        }
+
+    if evidence.get("schemaVersion") == 2:
+        conclusion = str(evidence.get("conclusion") or "").strip().lower()
+        provider = str(evidence.get("provider") or "").strip()
+        assurance = str(evidence.get("assurance") or "").strip()
+        subject = evidence.get("subject")
+        verification = evidence.get("verification")
+        subject = subject if isinstance(subject, dict) else {}
+        verification = verification if isinstance(verification, dict) else {}
+        product_commit = str(subject.get("productCommit") or "").strip()
+        product_tree_hash = str(subject.get("productTreeHash") or "").strip()
+        command_set_hash = str(verification.get("commandSetHash") or "").strip()
+        ledger_hash = str(verification.get("ledgerHash") or "").strip()
+        common_required_fields = {
+            "provider": provider,
+            "assurance": assurance,
+            "subject.productCommit": product_commit,
+            "subject.productTreeHash": product_tree_hash,
+        }
+        allowed_assurance = {
+            "local-reproducible": 1,
+            "remote-claimed": 2,
+            "remote-attested": 3,
+        }
+        policy = load_gate_policy(change_dir) or {}
+        candidate_policy = policy.get("candidateVerification")
+        candidate_policy = (
+            candidate_policy if isinstance(candidate_policy, dict) else {}
+        )
+        minimum_assurance = str(
+            candidate_policy.get("minimumAssurance") or "local-reproducible"
+        ).strip()
+        if minimum_assurance not in allowed_assurance:
+            minimum_assurance = "local-reproducible"
+        if (
+            provider == "local-harness"
+            and _remote_ci_history_present(change_dir)
+            and not bool(candidate_policy.get("allowLocalFallback"))
+        ):
+            return {
+                "ok": False,
+                "code": "REMOTE_CI_DOWNGRADE_REFUSED",
+                "message": (
+                    "remote CI history exists; local-harness evidence requires "
+                    "candidateVerification.allowLocalFallback=true"
+                ),
+                "assurance": assurance,
+                "evidence": evidence,
+            }
+        if provider == "local-harness":
+            local_required = {
+                "verification.commandSetHash": command_set_hash,
+                "verification.ledgerHash": ledger_hash,
+                "verification.toolchainHashes": verification.get("toolchainHashes"),
+                "verification.environmentHashes": verification.get("environmentHashes"),
+                "verification.dependencyHashes": verification.get("dependencyHashes"),
+                "verification.logHashes": verification.get("logHashes"),
+            }
+            required_fields = {**common_required_fields, **local_required}
+        elif provider == "remote-ci":
+            attestation = evidence.get("attestation")
+            attestation = attestation if isinstance(attestation, dict) else {}
+            if assurance == "remote-attested":
+                remote_identity_name = "verification.attestationDigest"
+                remote_identity = verification.get("attestationDigest")
+            else:
+                remote_identity_name = "verification.remoteIdentity"
+                remote_identity = (
+                    verification.get("legacyEvidenceHash") or ledger_hash
+                )
+            required_fields = {
+                **common_required_fields,
+                "attestation.url": attestation.get("url"),
+                remote_identity_name: remote_identity,
+            }
+        else:
+            required_fields = common_required_fields
+        missing = [name for name, value in required_fields.items() if not value]
+        if conclusion not in {
+            "success",
+            "successful",
+            "passed",
+            "pass",
+            "green",
+            "ok",
+        }:
+            return {
+                "ok": False,
+                "code": "PRODUCT_CANDIDATE_NOT_VERIFIED",
+                "message": (
+                    f"product candidate conclusion={conclusion or 'unknown'} "
+                    f"provider={provider or 'unknown'}"
+                ),
+                "assurance": assurance,
+                "evidence": evidence,
+            }
+        if missing or assurance not in allowed_assurance:
+            detail = ", ".join(missing) if missing else f"assurance={assurance}"
+            return {
+                "ok": False,
+                "code": "PRODUCT_CANDIDATE_NOT_VERIFIED",
+                "message": f"candidate evidence missing or invalid: {detail}",
+                "assurance": assurance,
+                "evidence": evidence,
+            }
+        if allowed_assurance[assurance] < allowed_assurance[minimum_assurance]:
+            return {
+                "ok": False,
+                "code": "PRODUCT_CANDIDATE_NOT_VERIFIED",
+                "message": (
+                    f"candidate assurance={assurance} is below required "
+                    f"minimumAssurance={minimum_assurance}"
+                ),
+                "assurance": assurance,
+                "evidence": evidence,
+            }
+        return {
+            "ok": True,
+            "code": "PRODUCT_CANDIDATE_VERIFIED",
+            "message": (
+                f"product candidate verified provider={provider} "
+                f"assurance={assurance} commit={product_commit}"
+            ),
+            "assurance": assurance,
+            "evidence": evidence,
+        }
+
+    conclusion = str(
+        evidence.get("conclusion") or evidence.get("status") or ""
+    ).strip().lower()
+    run_url = str(evidence.get("runUrl") or evidence.get("url") or "").strip()
+    commit = str(evidence.get("commit") or evidence.get("headSha") or "").strip()
+    if conclusion in {"success", "successful", "passed", "pass", "green", "ok"}:
+        # Review Y1: success alone is insufficient — runUrl + commit are required.
+        if not run_url or not commit:
+            return {
+                "ok": False,
+                "code": "PRODUCT_CI_NOT_GREEN",
+                "message": (
+                    "product candidate CI conclusion is success but missing "
+                    f"runUrl={run_url or 'empty'} commit={commit or 'empty'}"
+                ),
+                "evidence": evidence,
+            }
+        return {
+            "ok": True,
+            "code": "PRODUCT_CI_GREEN",
+            "message": f"product candidate CI green commit={commit} url={run_url}",
+            "evidence": evidence,
+        }
+    return {
+        "ok": False,
+        "code": "PRODUCT_CI_NOT_GREEN",
+        "message": (
+            f"product candidate CI conclusion={conclusion or 'unknown'} "
+            f"commit={commit or 'unknown'} runUrl={run_url or 'unknown'}"
+        ),
+        "evidence": evidence,
+    }
+
+
+def _candidate_value_hash(value: Any) -> str:
+    encoded = json.dumps(
+        value, ensure_ascii=False, sort_keys=True, separators=(",", ":")
+    ).encode("utf-8")
+    return f"sha256:{hashlib.sha256(encoded).hexdigest()}"
+
+
+def _candidate_evidence_hash(change_dir: Path, value: Any) -> str:
+    if isinstance(value, str) and value.strip():
+        raw = Path(value.strip())
+        candidate = raw if raw.is_absolute() else change_dir / raw
+        try:
+            resolved = candidate.resolve()
+            resolved.relative_to(change_dir.resolve())
+        except (OSError, ValueError):
+            resolved = None
+        if resolved is not None and resolved.is_file():
+            return f"sha256:{sha256_file(resolved)}"
+    return _candidate_value_hash(value)
+
+
+def migrate_legacy_candidate_evidence(
+    change_dir: Path,
+    *,
+    project: Path | None = None,
+) -> dict[str, Any]:
+    """Convert legacy CI JSON into an explicit remote-claimed v2 receipt."""
+    change_dir = change_dir.resolve()
+    legacy_path = _legacy_candidate_path(change_dir)
+    if legacy_path is None:
+        raise ValueError("legacy product-candidate-ci.json missing")
+    legacy = read_json(legacy_path)
+    if not isinstance(legacy, dict) or legacy.get("schemaVersion") != 1:
+        raise ValueError("legacy product-candidate-ci.json is invalid")
+    conclusion = str(
+        legacy.get("conclusion") or legacy.get("status") or ""
+    ).strip().lower()
+    commit = str(legacy.get("commit") or legacy.get("headSha") or "").strip()
+    run_url = str(legacy.get("runUrl") or legacy.get("url") or "").strip()
+    if conclusion not in {
+        "success",
+        "successful",
+        "passed",
+        "pass",
+        "green",
+        "ok",
+    }:
+        raise ValueError(f"legacy CI conclusion is not successful: {conclusion}")
+    if not commit or not run_url:
+        raise ValueError("legacy CI evidence requires commit and runUrl")
+    project_root = (project or find_project_root(change_dir)).resolve()
+    tree_detail = compute_product_tree_hash_detail(project_root)
+    if tree_detail.get("truncated"):
+        raise ValueError("product tree hash truncated during legacy migration")
+    receipt = {
+        "schemaVersion": 2,
+        "provider": "remote-ci",
+        "conclusion": "success",
+        "assurance": "remote-claimed",
+        "recordedAt": now_iso(),
+        "subject": {
+            "productCommit": commit,
+            "productTreeHash": f"sha256:{tree_detail['hash']}",
+        },
+        "attestation": {
+            "url": run_url,
+            "source": "legacy-product-candidate-ci",
+        },
+        "verification": {
+            "legacyEvidenceHash": f"sha256:{sha256_file(legacy_path)}",
+        },
+        "migration": {
+            "fromSchemaVersion": 1,
+            "sourcePath": legacy_path.relative_to(change_dir).as_posix(),
+        },
+    }
+    write_json(
+        change_dir / "evidence" / "product-candidate-verification.json",
+        receipt,
+    )
+    return receipt
+
+
+def certify_local_candidate(
+    change_dir: Path,
+    *,
+    project: Path | None = None,
+) -> dict[str, Any]:
+    """Create a reproducible local receipt from existing ledger evidence.
+
+    This function never executes verification commands. It deliberately reuses
+    only complete, successful ledger entries so submit/archive do not rerun an
+    identical full suite merely to produce candidate evidence.
+    """
+    change_dir = change_dir.resolve()
+    project_root = (project or find_project_root(change_dir)).resolve()
+    ledger = load_ledger(change_dir)
+    if not isinstance(ledger, dict):
+        raise ValueError("verification ledger missing")
+    validations = ledger.get("validations")
+    if not isinstance(validations, dict):
+        raise ValueError("verification ledger validations missing")
+
+    policy = load_gate_policy(change_dir) or {}
+    candidate_policy = policy.get("candidateVerification")
+    candidate_policy = (
+        candidate_policy if isinstance(candidate_policy, dict) else {}
+    )
+    if (
+        _remote_ci_history_present(change_dir)
+        and not bool(candidate_policy.get("allowLocalFallback"))
+    ):
+        raise ValueError(
+            "remote CI history exists; refusing silent local fallback "
+            "(set candidateVerification.allowLocalFallback=true explicitly)"
+        )
+    required = candidate_policy.get("requiredValidations")
+    if not isinstance(required, list) or not required:
+        required = ["unitTestFull"]
+    required = [str(item).strip() for item in required if str(item).strip()]
+
+    selected: list[dict[str, Any]] = []
+    for name in required:
+        entry = validations.get(name)
+        if not isinstance(entry, dict):
+            raise ValueError(f"required validation missing: {name}")
+        missing: list[str] = []
+        if str(entry.get("status") or "").upper() != "OK":
+            missing.append("status=OK")
+        for field in (
+            "command",
+            "evidence",
+            "inputsHash",
+            "toolchainHash",
+            "environmentHash",
+        ):
+            if entry.get(field) in (None, "", [], {}):
+                missing.append(field)
+        if missing:
+            raise ValueError(
+                f"required validation {name} is incomplete: {', '.join(missing)}"
+            )
+        selected.append(
+            {
+                "name": name,
+                "command": entry.get("command"),
+                "inputsHash": entry.get("inputsHash"),
+                "toolchainHash": entry.get("toolchainHash"),
+                "environmentHash": entry.get("environmentHash"),
+                "logHash": _candidate_evidence_hash(
+                    change_dir, entry.get("evidence")
+                ),
+            }
+        )
+
+    ledger_path = next(
+        (
+            change_dir / relative
+            for relative in (
+                "evidence/verification-ledger.json",
+                "verification-ledger.json",
+            )
+            if (change_dir / relative).is_file()
+        ),
+        None,
+    )
+    if ledger_path is None:
+        raise ValueError("verification ledger path missing")
+
+    product_commit = str(
+        ledger.get("productCommit")
+        or ledger.get("currentHead")
+        or ledger.get("finalCommit")
+        or ""
+    ).strip()
+    rc, current_head, _stderr = git_run(project_root, "rev-parse", "HEAD")
+    if rc == 0 and current_head:
+        if product_commit and not (
+            current_head.startswith(product_commit)
+            or product_commit.startswith(current_head)
+        ):
+            raise ValueError(
+                "product commit is stale: "
+                f"ledger={product_commit} current={current_head}"
+            )
+        product_commit = current_head
+    if not product_commit:
+        raise ValueError("product commit unavailable")
+
+    detail = compute_product_tree_hash_detail(project_root)
+    if detail.get("truncated"):
+        raise ValueError(
+            "product tree hash truncated; narrow the project or raise the explicit limit"
+        )
+    current_tree_hash = f"sha256:{detail['hash']}"
+    recorded_tree_hash = str(ledger.get("productTreeHash") or "").strip()
+    if recorded_tree_hash and recorded_tree_hash.removeprefix(
+        "sha256:"
+    ) != current_tree_hash.removeprefix("sha256:"):
+        raise ValueError(
+            "product tree is stale: "
+            f"ledger={recorded_tree_hash} current={current_tree_hash}"
+        )
+    product_tree_hash = current_tree_hash
+
+    receipt = {
+        "schemaVersion": 2,
+        "provider": "local-harness",
+        "conclusion": "success",
+        "assurance": "local-reproducible",
+        "recordedAt": now_iso(),
+        "subject": {
+            "productCommit": product_commit,
+            "productTreeHash": product_tree_hash,
+        },
+        "verification": {
+            "requiredValidations": required,
+            "reusedValidations": [item["name"] for item in selected],
+            "commandSetHash": _candidate_value_hash(
+                [item["command"] for item in selected]
+            ),
+            "ledgerHash": f"sha256:{sha256_file(ledger_path)}",
+            "toolchainHashes": sorted(
+                {str(item["toolchainHash"]) for item in selected}
+            ),
+            "environmentHashes": sorted(
+                {str(item["environmentHash"]) for item in selected}
+            ),
+            "dependencyHashes": sorted(
+                {str(item["inputsHash"]) for item in selected}
+            ),
+            "logHashes": sorted({str(item["logHash"]) for item in selected}),
+        },
+    }
+    write_json(
+        change_dir / "evidence" / "product-candidate-verification.json",
+        receipt,
+    )
+    return receipt
+
+
+PRODUCT_TREE_HASH_FILE_LIMIT = 20_000
+
+
+def compute_product_tree_hash_detail(
+    project: Path,
+    *,
+    file_limit: int = PRODUCT_TREE_HASH_FILE_LIMIT,
+) -> dict[str, Any]:
+    """Hash product tree excluding .harness/**; report truncation metadata (Y3)."""
+    project = project.resolve()
+    skip_dirs = {
+        ".harness",
+        ".git",
+        ".worktrees",
+        "node_modules",
+        ".next",
+        "dist",
+        "coverage",
+        "__pycache__",
+        ".venv",
+        "venv",
+    }
+    limit = max(1, int(file_limit))
+    lines: list[str] = []
+    truncated = False
+    for root, dirs, files in os.walk(project, onerror=lambda _exc: None):
+        dirs[:] = [name for name in dirs if name not in skip_dirs]
+        for name in sorted(files):
+            path = Path(root) / name
+            try:
+                rel = path.relative_to(project).as_posix()
+            except ValueError:
+                continue
+            try:
+                digest = sha256_file(path)
+            except OSError:
+                continue
+            lines.append(f"{rel}:{digest}")
+            if len(lines) >= limit:
+                truncated = True
+                break
+        if truncated:
+            break
+    digest = hashlib.sha256("\n".join(lines).encode("utf-8")).hexdigest()
+    return {
+        "hash": digest,
+        "truncated": truncated,
+        "fileCount": len(lines),
+        "limit": limit,
+    }
+
+
+def compute_product_tree_hash(
+    project: Path,
+    *,
+    file_limit: int = PRODUCT_TREE_HASH_FILE_LIMIT,
+) -> str:
+    """Hash product tree excluding .harness/** governance paths."""
+    return str(compute_product_tree_hash_detail(project, file_limit=file_limit)["hash"])
+
+
+def resolve_product_archive_identity(
+    change_dir: Path,
+    *,
+    project: Path | None = None,
+    product_commit: str | None = None,
+    archive_commit: str | None = None,
+) -> dict[str, Any]:
+    """Resolve the three-way archive identity fields for summary/meta."""
+    change_dir = change_dir.resolve()
+    project_root = (project or find_project_root(change_dir)).resolve()
+    ledger = load_ledger(change_dir) or {}
+    ci = load_product_candidate_ci(change_dir) or {}
+    candidate_subject = (
+        ci.get("subject") if isinstance(ci.get("subject"), dict) else {}
+    )
+    product = (
+        product_commit
+        or ledger.get("productCommit")
+        or candidate_subject.get("productCommit")
+        or ci.get("commit")
+        or ledger.get("finalCommit")
+        or ""
+    )
+    archive = (
+        archive_commit
+        or ledger.get("archiveCommit")
+        or ledger.get("finalCommit")
+        or product
+    )
+    tree = str(ledger.get("productTreeHash") or "")
+    under_harness = False
+    try:
+        change_dir.relative_to(project_root / ".harness")
+        under_harness = True
+    except ValueError:
+        under_harness = False
+    tree_meta: dict[str, Any] = {
+        "truncated": False,
+        "fileCount": 0,
+        "limit": PRODUCT_TREE_HASH_FILE_LIMIT,
+    }
+    if not tree:
+        if under_harness:
+            try:
+                tree_meta = compute_product_tree_hash_detail(project_root)
+                tree = str(tree_meta["hash"])
+            except OSError:
+                tree = hashlib.sha256(b"").hexdigest()
+        else:
+            # Bare temp fixtures are not real project roots — avoid scanning up-tree.
+            tree = hashlib.sha256(b"fixture-no-product-tree").hexdigest()
+    identity = {
+        "productCommit": str(product),
+        "productTreeHash": str(tree),
+        "archiveCommit": str(archive),
+        "productTreeHashTruncated": bool(tree_meta.get("truncated")),
+        "productTreeHashFileCount": int(tree_meta.get("fileCount") or 0),
+    }
+    expected_tree = tree
+    if under_harness:
+        try:
+            expected_meta = compute_product_tree_hash_detail(project_root)
+            expected_tree = str(expected_meta["hash"])
+            identity["productTreeHashTruncated"] = bool(expected_meta.get("truncated"))
+            identity["productTreeHashFileCount"] = int(expected_meta.get("fileCount") or 0)
+        except OSError:
+            expected_tree = tree
+    identity["validation"] = validate_product_identity(
+        product_commit=identity["productCommit"],
+        product_tree_hash=identity["productTreeHash"],
+        archive_commit=identity["archiveCommit"] or "unknown",
+        project=project_root if under_harness else None,
+        expected_tree_hash=expected_tree if under_harness else tree,
+    )
+    return identity
+
+
+def validate_product_identity(
+    *,
+    product_commit: str,
+    product_tree_hash: str,
+    archive_commit: str,
+    project: Path | None = None,
+    expected_tree_hash: str | None = None,
+) -> dict[str, Any]:
+    """Validate productCommit/productTreeHash/archiveCommit relationship."""
+    if not product_commit or not product_tree_hash or not archive_commit:
+        return {
+            "ok": False,
+            "code": "PRODUCT_IDENTITY_INCOMPLETE",
+            "message": "productCommit, productTreeHash, and archiveCommit are required",
+        }
+    expected = expected_tree_hash
+    if expected is None and project is not None:
+        expected = compute_product_tree_hash(project)
+    if expected is not None and str(product_tree_hash) != str(expected):
+        return {
+            "ok": False,
+            "code": "PRODUCT_TREE_HASH_MISMATCH",
+            "message": (
+                f"productTreeHash={product_tree_hash} does not match "
+                f"product tree={expected} for productCommit={product_commit}"
+            ),
+            "expected": expected,
+            "actual": product_tree_hash,
+        }
+    return {
+        "ok": True,
+        "code": "PRODUCT_IDENTITY_OK",
+        "productCommit": product_commit,
+        "productTreeHash": product_tree_hash,
+        "archiveCommit": archive_commit,
+    }
+
+
+def evaluate_release_evidence(
+    archived_identity: dict[str, Any],
+    *,
+    current_product_tree_hash: str,
+) -> dict[str, Any]:
+    """Old archive cannot remain release evidence after product inputs change."""
+    archived_tree = str(archived_identity.get("productTreeHash") or "")
+    if not archived_tree:
+        return {
+            "ok": False,
+            "code": "ARCHIVE_EVIDENCE_REOPEN_REQUIRED",
+            "message": "archived productTreeHash missing; reopen required",
+        }
+    if archived_tree != str(current_product_tree_hash):
+        return {
+            "ok": False,
+            "code": "ARCHIVE_EVIDENCE_REOPEN_REQUIRED",
+            "message": (
+                "product inputs changed since archive; "
+                f"archivedTree={archived_tree} currentTree={current_product_tree_hash}"
+            ),
+            "archivedProductTreeHash": archived_tree,
+            "currentProductTreeHash": current_product_tree_hash,
+        }
+    return {
+        "ok": True,
+        "code": "ARCHIVE_EVIDENCE_CURRENT",
+        "productTreeHash": archived_tree,
+    }
+
+
+def build_workflow_timing(
+    events: list[dict[str, Any]],
+    *,
+    report_cutoff_at: str | None = None,
+) -> dict[str, Any]:
+    """Formal multi-semantic timing object (IA-2 / IA-6)."""
+    stamps = [e.get("timestamp") for e in events if e.get("timestamp")]
+    started = str(stamps[0]) if stamps else None
+    cutoff = report_cutoff_at or (str(stamps[-1]) if stamps else None)
+    stage_active = 0
+    stage_wall = 0
+    unclosed = 0
+    for _phase, phase_events in he.group_events_by_phase(events):
+        timing = he.canonical_phase_timing(phase_events, cutoff_ts=cutoff)
+        stage_active += int(timing.get("activeExecutionMs") or 0)
+        stage_wall += int(timing.get("wallClockSpanMs") or 0)
+        unclosed += int(timing.get("unclosedAttemptCount") or 0)
+    workflow_wall = he.duration_ms_between(started, cutoff) if started and cutoff else 0
+    external = 0
+    for event in events:
+        etype = str(event.get("type") or "").lower()
+        if etype in {"external.wait", "ci.wait", "environment.wait", "env.wait"}:
+            dur = event.get("duration_ms") or event.get("durationMs")
+            if isinstance(dur, int):
+                external += max(0, dur)
+            elif event.get("timestamp") and event.get("endedAt"):
+                gap = he.duration_ms_between(event.get("timestamp"), event.get("endedAt"))
+                if gap:
+                    external += gap
+    unattributed = max(0, int(workflow_wall or 0) - stage_active - external)
+    post_archive_excluded = 0
+    if cutoff:
+        for event in events:
+            if str(event.get("phase") or "").lower() != "archive":
+                continue
+            ts = event.get("timestamp")
+            if ts and he.duration_ms_between(cutoff, ts) and he.duration_ms_between(cutoff, ts) > 0:
+                # timestamp after cutoff
+                start_dt = he.parse_timestamp(cutoff)
+                end_dt = he.parse_timestamp(ts)
+                if start_dt and end_dt and end_dt > start_dt:
+                    post_archive_excluded += 1
+    return {
+        "workflowStartedAt": started or NOT_AVAILABLE,
+        "reportCutoffAt": cutoff or NOT_AVAILABLE,
+        "workflowWallClockMs": int(workflow_wall or 0),
+        "stageActiveExecutionMs": int(stage_active),
+        "stageWallClockSpanMs": int(stage_wall),
+        "externalWaitMs": int(external),
+        "agentOrToolUnattributedMs": int(unattributed),
+        "unclosedAttemptCount": int(unclosed),
+        "postArchiveEventsExcluded": int(post_archive_excluded),
+        "totalMinutesSemantics": "active-only",
+    }
+
+
+def verify_manifest_byte_coverage(
+    root: Path,
+    manifest: dict[str, Any],
+    *,
+    exclude_paths: list[str] | None = None,
+    exclusion_reasons: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    """Verify every covered manifest entry still matches on-disk bytes (IA-7)."""
+    root = root.resolve()
+    excluded = {
+        p.replace("\\", "/") for p in (exclude_paths or [])
+    }
+    reasons = {
+        k.replace("\\", "/"): v for k, v in (exclusion_reasons or {}).items()
+    }
+    mismatches: list[dict[str, str]] = []
+    checked = 0
+    for item in manifest.get("files") or []:
+        if not isinstance(item, dict):
+            continue
+        rel = str(item.get("path") or "").replace("\\", "/")
+        if not rel or _manifest_path_excluded(rel):
+            continue
+        if rel in excluded:
+            reasons.setdefault(rel, "excluded from checksum coverage")
+            continue
+        path = root / rel
+        if not path.is_file():
+            mismatches.append({"path": rel, "reason": "missing"})
+            continue
+        actual = sha256_file(path)
+        expected = str(item.get("sha256") or "")
+        checked += 1
+        if actual != expected:
+            mismatches.append(
+                {
+                    "path": rel,
+                    "reason": "hash-mismatch",
+                    "expected": expected,
+                    "actual": actual,
+                }
+            )
+    ok = not mismatches
+    if ok and reasons:
+        checksum_status = "OK_WITH_EXCLUSIONS"
+    elif ok:
+        checksum_status = "OK"
+    else:
+        checksum_status = "FAIL"
+    return {
+        "ok": ok,
+        "checksumStatus": checksum_status,
+        "checked": checked,
+        "mismatched": mismatches,
+        "exclusionReasons": reasons,
+    }
+
 def load_execution_log(change_dir: Path) -> str:
     for rel in ("logs/execution-log.md", "execution-log.md"):
         path = change_dir / rel
@@ -491,8 +1296,13 @@ def check_status(
     change_dir: Path,
     *,
     allow_missing_review: bool = False,
+    archive_intent: str = "release-candidate",
 ) -> dict[str, Any]:
     """Read-only archive preconditions. Never mutates."""
+    if archive_intent not in {"release-candidate", "record-only"}:
+        raise ValueError(
+            "archive_intent must be release-candidate or record-only"
+        )
     blockers: list[dict[str, str]] = []
     warnings: list[dict[str, str]] = []
     checks: dict[str, Any] = {}
@@ -501,6 +1311,7 @@ def check_status(
         return {
             "ok": False,
             "archivable": False,
+            "releaseEligible": False,
             "change_dir": str(change_dir),
             "blockers": [{"code": "missing-change-dir", "message": f"not found: {change_dir}"}],
             "warnings": [],
@@ -731,6 +1542,31 @@ def check_status(
             else:
                 blockers.append(tier_issue)
 
+    # Candidate verification is a release gate, not an archive-integrity fact.
+    # A record-only archive may persist incomplete work but can never claim
+    # release eligibility.
+    ci_gate = evaluate_product_ci_gate(change_dir)
+    checks["product_candidate_ci"] = {
+        "ok": bool(ci_gate.get("ok")),
+        "code": ci_gate.get("code"),
+        "evidence": ci_gate.get("evidence"),
+    }
+    if not ci_gate.get("ok"):
+        candidate_issue = {
+            "code": (
+                "PRODUCT_CANDIDATE_NOT_VERIFIED"
+                if archive_intent == "record-only"
+                else str(ci_gate.get("code") or "PRODUCT_CANDIDATE_NOT_VERIFIED")
+            ),
+            "message": str(
+                ci_gate.get("message") or "product candidate not verified"
+            ),
+        }
+        if archive_intent == "record-only":
+            warnings.append(candidate_issue)
+        else:
+            blockers.append(candidate_issue)
+
     # --- artifact preflight (retro §5.31) ---
     # Classify artifact events before destructive finalize: informational (OK),
     # canonicalizable (same-change repo-relative path, warning), or blocking
@@ -760,9 +1596,20 @@ def check_status(
             })
 
     archivable = len(blockers) == 0
+    candidate_codes = {
+        "PRODUCT_CI_NOT_GREEN",
+        "PRODUCT_CANDIDATE_NOT_VERIFIED",
+    }
+    archive_integrity_ok = not any(
+        item.get("code") not in candidate_codes for item in blockers
+    )
     return {
         "ok": True,
         "archivable": archivable,
+        "archiveIntent": archive_intent,
+        "archiveIntegrity": {"ok": archive_integrity_ok},
+        "candidateVerification": ci_gate,
+        "releaseEligible": bool(ci_gate.get("ok")) and archivable,
         "change_dir": str(change_dir),
         "change_name": infer_change_name(change_dir),
         "blockers": blockers,
@@ -1315,10 +2162,17 @@ def _durations_from_event_phases(
     events: list[dict[str, Any]] | None = None,
 ) -> dict[str, Any]:
     # Canonical per-phase timing (UT-008/RET-20): one reducer feeds every view.
+    # totalMinutes remains active-only (IA-2); use top-level timing for wall clock.
+    cutoff = None
+    if events:
+        stamps = [e.get("timestamp") for e in events if e.get("timestamp")]
+        cutoff = str(stamps[-1]) if stamps else None
     canonical: dict[str, dict[str, Any]] = {}
     if events:
         for phase_name, phase_events in he.group_events_by_phase(events):
-            canonical[phase_name] = he.canonical_phase_timing(phase_events)
+            canonical[phase_name] = he.canonical_phase_timing(
+                phase_events, cutoff_ts=cutoff
+            )
     stages: list[dict[str, Any]] = []
     total_ms = 0
     for name, info in (event_summary.get("phases") or {}).items():
@@ -1338,6 +2192,7 @@ def _durations_from_event_phases(
             "startedAt": info.get("started_at") or NOT_AVAILABLE,
             "endedAt": info.get("ended_at") or NOT_AVAILABLE,
             "minutes": minutes,
+            "minutesSemantics": "active-only",
             "result": result,
             "attempts": attempts,
         }
@@ -1346,11 +2201,13 @@ def _durations_from_event_phases(
             stage["activeExecutionMs"] = timing.get("activeExecutionMs")
             stage["wallClockSpanMs"] = timing.get("wallClockSpanMs")
             stage["lateEventCount"] = timing.get("lateEventCount")
+            stage["unclosedAttemptCount"] = timing.get("unclosedAttemptCount")
         stages.append(stage)
     total_min = round(total_ms / 60000, 2)
     return {
-        "totalLabel": f"约 {int(round(total_min))} 分",
+        "totalLabel": f"约 {int(round(total_min))} 分（活动执行）",
         "totalMinutes": total_min,
+        "totalMinutesSemantics": "active-only",
         "stages": stages,
     }
 
@@ -1950,6 +2807,10 @@ def collect_summary_data(
             "maintenanceNotes",
             "knownRisks",
             "manualActions",
+            "archiveIntent",
+            "archiveIntegrity",
+            "candidateVerification",
+            "releaseEligible",
         ):
             if key in existing:
                 data[key] = _deepcopy_json(existing[key])
@@ -2049,21 +2910,81 @@ def collect_summary_data(
 
     gate_policy = load_gate_policy(change_dir)
     data["riskTier"] = str((gate_policy or {}).get("tier") or "unknown")
+    intent_path = change_dir / "meta" / "archive-intent.json"
+    intent_data: dict[str, Any] = {}
+    if intent_path.is_file():
+        try:
+            loaded_intent = read_json(intent_path)
+            intent_data = loaded_intent if isinstance(loaded_intent, dict) else {}
+            sources.append("meta/archive-intent.json")
+        except (OSError, json.JSONDecodeError):
+            intent_data = {}
+    candidate_gate = evaluate_product_ci_gate(change_dir)
+    data["archiveIntent"] = str(
+        intent_data.get("intent") or "release-candidate"
+    )
+    data["archiveIntegrity"] = {"ok": True}
+    data["candidateVerification"] = candidate_gate
+    data["releaseEligible"] = bool(candidate_gate.get("ok"))
 
     # durations / skillCalls
     if events:
         data["durations"] = _durations_from_event_phases(event_summary, events)
         data["skillCalls"] = _skill_calls_from_stages(data["durations"].get("stages") or [])
+        stamps = [e.get("timestamp") for e in projected_events if e.get("timestamp")]
+        cutoff = str(stamps[-1]) if stamps else None
+        data["timing"] = build_workflow_timing(projected_events, report_cutoff_at=cutoff)
     elif log_text and (not for_replay or not data.get("durations")):
         data["durations"] = _parse_durations_from_log(log_text)
         data["skillCalls"] = _skill_calls_from_stages(data["durations"].get("stages") or [])
+        data.setdefault(
+            "timing",
+            {
+                "workflowStartedAt": NOT_AVAILABLE,
+                "reportCutoffAt": NOT_AVAILABLE,
+                "workflowWallClockMs": 0,
+                "stageActiveExecutionMs": int(
+                    round(float(data["durations"].get("totalMinutes") or 0) * 60000)
+                ),
+                "stageWallClockSpanMs": 0,
+                "externalWaitMs": 0,
+                "agentOrToolUnattributedMs": 0,
+                "unclosedAttemptCount": 0,
+                "postArchiveEventsExcluded": 0,
+                "totalMinutesSemantics": "active-only",
+            },
+        )
     elif not data.get("durations"):
         data["durations"] = {
             "totalLabel": NOT_AVAILABLE,
             "totalMinutes": 0,
+            "totalMinutesSemantics": "active-only",
             "stages": [],
         }
         data["skillCalls"] = []
+        data.setdefault(
+            "timing",
+            {
+                "workflowStartedAt": NOT_AVAILABLE,
+                "reportCutoffAt": NOT_AVAILABLE,
+                "workflowWallClockMs": 0,
+                "stageActiveExecutionMs": 0,
+                "stageWallClockSpanMs": 0,
+                "externalWaitMs": 0,
+                "agentOrToolUnattributedMs": 0,
+                "unclosedAttemptCount": 0,
+                "postArchiveEventsExcluded": 0,
+                "totalMinutesSemantics": "active-only",
+            },
+        )
+
+    # IA-1/4 identity (product vs archive)
+    if not for_replay:
+        identity = resolve_product_archive_identity(change_dir, project=project)
+        data["productCommit"] = identity.get("productCommit") or data.get("finalCommit")
+        data["productTreeHash"] = identity.get("productTreeHash")
+        data["archiveCommit"] = identity.get("archiveCommit") or data.get("finalCommit")
+        data["changeIdentity"] = identity
 
     # diffStat / changedFiles
     if not for_replay or not data.get("changedFiles"):
@@ -2305,6 +3226,33 @@ def render_fallback_html(summary: dict[str, Any]) -> str:
     if summary.get("riskTier"):
         parts.append(f"<p><strong>riskTier</strong>: {esc(summary.get('riskTier'))}</p>")
 
+    timing = summary.get("timing") if isinstance(summary.get("timing"), dict) else {}
+    if timing:
+        parts.append("<h3>Timing</h3>")
+        parts.append(
+            "<p id=\"timingColumns\">"
+            f"stageActiveExecution={esc(timing.get('stageActiveExecutionMs'))} · "
+            f"stageWallClockSpan={esc(timing.get('stageWallClockSpanMs'))} · "
+            f"workflowWallClock={esc(timing.get('workflowWallClockMs'))}"
+            "</p>"
+        )
+        parts.append(
+            f"<p><strong>reportCutoffAt</strong>: "
+            f"<span id=\"reportCutoffAt\">{esc(timing.get('reportCutoffAt'))}</span></p>"
+        )
+        parts.append(
+            "<p><small>durations.totalMinutes is active-only; "
+            "do not treat it as workflow wall clock.</small></p>"
+        )
+
+    if summary.get("productCommit") or summary.get("productTreeHash"):
+        parts.append("<h3>Identity</h3>")
+        parts.append(
+            f"<p>productCommit={esc(summary.get('productCommit'))} "
+            f"productTreeHash={esc(summary.get('productTreeHash'))} "
+            f"archiveCommit={esc(summary.get('archiveCommit'))}</p>"
+        )
+
     pipeline = summary.get("reportPipeline") or {}
     cmds = pipeline.get("commands") or []
     parts.append("<h3>Commands</h3><ul>")
@@ -3240,8 +4188,15 @@ def cmd_finalize(
     *,
     skip_ingest: bool = False,
     allow_missing_review: bool = False,
+    archive_intent: str = "release-candidate",
 ) -> tuple[int, dict[str, Any]]:
     """Execute the 9-step finalize pipeline. Returns (exit_code, payload)."""
+    if archive_intent not in {"release-candidate", "record-only"}:
+        return 1, {
+            "ok": False,
+            "action": "finalize",
+            "error": "archive_intent must be release-candidate or record-only",
+        }
     warnings: list[str] = []
     original_change_dir = change_dir.resolve()
     change_name = original_change_dir.name
@@ -3307,6 +4262,8 @@ def cmd_finalize(
         "operationId": operation_id,
         "operationTempDir": str(operation_temp_dir),
         "operationRecord": str(operation_record),
+        "archiveIntent": archive_intent,
+        "releaseEligible": False,
         "warnings": warnings,
         "steps": {},
     }
@@ -3458,6 +4415,65 @@ def cmd_finalize(
         payload["ok"] = False
         return 1, payload
 
+    # --- 2d. product candidate verification / release eligibility ---
+    if (
+        not (
+            work_dir / "evidence" / "product-candidate-verification.json"
+        ).is_file()
+        and _legacy_candidate_path(work_dir) is not None
+    ):
+        try:
+            migrated = migrate_legacy_candidate_evidence(
+                work_dir, project=project_root
+            )
+            payload["steps"]["candidate_evidence_migration"] = {
+                "ok": True,
+                "provider": migrated.get("provider"),
+                "assurance": migrated.get("assurance"),
+            }
+        except (OSError, ValueError, json.JSONDecodeError) as exc:
+            payload["steps"]["candidate_evidence_migration"] = {
+                "ok": False,
+                "error": str(exc),
+            }
+            warnings.append(f"legacy candidate evidence migration failed: {exc}")
+    ci_gate = evaluate_product_ci_gate(work_dir)
+    payload["steps"]["product_candidate_ci"] = {
+        "ok": bool(ci_gate.get("ok")),
+        "code": ci_gate.get("code"),
+        "message": ci_gate.get("message"),
+    }
+    payload["candidateVerification"] = ci_gate
+    payload["releaseEligible"] = bool(ci_gate.get("ok"))
+    if not ci_gate.get("ok") and archive_intent == "release-candidate":
+        payload["error"] = str(ci_gate.get("message") or "PRODUCT_CI_NOT_GREEN")
+        payload["issues"] = [
+            {
+                "code": "PRODUCT_CI_NOT_GREEN",
+                "severity": "error",
+                "message": str(ci_gate.get("message") or "product candidate CI not green"),
+            }
+        ]
+        _restore_finalize_failure()
+        payload["warnings"] = warnings
+        payload["ok"] = False
+        return 1, payload
+    if not ci_gate.get("ok"):
+        warnings.append(
+            "record-only archive is not release eligible: "
+            + str(ci_gate.get("message") or "product candidate not verified")
+        )
+    write_json(
+        work_dir / "meta" / "archive-intent.json",
+        {
+            "schemaVersion": 1,
+            "intent": archive_intent,
+            "candidateVerificationCode": ci_gate.get("code"),
+            "releaseEligible": bool(ci_gate.get("ok")),
+            "recordedAt": now_iso(),
+        },
+    )
+
     # --- 3. candidate phase.end + freeze cutoff (RET-19 freeze-first) ---
     # This terminal exists only inside the isolated operation staging tree. It
     # becomes authoritative atomically at publish; validation failure discards
@@ -3589,7 +4605,31 @@ def cmd_finalize(
         warnings.append(f"archive-meta write failed: {exc}")
         payload["steps"]["archive_meta"] = {"ok": False, "error": str(exc)}
 
-    # --- 9. after-manifest + compare ---
+    # --- 9/10. final summary stats + render, then LAST manifest (IA-7) ---
+    # Post-manifest rewrites of covered bytes are forbidden. We update summary /
+    # HTML first, regenerate after-manifest last, then verify on-disk hashes.
+    # If summary/html must still change after that, they are excluded with reasons.
+    summary = read_json(summary_path)
+    summary["archiveManifest"] = {
+        "movedFiles": 0,
+        "generatedFiles": 0,
+        "totalArchiveFiles": 0,
+        "checksumStatus": "PENDING",
+    }
+    write_json(summary_path, summary)
+    render_result = render_final_summary(work_dir, summary_path)
+    if not render_result.get("ok"):
+        payload["error"] = f"final summary re-render failed: {render_result.get('error')}"
+        _restore_finalize_failure()
+        return 1, payload
+    summary = read_json(summary_path)
+    validate_result = validate_summary(summary, html_path if html_path.is_file() else None)
+    payload["steps"]["validate"] = validate_result
+    summary.setdefault("reportPipeline", {})["validationIssues"] = validate_result.get(
+        "issues"
+    ) or []
+    write_json(summary_path, summary)
+
     after_path = work_dir / "evidence" / "archive-manifest-after.json"
     try:
         after_manifest = generate_manifest(work_dir, after_path)
@@ -3597,10 +4637,71 @@ def cmd_finalize(
         if before_in_archive.is_file():
             before_manifest = read_json(before_in_archive)
         compare_result = compare_manifests(before_manifest, after_manifest)
+        coverage = verify_manifest_byte_coverage(work_dir, after_manifest)
+        # Embed compare stats into summary AFTER manifest → must exclude those paths.
+        summary = read_json(summary_path)
+        summary["archiveManifest"] = {
+            "movedFiles": compare_result.get("movedFiles", 0),
+            "generatedFiles": compare_result.get("generatedFiles", 0),
+            "totalArchiveFiles": compare_result.get("totalArchiveFiles", 0),
+            "checksumStatus": coverage.get("checksumStatus", "FAIL"),
+            "exclusionReasons": {
+                "reports/final/summary-data.json": (
+                    "archiveManifest stats written after coverage snapshot"
+                ),
+                "reports/final/final-summary.html": (
+                    "re-rendered after coverage snapshot to display manifest stats"
+                ),
+            },
+            **_manifest_self_stats(work_dir, after_manifest, after_path),
+        }
+        write_json(summary_path, summary)
+        render_result = render_final_summary(work_dir, summary_path)
+        if not render_result.get("ok"):
+            payload["error"] = (
+                f"post-manifest summary render failed: {render_result.get('error')}"
+            )
+            _restore_finalize_failure()
+            return 1, payload
+        coverage = verify_manifest_byte_coverage(
+            work_dir,
+            after_manifest,
+            exclude_paths=[
+                "reports/final/summary-data.json",
+                "reports/final/final-summary.html",
+            ],
+            exclusion_reasons=summary["archiveManifest"]["exclusionReasons"],
+        )
+        summary["archiveManifest"]["checksumStatus"] = coverage.get(
+            "checksumStatus", "FAIL"
+        )
+        summary["archiveManifest"]["exclusionReasons"] = coverage.get(
+            "exclusionReasons"
+        ) or summary["archiveManifest"]["exclusionReasons"]
+        summary["archiveManifest"]["coverageChecked"] = coverage.get("checked")
+        write_json(summary_path, summary)
+        # Re-render once more for checksumStatus display; remain excluded.
+        render_final_summary(work_dir, summary_path)
+        summary = read_json(summary_path)
+        validate_result = validate_summary(
+            summary, html_path if html_path.is_file() else None
+        )
+        payload["steps"]["validate"] = validate_result
+        summary.setdefault("reportPipeline", {})["validationIssues"] = (
+            validate_result.get("issues") or []
+        )
+        write_json(summary_path, summary)
         payload["steps"]["after_manifest"] = {
-            "ok": True,
+            "ok": bool(coverage.get("ok")) and bool(compare_result.get("ok")),
             "path": str(after_path),
             "compare": compare_result,
+            "coverage": coverage,
+        }
+        compare_result = {
+            **compare_result,
+            "ok": bool(compare_result.get("ok")) and bool(coverage.get("ok")),
+            "checksumStatus": coverage.get("checksumStatus"),
+            "exclusionReasons": coverage.get("exclusionReasons"),
         }
     except (OSError, json.JSONDecodeError, ValueError) as exc:
         payload["error"] = f"after-manifest failed: {exc}"
@@ -3608,42 +4709,25 @@ def cmd_finalize(
         _restore_finalize_failure()
         return 1, payload
 
-    # --- 10. final summary update + final render/validate (no more events) ---
-    summary = read_json(summary_path)
-    summary["archiveManifest"] = {
-        "movedFiles": compare_result.get("movedFiles", 0),
-        "generatedFiles": compare_result.get("generatedFiles", 0),
-        "totalArchiveFiles": compare_result.get("totalArchiveFiles", 0),
-        "checksumStatus": compare_result.get("checksumStatus", "FAIL"),
-        **_manifest_self_stats(work_dir, after_manifest, after_path),
-    }
-    write_json(summary_path, summary)
-    render_result = render_final_summary(work_dir, summary_path)
-    if not render_result.get("ok"):
-        payload["error"] = f"final summary re-render failed: {render_result.get('error')}"
-        _restore_finalize_failure()
-        return 1, payload
-    summary = read_json(summary_path)
-    validate_result = validate_summary(summary, html_path if html_path.is_file() else None)
-    payload["steps"]["validate"] = validate_result
-    summary.setdefault("reportPipeline", {})["validationIssues"] = validate_result.get("issues") or []
-    write_json(summary_path, summary)
-
     # --- 11. closure: only when both validators and manifest pass ---
     validate_ok = bool(validate_result.get("ok"))
     manifest_ok = bool(compare_result.get("ok"))
-    can_close = validate_ok and manifest_ok
+    # Honest checksum: FAIL blocks; OK and OK_WITH_EXCLUSIONS (with reasons) pass.
+    checksum = str(compare_result.get("checksumStatus") or "")
+    checksum_ok = checksum in {"OK", "OK_WITH_EXCLUSIONS"}
+    can_close = validate_ok and manifest_ok and checksum_ok
 
     if not can_close:
         issues_out = list(validate_result.get("issues") or [])
-        if not manifest_ok:
+        if not manifest_ok or not checksum_ok:
             issues_out.append(
                 {
                     "code": "manifest-mismatch",
                     "severity": "error",
                     "message": (
                         f"missing={compare_result.get('missing')} "
-                        f"mismatched={compare_result.get('mismatched')}"
+                        f"mismatched={compare_result.get('mismatched')} "
+                        f"checksumStatus={checksum}"
                     ),
                 }
             )
@@ -3850,12 +4934,46 @@ def cmd_status_cli(args: argparse.Namespace) -> int:
     result = check_status(
         change_dir,
         allow_missing_review=bool(getattr(args, "allow_missing_review", False)),
+        archive_intent=str(getattr(args, "intent", "release-candidate")),
     )
     emit_json(result)
     # Checks completed → exit 0; archivable flag conveys the gate result.
     return 0 if result.get("ok") else 1
 
 
+def cmd_certify_local_cli(args: argparse.Namespace) -> int:
+    change_dir = resolve_path(args.change_dir)
+    project = (
+        resolve_path(args.project)
+        if getattr(args, "project", None)
+        else None
+    )
+    try:
+        receipt = certify_local_candidate(change_dir, project=project)
+    except (OSError, ValueError) as exc:
+        emit_json(
+            {
+                "ok": False,
+                "action": "certify-local",
+                "error": str(exc),
+            }
+        )
+        return 1
+    emit_json(
+        {
+            "ok": True,
+            "action": "certify-local",
+            "evidence": receipt,
+            "path": str(
+                change_dir
+                / "evidence"
+                / "product-candidate-verification.json"
+            ),
+        }
+    )
+    return 0
+
+
 def cmd_finalize_cli(args: argparse.Namespace) -> int:
     change_dir = resolve_path(args.change_dir)
     archive_root = resolve_path(args.archive_root)
@@ -3864,6 +4982,7 @@ def cmd_finalize_cli(args: argparse.Namespace) -> int:
         archive_root,
         skip_ingest=bool(args.skip_ingest),
         allow_missing_review=bool(getattr(args, "allow_missing_review", False)),
+        archive_intent=str(getattr(args, "intent", "release-candidate")),
     )
     emit_json(payload)
     return code
@@ -4053,8 +5172,23 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="downgrade full-tier missing review from blocker to warning",
     )
+    p_status.add_argument(
+        "--intent",
+        choices=("release-candidate", "record-only"),
+        default="release-candidate",
+        help="release-candidate enforces candidate evidence; record-only archives facts without release eligibility",
+    )
     p_status.set_defaults(func=cmd_status_cli)
 
+    p_cert = sub.add_parser(
+        "certify-local",
+        help="create candidate receipt from existing full ledger evidence without rerunning tests",
+    )
+    p_cert.add_argument("--change-dir", required=True)
+    p_cert.add_argument("--project", default=None)
+    p_cert.add_argument("--json", action="store_true", default=True)
+    p_cert.set_defaults(func=cmd_certify_local_cli)
+
     p_fin = sub.add_parser("finalize", help="single-process archive finalize")
     p_fin.add_argument("--change-dir", required=True)
     p_fin.add_argument("--archive-root", required=True)
@@ -4064,6 +5198,12 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="record override when full-tier review evidence is missing",
     )
+    p_fin.add_argument(
+        "--intent",
+        choices=("release-candidate", "record-only"),
+        default="release-candidate",
+        help="release-candidate enforces candidate evidence; record-only archives facts without release eligibility",
+    )
     p_fin.add_argument("--json", action="store_true", default=True)
     p_fin.set_defaults(func=cmd_finalize_cli)