@adamchanadam/agent-handoff-kit 0.1.0

package/packs/agent-governance.md

@@ -0,0 +1,30 @@
+# Agent Governance Pack
+
+## Scope
+
+Use for governance rules, prompts, agent instructions, handoff systems, startup/closeout behavior, skills, and rule packs.
+
+## Load When
+
+- User asks to change AI behavior, project governance, prompts, handoff, startup, closeout, or tool-use rules.
+- A change affects `AGENTS.md`, `dev/*`, rule packs, installer templates, or durable workflow docs.
+
+## Rules
+
+1. Locate the existing source of truth before adding a rule.
+2. Prefer merge, replace, or registry rows over append-only rule growth.
+3. Keep public runtime rules generic; project-specific incidents belong in logs, runbooks, or project index.
+4. Do not let development-only workspace rules enter public runtime.
+5. Check complexity budget before adding default-core behavior.
+6. Before creating durable workflow, runbook, or instruction files, first verify whether `dev/SESSION_HANDOFF.md`, `dev/PROJECT_INDEX.md`, `dev/DOC_SYNC_REGISTRY.md`, or existing rule packs can carry the need without a new file.
+
+## Checks
+
+- Verify affected files are indexed or intentionally installed templates.
+- Check `dev/DOC_SYNC_REGISTRY.md` for governance, closeout/startup, and README sync rows.
+- Confirm old overlapping wording was retired or marked legacy.
+- Confirm any new durable file is reachable from `dev/PROJECT_INDEX.md` and does not rely only on a one-session handoff note.
+
+## Closeout
+
+Record the changed rule home, reason, complexity impact, retired wording, and follow-up checks.

package/packs/coding.md

@@ -0,0 +1,28 @@
+# Coding Pack
+
+## Scope
+
+Use for code changes, tests, builds, package managers, SDKs, CLIs, APIs, or developer tooling.
+
+## Load When
+
+- User asks to write, edit, debug, refactor, test, build, package, or integrate code.
+- The task depends on framework, runtime, dependency, or API behavior.
+
+## Rules
+
+1. Read `dev/PROJECT_INDEX.md` for stack, commands, entry points, and directory roles before editing.
+2. Inspect relevant source, tests, configs, and docs before changing code.
+3. Prefer project-local patterns and helpers over new abstractions.
+4. Do not guess current SDK, CLI, package, API, or deployment behavior when docs or project files can verify it.
+5. Preserve unrelated user changes.
+
+## Checks
+
+- Run the narrowest relevant test, build, lint, or typecheck available.
+- If a check cannot run, record why and what remains unverified.
+- Check `dev/DOC_SYNC_REGISTRY.md` if behavior, commands, public docs, or runbooks changed.
+
+## Closeout
+
+Record files changed, commands run, results, remaining risks, and any project index or doc sync updates.

package/packs/communication.md

@@ -0,0 +1,28 @@
+# Communication Pack
+
+## Scope
+
+Use for reply format, language behavior, output schema, user-facing explanation, and cross-agent handoff wording.
+
+## Load When
+
+- User requests a specific response format, language, style, report, review, or schema.
+- The task changes public-facing instructions or AI-facing reply discipline.
+
+## Rules
+
+1. Match the user's language unless a project file requires another language.
+2. Lead with decisions, findings, or results before background.
+3. Mark assumptions and unverified facts.
+4. Keep operational instructions copy-paste-ready when they are meant for future sessions.
+5. Avoid exposing internal process unless it helps the user act.
+
+## Checks
+
+- Verify required headings, schema fields, or language split.
+- Check public README or docs if user-facing behavior changed.
+- Confirm handoff/opening messages are complete and root-specific when needed.
+
+## Closeout
+
+Record any durable response-format decisions and where they were persisted.

package/packs/knowledge.md

@@ -0,0 +1,31 @@
+# Knowledge Pack
+
+## Scope
+
+Use for external notes, knowledge bases, Notion, Obsidian, Drive, docs repositories, and source-of-truth mapping.
+
+## Load When
+
+- User references external knowledge tools or asks to sync project knowledge outside local files.
+- Project truth may be split between local markdown and an external system.
+
+## Rules
+
+1. Determine whether the external surface is source of truth, mirror, index, or attachment store.
+2. Record access mode and sync expectation before relying on external content.
+3. Prefer local durable files for installable runtime text unless the project declares otherwise.
+4. Do not perform destructive external writes without explicit confirmation.
+5. If direct access is unavailable, produce a ready-to-paste sync packet and mark status pending.
+6. When writing to an external mirror or index, read back the written record before claiming sync success.
+7. Preserve local file paths as plain text, code, or structured rich text fields when the external tool parses Markdown links or escape characters.
+
+## Checks
+
+- Verify external source identity, timestamp, and scope.
+- Check `dev/DOC_SYNC_REGISTRY.md` for required sync targets and status vocabulary.
+- Record conflicts between local and external content.
+- Mark unread relevant sources as unread, pending, or blocked. Do not treat unread sources as absent.
+
+## Closeout
+
+Record external sync status, pending paste/manual steps, unresolved conflicts, and next verification point.

package/packs/release.md

@@ -0,0 +1,28 @@
+# Release Pack
+
+## Scope
+
+Use for release, publish, deploy, tag, version bump, hotfix, or GA completion claims.
+
+## Load When
+
+- User asks to publish, deploy, tag, release, upload, announce, or mark work as production-ready.
+- A task changes package metadata, changelog, release notes, or distribution artifacts.
+
+## Rules
+
+1. Treat release claims as evidence-bound.
+2. Verify version, target branch, commit, artifacts, release notes, and public docs before claiming completion.
+3. Do not publish, deploy, tag, or upload without explicit user approval.
+4. Keep rollback or recovery notes when release risk is non-trivial.
+5. Preserve migration and upgrade safety for existing users.
+
+## Checks
+
+- Run build/test/package checks required by `dev/PROJECT_INDEX.md`.
+- Check README, changelog, migration notes, and `dev/DOC_SYNC_REGISTRY.md`.
+- Record exact command results or blockers.
+
+## Closeout
+
+Record release status, version, commit, artifacts, verification evidence, blocked items, and post-release follow-up.

package/packs/research.md

@@ -0,0 +1,28 @@
+# Research Pack
+
+## Scope
+
+Use for source gathering, evidence comparison, fact synthesis, recommendations, and uncertainty handling.
+
+## Load When
+
+- User asks for current facts, comparisons, recommendations, source-backed conclusions, or external evidence.
+- The topic may have changed recently or needs precise attribution.
+
+## Rules
+
+1. Prefer primary sources, official docs, papers, standards, or direct data when available.
+2. Separate verified facts, source summaries, and inference.
+3. Record dates for time-sensitive facts.
+4. Do not overstate confidence when sources conflict or coverage is thin.
+5. Keep source quotes short and cite where evidence came from.
+
+## Checks
+
+- Confirm source relevance, date, and authority.
+- Cross-check important claims with more than one source when practical.
+- Record open questions or unverified claims.
+
+## Closeout
+
+Record sources used, conclusions, uncertainty, and any facts that should be persisted into project files.

package/packs/safety.md

@@ -0,0 +1,29 @@
+# Safety Pack
+
+## Scope
+
+Use for file operations, shell commands, Git changes, package managers, installers, deploy tools, release tools, cloud tools, external APIs, locked files, permission errors, sandbox restrictions, or any task that could affect data loss, credentials, public release state, or external systems.
+
+## Rules
+
+1. Before deleting, overwriting, moving, renaming, cleaning, resetting, publishing, or running destructive tool operations, list the exact target paths, expected scope, impact, and required confirmation.
+2. Preserve user-provided source files by default. Create renamed outputs instead of in-place overwrites unless overwrite is explicitly requested.
+3. Never operate on a filesystem root, drive root, home directory root, repository parent root, system directory, or ambiguous path.
+4. Do not bypass permissions, file locks, sandbox limits, failed safety checks, or denied operations. Report the blocker and manual action needed.
+5. Do not run recursive or bulk destructive commands such as `rm -rf`, `Remove-Item -Recurse -Force`, `git clean -fdx`, or equivalent cleanup operations unless the user explicitly requested the operation and resolved absolute targets are verified.
+6. On Windows, do not use `cmd /c rmdir`, `cmd /c rd`, or any `cmd.exe /c` variant combined with `rmdir` or `rd`. Prefer native PowerShell cmdlets when PowerShell is active, and do not compose filesystem modification commands across shells.
+7. On macOS / Linux, do not run `rm -rf`, `sudo rm`, recursive `chmod`, recursive `chown`, or destructive wildcard operations unless the user explicitly requested the operation and target paths are listed and verified.
+8. Do not run `git reset --hard`, branch deletion, tag deletion, force push, or history rewrite unless the user explicitly requested it and affected refs/files are listed.
+9. Before staging or committing, inspect current status and avoid staging unrelated parent-repo, sibling-directory, generated, credential, or user-owned changes.
+10. Before using external APIs, SDKs, CLIs, package managers, deploy tools, cloud tools, or release tools, verify current official documentation or project-local runbooks. If verification is blocked, mark the result unverified instead of guessing.
+11. Do not print, copy, log, commit, upload, or generate files containing secret values. Use redacted placeholders or line references.
+
+## Checks
+
+- Report which safety-relevant command, path, API, install, deploy, release, or Git check was performed and the result.
+- If checks cannot run, state the reason and mark the result unverified.
+- For durable governance changes, update the project index, sync registry, and any human review map if they exist.
+
+## Closeout
+
+Record unresolved safety risks, blocked verification, pending manual actions, dirty worktrees, or external sync gaps in `dev/SESSION_HANDOFF.md`.

package/packs/writing.md

@@ -0,0 +1,28 @@
+# Writing Pack
+
+## Scope
+
+Use for drafting, editing, style, structure, publication copy, documentation prose, and tone control.
+
+## Load When
+
+- User asks to write, rewrite, summarize, translate, or edit text.
+- The task has a target audience, voice, format, or publication surface.
+
+## Rules
+
+1. Identify audience, purpose, and target surface before rewriting.
+2. Preserve factual meaning unless the user asks for content changes.
+3. Keep terminology consistent with project docs.
+4. Mark uncertain claims instead of inventing support.
+5. Do not bury durable requirements only in prose; use project index, spec, runbook, or handoff when needed.
+
+## Checks
+
+- Verify requested format, language, and tone.
+- Check links, commands, names, and version-sensitive claims when relevant.
+- Check `dev/DOC_SYNC_REGISTRY.md` if public docs or user-facing instructions changed.
+
+## Closeout
+
+Record changed documents, unresolved content questions, and any sync or follow-up needed.

package/runtime-core/AGENTS.core.md

@@ -0,0 +1,110 @@
+# Agent Handoff Kit Core Runtime
+
+This is the lightweight core. It is the always-read contract for AI sessions.
+
+## 1. Startup Reads
+
+After this core is loaded, read in order:
+
+1. `dev/SESSION_HANDOFF.md`
+2. the latest entry in `dev/SESSION_LOG.md`
+3. `dev/PROJECT_INDEX.md`
+4. `dev/RULE_PACKS.md`
+
+Then classify the user's task and read only the required rule pack(s). State which pack(s) you loaded and why, using plain language so the user understands the working mode without needing to know pack names.
+
+If the user did not paste the previous opening message but the current project root is clear, read `AGENTS.md` first as fallback entry, then use this read order. If the root is unclear or mismatched, stop and ask for the intended project root before reading or editing project state.
+
+If a required file is missing, create the smallest useful version only after confirming the target project root.
+
+Before acting on a non-trivial task, identify required local source-of-truth files and external sources from the handoff, project index, user request, and sync registry. Read them or mark them blocked. Reachable is not the same as ingested. Do not treat unread sources as absent.
+
+After startup reads are complete, show a short startup card:
+
+```text
+   /\_/\   Agent Handoff Kit v<version>
+  ( o.o )  continuity ready
+   > ^ <
+
+🔎 Handoff: loaded
+📌 Objective: <current objective>
+⚠️ Boundary: <important boundary or none>
+🚀 Next: <next action>
+```
+
+Keep the card short. Use the full product name, not an abbreviation. If the installed template or CLI version is unknown, write `version unverified` instead of guessing.
+
+## 2. Work Loop
+
+Use this loop for every task:
+
+1. PLAN: restate the user's intent, scope, risk, and acceptance criteria.
+2. READ: inspect relevant files from `PROJECT_INDEX.md` and search for related definitions before editing.
+3. CHANGE: make focused changes only.
+4. QC: run available checks or state why they cannot run.
+5. PERSIST: update handoff/log and any affected project index or sync registry.
+
+For high-risk work, pause after PLAN. High-risk means destructive operations, ambiguous target, external systems, release/publish, or broad multi-file change.
+
+## 3. Safety Boundaries
+
+Do not delete, reset, overwrite, bulk-move, or publish without explicit user approval.
+
+Do not guess commands, APIs, SDK behavior, deployment steps, or file ownership when project docs or official docs are needed. Mark unverified facts as unverified.
+
+Do not modify unrelated files. If unexpected user changes appear, work with them or ask before touching them.
+
+Do not claim completion without evidence from checks, inspection, or a clear explanation of what could not be verified.
+
+## 4. Closeout And Handoff
+
+Detect end-of-session or handoff intent in natural language, such as "收工", "wrap up", or "handoff". If intent is ambiguous, ask one concise confirmation question.
+
+At full closeout:
+
+1. Reconcile `dev/SESSION_HANDOFF.md`. Do not append a new state snapshot under old state. Verify `Durable Anchors`, then rewrite or explicitly confirm every section under `Closeout-Reconciled State`.
+2. Add a concise entry to `dev/SESSION_LOG.md` with work actually completed this session and the exact next-session opening message.
+3. Update `dev/PROJECT_INDEX.md` if files, stack, commands, entry points, workspace identity, or durable document map changed.
+4. Check `dev/DOC_SYNC_REGISTRY.md` and record required sync status.
+5. Record unresolved drift risk, active worktree, parallel workspace, uncommitted changes, or blocked verification.
+6. Complete the `State Reconciliation Check`: it must state when reconciliation happened, which state sections were rewritten or confirmed current, whether stale snapshots remain, and whether the opening message matches current state.
+7. Run the handoff sufficiency check: the next AI should be able to continue from `AGENTS.md`, `dev/SESSION_HANDOFF.md`, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history.
+8. If either check fails, fix `dev/SESSION_HANDOFF.md` first; do not push current-state responsibility into `dev/SESSION_LOG.md`.
+9. Show a short closeout card, then provide a copy-paste-ready next-session opening message inside a fenced `text` code block, so the user can clearly copy and paste it into the next session.
+
+Installed handoff templates use English headings by default for cross-tool stability, but project teams may translate `dev/SESSION_HANDOFF.md` section headings and visible field labels into the project's working language. Keep the `ack:section:*` and `ack:field:*` semantic markers intact; `doctor` validates those markers so localized handoff notes remain supported.
+
+Use this closeout card:
+
+```text
+   /\_/\   Agent Handoff Kit v<version>
+  ( -.- )  handoff saved
+   > ^ <
+
+✅ Done: <completed summary>
+🔎 QC: <validation summary>
+📌 Handoff: opening message ready
+⚠️ Boundary: <important boundary or none>
+```
+
+Immediately before the fenced opening message, write:
+
+```text
+📋 Next session: copy and paste the whole block below
+```
+
+Record only work actually performed in the current session. Do not copy old completed work forward as new work.
+`dev/SESSION_HANDOFF.md` carries continuity. `dev/SESSION_LOG.md` carries recent evidence. Archive old detail only when needed; do not create an archive directory by default.
+Do not declare handoff ready if `dev/SESSION_HANDOFF.md` still contains stale state, unreconciled placeholders in current-state sections, or an opening message that no longer matches the reconciled state.
+
+## 5. Pack Loading
+
+Use `dev/RULE_PACKS.md` to decide which pack to read.
+
+A pack may add task-specific requirements. A pack cannot weaken core safety. If two packs conflict, choose the safer and more verifiable path, then record the conflict in closeout.
+
+After the task, persist durable facts into handoff/log/index/registry. Do not assume the next session remembers pack context unless it is recorded.
+
+## Core Complexity Rule
+
+New default-core rules are allowed only when they apply to most sessions, protect safety or continuity, cannot live in a pack or registry, and keep the core within budget.

package/runtime-core/CLAUDE.md

@@ -0,0 +1,13 @@
+# Claude Entry Bridge
+
+This file exists so Claude Code can find the Agent Handoff Kit startup path.
+
+Authoritative operating rules remain in `AGENTS.md`. Do not duplicate or fork the rules here.
+
+At session startup:
+
+1. Confirm the current root is the intended project root.
+2. Read `AGENTS.md`.
+3. Follow the startup read order in `AGENTS.md`.
+
+If the current root does not match the intended project root, stop and ask the user to confirm the workspace before reading or editing project state.

package/runtime-core/DOC_SYNC_REGISTRY.md

@@ -0,0 +1,23 @@
+# Doc Sync Registry
+
+Purpose: map change types to documents and checks. Keep this as rows, not long prose.
+
+## Status Vocabulary
+
+Use: `confirmed`, `unverified`, `pending`, `blocked`, `not_applicable`.
+
+| Change type | Also check/update | Verification |
+|---|---|---|
+| New file or directory | `dev/PROJECT_INDEX.md` Directory Map | path listed |
+| Stack or command change | `dev/PROJECT_INDEX.md` Stack / Entry Points | command verified or marked unverified |
+| Public behavior change | README, public docs, changelog | docs mention current behavior |
+| API or SDK behavior change | API docs, examples, tests | tests or documented reason |
+| Runbook change | runbook path in `PROJECT_INDEX.md` | procedure still executable |
+| Governance rule change | relevant pack/core, registry, README if public-facing | complexity budget checked |
+| Closeout/startup contract change | `AGENTS.md`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, README quick usage | opening message schema + workspace identity present |
+| Workspace identity change | `dev/SESSION_HANDOFF.md`, `dev/PROJECT_INDEX.md` | root/branch/commit/status recorded or marked unverified |
+| Release | release notes, README version, changelog | release pack checklist |
+
+## Registry Rule
+
+If a change has no matching row, add a row before closeout or record why no durable sync rule is needed. At closeout, record sync status for every row touched by the session.

package/runtime-core/GEMINI.md

@@ -0,0 +1,13 @@
+# Gemini Entry Bridge
+
+This file exists so Gemini CLI can find the Agent Handoff Kit startup path.
+
+Authoritative operating rules remain in `AGENTS.md`. Do not duplicate or fork the rules here.
+
+At session startup:
+
+1. Confirm the current root is the intended project root.
+2. Read `AGENTS.md`.
+3. Follow the startup read order in `AGENTS.md`.
+
+If the current root does not match the intended project root, stop and ask the user to confirm the workspace before reading or editing project state.

package/runtime-core/PROJECT_INDEX.md

@@ -0,0 +1,92 @@
+# Project Index
+
+Purpose: give a stateless AI a compact map of the project before it reads or edits files.
+
+## Stack
+
+| Field | Value | Last verified |
+|---|---|---|
+| Agent Handoff Kit template version | 0.1.0 | package prototype |
+| Runtime | TBD | TBD |
+| Framework | TBD | TBD |
+| Package manager | TBD | TBD |
+| Test command | TBD | TBD |
+| Build command | TBD | TBD |
+| Deploy command | TBD | TBD |
+
+## Directory Map
+
+| Path | Role | Read when |
+|---|---|---|
+| `AGENTS.md` | primary Agent Handoff Kit entry and startup contract | session startup |
+| `CLAUDE.md` | Claude Code bridge to the same startup path | Claude Code startup |
+| `GEMINI.md` | Gemini CLI bridge to the same startup path | Gemini CLI startup |
+| `src/` | application source | coding task |
+| `tests/` | tests | coding/QC |
+| `docs/` | user or product docs | doc/public behavior change |
+| `dev/` | governance state | startup/closeout |
+| `TBD` | local source-of-truth files | before tasks that depend on project facts |
+| `TBD` | external-source indexes or mirrors | before research, writing, or knowledge-sync tasks |
+
+## Entry Points
+
+| Entry | Path | Notes |
+|---|---|---|
+| App entry | TBD | TBD |
+| Main config | TBD | TBD |
+| Test suite | TBD | TBD |
+| Runbook | TBD | TBD |
+| Public docs | TBD | TBD |
+
+## Fact Base
+
+Reachable means the source can be found. It does not mean the source has been read in this session.
+
+| Source | Role | Required before | Access method | Last verified |
+|---|---|---|---|---|
+| TBD | local source of truth / reference / draft / archive | TBD | path or instruction | TBD |
+
+## External Sources
+
+| Source | Role | Required before | Access method | Write-back rule | Last verified |
+|---|---|---|---|---|---|
+| TBD | source of truth / mirror / index / attachment store | TBD | URL, connector, or manual packet | read-back required / manual only / no write | TBD |
+
+## Local QC Commands
+
+| Check | Command | Run before | Last verified |
+|---|---|---|---|
+| Agent Handoff Kit doctor | TBD | closeout / governance changes | TBD |
+| Project governance check | TBD | closeout / durable file changes | TBD |
+
+## Workspace Identity
+
+Record this at closeout so the next AI can detect wrong-root or workspace drift.
+
+| Field | Value | Last verified |
+|---|---|---|
+| Expected project root | TBD | TBD |
+| Git root | TBD | TBD |
+| Branch / commit | TBD | TBD |
+| Worktree or parallel workspace | TBD | TBD |
+| Uncommitted change summary | TBD | TBD |
+
+## Change Hotspots
+
+| Change type | Likely files | Required checks |
+|---|---|---|
+| API behavior | TBD | tests + docs sync |
+| UI behavior | TBD | build + visual/manual check |
+| Data model | TBD | migration/checks |
+| Governance behavior | `AGENTS.md`, `dev/*` | doc sync registry |
+| Closeout/startup contract | `AGENTS.md`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md` | opening message present + workspace identity current |
+
+## External Services
+
+| Service | Scope | Verification source | Last verified |
+|---|---|---|---|
+| TBD | TBD | TBD | TBD |
+
+## Maintenance Rule
+
+Update this file when stack, commands, directory roles, entry points, external services, workspace identity, durable runbooks, or governance file map changes.

package/runtime-core/RULE_PACKS.md

@@ -0,0 +1,18 @@
+# Rule Packs Router
+
+Read only the packs needed for the current task.
+
+| Task signal | Pack | Purpose |
+|---|---|---|
+| Destructive file operations, shell writes, Git state changes, package managers, installers, deploy, release, cloud tools, external APIs, credentials, locked files, permission errors | `dev/rules/safety.md` | safety checks for data loss, external systems, secrets, and high-risk operations |
+| Code, tests, build, package manager, SDK, CLI, API | `dev/rules/coding.md` | development workflow and verification |
+| Draft, edit, style, publication content | `dev/rules/writing.md` | writing workflow and tone control |
+| Sources, evidence, comparison, fact finding | `dev/rules/research.md` | source handling and uncertainty |
+| Governance, prompts, agents, handoff, startup/closeout, skills | `dev/rules/agent-governance.md` | governance changes and boundary control |
+| Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |
+| External notes, knowledge base, Notion, Obsidian, Drive | `dev/rules/knowledge.md` | external knowledge source integration |
+| Reply format, language, output schema | `dev/rules/communication.md` | user-facing response rules |
+
+## Routing Rule
+
+Load the minimum set. If uncertain, load the narrower pack first. If a task clearly involves safety risk plus another domain, load `dev/rules/safety.md` with the relevant domain pack and state why. Packs can add stricter rules, but cannot weaken core safety or closeout requirements.

package/runtime-core/SESSION_HANDOFF.md

@@ -0,0 +1,148 @@
+# Session Handoff
+
+Last Updated: TBD
+
+<!-- ack:section:durable-anchors -->
+## Durable Anchors
+
+Stable facts that should survive across sessions. Update only when they change, but verify they still match reality at closeout.
+
+1. Project root and boundary: TBD
+2. Product/system identity: TBD
+3. Governance model: TBD
+4. Source-of-truth ownership: TBD
+5. Release / publish boundary: TBD
+
+<!-- ack:section:closeout-reconciled-state -->
+## Closeout-Reconciled State
+
+This is the current-state area. At every full closeout, rewrite or explicitly confirm every section below. Do not append a new state snapshot under an old one.
+
+<!-- ack:section:current-baseline -->
+## Current Baseline
+
+1. Project root: TBD
+2. Product/system state: TBD
+3. Governance state: TBD
+4. Source-of-truth notes: TBD
+
+<!-- ack:section:task-understanding-summary -->
+## Task Understanding Summary
+
+<!-- ack:field:user-intent -->
+- User intent: TBD
+<!-- ack:field:task-essence -->
+- Task essence: TBD
+- User value: TBD
+<!-- ack:field:success-criteria -->
+- Success criteria: TBD
+- Key background already read: TBD
+- Background still unread or blocked: TBD
+- Non-goals / boundaries: TBD
+
+<!-- ack:section:active-objective -->
+## Active Objective
+
+TBD
+
+<!-- ack:section:completed-this-session -->
+## Completed This Session
+
+Record only work actually completed in the current session.
+
+1. TBD
+
+<!-- ack:section:next-priorities -->
+## Next Priorities
+
+1. TBD
+
+<!-- ack:section:next-task-required-reading -->
+## Next Task Required Reading
+
+Before acting on the next task, read or mark blocked:
+
+| Source | Why required | Status |
+|---|---|---|
+| TBD | TBD | pending |
+
+<!-- ack:section:risks-blockers -->
+## Risks / Blockers
+
+1. TBD
+
+<!-- ack:section:validation-qc -->
+## Validation / QC
+
+- Checks run this session: TBD
+- Checks not run and why: TBD
+- Handoff evidence location: TBD
+
+<!-- ack:section:workspace-identity -->
+## Workspace Identity
+
+Expected project root: TBD
+Git root: TBD
+Branch: TBD
+Commit: TBD
+Worktree / parallel workspace status: TBD
+Uncommitted changes summary: TBD
+
+<!-- ack:section:sync-status -->
+## Sync Status
+
+Use statuses from `dev/DOC_SYNC_REGISTRY.md`: `confirmed`, `unverified`, `pending`, `blocked`, `not_applicable`.
+
+- Project index: TBD
+- Doc sync registry: TBD
+- Public docs / README: TBD
+- External knowledge tools: TBD
+
+<!-- ack:section:state-reconciliation-check -->
+## State Reconciliation Check
+
+At full closeout, complete this check after updating the state sections above.
+
+- Reconciled at: TBD
+<!-- ack:field:state-sections-rewritten-or-confirmed -->
+- State sections rewritten or confirmed current: TBD
+<!-- ack:field:stale-snapshots-left -->
+- Stale snapshots left in this handoff: TBD
+<!-- ack:field:opening-message-matches-current-state -->
+- Opening message matches current state: TBD
+<!-- ack:field:next-ai-can-continue -->
+- Next AI can continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history: TBD
+
+If any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready.
+
+<!-- ack:section:handoff-sufficiency-check -->
+## Handoff Sufficiency Check
+
+Can the next AI continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history?
+
+Answer: TBD
+If no, update this handoff before closeout.
+
+Continuity rule: this file carries current state and next action. `dev/SESSION_LOG.md` carries recent evidence only. Archive old detail only when needed; do not create an archive directory by default.
+
+<!-- ack:section:next-session-opening-message -->
+## Next Session Opening Message
+
+📋 Next session: copy and paste the whole block below
+
+```text
+Work in <absolute project root>.
+
+Read in order:
+1. AGENTS.md
+2. dev/SESSION_HANDOFF.md
+3. dev/SESSION_LOG.md
+4. dev/PROJECT_INDEX.md
+5. dev/RULE_PACKS.md
+
+Read dev/DOC_SYNC_REGISTRY.md before file changes or closeout.
+
+If this root does not match the expected project root, stop and ask for confirmation.
+
+After reading, summarize current objective, task understanding, confirmed decisions, pending work, risks, and the next recommended action.
+```