Session Update

Session Update

Synchronize the living Board queue in the shared handoff file. This skill writes files.

Artifact Boundary

• Write generated handoff data only under shared project paths, preferably .session/handoff/ at the main repo/worktree root.
• Never write runtime handoff data inside .agents/skills/, .claude/skills/, .codex/skills/, or another skill installation path.
• If no shared handoff directory exists, create .session/handoff/.
• Historical handoffs are read-only. Record corrections in today's handoff rather than editing older daily files.

Handoff Root Resolution

Follow ## Handoff Root Resolution in session-handoff/schema/handoff.md. As a writer skill: refuse to write a divergent worktree-local handoff directory and report it as a migration/mismatch warning.

Core Rules

• Read project instructions when present: AGENTS.md, CLAUDE.md. Do not read .claude/settings.json by default; inspect it only under the Project Instruction Reading Boundary in session-handoff/schema/handoff.md.
• Use .session/handoff/YYYY-MM-DD.md for today's Board. If today's file does not exist, create it from the most recent handoff following the inheritance rules in ## Artifact Boundary of session-handoff/schema/handoff.md.
• Do not update ## Active Work; claiming belongs to session-claim, completion belongs to session-handoff.
• session-update is not a required pre-step for session-handoff. Use session-handoff to close/pause a task and perform Handoff Board Sync for that task; use session-update for broader queue grooming and stale Board cleanup.
• Do not use this skill for handoff completion records; use session-handoff when a session entry is needed.
• Keep ## Remaining for claimable unfinished work only.
• Treat ## Remaining as the claimable queue. In Spectra projects, put parked or active Spectra changes that can be claimed as future work in Remaining; the next session still follows the Spectra workflow appropriate to that change's state.
• Treat ## Phase Plan as ordering/dependency/phase context. Do not use it as a historical checklist, and do not duplicate the complete Remaining queue in Phase Plan.
• Remove completed/archived items from Phase Plan unless they are mentioned only as brief dependency context for current work. Historical completion belongs in Session Log, Spectra archive, and ## Spectra recent archive.
• Do not duplicate claimed work across Active Work and Remaining.
• Active Work checks here are read-only. If same workspace/branch has multiple different in-progress work items, a row has missing workspace/branch, or a claimable Remaining item is already active/paused, report a Board mismatch and direct the user to session-claim or session-handoff; do not rewrite Active Work.
• Do not invent progress-source paths. Mark source-less items as Progress Source: Handoff only.
• Before writing, verify actionable Board entries against current sources when available.

Concurrent Write Guard

Follow ## Concurrent Write Guard in session-handoff/schema/handoff.md — prefer the session-handoff/scripts/locked_write.py helper over manual lock steps. Apply the guard to Phase Plan, Remaining, Related Docs, Open Questions, Blockers, and Spectra (session-update does not write Active Work).

Quote-Trace Discipline

Follow ## Quote-Trace Discipline in session-handoff/schema/handoff.md.

Claim Board Scope

• If Spectra is detected by CLI or openspec/, Active Work, Remaining, and Phase Plan should track Spectra change names only.
• In Spectra projects, do not register ad-hoc/non-Spectra work as claimable Board work. Preserve displaced context only in Open Questions, Blockers, Related Docs, or Board notes with source labels; tell the user to run session-handoff if a retrospective log entry is needed.
• In Spectra projects, move existing non-Spectra Remaining entries out of the claimable queue during update: preserve them as Open Questions, Blockers, Related Docs context, or Board notes with source labels.
• If Spectra is absent, non-Spectra work may be registered as claimable work when it has a stable slug/name and either a progress source or explicit handoff-only completion criteria.

Spectra Discovery

Spectra is optional, but detection is required. Follow ## Spectra Discovery in session-handoff/schema/handoff.md (including the session-update delta there).

Workflow

1. Read today's shared handoff file, or create it from the most recent unfinished Board per the schema's inheritance rules (## Artifact Boundary).
2. Discover work items from:
   • existing Board
   • progress-source docs referenced by Board
   • user-provided work item names
   • Spectra active/parked changes
3. Re-read current sources that determine completion, blockers, dependencies, or durable documentation sync checks that belong in Related Docs.
4. Inspect ## Active Work read-only for occupancy/stale/duplicate-Remaining mismatches using the Workspace/Branch schema. Report mismatches; do not edit Active Work.
5. Update:
   • ## Phase Plan: phase/dependency/order notes only; not a changelog and not a duplicate claim queue
   • ## Remaining: claimable unfinished work only
   • ## Related Docs: durable documentation sync checks for claimed work, preserving triggers: notes when present and enforcing Related Docs Scope from the shared schema
   • ## Open Questions: unresolved questions only
   • ## Blockers: active blockers only
   • ## Spectra: only when Spectra is detected
6. Preserve explicit paths and user notes unless current sources clearly supersede them.
7. Audit Related Docs trigger notes against git status/diff and current Board items. Surface missing or stale triggers, and groom out source/test/generated paths that violate the shared schema.
8. Report what changed and which sources were checked.

Board vs Log Boundary

Follow ## Board Semantics in session-handoff/schema/handoff.md for the Board-vs-Session-Log layering and the rule that resolved/stale notes are removed from the Board. session-update grooming-specific actions:

• Baseline dirty file blocks at the Board top: collapse to one-line summary (Session N baseline: X modified + Y untracked; see Session N Notes). Move displaced detail into a note inside the relevant Session Log entry; do not silently drop it.
• When removing stale Board notes (resolved conflict warnings, (inherited from...) labels on sections already touched today, occupancy notes that no longer apply), capture historically useful context as a date-labelled Board note or fold it into a Session Log entry if it explains a past decision.

Open Questions Prune

session-update owns the interactive Open Questions prune. Staleness and the exemption rule are defined in ## Open Questions and Ideas Backlog in session-handoff/schema/handoff.md; session-handoff only surfaces stale questions as prune candidate and defers the prune to here.

For each detected stale, non-exempt question, prompt the user with three options:

• Move to ideas backlog — invoke the project-logbook skill (via the Skill tool) with --backlog add to record it in .knowledge/ideas-backlog.md. Never edit that file directly from this skill — writes must go through project-logbook's insert script, which validates the schema and rebuilds _backlog_index.json. Preserve flagged: YYYY-MM-DD and last-seen: YYYY-MM-DD metadata.
• Delete — remove from Open Questions.
• Keep — leave in Open Questions (resets the 14-day clock via last-seen update).

Related Docs Freshness

Follow ## Related Docs Freshness and ## Related Docs Scope in session-handoff/schema/handoff.md for last reviewed stamping, the 30-day stale flag, and what may appear in ## Related Docs. session-update specifics:

• Do not list parked Spectra change directories in Related Docs merely because those changes are queued in Remaining; the queued change name is the Board pointer. Add a parked proposal/design/spec artifact only when this update actually changed or must synchronize that artifact's content.
• Do not list archived Spectra directories in Related Docs as history; keep only the latest one or two relevant archives in ## Spectra Recent archive.

Spectra Section Scope

Follow ## Spectra Board Scope in session-handoff/schema/handoff.md for what ## Spectra, ## Remaining, and ## Phase Plan should contain: active changes listed in full, only relevant parked changes plus parked total: N (see spectra list --parked), and recent archives limited to the latest one or two relevant to current work. No session-update-specific additions.

Non-Spectra Registration

Only when Spectra is absent:

• If the user provides a work item name, add it to Remaining.
• If a progress source is provided or obvious, link it.
• If no progress source is available, require a stable slug/name and explicit handoff-only completion criteria; mark Progress Source: Handoff only.
• Use generic groupings such as Unphased or the user's supplied grouping when no phase plan exists.

Output

Summarize:

• Board file written
• Remaining/Phase Plan/Related Docs changes
• Open Questions/Blockers changes
• Spectra result, if relevant
• Sources checked
• Items still handoff-only
• Active Work mismatches found read-only, if any