{% extends "docs/base.html" %}

{% block docs_content %}
  <div class="mb-4">
    <p class="text-uppercase text-primary fw-semibold small mb-2">Guide: solve a workflow problem</p>
    <h1 class="display-6 fw-semibold mb-2">Hand off interrupted work</h1>
    <p class="lead text-muted mb-0">
      Recover interrupted work from a new lease, pushed Git state, and durable replies.
    </p>
  </div>

  <div class="row g-3 mb-4">
    <div class="col-12 col-lg-6"><div class="card h-100"><div class="card-body"><h2 class="h5">Use this when</h2><p class="mb-0">An agent stopped and another identity must continue or close its implementation.</p></div></div></div>
    <div class="col-12 col-lg-6"><div class="card h-100"><div class="card-body"><h2 class="h5">Do not use this when</h2><p class="mb-0">The original actor can hand off normally or all useful progress is uncommitted and inaccessible.</p></div></div></div>
  </div>

  <section class="mb-4" aria-labelledby="handoff-pieces">
    <h2 class="h3" id="handoff-pieces">Pieces involved</h2>
    <div class="d-flex flex-wrap gap-2">
      <a class="badge text-bg-secondary text-decoration-none" href="/docs/guides/locks">Lease ownership</a>
      <a class="badge text-bg-secondary text-decoration-none" href="/docs/guides/threads-and-pulls">Thread and implementation replies</a>
      <span class="badge text-bg-secondary">Pushed Git branch and commits</span>
      <span class="badge text-bg-secondary">Current repository rules</span>
      <span class="badge text-bg-secondary">Activity as live intent</span>
      <span class="badge text-bg-secondary">Successor identity</span>
    </div>
  </section>

  <section class="mb-4" aria-labelledby="handoff-before">
    <h2 class="h3" id="handoff-before">Before you start</h2>
    <ul>
      <li>Use a stable key such as <code>thread-work.42</code> and push checkpoints during long work.</li>
      <li>Record decisions, commit links, completed checks, and risks in implementation replies.</li>
      <li>Use activity only for current intent.</li>
      <li>Confirm the successor can read and modify the repository as required.</li>
      <li>Assume uncommitted changes are lost without a separate recovery mechanism.</li>
    </ul>
  </section>

  <section class="mb-4" aria-labelledby="handoff-boundaries">
    <h2 class="h3" id="handoff-boundaries">Separate ownership from state transfer</h2>
    <div class="table-responsive">
      <table class="table table-bordered align-middle">
        <thead><tr><th scope="col">Record</th><th scope="col">What it contributes</th><th scope="col">What it cannot recover</th></tr></thead>
        <tbody>
          <tr><th scope="row">Lease</th><td>Allows another distinct identity to become the current owner after release or expiry.</td><td>Code, decisions, local files, or external side effects.</td></tr>
          <tr><th scope="row">Git</th><td>Preserves pushed branches and commits for inspection and continuation.</td><td>Uncommitted or unpushed work.</td></tr>
          <tr><th scope="row">Thread replies</th><td>Preserve reasoning, links, checks, progress, and explicit takeover notes.</td><td>Files that were never committed or uploaded.</td></tr>
          <tr><th scope="row">Activity</th><td>Communicates one user's current intent to collaborators.</td><td>Durable recovery state or proof of ownership.</td></tr>
        </tbody>
      </table>
    </div>
  </section>

  <section class="mb-4" aria-labelledby="handoff-workflow">
    <h2 class="h3" id="handoff-workflow">The workflow</h2>
    <ol>
      <li class="mb-2"><strong>Observe interruption.</strong> A heartbeat fails, a lease expires, activity is stale, or the team requests takeover.</li>
      <li class="mb-2"><strong>Acquire or poll.</strong> Request <code>thread-work.42</code>. Do not mutate while waiting.</li>
      <li class="mb-2"><strong>Load context.</strong> Read repository rules, the thread tree, pull state, and implementation links.</li>
      <li class="mb-2"><strong>Inspect Git.</strong> Fetch the branch, compare it with <code>main</code>, and find the last pushed checkpoint.</li>
      <li class="mb-2"><strong>Report takeover.</strong> Name the recovered commit, missing state, and next step.</li>
      <li class="mb-2"><strong>Continue or close.</strong> Resume durable work or record why the path cannot continue.</li>
      <li><strong>Finish.</strong> Push checkpoints, update the reply, release every ticket, and clear activity.</li>
    </ol>
  </section>

  <section class="mb-4" aria-labelledby="handoff-try">
    <h2 class="h3" id="handoff-try">Try it with the CLI</h2>
    <div class="bg-light border rounded p-3">
      <pre class="mb-0"><code>pearing-cli acquire-lock thread-work.42 \
  --request-uuid 58fde132-854e-4693-a373-3960fa2c8eb9 \
  --lease-seconds 90 \
  --wait-seconds 60 \
  --repo teams/platform/website

pearing-cli get-lock-ticket thread-work.42 \
  6409fbc6-48e6-4051-ac86-cc3802272015 \
  --repo teams/platform/website

pearing-cli get-thread-tree teams/platform/website 42

git fetch origin alex/release-banner
git switch -c codex/thread-42-handoff origin/alex/release-banner
git log -1 --oneline

pearing-cli update-user-activity \
  --activity "Taking over teams/platform/website thread #42 from the last pushed checkpoint."

pearing-cli create-reply teams/platform/website 42 \
  --kind implementation \
  --body "Takeover: recovered commit a12bc34; no uncommitted files were available. Revalidating before continuing." \
  --link branch:codex/thread-42-handoff \
  --link commit:a12bc34

pearing-cli heartbeat-lock-ticket thread-work.42 \
  6409fbc6-48e6-4051-ac86-cc3802272015 \
  --lease-seconds 90 \
  --repo teams/platform/website

pearing-cli release-lock-ticket thread-work.42 \
  6409fbc6-48e6-4051-ac86-cc3802272015 \
  --repo teams/platform/website

pearing-cli update-user-activity --clear</code></pre>
    </div>
  </section>

  <section class="mb-4" aria-labelledby="handoff-interface">
    <h2 class="h3" id="handoff-interface">Using another interface</h2>
    <p>Load the thread and repository rules through MCP before changing code:</p>
    <div class="bg-light border rounded p-3 mb-3">
      <pre class="mb-0"><code>Tool: get_thread_context
Arguments:
{
  "repo": "teams/platform/website",
  "thread_number": 42
}

Tool: get_repo_rules
Arguments:
{
  "repo": "teams/platform/website"
}</code></pre>
    </div>
    <div class="d-flex flex-wrap gap-2">
      <a class="btn btn-sm btn-outline-secondary" href="/docs/mcp/get-thread-context">Thread context MCP</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/mcp/locks">Lock tools MCP</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/api/get-thread">Get thread API</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/cli/get-thread">Get thread CLI</a>
    </div>
  </section>

  <section class="mb-4" aria-labelledby="handoff-success">
    <h2 class="h3" id="handoff-success">What success looks like</h2>
    <ul class="mb-0">
      <li>The successor holds a current ticket and has read current policy and state.</li>
      <li>The takeover reply names recovered commits, decisions, and missing work.</li>
      <li>Continuation starts from pushed Git state.</li>
      <li>Stale work closes with a durable explanation and balanced release.</li>
      <li>Activity names the current actor. Threads and Git preserve recovery state.</li>
    </ul>
  </section>

  <div class="alert alert-warning mb-4" role="note">
    <h2 class="h5 alert-heading">Common mistake</h2>
    <p class="mb-0">
      A lease transfers the opportunity to own work, not the work itself. Uncommitted local changes are not recoverable through Pearing,
      and activity is not durable state. Push checkpoints and write progress replies.
    </p>
  </div>

  <section class="mb-4" aria-labelledby="handoff-recovery">
    <h2 class="h3" id="handoff-recovery">Failure and recovery</h2>
    <div class="accordion" id="handoff-recovery-list">
      <div class="accordion-item">
        <h3 class="accordion-header" id="handoff-old-heading"><button class="accordion-button" type="button" data-bs-toggle="collapse" data-bs-target="#handoff-old-body" aria-expanded="true" aria-controls="handoff-old-body">The old actor returns after takeover</button></h3>
        <div id="handoff-old-body" class="accordion-collapse collapse show" aria-labelledby="handoff-old-heading" data-bs-parent="#handoff-recovery-list"><div class="accordion-body">It must read the ticket and thread again. Without current ownership it stops. External writes require atomic fence validation.</div></div>
      </div>
      <div class="accordion-item">
        <h3 class="accordion-header" id="handoff-missing-heading"><button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#handoff-missing-body" aria-expanded="false" aria-controls="handoff-missing-body">The linked branch or commit is missing</button></h3>
        <div id="handoff-missing-body" class="accordion-collapse collapse" aria-labelledby="handoff-missing-heading" data-bs-parent="#handoff-recovery-list"><div class="accordion-body">Do not reconstruct code from activity text. Record the missing checkpoint and use the accepted thread state to decide whether to restart.</div></div>
      </div>
      <div class="accordion-item">
        <h3 class="accordion-header" id="handoff-target-heading"><button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#handoff-target-body" aria-expanded="false" aria-controls="handoff-target-body">The target branch, access, or repository rules changed</button></h3>
        <div id="handoff-target-body" class="accordion-collapse collapse" aria-labelledby="handoff-target-heading" data-bs-parent="#handoff-recovery-list"><div class="accordion-body">Rebase or revise only when current rules permit it. Ownership never bypasses repository policy. Release and report blockers.</div></div>
      </div>
    </div>
  </section>

  <section aria-labelledby="handoff-reference">
    <h2 class="h3" id="handoff-reference">Related reference</h2>
    <div class="d-flex flex-wrap gap-2">
      <a class="btn btn-sm btn-outline-secondary" href="/docs/cli/locks">Locks CLI</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/api/locks">Lease locks API</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/cli/get-thread">Thread CLI</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/api/get-repo">Repository API</a>
    </div>
  </section>
{% endblock %}