agentflight 0.6.0 → 0.7.1

package/CHANGELOG.md

@@ -2,6 +2,275 @@
 
 All notable AgentFlight changes are documented here.
 
+## [0.7.1] - 2026-06-21
+
+### Fixed
+
+- Refreshed the README terminal hero GIF so it shows the current
+  handoff-first review flow instead of the older replay-first flow.
+- Updated the README hero caption and sample output to include `handoff` and
+  `history` accurately.
+
+### Changed
+
+- Tightened README workflow copy around the local handoff packet, recent local
+  session history, and current failure-excerpt surfaces.
+
+## [0.7.0] - 2026-06-21
+
+### Added
+
+- Added `agentflight handoff`, a local-only review handoff command that generates the report, replay, and resume artifacts and summarizes readiness, proof gaps, review focus, and failed verification excerpts.
+- Added `agentflight history`, a read-only local command for listing recent
+  sessions, proof counts, the current-session marker, and existing report/replay
+  artifact paths without search indexing, export, sync, or session switching.
+- Added local `agentflight history --task <text>` and
+  `agentflight history --state ready|blocked|needs_verification|unknown|current`
+  filters so engineers can find relevant local sessions without scanning long
+  histories or adding any index, sync, export, or session switching behavior.
+- Added a compact Review Path section to local HTML replay artifacts so long
+  sessions lead reviewers through proof gaps, unresolved failed runs, review
+  focus, and verification evidence without adding scripts, exports, or hosted
+  behavior.
+- Documented the `agentflight history --limit 1` latest-action workflow for
+  reopening local handoff/report/replay/resume artifacts.
+- Added session-specific handoff artifacts under `.agentflight/reports/` so
+  `agentflight history` can point to stable handoff packets from prior sessions.
+- Added session-specific resume artifacts under `.agentflight/reports/` so
+  `agentflight history` can point to stable continuation prompts from prior
+  sessions.
+- Added post-v0.6.0 user-research findings and a v0.6.0 website update prompt focused on the local handoff workflow.
+- Added a post-v0.6.0 product direction note that keeps local handoff, first-run
+  workspace hygiene, replay ergonomics, proof guidance, and explainable ranking
+  as the priority order.
+
+### Fixed
+
+- Ready `agentflight status` output now points at an existing local handoff,
+  replay, or report artifact when one already exists, instead of repeating
+  handoff-generation guidance.
+- Ready `agentflight resume` prompts now point at an existing local handoff,
+  replay, or report artifact when one already exists, instead of repeating
+  handoff-generation guidance.
+- Review Intelligence now ignores unfinished AgentFlight readout/artifact
+  commands such as `agentflight replay` and `node dist/cli.js replay` when
+  computing incomplete proof gaps, so readiness guidance keeps pointing at
+  meaningful verification commands.
+- Incomplete verification guidance now says a command may still be running and
+  suggests waiting before rerunning, avoiding false lost-evidence alarms when
+  status is checked during parallel verification.
+- Ready `agentflight handoff` terminal guidance now tells reviewers to share
+  the local handoff packet first, with report/replay as supporting detail
+  artifacts.
+- Current start-only `agentflight history` sessions now guide users to run
+  verification before handoff when no proof exists yet, while keeping
+  handoff-only guidance once verification has been recorded.
+- Public positioning regression coverage now guards current public/runtime
+  surfaces against stale assistant-style positioning.
+- Clean-worktree status now tells users to open handoff/report/replay or JSON
+  output for tucked verification details, matching the handoff-first ready
+  review path.
+- Ready-session `Open first` guidance now prefers the generated handoff packet
+  in handoff, clean status/resume, and history surfaces, while blocked sessions
+  still point to the report/fix path.
+- Full Markdown proof reports now show changed files, risk, verification,
+  review focus, proof gaps, readiness, recommendation, and next action before
+  the timeline, keeping long sessions faster to review.
+- `agentflight history` now compacts non-current start-only sessions that have
+  no proof or review artifacts, keeping recent local artifacts easier to scan.
+- Review Intelligence now keeps generated `.agentflight/.gitignore` helper files
+  below real first-run review targets while leaving them visible.
+- `agentflight resume` now includes unresolved and historical failed-run context
+  below the verification count, matching status/report trust cues.
+- Clean-worktree `agentflight resume` prompts now include the latest local
+  `Open first:` artifact path when current report/replay/handoff evidence
+  exists.
+- Clean-worktree `agentflight status` now shows the latest local `Open first:`
+  artifact path when current report/replay/handoff evidence exists.
+- `agentflight history` now shows the nearest previous local artifact when the
+  current latest session has none yet, while keeping the current-session
+  handoff next action.
+- First-run AgentFlight generated-file lists and local-file guidance now use
+  shared output helpers, keeping `init` and `start --yes` copy consistent.
+- `agentflight start --yes` now explains the AgentFlight files it generated
+  during safe auto-init, including project config and local runtime evidence.
+- `agentflight init` and `agentflight start` now use concise ProjScan version
+  checks instead of extra help probing, while `agentflight doctor` keeps deeper
+  diagnostics.
+- `agentflight doctor` now renders multiple detected proof-command suggestions
+  as an indented list instead of one long semicolon-separated line.
+- `agentflight history` now prefers useful review-ready or blocked artifact
+  metadata over later clean-worktree artifact metadata, while preserving
+  clean-only session history.
+- Clean-worktree `agentflight handoff` now preserves existing session review
+  artifacts instead of overwriting report/replay/resume evidence with an empty
+  post-commit clean-state artifact.
+- Clean-worktree `agentflight handoff` now exits successfully instead of
+  treating an informational post-commit handoff as a command failure.
+- `agentflight doctor` now suggests concrete detected `agentflight verify -- ...`
+  commands when config verification commands are empty.
+- `agentflight verify` now suggests detected package proof commands when no
+  explicit command is provided and config commands are empty.
+- `agentflight doctor` now warns when package proof scripts exist but
+  `.agentflight/config.json` has no configured verification commands.
+- `agentflight history` now lists capped repo-relative malformed session paths
+  instead of only reporting a skipped-file count.
+- Concurrent `agentflight verify` runs now reserve distinct stdout/stderr
+  evidence paths and merge verification updates without dropping either run.
+- `agentflight history --limit` now rejects non-integer, zero, and negative
+  values with a clear local error instead of silently falling back or returning
+  an empty history.
+- Review Intelligence now treats an earlier failed verification as resolved when
+  the same stored command later passes, so TDD red/green and format-fix loops do
+  not leave handoffs permanently blocked.
+- Status, report, replay, and handoff now distinguish unresolved failed
+  verification from historical failed runs that later passed.
+- Resume prompts now use the same unresolved-versus-resolved verification count
+  wording as the other review surfaces.
+- Clean-worktree status now points users to `agentflight history --limit 1` to
+  reopen the latest local artifacts before starting the next session.
+- History now shows unresolved-versus-resolved failed verification counts for
+  prior sessions.
+- History now includes stable handoff artifact paths alongside report and
+  replay paths when those artifacts exist.
+- History now includes stable resume artifact paths when those artifacts exist.
+- History now suggests which existing local artifact to open first for each
+  session.
+- History now surfaces the newest session's open-first action before the full
+  session list, reducing scan work in long local histories.
+- History now tells users to run `agentflight handoff` when the latest local
+  session is current but no handoff/report/replay artifact exists yet.
+- History now shows the latest session's recorded readiness in the top-level
+  `Latest action:` block.
+- History now says `Open first: none yet` when no handoff, report, or replay
+  artifact exists.
+- HTML replay now reserves urgent failed-run navigation for unresolved failed
+  verification while keeping historical failed runs visible in the ledger.
+- Ready handoffs no longer inline historical failed verification excerpts once
+  no unresolved failed-verification proof gap remains; those excerpts stay in
+  report/replay evidence.
+- `agentflight start` now treats AgentLoopKit's `Active task: none pinned.`
+  status as no active task instead of falsely reporting task reuse.
+- AgentLoopKit task-link diagnostics now use generic link-check wording instead
+  of stale automatic task-creation copy.
+- `agentflight init` now reports ProjScan and AgentLoopKit CLI availability
+  using the same concise tool formatter as start/report surfaces instead of
+  relying on repo marker files.
+- `agentflight status` now reports a clean worktree explicitly instead of
+  calling zero changed files `Unknown` after a completed session has been
+  committed.
+- `agentflight status` now compacts very long terminal verification run lists
+  while keeping full verification runs in JSON, report/replay, and local
+  evidence files.
+- Clean-worktree `agentflight status` now tucks individual verification run
+  details when there are no unresolved failed runs, while keeping counts and
+  JSON evidence complete.
+- Review Intelligence now treats incomplete verification attempts as blocking
+  before clean-worktree readiness, so live status cannot call a session clean
+  while verification is still in progress.
+- `agentflight init` now lists created and skipped files by repo-relative path
+  instead of only showing counts.
+- `agentflight doctor` now warns when `.projscan-memory/memory.json` exists
+  without a matching project filter and reports OK once the repo filters it
+  through `changedFileFilters.ignore`.
+- `agentflight history` now labels stored review metadata as
+  `Recorded readiness:` so it is not confused with live worktree readiness.
+- `agentflight doctor` no longer prints the absolute repository root in the
+  successful repository-root check.
+- HTML replay now labels resolved failed verification rows as historical when
+  no unresolved failed runs remain.
+- `agentflight doctor` now treats a missing current session as OK first-run
+  guidance instead of warning when the rest of the local setup is healthy.
+- Clean-worktree status now reports `Risk: none` instead of `Risk: unknown`
+  while preserving `unknown` for legacy or genuinely missing metadata.
+- Clean-worktree risk reasons now use current-state wording instead of saying
+  no changed files were detected "yet."
+- Parallel report, replay, and resume commands now preserve each artifact event
+  in session history instead of letting the last stale session write win.
+- Review Intelligence no longer lets ProjScan risk hints boost generated
+  `.projscan-memory/memory.json` above real first-run review targets, while the
+  file remains visible with the existing `changedFileFilters.ignore` guidance.
+- `agentflight history` now includes the selected local artifact path directly
+  on the `Open first:` line, reducing lookup work in long session lists.
+- `agentflight handoff` now includes the selected report or replay path directly
+  on the `Open first:` line while preserving the full artifact list.
+
+### Changed
+
+- Clean-worktree `agentflight resume` constraints now tell agents to start a new
+  AgentFlight session before unrelated work instead of applying active-task
+  constraints to a completed clean session.
+- `agentflight start` now prefers configured no-arg `agentflight verify`
+  guidance when `.agentflight/config.json` already has verification commands,
+  while keeping detected package-script fallback guidance for empty configs.
+- Current product copy now uses `coding agent sessions` and agentic engineering
+  language instead of assistant-style positioning.
+- Idempotent `agentflight init` now shows a concrete detected proof command
+  when existing config verification commands are empty.
+- First-run `agentflight init` now points seeded configs at no-arg
+  `agentflight verify` in the primary workflow.
+- `agentflight init` now points first-run users through the handoff golden path:
+  start a session, capture verification, then generate a local handoff, with
+  status and doctor listed as supporting checks.
+- `agentflight init` now uses the first detected verification command in its
+  primary workflow guidance, falling back to `<proof command>` when no proof
+  script is detected.
+- Newly generated `.agentflight/config.json` files now seed detected
+  verification commands from package scripts while leaving profiles empty and
+  preserving existing configs.
+- README and verification docs now describe the handoff-first first-run workflow
+  and init-seeded verification commands.
+- Kept ready-review report, replay, resume, examples, and demo copy aligned with
+  the `agentflight handoff` golden path while keeping report/replay/resume as
+  supporting local artifacts.
+- Changed-file review surfaces now fail with an actionable git-status error
+  instead of treating git-status failures as an empty diff.
+- Shortened the optional ProjScan baseline budget during `agentflight start` so
+  busy local ProjScan work cannot stall session startup for too long.
+- `agentflight start` now reuses an active AgentLoopKit task instead of creating
+  a duplicate AgentFlight placeholder task.
+- `agentflight start` now shows concise ProjScan and AgentLoopKit warning
+  summaries when optional tooling is available but degraded.
+- `agentflight start` now inspects ProjScan availability without running the
+  heavier optional `projscan start` baseline on the startup path.
+- `agentflight start` now uses lightweight AgentLoopKit availability inspection
+  on the startup path while preserving task reuse/linking.
+- `agentflight start` now reuses AgentLoopKit's local active-task state file
+  directly instead of parsing `agentloopkit status` output.
+- `agentflight start` now links existing AgentLoopKit task state without
+  creating new AgentLoopKit task contracts automatically.
+- Start output and Markdown tooling rows now show whether AgentLoopKit has an
+  active task linked when that local state is known.
+- `agentflight handoff` now treats missing required proof as not ready to share:
+  it exits non-zero, uses `Fix before sharing`, and points users to the report
+  first.
+- Start, report, replay, and handoff terminal output now display local
+  `.agentflight/...` artifact paths relative to the repo instead of absolute
+  user-directory paths.
+- Handoff verification details now distinguish zero verification runs from
+  passing runs that simply have no failed excerpts.
+- Review Intelligence suggested proof now follows each proof gap's preferred
+  proof-kind order, so source gaps prefer `npm test` when available and
+  dependency gaps prefer build/install-style proof before typecheck.
+- Review Intelligence proof-gap rules are now centralized in one ordered table
+  to keep future proof guidance changes easier to review.
+- HTML replay verification ledgers now display long run commands compactly while
+  keeping the full command available in the title text.
+- Status and Markdown report verification evidence rows now use compact display
+  labels for long run commands while preserving stored command evidence.
+- `agentflight init` now writes `.agentflight/.gitignore` for runtime evidence
+  directories instead of seeding new runtime `.gitkeep` files, reducing
+  first-run Git noise while keeping `.agentflight/config.json` and the local
+  AgentFlight ignore file visible as project config.
+- AgentFlight session JSON writes now use same-directory temp files and atomic
+  rename so concurrent report, replay, resume, and handoff commands do not read
+  partially written session state.
+- Review Intelligence now describes `.projscan-memory/memory.json` as generated
+  tool state instead of arbitrary unknown code while keeping the file visible.
+- Report and replay generation now persist a compact local readiness summary in
+  session events, letting `agentflight history` show the latest recorded
+  readiness without recalculating old sessions.
+
 ## AgentFlight v0.6.0 - 2026-06-19
 
 Local review ergonomics and automation surfaces for heavier real-world dogfood.
@@ -19,7 +288,20 @@ Local review ergonomics and automation surfaces for heavier real-world dogfood.
 
 ### Changed
 
-- AgentFlight now describes itself as a local-first review layer for AI coding sessions across package metadata, README, and product docs.
+- Clarified first-run workspace hygiene docs: `.projscan-memory/**` can be added
+  to `changedFileFilters.ignore` when ProjScan memory is generated evidence
+  rather than a review target.
+- Lowered generated ProjScan memory priority in Review Intelligence so
+  `.projscan-memory/memory.json` remains visible but no longer outranks real
+  first-run review targets such as `.agentflight/config.json` or docs changes.
+- Classified first-party TypeScript/JavaScript source files under `src/` as
+  source changes so review focus gives clearer guidance and proof gaps than the
+  previous unknown-file fallback.
+- Aligned ready-review next actions with the handoff golden path: status,
+  report, replay, and resume now point users toward `agentflight handoff`, while
+  the handoff artifact itself tells users to share the generated local packet.
+
+- AgentFlight now describes itself as a local-first review layer for coding agent sessions across package metadata, README, and product docs.
 - Long suggested proof commands stay compact in high-density review surfaces while preserving the full suggested action where useful.
 - Local AgentLoopKit evidence paths are filtered from AgentFlight changed-file review surfaces:
   - `.agentloop/state.json`
@@ -151,7 +433,7 @@ Review Intelligence trust patch focused on v0.4.0 dogfood findings.
 
 ### Added
 
-- Added deterministic Review Intelligence for AI coding sessions.
+- Added deterministic Review Intelligence for coding agent sessions.
 - Added review focus ranking to highlight the files developers should inspect first.
 - Added proof gap detection for missing or failed verification evidence.
 - Added clearer readiness states and next-best-action guidance.

package/README.md

@@ -8,21 +8,22 @@
 
 See what your coding agent did, what failed, and whether the work is ready for review.
 
-AgentFlight is a local-first review layer for AI coding sessions from Baseframe Labs. It records what your coding agent did, captures verification evidence, shows failure excerpts, and tells you what needs review before you trust the result.
+AgentFlight is a local-first review layer for coding agent sessions from Baseframe Labs. It records what your coding agent did, captures verification evidence, shows failure excerpts, and tells you what needs review before you trust the result.
 
 Website: [baseframelabs.com/apps/agentflight](https://www.baseframelabs.com/apps/agentflight)
 
 AgentFlight helps you:
 
-- start an AI coding session
+- start a coding agent session
 - capture verification evidence
 - see changed files and risk
 - create snapshots during the session
-- generate a proof report
-- generate a local replay timeline
+- generate a local review handoff
+- generate a proof report and local replay timeline
+- find recent local sessions and their artifacts
 - create a resume prompt for the next agent or reviewer
 
-![AgentFlight CLI workflow: start, verify, status, and replay](docs/assets/agentflight-terminal-demo.gif)
+![AgentFlight CLI workflow: init, start, verify, status, handoff, and history](docs/assets/agentflight-terminal-demo.gif)
 
 ## 60-Second Workflow
 
@@ -30,38 +31,40 @@ AgentFlight helps you:
 npx agentflight@latest init
 npx agentflight@latest start --task "Add password reset flow"
 
-# Run Codex, Claude Code, Cursor, or your coding agent normally
+# Run your coding agent normally
 
-npx agentflight@latest verify -- npm test
+npx agentflight@latest verify
 npx agentflight@latest snapshot --note "Initial implementation verified"
 npx agentflight@latest status
-npx agentflight@latest report
-npx agentflight@latest replay
-npx agentflight@latest resume
+npx agentflight@latest handoff
+npx agentflight@latest history --limit 1
 ```
 
 What you get:
 
-- `init` creates local `.agentflight/` project files.
+- `init` creates local `.agentflight/` project files and seeds detected verification commands into `.agentflight/config.json` when package scripts exist.
 - `start` records the task, git branch, commit, dirty state, package manager, and tool availability.
-- `verify -- npm test` runs the command and stores stdout, stderr, exit code, timing, and pass/fail status.
-- `snapshot --note "..."` records the current git, risk, and proof state as a timeline event.
+- `verify` runs configured commands and stores stdout, stderr, exit code, timing, and pass/fail status. Use `verify -- <command>` for one explicit proof command.
 - `status` answers what changed, how risky it is, what proof exists, what proof is missing, and what to do next.
+- `snapshot --note "..."` records the current git, risk, and proof state as a timeline event.
+- `handoff` generates the local review packet: readiness, proof gaps, failed excerpts, and report/replay/resume artifact paths.
 - `report` writes a Markdown proof report for review.
-- `replay` writes a local HTML timeline you can open in a browser.
-- `resume` writes a Codex/Claude-ready prompt for the next safe step.
+- `replay` writes a local HTML review path and timeline you can open in a browser.
+- `resume` writes a continuation prompt for the next safe step.
+- `history` shows a latest action with recorded readiness, the artifact to open first, and recent local handoff/report/replay/resume paths without uploading, syncing, or switching sessions. Use `history --task <text>` or `history --state ready|blocked|needs_verification|unknown|current` to narrow existing local records.
 
 ## Watch The Flow
 
-AgentFlight turns a loose AI-agent session into a local proof trail:
+AgentFlight turns a loose coding agent session into a local proof trail:
 
 1. Start a session before you ask the coding agent to work.
 2. Capture real verification output with `agentflight verify`.
 3. Snapshot meaningful checkpoints.
 4. Read `status` to see changed files, risk, proof, gaps, and next action.
-5. Generate `report`, `replay`, and `resume` when the work is ready to review or hand off.
+5. Run `handoff` when the work is ready to review or when you need a clear fix-before-sharing summary.
+6. Use `history --limit 1` to reopen the latest local handoff, report, replay, or resume artifact.
 
-The replay artifact is a self-contained local HTML file. It leads with the review verdict, then lays out risk, review focus, proof gaps, the session timeline, and verification evidence (with inline failure excerpts, so you can see what broke without opening a log file) as a readable flight record:
+The replay artifact is a self-contained local HTML file. It leads with the review verdict and a compact review path, then lays out risk, review focus, proof gaps, the session timeline, and verification evidence (with inline failure excerpts, so you can see what broke without opening a log file) as a readable flight record:
 
 ![AgentFlight replay: review verdict, risk, timeline, and verification evidence](docs/assets/agentflight-replay-scroll.gif)
 
@@ -69,7 +72,7 @@ A high-resolution still is also available at [`docs/assets/agentflight-replay-ti
 
 ## Why This Exists
 
-AI coding agents move fast. After a few prompts, you can lose track of:
+Coding agents move fast. After a few prompts, you can lose track of:
 
 - what changed
 - whether the agent drifted from the task
@@ -94,30 +97,30 @@ Changed files:
 3
 
 Risk: medium
-- Dependency, backend, or unknown files changed.
+- Application source files changed.
 
 Verification Evidence:
 1 passed, 0 failed
 
 Review first:
 1. src/auth/reset.ts
-   Why: identity/session path; no passing test evidence
+   Why: identity/session path
    Focus: Check session, permission, and identity boundaries first.
    Suggested proof: npm test
 
 Proof gaps:
-- blocking: Sensitive auth, payment, or security files changed without passing test evidence.
+- none
 
 Latest snapshot:
 - Note: Initial implementation verified
 - Risk: medium
 - Changed files: 3
 
-Readiness: Needs verification
-Reason: Sensitive auth, payment, or security files changed without passing test evidence.
+Readiness: Ready for review
+Reason: Verification evidence is present and no blocking proof gaps were detected.
 
 Next action:
-Run agentflight verify -- npm test
+Run agentflight handoff to generate the local review packet.
 ```
 
 `agentflight report`:
@@ -127,7 +130,7 @@ Run agentflight verify -- npm test
 
 ## Review First
 1. src/auth/reset.ts
-   - Why: identity/session path; no passing test evidence
+   - Why: identity/session path
 
 ## Verification Evidence
 - passed: npm test
@@ -135,7 +138,25 @@ Run agentflight verify -- npm test
 - stderr: .agentflight/evidence/.../verification-1.stderr.txt
 
 ## Review Readiness
-Needs verification
+Ready for review
+```
+
+`agentflight handoff`:
+
+```text
+AgentFlight handoff
+
+Task:
+Add password reset flow
+
+Readiness: Ready for review
+Open first: handoff .agentflight/reports/af-...-handoff.md
+
+Artifacts:
+- Handoff: .agentflight/reports/af-...-handoff.md
+- Report: .agentflight/reports/af-...-report.md
+- Replay: .agentflight/reports/af-...-replay.html
+- Resume: .agentflight/reports/af-...-resume.md
 ```
 
 `agentflight replay`:
@@ -145,7 +166,22 @@ Replay saved:
 .agentflight/reports/af-...-replay.html
 
 Timeline:
-session_started -> verification_passed -> snapshot_created -> replay_generated
+session_started -> verification_passed -> snapshot_created -> report_generated -> replay_generated
+```
+
+`agentflight history --limit 1`:
+
+```text
+AgentFlight history
+
+Latest action:
+Open first: handoff .agentflight/reports/af-...-handoff.md
+Recorded readiness: Ready for review
+
+Recent sessions:
+1. Add password reset flow
+   Proof: 1 passed, 0 failed
+   Handoff: .agentflight/reports/af-...-handoff.md
 ```
 
 `agentflight resume`:
@@ -181,12 +217,14 @@ The current AgentFlight release supports:
 - config-defined verification profiles for repeated local command groups
 - configurable generated/internal changed-file filters
 - verification evidence capture with `agentflight verify`
-- inline failure excerpts in the replay and report, so failures are visible without opening evidence files
+- inline failure excerpts in terminal output, handoffs, reports, and replays, so failures are visible without opening evidence files
 - session events
 - snapshots with `agentflight snapshot --note "..."`
 - Markdown proof reports
-- self-contained HTML replay timelines
-- resume prompts for Codex, Claude Code, or a human reviewer
+- self-contained HTML replays with review-path guidance and timelines
+- local review handoffs that point to the report, replay, and resume artifacts
+- local history filters for finding sessions by task text or recorded readiness
+- resume prompts for the next agent or reviewer
 - doctor checks for local setup
 - defensive ProjScan and AgentLoopKit adapters
 - no telemetry, cloud sync, or source upload
@@ -213,10 +251,13 @@ AgentFlight creates a local `.agentflight/` directory in your repo:
 - `current/` stores the active session, handoff, and resume prompt.
 - `reports/` stores Markdown proof reports and HTML replays.
 - `evidence/` stores stdout and stderr from captured verification runs.
+- `.gitignore` keeps those runtime directories out of git while leaving
+  `config.json` visible.
 
 Sessions store an `events` timeline with meaningful moments such as session start, verification attempts, snapshots, and generated artifacts. Reports include filenames and summaries by default, not full source diffs.
 
-Runtime session data is ignored by git by default in this repo:
+Runtime session data is ignored by the `.agentflight/.gitignore` created by
+`agentflight init`:
 
 - `.agentflight/sessions/`
 - `.agentflight/reports/`
@@ -235,11 +276,18 @@ AgentFlight always excludes its own runtime session/report/current/evidence file
 }
 ```
 
+On a first run, ProjScan fallback state may create `.projscan-memory/memory.json`
+and AgentFlight may surface it in status, report, replay, or handoff output. If
+that memory file is generated evidence rather than something reviewers should
+inspect, add `.projscan-memory/**` to `changedFileFilters.ignore`. AgentFlight
+does not ignore it by default, because some teams may want generated tool state
+to stay visible.
+
 See [docs/development/changed-file-filters.md](docs/development/changed-file-filters.md).
 
 ## Commands
 
-- `agentflight init` initializes `.agentflight/` with safe writes and explains which local files are project config versus runtime evidence.
+- `agentflight init` initializes `.agentflight/` with safe writes, seeds detected verification commands into config when package scripts exist, and explains which local files are project config versus runtime evidence.
 - `agentflight start --task "..."` starts a session and writes the current handoff.
 - `agentflight status` summarizes changed files, risk, verification status, review focus, proof gaps, readiness, snapshots, and next action.
 - `agentflight status --format json` prints the same local status data as structured JSON for scripts.
@@ -252,6 +300,10 @@ See [docs/development/changed-file-filters.md](docs/development/changed-file-fil
 - `agentflight report --mode pr-comment` writes a local PR-comment draft without posting anywhere.
 - `agentflight replay` generates a local self-contained HTML replay with review focus and proof gaps.
 - `agentflight resume` prints and saves a continuation prompt with the next safest action.
+- `agentflight handoff` generates a local review handoff, report, replay, and resume prompt without posting anywhere. It exits non-zero when verification failures or missing proof make the work not ready to share.
+- `agentflight history` shows the latest action first, including recorded readiness, open-first artifact guidance, current-session marker, proof counts, and existing local handoff/report/replay/resume paths.
+- `agentflight history --task <text>` narrows existing local sessions by task title before applying `--limit`.
+- `agentflight history --state ready|blocked|needs_verification|unknown|current` narrows existing local sessions by recorded readiness or the current-session marker before applying `--limit`.
 - `agentflight doctor` checks local setup, scripts, tools, config, and current session state.
 
 Future placeholders exist for `upgrade`, `license`, and `login`; AgentFlight Pro/Team is not available yet.
@@ -273,7 +325,7 @@ Strategic architecture:
 
 ## Example Session
 
-Read [docs/examples/basic-agentflight-session.md](docs/examples/basic-agentflight-session.md) for a short password-reset walkthrough with status, report, replay, and resume artifacts.
+Read [docs/examples/basic-agentflight-session.md](docs/examples/basic-agentflight-session.md) for a short password-reset walkthrough with status, handoff, report, replay, and resume artifacts.
 
 ## Roadmap
 

package/dist/adapters/agentloopkit.d.ts

@@ -4,7 +4,8 @@ export interface InspectAgentLoopKitOptions {
     cwd?: string;
     run?: CommandRunner;
     command?: string;
+    includeDoctor?: boolean;
 }
 export declare function inspectAgentLoopKit(options?: InspectAgentLoopKitOptions): Promise<ToolAdapterResult>;
-export declare function createAgentLoopTask(cwd: string, title: string, run?: CommandRunner): Promise<ToolAdapterResult>;
+export declare function linkAgentLoopTask(cwd: string): Promise<ToolAdapterResult>;
 //# sourceMappingURL=agentloopkit.d.ts.map

package/dist/adapters/agentloopkit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agentloopkit.d.ts","sourceRoot":"","sources":["../../src/adapters/agentloopkit.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,MAAM,WAAW,0BAA0B;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,mBAAmB,CACvC,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,iBAAiB,CAAC,CAsC5B;AAED,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,GAAG,GAAE,aAA0B,GAC9B,OAAO,CAAC,iBAAiB,CAAC,CAoC5B"}
+{"version":3,"file":"agentloopkit.d.ts","sourceRoot":"","sources":["../../src/adapters/agentloopkit.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAG3D,MAAM,WAAW,0BAA0B;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,wBAAsB,mBAAmB,CACvC,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,iBAAiB,CAAC,CA+C5B;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAU/E"}