@hunter-harness/workflow-harness 0.2.13 → 0.2.14

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

@@ -621,12 +621,13 @@ def validate_ledger_identity(ledger: dict[str, Any]) -> list[str]:
 def record_integration_hashes(
     ledger_path: Path,
     *,
+    change_dir: Path | None = None,
     repository_id: str,
     merge_final_hash: str,
     ci_expected_head: str,
     remote_head: str,
 ) -> dict[str, Any]:
-    """Atomically attach post-push identity to an existing ledger v3."""
+    """Atomically attach post-push hashes using the change contract's ledger rules."""
     path = Path(ledger_path).resolve()
     if not path.is_file():
         return {"ok": False, "code": "LEDGER_MISSING", "ledgerPath": str(path)}
@@ -637,15 +638,26 @@ def record_integration_hashes(
             "ok": False, "code": "LEDGER_INVALID", "ledgerPath": str(path),
             "message": str(exc),
         }
+    legacy_contract = False
+    if change_dir is not None:
+        resolved_change_dir = Path(change_dir).resolve()
+        if ledger.get("changeName") != resolved_change_dir.name:
+            return {
+                "ok": False,
+                "code": "LEDGER_CHANGE_MISMATCH",
+                "ledgerPath": str(path),
+            }
+        legacy_contract = not _contract_is_v2(resolved_change_dir)
+
     missing = validate_ledger_identity(ledger)
-    if missing:
+    if missing and not legacy_contract:
         return {
             "ok": False,
             "code": "LEDGER_IDENTITY_INVALID",
             "ledgerPath": str(path),
             "missing": missing,
         }
-    if ledger.get("repositoryId") != repository_id:
+    if not missing and ledger.get("repositoryId") != repository_id:
         return {
             "ok": False,
             "code": "LEDGER_REPOSITORY_MISMATCH",

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

@@ -29,6 +29,7 @@ if hasattr(sys.stderr, "reconfigure"):
     sys.stderr.reconfigure(encoding="utf-8")
 
 
+import harness_change as hc  # noqa: E402
 import harness_profile as hprof  # noqa: E402
 
 
@@ -69,6 +70,52 @@ def cmd_check(project: Path) -> dict[str, Any]:
     return result
 
 
+def check_concurrency(project: Path) -> dict[str, Any]:
+    """Report the configured concurrency mode and active Change landscape.
+
+    Retro §5.2: preflight must surface concurrencyMode, activeChanges, and
+    allowedParallelLevels so agents don't have to guess whether parallel
+    Changes are supported.
+    """
+    mode = hc.read_concurrency_mode(project)
+    active = hc.list_active_changes(project)
+    shared_conflicts: list[dict[str, Any]] = []
+    # In isolated-multi-active, surface any shared-state conflicts (e.g. same
+    # worktree path) so callers know isolation is incomplete.
+    if mode == "isolated-multi-active" and len(active) > 1:
+        seen_worktrees: dict[str, str] = {}
+        for entry in active:
+            change_dir = Path(entry["path"])
+            worktree_meta = change_dir / "meta" / "worktree.json"
+            if not worktree_meta.is_file():
+                continue
+            try:
+                meta = json.loads(worktree_meta.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                continue
+            wt = meta.get("path") if isinstance(meta, dict) else None
+            if isinstance(wt, str) and wt:
+                if wt in seen_worktrees:
+                    shared_conflicts.append({
+                        "kind": "worktree",
+                        "path": wt,
+                        "changes": [seen_worktrees[wt], entry["changeId"]],
+                    })
+                else:
+                    seen_worktrees[wt] = entry["changeId"]
+    levels = ["change-internal"] if mode == "single-active" else [
+        "change-internal",
+        "multi-change",
+    ]
+    return {
+        "ok": True,
+        "concurrencyMode": mode,
+        "activeChanges": active,
+        "sharedStateConflicts": shared_conflicts,
+        "allowedParallelLevels": levels,
+    }
+
+
 # ---------------------------------------------------------------------------
 # record-quirk — 适配 v2 commands（source=user override）
 # ---------------------------------------------------------------------------

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

@@ -448,9 +448,18 @@ def _validate_existing_manifest(
         tracked_now = _git(
             project, "ls-files", "--error-unmatch", "--", rel
         ).returncode == 0
-        if item["ignored"] != ignored_now or item["trackedBefore"] != tracked_now:
+        checkpointed = not item["trackedBefore"] and tracked_now
+        if (
+            item["trackedBefore"] != tracked_now and not checkpointed
+        ) or (
+            item["ignored"] != ignored_now and not checkpointed
+        ):
             return "MANIFEST_INVALID", {}
-        validated[rel] = dict(item)
+        normalized_item = dict(item)
+        if checkpointed:
+            normalized_item["trackedBefore"] = True
+            normalized_item["ignored"] = ignored_now
+        validated[rel] = normalized_item
     return None, validated
 
 
@@ -734,11 +743,26 @@ def _stage_locked(
     error, entries = validator(project_root, manifest, require_files=True)
     if error:
         return _result(False, action, error, [])
-    rels = [
-        rel
-        for rel, entry in entries.items()
-        if not is_v2 or entry.get("commitScope") == "current-change"
-    ]
+    rels: list[str] = []
+    for rel, entry in entries.items():
+        if is_v2:
+            if entry.get("commitScope") == "current-change":
+                rels.append(rel)
+            continue
+        if not entry["trackedBefore"]:
+            rels.append(rel)
+            continue
+        changed = _git(project_root, "diff", "--quiet", "HEAD", "--", rel)
+        if changed.returncode == 1:
+            rels.append(rel)
+        elif changed.returncode != 0:
+            return _result(
+                False,
+                action,
+                "GIT_DIFF_FAILED",
+                [rel],
+                error=changed.stderr.strip(),
+            )
     if not rels:
         return _result(True, action, "STAGED", [])
 
@@ -925,9 +949,22 @@ def close(project: Path | str, change_dir: Path | str) -> dict[str, Any]:
     if (
         not isinstance(snapshot, dict)
         or snapshot.get("schemaVersion") != SCHEMA_VERSION
-        or snapshot.get("projectRoot") != str(project_root)
     ):
         return _result(False, action, "SNAPSHOT_INVALID", [])
+    # Execution-root contract (retro §5.10): a snapshot captured against a
+    # different project root must fail with EXECUTION_ROOT_MISMATCH before
+    # the generic SNAPSHOT_INVALID, so callers can distinguish "wrong root"
+    # from "corrupt snapshot".
+    snapshot_root = snapshot.get("projectRoot")
+    if snapshot_root is not None and snapshot_root != str(project_root):
+        return _result(
+            False,
+            action,
+            "EXECUTION_ROOT_MISMATCH",
+            [],
+            expectedRoot=snapshot_root,
+            actualRoot=str(project_root),
+        )
 
     before_entries = snapshot.get("files")
     if not isinstance(before_entries, list):
@@ -963,15 +1000,51 @@ def close(project: Path | str, change_dir: Path | str) -> dict[str, Any]:
         if before[rel]["sha256"] != digest:
             touched.append((rel, "test-updated"))
 
-    recorded: list[str] = []
-    for rel, reason in touched:
-        result = record(project_root, change_root, [str(project_root / rel)], reason)
+    for reason in ("tdd-created", "test-updated"):
+        rels = [rel for rel, item_reason in touched if item_reason == reason]
+        if not rels:
+            continue
+        result = record(
+            project_root,
+            change_root,
+            [str(project_root / rel) for rel in rels],
+            reason,
+        )
         if not result.get("ok"):
             code = result.get("code", "RECORD_FAILED")
             if code == "TEST_PATH_NOT_ALLOWED":
-                return _result(False, action, "UNCLASSIFIABLE_TEST", [rel])
+                return _result(False, action, "UNCLASSIFIABLE_TEST", rels)
             return result
-        recorded.append(rel)
+
+    recorded = [rel for rel, _ in touched]
+
+    # Cross-check (retro §5.10): if the manifest has active entries for this
+    # change but close computed recordedCount=0, the snapshot/manifest/diff
+    # are inconsistent. Fail closed instead of silently returning success.
+    manifest_path = _manifest_path(change_root)
+    if manifest_path is not None and manifest_path.is_file():
+        try:
+            manifest = _read_json(manifest_path)
+        except (OSError, json.JSONDecodeError):
+            manifest = None
+        if isinstance(manifest, dict):
+            manifest_files = manifest.get("files")
+            if isinstance(manifest_files, list):
+                active_entries = [
+                    f for f in manifest_files
+                    if isinstance(f, dict)
+                    and f.get("reason") in ("tdd-created", "test-updated", "stale-test-repair")
+                ]
+                if active_entries and not recorded:
+                    return _result(
+                        False,
+                        action,
+                        "MANIFEST_DIFF_HASH_MISMATCH",
+                        [],
+                        manifestEntries=len(active_entries),
+                        recordedCount=0,
+                        detail="manifest has active entries but close computed 0 recorded tests",
+                    )
 
     return _result(
         True,

package/harness/bundles/java/claude-code/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "claude-code",
-  "coreHash": "14a6b9abc6a451bd"
+  "coreHash": "d90d5df79c624dc7"
 }

package/harness/bundles/java/claude-code/harness-apidoc/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=14a6b9abc6a451bd; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d90d5df79c624dc7; overlay=java; agent=claude-code; do not edit -->
 # harness-apidoc — 前端接口文档（Java overlay）
 
 ## Purpose

package/harness/bundles/java/claude-code/harness-archive/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=14a6b9abc6a451bd; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d90d5df79c624dc7; overlay=java; agent=claude-code; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose

package/harness/bundles/java/claude-code/harness-codebase-map/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=14a6b9abc6a451bd; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d90d5df79c624dc7; overlay=java; agent=claude-code; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

package/harness/bundles/java/claude-code/harness-knowledge-ingest/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=14a6b9abc6a451bd; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d90d5df79c624dc7; overlay=java; agent=claude-code; do not edit -->
 # harness-knowledge-ingest
 
 从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。

package/harness/bundles/java/claude-code/harness-knowledge-query/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=14a6b9abc6a451bd; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d90d5df79c624dc7; overlay=java; agent=claude-code; do not edit -->
 # harness-knowledge-query
 
 并行 change 中查询必须传 `--change <change-id>`；成功后以该 change 的 `meta/knowledge-context.json` 为稳定指针。全局 `context-packs/latest.json` 仅向后兼容，不得用于判断多个 active change 的上下文归属。

package/harness/bundles/java/claude-code/harness-package/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=14a6b9abc6a451bd; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d90d5df79c624dc7; overlay=java; agent=claude-code; do not edit -->
 # harness-package — 增量模块打包（Java overlay）
 
 ## Purpose

package/harness/bundles/java/claude-code/harness-plan/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=14a6b9abc6a451bd; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d90d5df79c624dc7; overlay=java; agent=claude-code; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose

package/harness/bundles/java/claude-code/harness-review/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=14a6b9abc6a451bd; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d90d5df79c624dc7; overlay=java; agent=claude-code; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose

package/harness/bundles/java/claude-code/harness-run/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=14a6b9abc6a451bd; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d90d5df79c624dc7; overlay=java; agent=claude-code; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose

package/harness/bundles/java/claude-code/harness-submit/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=14a6b9abc6a451bd; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d90d5df79c624dc7; overlay=java; agent=claude-code; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose
@@ -130,7 +130,7 @@ commit+push / 仅本地 commit / 取消；**不调用 Superpowers 呈现 PR/丢
 
 见 `checklist.md` 与 `../protocols/ledger-protocol.md`、`../protocols/submit-protocol.md`。
 
-test-tracking manifest 是 ignored test 的唯一强制暂存授权：只允许 `harness_test_guard.py stage` 暂存 manifest 中已校验路径，禁止 `git add -f .`、目录级 `git add -f` 或全局修改 `.gitignore`。worktree commit 前须确认 manifest 路径全部进入 cached diff；合并回主分支后、删除 worktree 前须确认这些路径已由目标 commit 跟踪，否则停止清理。
+test-tracking manifest 是 ignored test 的唯一强制暂存授权：只允许 `harness_test_guard.py stage` 暂存 manifest 中已校验且相对 `HEAD` 仍有差异的路径，禁止 `git add -f .`、目录级 `git add -f` 或全局修改 `.gitignore`。worktree commit 前须确认 guard 返回的 `files` 全部进入 cached diff；manifest 中已由 `HEAD` 跟踪且未变化的历史条目允许保留而不进入本次 cached diff。合并回主分支后、删除 worktree 前仍须确认 manifest 路径已由目标 commit 跟踪，否则停止清理。
 
 ### 四、worktree 合并硬规则
 

package/harness/bundles/java/claude-code/harness-submit/checklist.md

@@ -119,7 +119,7 @@ python <skills-root>/scripts/harness_ledger.py can-reuse `
 
 - [ ] 检查 `.harness/changes/<change-name>/evidence/test-tracking.json` 是否存在
 - [ ] 存在时先执行 `python <skills-root>/scripts/harness_test_guard.py stage --project . --change-dir ".harness/changes/<change-name>" --json`；任一 manifest/path/hash/index 校验失败立即停止
-- [ ] 用 `git diff --cached --name-only` 验证 manifest 中每个精确路径均已暂存，且没有 guard 引入的额外路径
+- [ ] 用 `git diff --cached --name-only` 验证 guard 响应 `files` 中的每个精确路径均已暂存，且没有 guard 引入的额外路径；manifest 中已由 `HEAD` 跟踪且未变化的历史条目无需进入本次 cached diff
 - [ ] 无 manifest 时禁止使用 `git add -f`；有 manifest 时也只允许 guard 内部的 exact force-add，**禁止全局 force-add**、目录级 force-add 和全局修改 `.gitignore`
 
 提交前**强制检查 `.gitignore`** 是否包含 `.harness/`：

package/harness/bundles/java/claude-code/harness-sync/SKILL.md

@@ -19,7 +19,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=14a6b9abc6a451bd; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d90d5df79c624dc7; overlay=java; agent=claude-code; do not edit -->
 # harness-sync — 元数据同步
 
 ## Purpose

package/harness/bundles/java/claude-code/harness-test/SKILL.md

@@ -22,7 +22,7 @@ disallowed-tools:
   - Bash(node *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=14a6b9abc6a451bd; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d90d5df79c624dc7; overlay=java; agent=claude-code; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose

package/harness/bundles/java/claude-code/scripts/harness_archive.py

@@ -2799,6 +2799,130 @@ def _html_escape(text: str) -> str:
 # ---------------------------------------------------------------------------
 
 
+def validate_report_adequacy(summary: dict[str, Any]) -> dict[str, Any]:
+    """Validate that final summary is factually complete (retro §5.32).
+
+    The archive validator must not return all-green when the summary is
+    factually incomplete. This gate checks independent sources (git facts,
+    typed metrics, stage status) rather than comparing the summary against
+    a lossy projection of itself.
+    """
+    issues: list[dict[str, str]] = []
+
+    git_facts = summary.get("gitFacts") or {}
+    if isinstance(git_facts, dict):
+        base = str(git_facts.get("baseCommit") or "").strip()
+        final = str(git_facts.get("finalCommit") or "").strip()
+        files_changed = int(git_facts.get("filesChanged") or 0)
+        # base != final but diff=0 → factually incomplete.
+        if base and final and base != final and files_changed == 0:
+            issues.append({
+                "code": "DIFF_ZERO_WITH_NONEMPTY_COMMIT",
+                "severity": "error",
+                "message": f"final commit {final} differs from base {base} but filesChanged=0",
+            })
+
+    # Typed metrics missing despite test report artifacts present.
+    verification = summary.get("verification") or {}
+    if isinstance(verification, dict):
+        unit = verification.get("unitTests") or {}
+        api = verification.get("apiTests") or {}
+        artifacts = summary.get("artifacts") or []
+        has_test_report = any(
+            isinstance(a, dict) and "test" in str(a.get("path") or "").lower()
+            for a in artifacts
+        ) if isinstance(artifacts, list) else False
+        unit_pass = int(unit.get("passed") or 0) if isinstance(unit, dict) else 0
+        api_status = str(api.get("status") or "") if isinstance(api, dict) else ""
+        if has_test_report and unit_pass == 0 and api_status in {"", "not_available"}:
+            issues.append({
+                "code": "TYPED_METRICS_MISSING",
+                "severity": "error",
+                "message": "test report artifacts present but unitTests/apiTests typed metrics are empty",
+            })
+
+    # stageStatus contradicts event reducer.
+    stage = summary.get("stageStatus") or {}
+    stage_from_events = summary.get("stageStatusFromEvents") or {}
+    if isinstance(stage, dict) and isinstance(stage_from_events, dict):
+        for phase, status in stage.items():
+            event_status = stage_from_events.get(phase)
+            if event_status is not None and str(status) != str(event_status):
+                issues.append({
+                    "code": "STAGE_STATUS_CONTRADICTION",
+                    "severity": "error",
+                    "message": f"stageStatus.{phase}={status} but event reducer says {event_status}",
+                })
+
+    return {"ok": not issues, "issues": issues}
+
+
+def artifact_preflight(change_dir: Path) -> dict[str, Any]:
+    """Classify artifact events before destructive finalize (retro §5.31).
+
+    Returns per-artifact classification: informational (no path, OK),
+    canonicalizable (same-change repo-relative path, auto-normalize), or
+    blocking (cross-change/absolute/escaping path, fail closed).
+    """
+    change_dir = change_dir.resolve()
+    events_p = change_dir / "events.ndjson"
+    items: list[dict[str, Any]] = []
+    blocking: list[dict[str, Any]] = []
+    if not events_p.is_file():
+        return {"ok": True, "items": [], "blocking": []}
+    change_id = change_dir.name
+    for line in events_p.read_text(encoding="utf-8").splitlines():
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(event, dict) or event.get("type") != "artifact":
+            continue
+        path = str(event.get("path") or "").strip()
+        kind = str(event.get("kind") or "").strip()
+        event_id = str(event.get("id") or "")
+        if not path:
+            items.append({
+                "eventId": event_id,
+                "category": "informational",
+                "kind": kind or "informational",
+                "note": str(event.get("note") or "")[:80],
+            })
+            continue
+        # Check for escaping/cross-change paths.
+        parts = path.replace("\\", "/").split("/")
+        if ".." in parts or path.startswith("/") or re.match(r"^[A-Za-z]:", path):
+            item = {
+                "eventId": event_id,
+                "category": "blocking",
+                "path": path,
+                "reason": "absolute or escaping path",
+            }
+            items.append(item)
+            blocking.append(item)
+            continue
+        # Same-change repo-relative path: canonicalizable.
+        prefix = f".harness/changes/{change_id}/"
+        if path.startswith(prefix):
+            canonical = path[len(prefix):]
+            items.append({
+                "eventId": event_id,
+                "category": "canonicalizable",
+                "path": path,
+                "canonicalPath": canonical,
+                "correction": f"append correction --target-event-id {event_id} --target-field path --new-value-json \"{canonical}\"",
+            })
+            continue
+        # Change-relative path: OK.
+        items.append({
+            "eventId": event_id,
+            "category": "file-backed",
+            "path": path,
+            "exists": (change_dir / path).is_file(),
+        })
+    return {"ok": not blocking, "items": items, "blocking": blocking}
+
+
 def run_knowledge_poststeps(project_root: Path) -> dict[str, Any]:
     results: dict[str, Any] = {"ran": False, "steps": [], "warnings": []}
     if not KNOWLEDGE_SCRIPT.is_file():

package/harness/bundles/java/claude-code/scripts/harness_change.py

@@ -224,6 +224,60 @@ def _layout_fields(project_root: Path, change_id: str) -> dict[str, Any]:
     }
 
 
+def read_concurrency_mode(project_root: Path) -> str:
+    """Return the configured concurrency mode (retro §5.2).
+
+    Defaults to ``single-active`` when no config declares a mode. Supported
+    values: ``single-active`` (default, blocks a second active Change),
+    ``isolated-multi-active`` (allows multiple active Changes but all
+    Change-scoped commands require ``--change``).
+    """
+    cfg = project_root / ".harness" / "config.json"
+    if cfg.is_file():
+        try:
+            data = json.loads(cfg.read_text(encoding="utf-8"))
+            if isinstance(data, dict):
+                mode = data.get("concurrencyMode")
+                if isinstance(mode, str) and mode in {
+                    "single-active",
+                    "isolated-multi-active",
+                }:
+                    return mode
+        except (OSError, json.JSONDecodeError):
+            pass
+    return "single-active"
+
+
+def check_concurrency_block(
+    project_root: Path, change_id: str
+) -> dict[str, Any] | None:
+    """Return a blocking payload when a second active Change is forbidden.
+
+    Returns ``None`` when the begin may proceed. In ``single-active`` mode a
+    second active Change (any other than ``change_id``) blocks begin; in
+    ``isolated-multi-active`` mode multiple active Changes are allowed.
+    """
+    mode = read_concurrency_mode(project_root)
+    if mode == "isolated-multi-active":
+        return None
+    active = list_active_changes(project_root)
+    others = [entry for entry in active if entry.get("changeId") != change_id]
+    if not others:
+        return None
+    return {
+        "ok": False,
+        "code": "SINGLE_ACTIVE_BLOCKED",
+        "message": (
+            "single-active concurrency mode: another active Change exists; "
+            "use portfolio/decompose to sequence multiple Changes, or switch "
+            "to isolated-multi-active after ensuring full Change-scoped isolation"
+        ),
+        "concurrencyMode": mode,
+        "activeChanges": active,
+        "blockingChanges": others,
+    }
+
+
 def resolve_change(
     project_root: Path,
     change_id: str | None,