@hunter-harness/workflow-harness 0.2.15 → 0.2.16

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

@@ -14,6 +14,7 @@ Python 3.10+, stdlib only.
 from __future__ import annotations
 
 import argparse
+import datetime as dt
 import hashlib
 import json
 import os
@@ -270,6 +271,112 @@ def _emit(payload: Any, *, as_json: bool) -> int:
     return 0 if payload.get("ok") else 1
 
 
+def dispatch_review(
+    *,
+    change_dir: Path,
+    run_id: str,
+    budget_seconds: int = 300,
+) -> dict[str, Any]:
+    """C11: dispatch a bounded review task.
+
+    Returns reviewTaskId / deadline / heartbeatAt. The caller is expected to
+    poll the review subagent and collect partial findings on timeout.
+    """
+    now = dt.datetime.now(dt.timezone.utc).astimezone()
+    task_id = f"review-{uuid.uuid4().hex}"
+    deadline = now + dt.timedelta(seconds=budget_seconds)
+    # heartbeat at midpoint of the budget
+    heartbeat = now + dt.timedelta(seconds=budget_seconds // 2)
+    return {
+        "ok": True,
+        "code": "DISPATCHED",
+        "reviewTaskId": task_id,
+        "runId": run_id,
+        "deadline": deadline.isoformat(timespec="milliseconds"),
+        "heartbeatAt": heartbeat.isoformat(timespec="milliseconds"),
+        "budgetSeconds": budget_seconds,
+    }
+
+
+def collect_partial_findings(
+    *,
+    change_dir: Path,
+    run_id: str,
+    completed_dimensions: list[str],
+    pending_dimensions: list[str],
+) -> dict[str, Any]:
+    """C11: collect partial findings after timeout — completed dimensions only.
+
+    Applies the degradation matrix to decide the fallback path.
+    """
+    matrix = degradation_matrix(
+        subagent_timed_out=bool(pending_dimensions),
+        main_session_available=True,
+    )
+    return {
+        "ok": True,
+        "code": "PARTIAL_FINDINGS",
+        "runId": run_id,
+        "completedDimensions": list(completed_dimensions),
+        "pendingDimensions": list(pending_dimensions),
+        "degradationMatrix": matrix,
+    }
+
+
+def degradation_matrix(
+    *,
+    subagent_timed_out: bool,
+    main_session_available: bool,
+) -> dict[str, Any]:
+    """C11: degradation matrix — subagent timeout → main session; main fail → ADVISORY."""
+    if not subagent_timed_out:
+        return {"fallback": "none", "status": "OK"}
+    if main_session_available:
+        return {"fallback": "main-session", "status": "DEGRADED"}
+    return {"fallback": "advisory", "status": "ADVISORY"}
+
+
+def validate_codegraph_identity(
+    *,
+    response: dict[str, Any],
+    expected_repository_id: str,
+    expected_head: str,
+) -> dict[str, Any]:
+    """C12: validate CodeGraph identity — repositoryId/indexedHead must match.
+
+    On mismatch, signal CODEGRAPH_IDENTITY_MISMATCH with fallback to Grep/Glob + Read.
+    """
+    repo_id = response.get("repositoryId")
+    indexed_head = response.get("indexedHead")
+    indexed_at = response.get("indexedAt")
+    if (
+        repo_id == expected_repository_id
+        and indexed_head == expected_head
+        and indexed_at
+    ):
+        return {
+            "ok": True,
+            "code": "IDENTITY_OK",
+            "repositoryId": repo_id,
+            "indexedHead": indexed_head,
+            "indexedAt": indexed_at,
+        }
+    return {
+        "ok": False,
+        "code": "CODEGRAPH_IDENTITY_MISMATCH",
+        "expected": {
+            "repositoryId": expected_repository_id,
+            "indexedHead": expected_head,
+        },
+        "actual": {
+            "repositoryId": repo_id,
+            "indexedHead": indexed_head,
+            "indexedAt": indexed_at,
+        },
+        "fallback": "grep-glob-read",
+    }
+
+
 def cmd_validate_findings(args: argparse.Namespace) -> int:
     doc = _read_json(Path(args.input))
     problems = validate_findings(doc)

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "claude-code",
-  "coreHash": "0e12e18a8a2b6489"
+  "coreHash": "822ced2e1d949aed"
 }

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=0e12e18a8a2b6489; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=822ced2e1d949aed; 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=0e12e18a8a2b6489; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=822ced2e1d949aed; 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=0e12e18a8a2b6489; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=822ced2e1d949aed; 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=0e12e18a8a2b6489; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=822ced2e1d949aed; 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-ingest/scripts/harness_knowledge.py

@@ -4552,6 +4552,11 @@ def main(argv: list[str] | None = None) -> int:
     query.add_argument("--status", action="append", dest="statuses", default=[], help="Only return entries with this lifecycle status")
     query.add_argument("--type", action="append", dest="types", default=[], help="Only return entries of this knowledge type")
     query.add_argument("--change", default=None, help="Write a change-scoped knowledge-context pointer")
+    query.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Emit full payload including matches array (default: compact output for host decisioning)",
+    )
 
     promote = sub.add_parser("promote", help="Promote a candidate knowledge entry to active")
     promote.add_argument("--project", default=".", help="Project root containing .harness/knowledge")
@@ -4652,7 +4657,17 @@ def main(argv: list[str] | None = None) -> int:
             Path(args.project), args.query, args.limit, args.files, args.statuses,
             args.types, args.change,
         )
-        print(json.dumps(result, ensure_ascii=False, indent=2))
+        if getattr(args, "verbose", False):
+            print(json.dumps(result, ensure_ascii=False, indent=2))
+        else:
+            # C5: compact output — omit matches array; host reads context pack for details.
+            compact = {
+                "query": result["query"],
+                "matchCount": result["matchCount"],
+                "contextPack": result["contextPack"],
+                "planInput": result["planInput"],
+            }
+            print(json.dumps(compact, ensure_ascii=False, indent=2))
         return 0
     if args.command == "promote":
         try:

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=0e12e18a8a2b6489; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=822ced2e1d949aed; 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=0e12e18a8a2b6489; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=822ced2e1d949aed; 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=0e12e18a8a2b6489; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=822ced2e1d949aed; 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=0e12e18a8a2b6489; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=822ced2e1d949aed; overlay=java; agent=claude-code; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose

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

@@ -84,3 +84,16 @@ RED 高风险建议: N | YELLOW 中低风险建议: M | 仅供参考，不阻塞
 ```
 
 fixback 是给后续修复循环使用的结构化清单，不替代 review-report；无 RED/YELLOW 时记录跳过原因，不生成空文件。
+
+## CodeGraph Identity 合同（C12）
+
+调用 `codegraph_explore` 后必须校验响应中的 `repositoryId` / `indexedHead` / `indexedAt`：
+
+- `repositoryId` 必须与 `harness_paths.repository_identity(project_root)` 一致
+- `indexedHead` 必须与当前 HEAD 一致
+- `indexedAt` 必须存在
+
+identity 不匹配时记 `CODEGRAPH_IDENTITY_MISMATCH` warning，降级为 Grep/Glob + Read。
+identity 匹配时正常使用 codegraph 结果。
+
+校验函数：`harness_review.validate_codegraph_identity(response, expected_repository_id, expected_head)`。

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=0e12e18a8a2b6489; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=822ced2e1d949aed; 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=0e12e18a8a2b6489; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=822ced2e1d949aed; overlay=java; agent=claude-code; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose

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=0e12e18a8a2b6489; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=822ced2e1d949aed; 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=0e12e18a8a2b6489; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=822ced2e1d949aed; overlay=java; agent=claude-code; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose

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

@@ -1201,6 +1201,70 @@ def _phase_event_exists(change_dir: Path, phase: str, type_: str, run_id: str) -
     )
 
 
+def _validate_scenario_coverage(change_dir: Path) -> dict[str, Any]:
+    """C9: validate all P0 scenarios have a ledger entry with scenarioIds covering them.
+
+    Reads meta/scenario-manifest.json and evidence/verification-ledger.json.
+    Returns ok=True when manifest missing (backward compat) or all P0 scenarios covered.
+    """
+    manifest_path = change_dir / "meta" / "scenario-manifest.json"
+    if not manifest_path.is_file():
+        return {"ok": True, "code": "MANIFEST_MISSING", "skipped": True}
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8-sig"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return {
+            "ok": False,
+            "code": "SCENARIO_MANIFEST_INVALID",
+            "message": f"scenario-manifest.json unreadable: {exc}",
+        }
+    scenarios = manifest.get("scenarios") or []
+    p0_ids = {
+        str(s.get("id"))
+        for s in scenarios
+        if isinstance(s, dict)
+        and str(s.get("priority", "")).upper() == "P0"
+        and s.get("requiredEvidenceKind") == "ledger"
+    }
+    if not p0_ids:
+        return {"ok": True, "code": "NO_P0_SCENARIOS"}
+
+    ledger_path = change_dir / "evidence" / "verification-ledger.json"
+    if not ledger_path.is_file():
+        return {
+            "ok": False,
+            "code": "SCENARIO_COVERAGE_FAILED",
+            "message": "ledger missing; cannot verify P0 scenario coverage",
+            "missing": sorted(p0_ids),
+        }
+    try:
+        ledger = json.loads(ledger_path.read_text(encoding="utf-8-sig"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return {
+            "ok": False,
+            "code": "SCENARIO_COVERAGE_FAILED",
+            "message": f"ledger unreadable: {exc}",
+            "missing": sorted(p0_ids),
+        }
+    covered: set[str] = set()
+    validations = ledger.get("validations") or {}
+    if isinstance(validations, dict):
+        for entry in validations.values():
+            if isinstance(entry, dict):
+                ids = entry.get("scenarioIds")
+                if isinstance(ids, list):
+                    covered.update(str(i) for i in ids)
+    missing = sorted(p0_ids - covered)
+    if missing:
+        return {
+            "ok": False,
+            "code": "SCENARIO_COVERAGE_FAILED",
+            "message": f"P0 scenarios without ledger entry: {', '.join(missing)}",
+            "missing": missing,
+        }
+    return {"ok": True, "code": "SCENARIO_COVERAGE_OK", "covered": sorted(covered & p0_ids)}
+
+
 def cmd_begin(args: argparse.Namespace) -> int:
     as_json = bool(args.json)
     project = hc.resolve_main_project_root()
@@ -1470,6 +1534,17 @@ def cmd_close(args: argparse.Namespace) -> int:
             extra={k: v for k, v in ledger_result.items() if k not in {"ok", "message", "code"}},
         )
 
+    # C9: scenario coverage check — all P0 scenarios must have a ledger entry.
+    if args.phase in {"run", "test"}:
+        coverage = _validate_scenario_coverage(change_dir)
+        if not coverage.get("ok"):
+            return emit_error(
+                str(coverage.get("code", "SCENARIO_COVERAGE_FAILED")),
+                str(coverage.get("message", "scenario coverage validation failed")),
+                as_json=as_json,
+                extra={k: v for k, v in coverage.items() if k not in {"ok", "message", "code"}},
+            )
+
     close_status = args.status
     close_code = "PHASE_CLOSED"
     if ledger_result.get("code") == "LEDGER_OK_DEGRADED":

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

@@ -1266,6 +1266,31 @@ def cmd_status(args: argparse.Namespace) -> int:
     return _emit(_txn_from_args(args).status())
 
 
+def cmd_journal(args: argparse.Namespace) -> int:
+    """C5: journal 子命令 — 默认 compact (transactionId/currentStep/status)，--verbose 全量。"""
+    txn = _txn_from_args(args)
+    full = txn.status()
+    if getattr(args, "verbose", False):
+        return _emit(full)
+    # Derive currentStep: first non-DONE step, or last step name if all DONE.
+    current_step = None
+    for step in full.get("steps", []):
+        if step.get("status") != "DONE":
+            current_step = step.get("name")
+            break
+    if current_step is None and full.get("steps"):
+        current_step = full["steps"][-1].get("name")
+    overall_status = "DONE" if all(
+        step.get("status") == "DONE" for step in full.get("steps", [])
+    ) else "IN_PROGRESS"
+    compact = {
+        "transactionId": full.get("transactionId"),
+        "currentStep": current_step,
+        "status": overall_status,
+    }
+    return _emit(compact)
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="harness_integration.py")
     sub = parser.add_subparsers(dest="command_name", required=True)
@@ -1287,6 +1312,19 @@ def build_parser() -> argparse.ArgumentParser:
     add("recover", cmd_recover)
     add("status", cmd_status)
 
+    p_journal = sub.add_parser("journal")
+    p_journal.add_argument("--change", required=True)
+    p_journal.add_argument("--run-id", required=True)
+    p_journal.add_argument("--target-branch", default="main")
+    p_journal.add_argument("--feature-branch", required=True)
+    p_journal.add_argument("--temp-root", required=True)
+    p_journal.add_argument(
+        "--verbose",
+        action="store_true",
+        help="emit full journal payload (default: compact transactionId/currentStep/status)",
+    )
+    p_journal.set_defaults(func=cmd_journal)
+
     p_verify = sub.add_parser("verify")
     p_verify.add_argument("--change", required=True)
     p_verify.add_argument("--run-id", required=True)

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

@@ -100,6 +100,37 @@ def emit_json(payload: dict[str, Any], *, as_json: bool) -> None:
             sys.stdout.write(("ok" if ok else "error") + "\n")
 
 
+def _compact_record_payload(payload: dict[str, Any]) -> dict[str, Any]:
+    """C5: record compact — ok/action/verification/status only."""
+    return {
+        "ok": payload.get("ok", True),
+        "action": payload.get("action"),
+        "verification": payload.get("verification"),
+        "status": payload.get("status"),
+    }
+
+
+def _compact_can_reuse_payload(payload: dict[str, Any]) -> dict[str, Any]:
+    """C5: can-reuse compact — ok/reuse/code only."""
+    return {
+        "ok": payload.get("ok", True),
+        "reuse": payload.get("reuse"),
+        "code": payload.get("code"),
+    }
+
+
+def emit_compact_or_verbose(
+    payload: dict[str, Any],
+    *,
+    as_json: bool,
+    verbose: bool,
+    compact_fn,
+) -> None:
+    """Emit compact payload by default; full payload when --verbose."""
+    out = payload if verbose else compact_fn(payload)
+    emit_json(out, as_json=as_json)
+
+
 def emit_error(message: str, *, as_json: bool, code: int = 1) -> int:
     payload = {"ok": False, "error": message}
     if as_json:
@@ -1227,6 +1258,7 @@ def cmd_hash(args: argparse.Namespace) -> int:
 
 def cmd_can_reuse(args: argparse.Namespace) -> int:
     as_json = bool(args.json)
+    verbose = bool(getattr(args, "verbose", False))
     verification = args.verification
     if verification not in VERIFICATIONS:
         return emit_error(
@@ -1253,7 +1285,10 @@ def cmd_can_reuse(args: argparse.Namespace) -> int:
                 "verification": verification,
                 "detail": err,
             }
-            emit_json(payload, as_json=as_json)
+            emit_compact_or_verbose(
+                payload, as_json=as_json, verbose=verbose,
+                compact_fn=_compact_can_reuse_payload,
+            )
             return 0
         files = resolve_input_files(resolved_files, project_root)
     if not files:
@@ -1275,12 +1310,16 @@ def cmd_can_reuse(args: argparse.Namespace) -> int:
     except (OSError, ValueError, json.JSONDecodeError) as exc:
         return emit_error(f"can-reuse failed: {exc}", as_json=as_json)
 
-    emit_json(payload, as_json=as_json)
+    emit_compact_or_verbose(
+        payload, as_json=as_json, verbose=verbose,
+        compact_fn=_compact_can_reuse_payload,
+    )
     return 0
 
 
 def cmd_record(args: argparse.Namespace) -> int:
     as_json = bool(args.json)
+    verbose = bool(getattr(args, "verbose", False))
     change_dir = resolve_path(args.change_dir)
     verification = args.verification
     if verification not in VERIFICATIONS:
@@ -1421,6 +1460,16 @@ def cmd_record(args: argparse.Namespace) -> int:
             if _nonempty_str(getattr(args, "tests_reused_from", None)):
                 entry["testsReusedFrom"] = str(args.tests_reused_from).strip()
 
+        # C9: bind scenario IDs from --scenario-ids to this ledger entry.
+        scenario_ids_raw = getattr(args, "scenario_ids", None)
+        if _nonempty_str(scenario_ids_raw):
+            ids = [s.strip() for s in str(scenario_ids_raw).split(",") if s.strip()]
+            if ids:
+                entry["scenarioIds"] = ids
+        elif "scenarioIds" in entry:
+            # Fresh record without scenario-ids must not keep stale ids from prev.
+            entry.pop("scenarioIds", None)
+
         ledger["validations"][verification] = entry
         if "changeName" not in ledger:
             ledger["changeName"] = change_dir.name
@@ -1487,7 +1536,10 @@ def cmd_record(args: argparse.Namespace) -> int:
         "diffHash": ledger.get("diffHash"),
         "resolvedProjectRoot": str(project_root) if project_root else None,
     }
-    emit_json(payload, as_json=as_json)
+    emit_compact_or_verbose(
+        payload, as_json=as_json, verbose=verbose,
+        compact_fn=_compact_record_payload,
+    )
     return 0
 
 
@@ -1589,6 +1641,11 @@ def build_parser() -> argparse.ArgumentParser:
         default=None,
         help="optional environment hash to compare against ledger entry (UT-017)",
     )
+    p_reuse.add_argument(
+        "--verbose",
+        action="store_true",
+        help="emit full payload (default: compact ok/reuse/code)",
+    )
     p_reuse.set_defaults(func=cmd_can_reuse)
 
     p_record = sub.add_parser("record", parents=[shared_json], help="write validation result into ledger")
@@ -1669,6 +1726,16 @@ def build_parser() -> argparse.ArgumentParser:
         default=None,
         help="ledger v3: scope reason (required when --applicability NOT_APPLICABLE)",
     )
+    p_record.add_argument(
+        "--scenario-ids",
+        default=None,
+        help="comma-separated scenario IDs from scenario-manifest.json to bind to this entry",
+    )
+    p_record.add_argument(
+        "--verbose",
+        action="store_true",
+        help="emit full payload (default: compact ok/action/verification/status)",
+    )
     p_record.set_defaults(func=cmd_record)
 
     p_diff = sub.add_parser(

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

@@ -83,6 +83,23 @@ def _git_common_dir(cwd: Path) -> Path | None:
     return common
 
 
+def common_root(project_root: Path) -> Path:
+    """Resolve the shared "common" root for a project.
+
+    For a linked worktree, ``git rev-parse --git-common-dir`` points at the
+    main repository's ``.git`` directory; its parent is the main project root.
+    For the main worktree, the common dir is ``<root>/.git`` so the parent is
+    the project root itself. Falls back to the resolved input when not in a
+    git repo (e.g. exploratory scratch dirs).
+    """
+    cwd = Path(project_root).resolve()
+    common = _git_common_dir(cwd)
+    if common is None:
+        return cwd
+    # common dir is <root>/.git — its parent is the main project root.
+    return common.parent.resolve()
+
+
 def _root_commit(cwd: Path) -> str | None:
     raw = _git_text(cwd, "rev-list", "--max-parents=0", "HEAD")
     if not raw: