chore: housekeeping sweep — truth-path dedup, per-repo default branch, executor hardening, drop vestigial uv.lock (#47)

* refactor(truth): single-source portfolio-truth-latest.json via truth_latest_path()

Introduce TRUTH_LATEST_FILENAME + truth_latest_path(output_dir) in
portfolio_truth_types (the domain leaf), and route all 19 path-join
sites + the glob through it. The filename now lives in one place
instead of being reconstructed across cli, serve/routes, report
enrichment, weekly command center, excel export, and the publisher.

Human-readable error/log copy and docstrings keep the literal as
prose. No behavior change.

* feat(automation): use per-repo default branch for context-PR base

The bounded-automation executor opened context-improvement PRs against a
hardcoded 'main' base. Detect each repo's actual default branch from the
local origin/HEAD ref (no network) in the truth-build pipeline, carry it
through IdentityFields, and resolve the PR base in precedence order:
explicit caller override > repo-detected default > portfolio fallback.

- portfolio_truth_sources: _git_default_branch() + thread through git facts
  (also DRYs _gather_git_facts' repeated dict construction)
- IdentityFields.default_branch: new optional field (additive, '' default)
- automation_workflow.build_context_pr_plan: resolve per-repo, '' = auto

Covered: origin/HEAD detection incl. multi-segment branches + unset
fallback; plan precedence (detected vs explicit override).

* fix(automation): harden executor failure paths (orphan branch + missing PR URL)

Two edge cases in execute_context_pr:

- branch-orphan: when apply_change fails after 'git checkout -b', the
  executor returned to the default branch but left the created branch
  behind, so a retry hit 'branch already exists'. Now delete the orphan
  on rollback — the operation is retry-safe.

- empty execution_ref: when gh pr create succeeds (rc 0) with no URL on
  stdout, the proposal silently recorded an empty audit ref. The PR was
  created (re-running would duplicate it), so keep 'applied' but surface
  the missing URL in the detail instead of losing it silently.

* chore(deps): remove vestigial uv.lock

Nothing reads this lockfile: every install path (ci.yml, audit.yml,
release.yml) uses `pip install -e ".[extras]"` resolved from
pyproject.toml. There is no [tool.uv] config and no CI `uv lock --check`,
so the committed lock had drifted lean while a fresh `uv lock` resolves
the full optional-extra tree (torch/CUDA/transformers).

Removing it stops Dependabot from opening regressive weekly uv-lock PRs
against an artifact that affects nothing. pip + pyproject is the real,
authoritative install path.

* fix(automation): force-checkout default branch on apply_change rollback

Review follow-up to eeb910c. The orphan-branch cleanup only worked when
apply_change failed without dirtying the tree. In the common case where
apply_change writes a partial file then raises, a plain checkout of the
default branch is blocked ('local changes would be overwritten'), its
unchecked returncode leaves HEAD on the orphan, and the orphan delete is
then refused ('currently checked out') — stranding the repo on the orphan,
the exact failure the cleanup targets.

Use a force checkout: the worktree is verified clean before apply_change
(skip-dirty rail), so it only discards apply_change's partial writes, then
the orphan deletes cleanly.

Author: saagpatel

src/automation_executor.py

@@ -159,9 +159,15 @@ def execute_context_pr(
     try:
         plan.apply_change(plan.repo_path)
     except Exception as error:  # noqa: BLE001 - surface as a failed result, not a strand
-        # The change failed after the branch was created; best-effort return to
-        # the default branch so the repo is not left stranded on a partial branch.
-        runner(["git", "checkout", default_branch], plan.repo_path)
+        # The change failed after the branch was created. apply_change may have
+        # left partial writes, so a plain checkout would be blocked ("local
+        # changes would be overwritten") and we'd be stranded on the orphan with
+        # the branch -D refused ("currently checked out"). Force-checkout the
+        # default branch — the worktree was verified clean before apply_change,
+        # so -f only discards its partial garbage — then delete the orphan so a
+        # retry isn't blocked by an "already exists" branch.
+        runner(["git", "checkout", "-f", default_branch], plan.repo_path)
+        runner(["git", "branch", "-D", branch], plan.repo_path)
         return ExecutionResult(proposal.proposal_id, "failed", f"apply-change: {error}".strip())
 
     for args in (
@@ -194,11 +200,21 @@ def execute_context_pr(
     if pr.returncode != 0:
         return ExecutionResult(proposal.proposal_id, "failed", f"gh pr create: {pr.stderr}".strip())
 
+    # gh prints the PR URL on success. If it somehow reported success with no
+    # URL, the PR was still created (rc 0) so we must not fail and re-run (that
+    # would duplicate it) — but surface the missing reference in the detail
+    # rather than silently recording an empty audit ref.
+    pr_url = pr.stdout.strip()
+    detail = (
+        f"Opened PR on branch {branch}."
+        if pr_url
+        else f"Opened PR on branch {branch} (gh returned no PR URL)."
+    )
     return ExecutionResult(
         proposal.proposal_id,
         "applied",
-        f"Opened PR on branch {branch}.",
-        reference=pr.stdout.strip(),
+        detail,
+        reference=pr_url,
     )
 
 

src/automation_workflow.py

@@ -53,8 +53,10 @@
 CONTRACT_VERSION = "automation_workflow_v1"
 
 # Auto-PR branch defaults. ``default_branch`` is the PR base / the branch the
-# executor refuses to commit onto; it is a parameter (not a buried literal) so
-# callers can override per-repo, defaulting to the portfolio convention.
+# executor refuses to commit onto. It resolves in precedence order: an explicit
+# caller override, then the repo's own detected default branch
+# (``identity.default_branch``), then this portfolio-wide fallback. Passing ""
+# (the new default) means "auto-detect per repo".
 DEFAULT_BRANCH_PREFIX = "auto/context-"
 DEFAULT_DEFAULT_BRANCH = "main"
 
@@ -75,15 +77,18 @@ def build_context_pr_plan(
     *,
     workspace_root: Path,
     branch_prefix: str = DEFAULT_BRANCH_PREFIX,
-    default_branch: str = DEFAULT_DEFAULT_BRANCH,
+    default_branch: str = "",
 ) -> ExecutionPlan:
     """Build the ``ExecutionPlan`` for a context-improvement auto-PR.
 
     The plan's ``apply_change`` regenerates the managed context block from the
     project's current repository signals; the executor handles all git/gh
-    mechanics (and every safety rail) around it.
+    mechanics (and every safety rail) around it. The PR base resolves in
+    precedence order: explicit ``default_branch`` arg, the repo's detected
+    default branch, then the portfolio-wide fallback.
     """
     repo_path = workspace_root / project.identity.path
+    resolved_branch = default_branch or project.identity.default_branch or DEFAULT_DEFAULT_BRANCH
     display = project.identity.display_name
     commit_message = f"docs(context): refresh managed context block for {display}"
     pr_body = (
@@ -95,7 +100,7 @@ def build_context_pr_plan(
     )
     return ExecutionPlan(
         repo_path=repo_path,
-        default_branch=default_branch,
+        default_branch=resolved_branch,
         branch_name=f"{branch_prefix}{_branch_slug(project)}",
         commit_message=commit_message,
         pr_title=commit_message,
@@ -148,7 +153,7 @@ def execute_approved_proposals(
     dry_run: bool = True,
     runner: CommandRunner = default_command_runner,
     branch_prefix: str = DEFAULT_BRANCH_PREFIX,
-    default_branch: str = DEFAULT_DEFAULT_BRANCH,
+    default_branch: str = "",
 ) -> list[ExecutionResult]:
     """Execute every APPROVED proposal in the queue, behind the executor's rails.
 

src/cli.py

@@ -41,6 +41,7 @@
 from src.cloner import clone_workspace
 from src.github_client import GitHubClient
 from src.models import AnalyzerResult, AuditReport, RepoAudit, RepoMetadata
+from src.portfolio_truth_types import TRUTH_LATEST_FILENAME, truth_latest_path
 from src.recurring_review import FULL_REFRESH_DAYS
 from src.report_enrichment import build_run_change_counts, build_run_change_summary
 from src.reporter import (
@@ -2742,7 +2743,7 @@ def _run_plan_campaign_mode(args) -> None:
     reviewer: str = getattr(args, "approval_reviewer", None) or _default_reviewer()
 
     # ── Load audit results from portfolio-truth-latest.json ───────────────────
-    truth_path = output_dir / "portfolio-truth-latest.json"
+    truth_path = truth_latest_path(output_dir)
     if not truth_path.exists():
         print_info(
             f"portfolio-truth-latest.json not found in {output_dir}. "
@@ -2870,7 +2871,7 @@ def _run_draft_readmes_mode(args) -> None:
 
     # ── Load audit results (portfolio-truth-latest.json or warehouse) ─────────
     audit_results: list[dict] = []
-    truth_path = output_dir / "portfolio-truth-latest.json"
+    truth_path = truth_latest_path(output_dir)
     if truth_path.exists():
         try:
             raw = json.loads(truth_path.read_text(encoding="utf-8"))
@@ -3036,7 +3037,7 @@ def _run_set_initiative_mode(args) -> None:
     # Load portfolio-truth to validate repo and check current tier
     import json as _json
 
-    pt_candidates = sorted(output_dir.glob("portfolio-truth-latest.json"))
+    pt_candidates = sorted(output_dir.glob(TRUTH_LATEST_FILENAME))
     if not pt_candidates:
         pt_candidates = sorted(output_dir.glob("portfolio-truth-*.json"))
     if not pt_candidates:
@@ -3046,7 +3047,7 @@ def _run_set_initiative_mode(args) -> None:
         )
         sys.exit(2)
 
-    pt_path = Path(str(output_dir / "portfolio-truth-latest.json"))
+    pt_path = truth_latest_path(output_dir)
     if not pt_path.exists():
         pt_path = pt_candidates[-1]
 
@@ -3109,7 +3110,7 @@ def _run_list_initiatives_mode(args) -> None:
 
     # Load portfolio-truth for current-tier lookup (best-effort)
     projects_by_name: dict[str, dict] = {}
-    pt_path = output_dir / "portfolio-truth-latest.json"
+    pt_path = truth_latest_path(output_dir)
     if pt_path.exists():
         try:
             pt_data = _json.loads(pt_path.read_text(encoding="utf-8"))
@@ -3194,7 +3195,7 @@ def _run_suggest_initiatives_mode(args) -> None:
     from src.maturity_tiers import tier_name
     from src.suggest_initiatives import generate_suggestions
 
-    truth_path = _Path(args.output_dir) / "portfolio-truth-latest.json"
+    truth_path = truth_latest_path(_Path(args.output_dir))
     if not truth_path.exists():
         print_warning(
             "portfolio-truth-latest.json not found. "
@@ -3238,7 +3239,7 @@ def _run_accept_suggestion_mode(args) -> None:
     from src.suggest_initiatives import accept_suggestion
 
     output_dir = Path(args.output_dir)
-    truth_path = output_dir / "portfolio-truth-latest.json"
+    truth_path = truth_latest_path(output_dir)
     if not truth_path.exists():
         print_warning(
             "portfolio-truth-latest.json not found. Run `audit run --portfolio-truth` first."
@@ -3369,7 +3370,7 @@ def _run_tier_gaps_export_mode(args) -> None:
     from src.maturity_tiers import compute_tier, tier_gap, tier_name
 
     output_dir = Path(args.output_dir)
-    truth_path = output_dir / "portfolio-truth-latest.json"
+    truth_path = truth_latest_path(output_dir)
     if not truth_path.exists():
         print_warning(
             "portfolio-truth-latest.json not found. Run `audit run --portfolio-truth` first."
@@ -5114,7 +5115,7 @@ def _run_auto_apply_approved_mode(args, output_dir: Path) -> None:
         print_info("No existing audit report found in output directory. Run a normal audit first.")
         return
 
-    truth_path = output_dir / "portfolio-truth-latest.json"
+    truth_path = truth_latest_path(output_dir)
     if not truth_path.exists():
         print_info("No portfolio truth snapshot found. Run --portfolio-truth first.")
         return
@@ -5586,7 +5587,7 @@ def _run_tier_recalibration_report_mode(args) -> None:
     from src.tier_recalibration import tier_distribution_report
 
     output_dir = Path(args.output_dir)
-    truth_path = output_dir / "portfolio-truth-latest.json"
+    truth_path = truth_latest_path(output_dir)
     if not truth_path.exists():
         print_warning(
             "portfolio-truth-latest.json not found. Run `audit run --portfolio-truth` first."
@@ -5626,7 +5627,7 @@ def _run_context_triage_mode(args) -> None:
     from src.portfolio_context_triage import run_triage
 
     output_dir = Path(args.output_dir)
-    truth_path = output_dir / "portfolio-truth-latest.json"
+    truth_path = truth_latest_path(output_dir)
     if not truth_path.exists():
         print_warning(
             "portfolio-truth-latest.json not found. Run `audit run --portfolio-truth` first."

src/excel_export_truth_helpers.py

@@ -5,12 +5,14 @@
 import json
 from pathlib import Path
 
+from src.portfolio_truth_types import truth_latest_path
+
 
 def load_risk_truth(truth_dir: Path | None) -> tuple[dict[str, str], dict[str, int]]:
     if not truth_dir:
         return {}, {}
 
-    truth_path = truth_dir / "portfolio-truth-latest.json"
+    truth_path = truth_latest_path(truth_dir)
     if not truth_path.is_file():
         return {}, {}
 

src/portfolio_truth_publish.py

@@ -7,6 +7,7 @@
 
 from src.portfolio_truth_reconcile import build_portfolio_truth_snapshot
 from src.portfolio_truth_render import render_portfolio_report_markdown, render_registry_markdown
+from src.portfolio_truth_types import truth_latest_path
 from src.portfolio_truth_validate import (
     validate_portfolio_report_markdown,
     validate_publish_targets,
@@ -56,7 +57,7 @@ def publish_portfolio_truth(
 
     snapshot_stamp = build_result.snapshot.generated_at.strftime("%Y-%m-%dT%H%M%SZ")
     snapshot_path = output_dir / f"portfolio-truth-{snapshot_stamp}.json"
-    latest_path = output_dir / "portfolio-truth-latest.json"
+    latest_path = truth_latest_path(output_dir)
     latest_name = latest_path.name
     snapshot_json = json.dumps(build_result.snapshot.to_dict(), indent=2) + "\n"
     registry_markdown = render_registry_markdown(build_result.snapshot)

src/portfolio_truth_reconcile.py

@@ -348,6 +348,7 @@ def _build_truth_project(
         section_label=_resolve_section_label(group_entry, raw_project),
         has_git=bool(raw_project["has_git"]),
         repo_full_name=str(raw_project.get("repo_full_name") or ""),
+        default_branch=str(raw_project.get("default_branch") or ""),
     )
 
     declared_values = {

src/portfolio_truth_sources.py

@@ -285,6 +285,7 @@ def _inspect_project_dir(
         "group_entry": group_entry,
         "has_git": bool(git_facts.get("has_git")),
         "repo_full_name": str(git_facts.get("repo_full_name", "") or "").strip(),
+        "default_branch": str(git_facts.get("default_branch", "") or "").strip(),
         "context_files": context_files,
         "context_quality": context_analysis.context_quality,
         "primary_context_file": context_analysis.primary_context_file,
@@ -405,7 +406,21 @@ def _read_small_json(path: Path) -> dict[str, Any]:
 def _gather_git_facts(project_path: Path) -> dict[str, Any]:
     git_dir = project_path / ".git"
     if not git_dir.exists():
-        return {"has_git": False, "last_commit_at": None, "repo_full_name": ""}
+        return {
+            "has_git": False,
+            "last_commit_at": None,
+            "repo_full_name": "",
+            "default_branch": "",
+        }
+
+    # Computed once; ``last_commit_at`` is the only field the git-log probe below
+    # can refine, so every error path returns this base unchanged.
+    base = {
+        "has_git": True,
+        "last_commit_at": None,
+        "repo_full_name": _git_remote_full_name(project_path),
+        "default_branch": _git_default_branch(project_path),
+    }
 
     try:
         result = subprocess.run(
@@ -416,31 +431,43 @@ def _gather_git_facts(project_path: Path) -> dict[str, Any]:
             check=False,
         )
     except (FileNotFoundError, subprocess.TimeoutExpired):
-        return {
-            "has_git": True,
-            "last_commit_at": None,
-            "repo_full_name": _git_remote_full_name(project_path),
-        }
+        return base
 
     if result.returncode != 0 or not result.stdout.strip():
-        return {
-            "has_git": True,
-            "last_commit_at": None,
-            "repo_full_name": _git_remote_full_name(project_path),
-        }
+        return base
 
     try:
         return {
-            "has_git": True,
+            **base,
             "last_commit_at": datetime.fromisoformat(result.stdout.strip().replace("Z", "+00:00")),
-            "repo_full_name": _git_remote_full_name(project_path),
         }
     except ValueError:
-        return {
-            "has_git": True,
-            "last_commit_at": None,
-            "repo_full_name": _git_remote_full_name(project_path),
-        }
+        return base
+
+
+def _git_default_branch(project_path: Path) -> str:
+    """The repo's default branch from the local ``origin/HEAD`` ref, if set.
+
+    Resolves only local refs (no network). Returns "" when ``origin/HEAD`` is
+    not set locally (common for repos that were ``git init``'d rather than
+    cloned) — callers fall back to the portfolio default.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(project_path), "symbolic-ref", "--short", "refs/remotes/origin/HEAD"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return ""
+
+    if result.returncode != 0:
+        return ""
+    # e.g. "origin/main" -> "main"; partition keeps multi-segment branch names
+    # like "origin/release/v1" -> "release/v1" intact.
+    return result.stdout.strip().partition("/")[2].strip()
 
 
 def _git_remote_full_name(project_path: Path) -> str:

src/portfolio_truth_types.py

@@ -3,10 +3,22 @@
 import dataclasses
 from dataclasses import dataclass, field
 from datetime import datetime
+from pathlib import Path
 from typing import Any
 
 SCHEMA_VERSION = "0.5.0"
 
+# The published "latest" portfolio-truth artifact. The producer
+# (portfolio_truth_publish) writes it; every reader resolves it through
+# truth_latest_path() so the filename lives in exactly one place.
+TRUTH_LATEST_FILENAME = "portfolio-truth-latest.json"
+
+
+def truth_latest_path(output_dir: Path) -> Path:
+    """Resolve the canonical portfolio-truth-latest.json under an output dir."""
+    return output_dir / TRUTH_LATEST_FILENAME
+
+
 VALID_CONTEXT_QUALITY = {"full", "standard", "minimum-viable", "boilerplate", "none"}
 VALID_ACTIVITY_STATUS = {"active", "recent", "stale", "archived"}
 VALID_REGISTRY_STATUS = {"active", "recent", "parked", "archived"}
@@ -47,6 +59,9 @@ class IdentityFields:
     # metadata.name) and not only the local-dir display_name, which often differ
     # (e.g. "Signal & Noise" vs "signal-noise").
     repo_full_name: str = ""
+    # The repo's default branch (from local ``origin/HEAD``), when detectable.
+    # Empty when not set locally; consumers fall back to the portfolio default.
+    default_branch: str = ""
 
     def to_dict(self) -> dict[str, Any]:
         return dataclasses.asdict(self)

src/report_enrichment.py

@@ -5,6 +5,7 @@
 from pathlib import Path
 from typing import Any
 
+from src.portfolio_truth_types import truth_latest_path
 from src.terminology import ACTION_SYNC_CANONICAL_LABELS
 from src.weekly_packaging import finalize_weekly_pack
 from src.weekly_scheduling_overlay import apply_weekly_scheduling_overlay
@@ -164,7 +165,7 @@ def build_risk_lookup(output_dir: Path | None) -> dict[str, dict[str, str]]:
     """
     if not output_dir:
         return {}
-    truth_path = output_dir / "portfolio-truth-latest.json"
+    truth_path = truth_latest_path(output_dir)
     if not truth_path.is_file():
         return {}
     try: