---
name: project-session-close
description: Use at the end of a Codex or agent session to run deterministic stop and project-closeout mechanics, then record only source-backed durable state and handoff knowledge.
---

# Project Session Close

Leave the repository ready for a fresh agent without manually replaying
mechanics already owned by the workflow engine.

## Workflow Authority

1. Read effective workflow and hook settings with `prd_config_get`.
2. Plan and run `session.stop` with `prd_workflow_run` when enabled. It owns
   state consistency, staleness audit, enabled reflection collection, and the
   deterministic session-summary bundle.
3. Run `project.closeout` when the task/project itself is closing. It owns the
   gate, final consistency check, and source-bound closeout judgment request.
4. Inspect the receipts. Do not repeat completed steps manually. If a workflow
   is disabled, run only its declared actions through their validated tools;
   the required fallback includes `python scripts/state_consistency_check.py
   --repo-root .` in the hub or `python
   .prd_plugin/scripts/state_consistency_check.py --repo-root .` downstream.

## Durable Updates

After the deterministic facts are current:

Boundary vs `project-memory`: use that skill to promote a durable lesson when
it is discovered mid-session; use session close to batch only the remaining
source-backed promotion and handoff work.

- Use `prd_find`/`prd_get` to load exact records; do not scan JSON for IDs.
- Use `prd_update_goal` or `prd_close_goal` for tracking.
- Use `prd_file_request`, `prd_record_evidence`, `prd_record_decision`, and
  `prd_log_change` for guarded REQ/EV/DEC/CHG writes.
- Use `prd_create`, `prd_update`, and `prd_link` for ordinary TRK/REQ/HLT
  records. Record-backed IDs are allocated atomically; never edit the registry.
- Promote concise, non-sensitive, source-backed memory under
  `memory.promotion_policy`; use the selective-promotion helper when enabled.
- Run `project-traceability-sync` after linked state changes.
- Finish with `prd_validate`; close a goal only when current evidence supports
  it.

## Reflections

When `reflection.enabled` and `reflection.on_stop` are effective, use
`prd_reflection_list` (or the `session.stop` receipt) to obtain only enabled
questions, honoring category switches and the configured question cap. Record
concise observable answers, never private reasoning or secrets. The Stop hook's
session marker prevents recursion; do not trigger a second reflection pass.

## Knowledge And Reporting

- If `knowledge.llm_wiki.enabled` is not false and durable understanding was
  produced, ingest it through `project-llm-wiki` and lint the wiki.
- If `reporting.delegation.enabled` allows `session_summary`, the deterministic
  bundle produced by `prd_reporting.py` may be dispatched through AI-Collab with
  `prd_substrate_runtime` (`action: report`, `task: session_summary`). The
  runtime result must return through `prd_reporting_validate`; it is a
  source-referenced draft and cannot write project state.
- Apply the configured `main`, `deterministic_only`, or `fail` fallback when
  delegation is unavailable or invalid. A reporting failure does not undo a
  valid deterministic closeout.
- Add a retrospective only when configured policy requires it and the session
  produced a durable lesson; do not manufacture one from turn count alone.

## Parallel Worker Boundary

Workers launched with `PRD_WORKER_SESSION=1`, `PRD_TRACKING_BRANCH_ID`, and
`PRD_TRACKING_BRANCH_OWNER` call only `prd_update_tracking_branch` on their
assigned `DBR-*`. They put required closeout mutations in branch notes. The lead
serially performs canonical state writes and calls
`prd_promote_tracking_branch`.

## Rules

- Never store credentials, raw prompts, private chain-of-thought, or unverified
  claims.
- Never hand-edit `.prd_plugin/state/*.json` or
  `.prd_plugin/ids/registry.json` when the validated authority is available.
- Do not run hub-only helpers downstream. Resolve installed helpers under
  `.prd_plugin/scripts/` and obey the script install-scope policy.
- Do not treat an absent remote or CI system as a blocker.
- Do not claim version-impacting work complete until the configured release
  checks pass or a concrete follow-up record exists.

## Staleness Coverage

Apply `.prd_plugin/method/staleness-rules.md`. Resolve, refresh with evidence,
supersede, or explicitly carry forward stale REQ/TRK/HLT/request-transport and
scheduler state before reporting closeout.

Before closeout, refresh or explicitly review stale `HLT-*`, `TRK-*`, `REQ-*`,
request transport, automation lock, and scheduler state.