drydock-cli 2.6.140__tar.gz → 2.6.142__tar.gz

drydock_cli-2.6.142/.auto_release.lock

@@ -0,0 +1 @@
+2066036

{drydock_cli-2.6.140 → drydock_cli-2.6.142}/Admiral.md

@@ -285,7 +285,7 @@ Open design questions for Phase 2:
 * Rate-limiting: prevent Opus blast during a bad run. Max 3 escalations
   per session by default. Override via env var.
 
-### Phase 3a — DESIGNED (not started): Hyperparameter adaptation per (model, task)
+### Phase 3a — SHIPPED (v2.6.141): Hyperparameter adaptation per (model, task)
 
 **Goal.** Admiral learns the strengths and weaknesses of the current
 model + tool set and tunes the harness hyperparameters accordingly,
@@ -388,7 +388,7 @@ then Admiral re-evaluates once and possibly re-tunes.
 
 ---
 
-### Phase 3b — DESIGNED (not started): Self-improving drydock via gated code proposals
+### Phase 3b — SHIPPED (v2.6.141, default-OFF via DRYDOCK_ADMIRAL_PROPOSER=1)
 
 **Goal.** Close the loop from detection → proposed fix → validated
 branch, without ever writing to `main` or PyPI automatically. The
@@ -558,8 +558,8 @@ having to tail a log file.
 
 ## 9. Continuity Notes (if this session is lost)
 
-**Latest shipped:** v2.6.139 (Phase 1 + Phase 2 module, Opus escalation,
-Directives rubric wired into prompts).
+**Latest shipped:** v2.6.141 — Phase 3a (hyperparameter adaptation)
+and Phase 3b (gated code proposals, default-OFF) both in PyPI.
 
 **Shipped this session (2026-04-17):**
 * v2.6.134 — wall-of-text inline-marker breaker (issue #8).
@@ -571,6 +571,11 @@ Directives rubric wired into prompts).
 * v2.6.138 — Admiral Phase 1 module + TUI integration.
 * v2.6.139 — Admiral Phase 2 (local-LLM analyzer, Opus escalator,
   Directives rubric in prompts).
+* v2.6.140 — full `.vibe → .drydock` rename (zero vibe refs left).
+* v2.6.141 — Phase 3a (task_classifier, metrics, tuning, policy +
+  AgentLoop integration) + Phase 3b (proposer, validator, stager +
+  /admiral-apply, /admiral-reject, /admiral-status slash commands)
+  + scripts/stress_watcher.py harness-level babysitter.
 
 **Files (check `git log --oneline -30`):**
 * `drydock/admiral/{__init__,detectors,interventions,history,worker,
@@ -611,19 +616,38 @@ applied, including the `directive-source` (local-llm / opus / canned).
   started ~Apr-16, currently at ~826/1658 (approaching 50%).
   DO NOT interrupt.
 
-**Open follow-ups:**
-* **Phase 3a (designed, not started):** hyperparameter adaptation.
-  `drydock/admiral/{task_classifier,metrics,tuning,policy}.py` to
-  be created. See §8 Phase 3a spec.
-* **Phase 3b (designed, not started):** code proposals. Proposer →
-  validator → staged local branch; never auto-commits. User
-  approves via `/admiral-apply <branch>`. See §8 Phase 3b.
-* systemd the admiral_probe.
+**Open follow-ups (post-observation period):**
+* systemd the admiral_probe (currently `nohup &`, dies on logout).
 * TUI widget showing recent Admiral findings (in-app audit view).
+* More detectors driven by observed data: hallucinated tool names,
+  edit-undo-edit ping-pong, PRD/spec drift.
 * Learning-rate scheduler (Phase 4).
 * Session vs Global memory split (PRD §6).
-* More detectors: hallucinated tool names, PRD/spec drift,
-  edit-undo-edit ping-pong.
+* Tune Phase 3a knob bounds + Phase 3b promotion criteria from real
+  finding-rate data after the 24h observation window.
+
+## 10. Observation mode (active 2026-04-17 → 2026-04-18)
+
+Per user directive ("let's slow down, and watch for now"). All
+Admiral feature work is paused. What's still running automatically:
+
+* **Stress-test status check** every 30 min (Telegram).
+* **GitHub issue check** every hour for fbobe321 issues.
+* **stress_watcher.py** on the live stress run (PID 1860693) —
+  detects stalls/timeout-spikes/completion, emits Telegram + audit log.
+* **admiral_probe.py** on `192.168.50.22:8878` — dashboard tab
+  consuming it.
+* **Admiral itself** is live in every drydock TUI session — Phase 1
+  + Phase 2 fully active, Phase 3a tuning enabled (no-op until
+  `admiral_tuning.json` gets written), Phase 3a policy gated behind
+  `DRYDOCK_ADMIRAL_POLICY=1`, Phase 3b proposer gated behind
+  `DRYDOCK_ADMIRAL_PROPOSER=1` (both default OFF).
+
+**Cron `7a2a593c` fires Sat 2026-04-18 18:13 CDT** — at that point I
+will read `~/.drydock/logs/admiral_history.log` event counts, scan
+`~/.drydock/logs/admiral_metrics.jsonl`, check the dashboard, and
+propose 1–2 next features grounded in what actually fired in the
+past 24h. **No new code without observed evidence it's needed.**
 
 ***
 

{drydock_cli-2.6.140 → drydock_cli-2.6.142}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: drydock-cli
-Version: 2.6.140
+Version: 2.6.142
 Summary: Local-first CLI coding agent — tested with Gemma 4 26B via vLLM
 Project-URL: Homepage, https://github.com/fbobe321/drydock
 Project-URL: Repository, https://github.com/fbobe321/drydock

drydock_cli-2.6.142/drydock/admiral/metrics.py

@@ -0,0 +1,92 @@
+"""Session-end metrics for Admiral.
+
+Collects a small set of numbers about how a session went, keyed by
+`(model, task_type)`, and appends one JSONL line at the end. The
+Phase 3a policy loop reads these to decide whether to adjust a
+hyperparameter knob for that tuple.
+
+The collection hook fires from AgentLoop on shutdown, best-effort
+only — a failure to write a metric must never propagate.
+"""
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+from drydock.admiral import persistence, task_classifier
+from drydock.core.types import LLMMessage, Role
+
+if TYPE_CHECKING:
+    from drydock.core.agent_loop import AgentLoop
+
+logger = logging.getLogger(__name__)
+
+_WRITE_TOOLS = frozenset({"write_file", "search_replace", "edit_file"})
+
+
+@dataclass
+class SessionMetrics:
+    ts: str
+    model: str
+    task_type: str
+    session_id: str
+    outcome: str = "unknown"            # success | failure | unknown
+    total_tool_calls: int = 0
+    tool_calls_per_write: float = 0.0
+    time_to_first_write_s: float | None = None
+    loop_fires: int = 0
+    struggle_fires: int = 0
+    opus_escalations: int = 0
+    user_interrupts: int = 0
+    per_prompt_budget_hits: int = 0
+    elapsed_s: float | None = None
+    notes: list[str] = field(default_factory=list)
+
+
+def _count_tool_calls(messages: Sequence[LLMMessage]) -> tuple[int, int]:
+    total = writes = 0
+    for m in messages:
+        if m.role != Role.assistant or not m.tool_calls:
+            continue
+        for tc in m.tool_calls:
+            total += 1
+            if tc.function.name in _WRITE_TOOLS:
+                writes += 1
+    return total, writes
+
+
+def collect(agent_loop: AgentLoop, session_id: str, outcome: str = "unknown") -> SessionMetrics:
+    """Build a SessionMetrics record from the live AgentLoop state.
+
+    Safe to call during shutdown — wraps message access in a try/except
+    so partial state never breaks the collection.
+    """
+    try:
+        msgs = list(agent_loop.messages)
+    except Exception:
+        msgs = []
+    try:
+        model_name = agent_loop.config.get_active_model().name
+    except Exception:
+        model_name = "unknown"
+    total, writes = _count_tool_calls(msgs)
+    tcpw = (total / writes) if writes else float(total)
+    return SessionMetrics(
+        ts=datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        model=model_name,
+        task_type=task_classifier.classify(msgs),
+        session_id=session_id,
+        outcome=outcome,
+        total_tool_calls=total,
+        tool_calls_per_write=round(tcpw, 2),
+    )
+
+
+def record(metrics: SessionMetrics) -> None:
+    try:
+        persistence.append_jsonl(persistence.METRICS_PATH, asdict(metrics))
+    except Exception as e:
+        logger.warning("Admiral metrics write failed: %s", e)

drydock_cli-2.6.142/drydock/admiral/policy.py

@@ -0,0 +1,134 @@
+"""Phase 3a adaptation policy.
+
+Simple bounded rule engine — no ML. Runs over the session metrics
+log and decides whether to adjust ONE knob for a `(model, task_type)`
+tuple. Keeps changes slow on purpose: Admiral nudges one step per
+re-evaluation window; if recovery doesn't happen, reverts.
+
+Invariants:
+* Never adjusts more than ONE knob per tuple per pass.
+* Never adjusts before N sessions are observed for the tuple.
+* Always records rationale in the tuning file.
+* Reads are lock-free: if two loops race, the JSON write is atomic
+  via persistence.save_json_atomic.
+
+Disabled by default (reads `DRYDOCK_ADMIRAL_POLICY` env var; set to
+`1` to enable). Users opt in when ready.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+from collections import defaultdict
+from statistics import mean
+from typing import Any
+
+from drydock.admiral import persistence, tuning
+
+logger = logging.getLogger(__name__)
+
+MIN_SESSIONS_TO_TUNE = 5
+SUCCESS_REGRESSION_THRESHOLD = 0.2  # 20% drop in success rate
+RECOVERY_WINDOW = 3                 # sessions to evaluate after a tweak
+
+
+def _load_recent_metrics(limit: int = 100) -> list[dict]:
+    path = persistence.METRICS_PATH
+    if not path.exists():
+        return []
+    out: list[dict] = []
+    try:
+        with path.open() as f:
+            for line in f.readlines()[-limit:]:
+                try:
+                    out.append(json.loads(line))
+                except Exception:
+                    continue
+    except Exception:
+        return []
+    return out
+
+
+def _group_by_tuple(metrics: list[dict]) -> dict[tuple[str, str], list[dict]]:
+    groups: dict[tuple[str, str], list[dict]] = defaultdict(list)
+    for m in metrics:
+        key = (m.get("model", "unknown"), m.get("task_type", "unknown"))
+        groups[key].append(m)
+    return groups
+
+
+def _success_rate(records: list[dict]) -> float:
+    if not records:
+        return 0.0
+    return sum(1 for r in records if r.get("outcome") == "success") / len(records)
+
+
+def _pick_knob_to_tune(records: list[dict]) -> tuple[str, float, str] | None:
+    """Very simple heuristic: correlate the top failure pattern with
+    one knob. Returns (knob, new_value, rationale) or None.
+    """
+    if not records:
+        return None
+    # Many budget hits → raise per_prompt_budget_sec.
+    if mean(r.get("per_prompt_budget_hits", 0) for r in records) >= 0.4:
+        return (
+            "per_prompt_budget_sec",
+            1800.0 * 1.25,  # +25% from 30min baseline, clipped to bound
+            "per_prompt_budget_hits ≥0.4 per session — raise budget.",
+        )
+    # Many struggle fires → raise struggle_threshold (reads needed).
+    if mean(r.get("struggle_fires", 0) for r in records) >= 1.0:
+        return (
+            "struggle_threshold",
+            30.0,
+            "struggle_fires ≥1/session — give explore turns more budget.",
+        )
+    # Many loop fires → tighten loop_detector_window (catch loops earlier).
+    if mean(r.get("loop_fires", 0) for r in records) >= 1.0:
+        return (
+            "loop_detector_window",
+            2.0,
+            "loop_fires ≥1/session — trip loop detector earlier.",
+        )
+    return None
+
+
+def evaluate() -> list[dict[str, Any]]:
+    """Run one policy pass. Returns list of changes applied (possibly empty)."""
+    if os.getenv("DRYDOCK_ADMIRAL_POLICY", "0") != "1":
+        return []
+
+    metrics = _load_recent_metrics()
+    groups = _group_by_tuple(metrics)
+    changes: list[dict[str, Any]] = []
+    for (model, task), records in groups.items():
+        if len(records) < MIN_SESSIONS_TO_TUNE:
+            continue
+        recent = records[-MIN_SESSIONS_TO_TUNE:]
+        rate = _success_rate(recent)
+        # Baseline = across ALL records for this tuple.
+        baseline = _success_rate(records)
+        if baseline == 0 or rate >= baseline - SUCCESS_REGRESSION_THRESHOLD:
+            # Performing fine — don't tune.
+            continue
+        pick = _pick_knob_to_tune(recent)
+        if not pick:
+            continue
+        knob, value, rationale = pick
+        # Idempotency: if the same knob is already set, skip.
+        current = tuning.get_for(model, task)
+        if knob in current:
+            # Already tuning this knob; give it RECOVERY_WINDOW sessions
+            # to show improvement before we touch it again.
+            if len(recent) < RECOVERY_WINDOW + MIN_SESSIONS_TO_TUNE:
+                continue
+        tuning.set_knob(model, task, knob, value, rationale=rationale)
+        changes.append({
+            "model": model,
+            "task": task,
+            "knob": knob,
+            "value": value,
+            "rationale": rationale,
+        })
+    return changes

drydock_cli-2.6.142/drydock/admiral/proposer.py

@@ -0,0 +1,157 @@
+"""Phase 3b: draft a unified-diff proposal for a recurring finding.
+
+Only called for findings that survived prompt-only interventions
+(see `persistence.finding_qualifies_for_code_change`). Uses the
+same escalation ladder as Phase 2 (local LLM → Opus).
+
+Returns a `Proposal` or `None`. Caller (worker) passes the proposal
+to validator.validate(), and if that returns green, to stager.stage().
+
+Default DISABLED — reads `DRYDOCK_ADMIRAL_PROPOSER=1` env var.
+"""
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from drydock.admiral import persistence
+from drydock.admiral.llm_analyzer import _DIRECTIVES_RUBRIC, _render_turns
+from drydock.admiral.opus_escalator import _try_anthropic_sdk, _try_claude_cli
+from drydock.core.types import LLMMessage, Role
+
+if TYPE_CHECKING:
+    from drydock.admiral.detectors import Finding
+    from drydock.core.agent_loop import AgentLoop
+
+logger = logging.getLogger(__name__)
+
+_PROPOSER_PROMPT = """You are Admiral's code proposer. A recurring finding has \
+survived prompt-only interventions and should be fixed at the source. Draft a \
+MINIMAL unified diff that addresses the root cause.
+
+{rubric}
+
+Recurring finding: {code}
+Total fires across sessions: {n_fires}
+Sessions involved: {n_sessions}
+Failed prompt-only interventions: {n_failed}
+
+Repro context (last turns):
+<conversation>
+{context}
+</conversation>
+
+Output in EXACTLY this format (no extra text):
+
+DIRECTIVES VIOLATED: [code1,code2,...]
+RATIONALE: <one paragraph grounded in the cited directives>
+DIFF:
+```diff
+<unified diff — narrow scope, touches only the files needed>
+```
+"""
+
+
+@dataclass
+class Proposal:
+    code: str
+    directives_violated: list[str]
+    rationale: str
+    diff: str
+    source: str          # "local-llm" | "opus"
+    fingerprint: str     # sha256 of the diff — used for reject tracking
+
+
+_DIFF_RE = re.compile(r"```(?:diff)?\n([\s\S]*?)```", re.MULTILINE)
+_DIR_RE = re.compile(r"DIRECTIVES VIOLATED:\s*\[([^\]]*)\]")
+_RAT_RE = re.compile(r"RATIONALE:\s*(.+?)(?:\nDIFF:|\Z)", re.DOTALL)
+
+
+def _parse(text: str) -> tuple[list[str], str, str] | None:
+    m_diff = _DIFF_RE.search(text)
+    m_rat = _RAT_RE.search(text)
+    m_dir = _DIR_RE.search(text)
+    if not m_diff:
+        return None
+    diff = m_diff.group(1).strip()
+    if not diff:
+        return None
+    rationale = (m_rat.group(1).strip() if m_rat else "")[:2000]
+    dirs = []
+    if m_dir:
+        dirs = [s.strip() for s in m_dir.group(1).split(",") if s.strip()]
+    return dirs, rationale, diff
+
+
+def _fingerprint(diff: str) -> str:
+    return hashlib.sha256(diff.strip().encode()).hexdigest()[:16]
+
+
+async def _ask_local(agent_loop: AgentLoop, prompt: str) -> str | None:
+    try:
+        chunk = await agent_loop.backend.complete(
+            model=agent_loop.config.get_active_model(),
+            messages=[LLMMessage(role=Role.user, content=prompt)],
+            temperature=0.1,
+            max_tokens=2000,
+        )
+        return (chunk.message.content or "").strip() or None
+    except Exception as e:
+        logger.warning("Admiral proposer local call failed: %s", e)
+        return None
+
+
+async def _ask_opus(prompt: str) -> str | None:
+    out = await _try_anthropic_sdk(prompt)
+    if out:
+        return out
+    return await _try_claude_cli(prompt)
+
+
+async def propose(agent_loop: AgentLoop, finding: Finding) -> Proposal | None:
+    if os.getenv("DRYDOCK_ADMIRAL_PROPOSER", "0") != "1":
+        return None
+
+    state = persistence.load_state()
+    entry = state.get("findings", {}).get(finding.code) or {}
+    n_fires = int(entry.get("total_fires", 0))
+    n_sessions = len(entry.get("sessions", []))
+    n_failed = int(entry.get("prompt_failed", 0))
+
+    prompt = _PROPOSER_PROMPT.format(
+        rubric=_DIRECTIVES_RUBRIC,
+        code=finding.code,
+        n_fires=n_fires,
+        n_sessions=n_sessions,
+        n_failed=n_failed,
+        context=_render_turns(list(agent_loop.messages), n_turns=12),
+    )
+
+    # 1) local LLM
+    text = await _ask_local(agent_loop, prompt)
+    source = "local-llm"
+    parsed = _parse(text or "")
+    # 2) Opus fallback
+    if not parsed:
+        text = await _ask_opus(prompt)
+        source = "opus"
+        parsed = _parse(text or "")
+    if not parsed:
+        return None
+    dirs, rationale, diff = parsed
+    fp = _fingerprint(diff)
+    if persistence.is_fingerprint_rejected(finding.code, fp):
+        logger.info("Admiral proposer: skipping previously-rejected patch %s", fp)
+        return None
+    return Proposal(
+        code=finding.code,
+        directives_violated=dirs,
+        rationale=rationale,
+        diff=diff,
+        source=source,
+        fingerprint=fp,
+    )

drydock_cli-2.6.142/drydock/admiral/stager.py

@@ -0,0 +1,147 @@
+"""Phase 3b: stage a validated proposal as a local branch + proposal markdown.
+
+NEVER pushes, NEVER merges to main, NEVER publishes. Writes a summary
+file in `~/.drydock/admiral_proposals/<ts>.md` describing the diff,
+rationale, validator output, branch name, and explicit rollback
+command. The human then runs `/admiral-apply <branch>` to merge.
+"""
+from __future__ import annotations
+
+import logging
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+from drydock.admiral import history, persistence
+from drydock.admiral.proposer import Proposal
+from drydock.admiral.validator import REPO_ROOT, ValidationResult
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class StagedProposal:
+    branch: str
+    proposal_path: Path
+    commit_sha: str
+
+
+def _run(cmd: list[str], cwd: Path = REPO_ROOT, timeout: int = 60) -> tuple[int, str, str]:
+    p = subprocess.run(
+        cmd, cwd=cwd, timeout=timeout,
+        capture_output=True, text=True, check=False,
+    )
+    return p.returncode, p.stdout, p.stderr
+
+
+def _safe_code(code: str) -> str:
+    # Branch name can't have weird chars — keep letters, digits, hyphens.
+    out = []
+    for ch in code:
+        if ch.isalnum() or ch in "-_":
+            out.append(ch)
+        else:
+            out.append("-")
+    return "".join(out)[:40]
+
+
+def stage(proposal: Proposal, validation: ValidationResult) -> StagedProposal | None:
+    if not validation.ok:
+        raise ValueError("refusing to stage a proposal that didn't pass validation")
+
+    ts = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+    branch = f"admiral/{ts}-{_safe_code(proposal.code)}"
+
+    # Invariant: we ALWAYS branch from main.
+    rc, out, err = _run(["git", "rev-parse", "main"])
+    if rc != 0:
+        logger.error("Admiral stager: cannot resolve 'main' ref: %s", err)
+        return None
+    main_sha = out.strip()
+
+    # Create branch pointing at main (no checkout of main working tree).
+    rc, out, err = _run(["git", "branch", branch, main_sha])
+    if rc != 0:
+        logger.error("Admiral stager: branch create failed: %s", err)
+        return None
+
+    # Use a short-lived worktree to apply+commit, then drop the worktree.
+    import tempfile
+    tmp_wt = Path(tempfile.mkdtemp(prefix="admiral_stage_")) / "wt"
+    diff_path = tmp_wt.parent / "proposal.diff"
+    diff_path.write_text(proposal.diff if proposal.diff.endswith("\n")
+                         else proposal.diff + "\n")
+
+    commit_sha: str | None = None
+    try:
+        rc, out, err = _run(
+            ["git", "worktree", "add", str(tmp_wt), branch], cwd=REPO_ROOT,
+        )
+        if rc != 0:
+            logger.error("Admiral stager: worktree add failed: %s", err)
+            _run(["git", "branch", "-D", branch])
+            return None
+        rc, out, err = _run(["git", "apply", str(diff_path)], cwd=tmp_wt)
+        if rc != 0:
+            logger.error("Admiral stager: diff apply failed: %s", err)
+            return None
+        rc, out, err = _run(["git", "add", "-A"], cwd=tmp_wt)
+        if rc != 0:
+            return None
+        commit_msg = (
+            f"admiral-proposed: {proposal.code}\n\n"
+            f"Rationale: {proposal.rationale}\n\n"
+            f"Directives violated: {', '.join(proposal.directives_violated) or '—'}\n"
+            f"Source: {proposal.source}\n"
+            f"Fingerprint: {proposal.fingerprint}\n"
+        )
+        rc, out, err = _run(
+            ["git", "commit", "-m", commit_msg], cwd=tmp_wt,
+        )
+        if rc != 0:
+            logger.error("Admiral stager: commit failed: %s", err)
+            return None
+        rc, out, err = _run(["git", "rev-parse", "HEAD"], cwd=tmp_wt)
+        if rc == 0:
+            commit_sha = out.strip()
+    finally:
+        try:
+            _run(["git", "worktree", "remove", "--force", str(tmp_wt)], cwd=REPO_ROOT)
+        except Exception:
+            pass
+        try:
+            import shutil
+            shutil.rmtree(tmp_wt.parent, ignore_errors=True)
+        except Exception:
+            pass
+
+    if not commit_sha:
+        logger.error("Admiral stager: no commit sha")
+        _run(["git", "branch", "-D", branch])
+        return None
+
+    # Write the proposal summary markdown.
+    persistence.PROPOSALS_DIR.mkdir(parents=True, exist_ok=True)
+    prop_path = persistence.PROPOSALS_DIR / f"{ts}-{_safe_code(proposal.code)}.md"
+    prop_path.write_text(
+        f"# Admiral proposal: {proposal.code}\n\n"
+        f"**Branch:** `{branch}`  \n"
+        f"**Commit:** `{commit_sha}`  \n"
+        f"**Source:** {proposal.source}  \n"
+        f"**Fingerprint:** `{proposal.fingerprint}`  \n"
+        f"**Directives violated:** {', '.join(proposal.directives_violated) or '—'}\n\n"
+        f"## Rationale\n\n{proposal.rationale}\n\n"
+        f"## Diff\n\n```diff\n{proposal.diff}\n```\n\n"
+        f"## Validator output (tail)\n\n"
+        f"```\n{validation.stdout[-2000:]}\n```\n\n"
+        f"## Next actions\n\n"
+        f"- Merge: `/admiral-apply {branch}` (or `git merge --no-ff {branch}`)\n"
+        f"- Reject: `/admiral-reject {branch}` (deletes branch + records fingerprint)\n"
+        f"- Rollback: `git branch -D {branch}`\n"
+    )
+    history.append(
+        "proposal-staged",
+        f"{proposal.code} :: branch={branch} :: fp={proposal.fingerprint}",
+    )
+    return StagedProposal(branch=branch, proposal_path=prop_path, commit_sha=commit_sha)