Picking up work across sessions

How paqad carries work from one session to the next

An AI coding session forgets everything when it ends. In 1.91.1, paqad does not rely on a written summary to bridge that gap. It relies on records it already keeps on disk for each change:

• the change's evidence bundle, with its plan.json, frozen specification.json, rules-loaded.json and a log of which stages have started and ended;
• a per-session routing state that lists the active workflow and any paused ones, with the lane and spec each paused change was using;
• the context package paqad prepares for each message, including the rules that apply to the files in play.

Because the plan, spec and stage progress are on disk, a new session can pick up a change at the stage where it stopped instead of starting again.

Pausing and resuming within one session

If you break off from a feature to ask a question, the feature is paused, not dropped. When you say "continue", the AI re-reads the saved plan, spec and stage progress, reloads the project rules and carries on from the same stage. Recognising that "continue" means that change is the AI's judgement; if it could mean more than one change, the AI asks you. Details are in Routing and lanes.

Starting a new session

On Claude Code and Codex CLI, a hook runs when a session starts. It does two things that matter here, both as machine checks:

1. It removes this session's "framework loaded" marker, so the AI must load paqad's instructions again before it can edit anything. Other sessions in the same checkout are not affected.
2. If the new session has no active change and exactly one unfinished change exists on the current git branch, it links the new session to that change. Later stage records then land on the same change instead of opening a duplicate. If there is no unfinished change, or more than one, it links nothing.

A change counts as unfinished when it has recorded stage activity but has not yet passed its end-of-change verification.

Resuming a specific change by name

When the automatic link does not apply (for example, two unfinished changes on one branch, or a tool without hooks), reactivate the change yourself:

npx paqad-ai resume --feature <ref>

<ref> can be the change's ID (the ULID at the end of its bundle folder name), its issue number, its slug or the full folder name under .paqad/ledger/feature-evidence/. The command also finds changes that were finished or displaced earlier, so you never need to edit the ledger by hand. It exits with an error if nothing matches. After resuming, tell the AI to continue that change.

On IDE tools without hooks (Cursor, Windsurf, Copilot and others), nothing runs at session start, so use this command whenever you return to an unfinished change.

Two sessions in the same project

Since 1.91.1, each session keeps its own "framework loaded" marker and its own route. The end-of-turn check only examines the change owned by the session that made it, so a question asked in a second window is not blocked by work happening in the first.

The structured handoff files

paqad also defines a structured handoff document for rebuilding context after a long session is compacted. It uses three files under .paqad/session/:

• handoff.md: a readable summary with the active task, recent decisions, files modified, blockers, next steps and pointers to the spec and relevant files;
• handoff.json: the same content in a structured form (version 2);
• handoff-stats.json: how much smaller the handoff is than the context it replaced.

The session-resume skill reads handoff.md together with the project profile and onboarding manifest to rebuild the working context, and paqad-ai status shows whether a handoff file exists.