@deksden-com/dd-flow-cli 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,671 @@
 # @deksden-com/dd-flow-cli
 
+## 0.8.0
+
+### Patch Changes
+
+- a092c98: Accept controlled OpenCode lifecycle events and cumulative root/child Session usage through the shared harness evidence path.
+- fb2395a: Accept trusted lifecycle events from controlled zcode-acp sessions and retain harness-native root, child, parent, and execution-daemon identities in Session evidence.
+- Promote the accepted SPECIFY-through-CODE-REVIEW runtime as stable 0.8.0 and align its shared compatibility, flow, stage-start and status schemas with Memory Bank 4.0.0.
+
+## 0.8.0-beta.138
+
+### Patch Changes
+
+- Replace CODE and repair file allowlists with optional `planned_write_areas`:
+  soft coordination hints that serialize likely concurrent collisions but never
+  deny a necessary project-local edit. Record unexpected actual paths as
+  `coordination.drift` instead of rejecting the Work.
+- Render the hard RUN workspace boundary separately from required reads,
+  discovery hints and planned coordination areas, so a worker can distinguish
+  semantic constraints from planning predictions.
+
+## 0.8.0-beta.137
+
+### Patch Changes
+
+- Transfer a running coordinator Work to a fresh Session at a frozen
+  `new_session` stage boundary, while still rejecting a second Session that
+  tries to repeat the same stage.
+
+## 0.8.0-beta.136
+
+### Patch Changes
+
+- Serialize the long CODE aggregate gate and reuse complete same-workspace
+  receipts after a client loses its command output, preventing a concurrent
+  retry from duplicating checks or colliding on receipt identifiers.
+
+## 0.8.0-beta.135
+
+### Patch Changes
+
+- Derive a CODE repair Work's additional write scope from exact existing
+  project files named by its retained failed-check receipt, with path-escape
+  and dependency-directory guards.
+- Keep eval snapshot rebasing out of restored workspaces and installed tools,
+  so valid JSON-with-comments project files cannot break a later stage entry.
+
+## 0.8.0-beta.134
+
+### Patch Changes
+
+- Pair the engine with the PLAN/PLAN-REVIEW prompt correction that makes every
+  linked acceptance scenario explicitly owned for update or explicitly
+  classified as unaffected before CODE opens.
+
+## 0.8.0-beta.133
+
+### Patch Changes
+
+- Reject a PLAN that assigns a project aggregate gate to one scoped CODE Work;
+  aggregate gates now run at the CODE/readiness fan-in, where failure can
+  create a correctly scoped repair Work.
+- Preserve the distinction between a worker that explicitly failed its Work
+  and a worker that omitted its lifecycle finish in eval runner evidence.
+
+## 0.8.0-beta.132
+
+### Patch Changes
+
+- Preserve the one-to-one relationship between PLAN-declared CODE checks and
+  their execution receipts, even when checks intentionally share a command.
+- Reject a CODE-REVIEW decision that rejects or defers a material P0/P1
+  finding before repair Work is created, so the initial repair packet is
+  complete and cannot leave the stage in a non-progressing state.
+
+## 0.8.0-beta.131
+
+### Patch Changes
+
+- Explain that a CODE Work receives shared end-to-end acceptance context but
+  owns only its declared contribution, write scope and checks. This prevents a
+  correctly scoped worker from failing merely because a dependent UI or
+  documentation surface belongs to another Work.
+
+## 0.8.0-beta.128
+
+### Patch Changes
+
+- Render an executable, one-command heredoc template for every agent-owned
+  HITL pause and preserve that template through Codex, ZCode, Grok, OpenCode
+  and Antigravity hook parsing.
+
+## 0.8.0-beta.127
+
+### Patch Changes
+
+- Keep PROTOCOLIZE stage attachment independent from coordinator Session reuse,
+  expose the measured worker capacity in the PLAN packet, and report an
+  explicit zero-capacity infrastructure outcome for PLAN-REVIEW.
+
+## 0.8.0-beta.122
+
+### Patch Changes
+
+- Preserve a portable Git bundle in each new eval snapshot and restore it
+  before the checkpoint tree, so later stages retain their branch and can
+  create managed worktrees.
+
+## 0.8.0-beta.121
+
+### Patch Changes
+
+- Keep CODE implementation in fresh Work sessions so the coordinator preserves
+  graph, evidence and final-gate context across a sequential delivery graph.
+
+## 0.8.0-beta.119
+
+### Patch Changes
+
+- Keep the accepted `@check/...` declaration when creating a CODE repair Work
+  from a failed receipt. Receipts retain the expanded command as evidence, but
+  the repair packet is validated and executed through the original alias.
+
+## 0.8.0-beta.118
+
+### Patch Changes
+
+- Keep PLAN-time document baselines immutable while validating CODE handoff, so
+  a required durable-documentation Work cannot invalidate its own generated
+  CODE batch.
+- Emit full Work ids in generated lifecycle commands and align the CODE
+  verification example with the installed `code-verification@2` schema.
+
+## 0.8.0-beta.116
+
+### Patch Changes
+
+- Register the CODE stage before workspace readiness so a failed bootstrap is
+  a recoverable, timed stage attempt rather than an unfinishable lifecycle.
+
+## 0.8.0-beta.115
+
+### Patch Changes
+
+- Materialize both partially filled PLAN artifacts at stage start and report
+  which fields are already owned by the CLI.
+- Prepopulate the aspect-map catalog identifiers without making semantic
+  applicability decisions for the planner.
+- Return exact artifact paths and schema-validation commands in the PLAN
+  packet while preserving `plan.json` as the sole semantic plan.
+
+## 0.8.0-beta.111
+
+### Patch Changes
+
+- Make a future CODE check an explicit, provider-owned `@check/...` alias
+  with an exact definition; reject unordered, raw or unmaterialized checks.
+- Run PLAN-declared available readiness checks after bootstrap, preserve their
+  receipts, and distinguish project policy gates from planner-selected CODE
+  checks.
+- Carry the stricter verification contract through PLAN and CODE worker
+  packets without asking the CLI to judge test relevance or cost.
+
+## 0.8.0-beta.110
+
+### Patch Changes
+
+- Make PLAN own verification selection through a single check catalogue;
+  validate only references, provider ordering and guarded commands.
+- Preserve review evidence in Work results instead of mutating aspect maps,
+  reuse one RUN capacity measurement, and support HITL-backed effective
+  obligation amendments.
+- Never rewrite Bash heredocs in lifecycle hooks.
+
+## 0.8.0-beta.109
+
+### Patch Changes
+
+- Keep the SQLite vNext RUN projection free of legacy `current_stage`, attempt,
+  worker and coverage mirrors; derive stage guidance from canonical stage runs.
+
+## 0.8.0-beta.108
+
+### Patch Changes
+
+- Align vNext runtime identity, Work/Session state, filesystem materialization,
+  stage reports, review findings and check receipts with SPC-009.
+- Add a single stage catalog, safe RUN path resolver, overlapping write-scope
+  scheduling guard and structured eval snapshot rebasing.
+- Remove automatic Work `try-001` materialization and the separate `work.json`
+  projection; explicit retries archive under `attempts/ATT-NNN`.
+
+## 0.8.0-beta.103
+
+### Patch Changes
+
+- Isolate local CODE check processes by checkout and pass the scope through deterministic bootstrap and gate commands.
+- Make CODE worker instructions distinguish repairable project check failures from evidenced external blockers.
+
+## 0.8.0-beta.102
+
+### Patch Changes
+
+- Permit the stdin pipe required by `stage resume` while retaining the strict
+  standalone-command guard for stage and Work starts.
+
+## 0.8.0-beta.101
+
+### Patch Changes
+
+- abef4b2: Reject ambiguous compound lifecycle starts, preserve trusted coordinator
+  ownership, enforce hard Work dependencies during review dispatch, and expose
+  complete reviewer, timing, evidence, Session and Agent observability.
+
+## 0.8.0-beta.100
+
+### Patch Changes
+
+- 430e49f: Preserve project check aliases until execution, add recoverable external stage
+  blockers, deduplicate physical-session usage, and improve session and review
+  routing projections.
+- 06e58ab: Stream machine-readable progress for long lifecycle commands, make CODE and
+  CODE-REVIEW retries idempotent, preserve terminal timestamps, and tighten
+  candidate usage/session projections.
+- Reject a completed CODE verification that cites evidence missing from the RUN or
+  its workspace, and refresh protocol summaries at deterministic CODE boundaries.
+
+## 0.8.0-beta.99
+
+### Patch Changes
+
+- Validate draft 2020-12 stage contracts with the matching JSON Schema engine
+  and surface schema-registry compilation failures as actionable engine errors.
+- Namespace CODE-REVIEW findings by reviewer group and require every assigned
+  aspect exactly once before accepting reviewer evidence.
+- Keep active RUN projections free of resolved pause/blocker records, preserve
+  their history in the timeline, and normalize quoted RUN ids from hooks.
+- Validate CODE completion evidence before running the aggregate project gate.
+
+## 0.8.0-beta.93
+
+### Patch Changes
+
+- Republish the beta.92 CODE packet validation fix as the matched engine for
+  the corrected flow-pack compatibility declaration.
+
+## 0.8.0-beta.92
+
+### Patch Changes
+
+- Treat each PLAN `verification.checks` entry as an executable command only.
+  With a project check profile, PLAN now accepts only declared aliases or exact
+  declared commands, and rejects semantic assertions before it can create a
+  CODE Work packet. Semantic proof stays in `expected_evidence`.
+
+## 0.8.0-beta.91
+
+### Patch Changes
+
+- Remove obsolete `session_coverage` and `usage_coverage` projections from
+  vNext RUN state, leaving factual Session and usage data to the stat commands.
+
+## 0.8.0-beta.90
+
+### Patch Changes
+
+- Snapshot one project-owned execution profile into each vNext RUN and keep
+  checkout routing separate from handoff, review and bootstrap policy.
+- Move deterministic workspace bootstrap to CODE, report its heartbeat, and
+  end successful CODE at the truthful terminal verdict `code_completed`.
+- Use readable `WRK-*` Work identifiers and replace synthetic coverage claims
+  in vNext stage reports with factual post-settlement statistics commands.
+
+## 0.8.0-beta.89
+
+### Patch Changes
+
+- Keep active CODE workers alive until the harness reports a terminal state.
+- Stream long check progress and validate project-owned check aliases before
+  CODE Work registration.
+- Scope Session, token, tool-call and timing evidence to the selected stage or
+  segment and keep only the latest check receipt as current evidence.
+
+## 0.8.0-beta.88
+
+### Patch Changes
+
+- Preserve accepted requirements, semantic responsibility, selected project
+  context, write scope and verification when PLAN projects CODE Work.
+- Execute CODE as the registered Work graph under the RUN root orchestrator,
+  with focused checks at Work completion and a deterministic aggregate gate at
+  stage completion.
+- Keep failed aggregate gates open and create an explicit repair Work from the
+  failed receipt plus the original Work context.
+
+## 0.8.0-beta.87
+
+### Patch Changes
+
+- Remove the obsolete vNext fixture handoff fallback so PROTOCOLIZE starts
+  only from the accepted SPECIFY context.
+- Prove that review-off uses the same validated final PLAN-to-CODE closure as
+  an enabled review.
+
+## 0.8.0-beta.86
+
+### Patch Changes
+
+- Make SPECIFY JSON the accepted semantic source, preserve all R/AC
+  obligations through PROTOCOLIZE and PLAN, and derive the CODE work batch
+  only after shared deterministic validation.
+- Reject stale PLAN/CODE handoffs and publish accepted semantic artifacts and
+  deterministic reports atomically.
+- Resolve Codex transcripts inside the selected `CODEX_HOME`; tests now use
+  isolated homes instead of scanning a developer's session history.
+
+## 0.8.0-beta.81
+
+### Patch Changes
+
+- Reject an accepted PLAN-REVIEW correction unless it regenerates the proposed
+  CODE batch and records that artifact in the correction receipt. This keeps
+  CODE work paths and verification aligned with the revised plan.
+
+## 0.8.0-beta.80
+
+### Patch Changes
+
+- Make failed eval snapshots read-only: an accidental worktree value for
+  `--project-root` no longer registers a second project in the dedicated
+  runtime before failing.
+
+## 0.8.0-beta.79
+
+### Patch Changes
+
+- Use the single vNext workspace policy for the frozen SPECIFY →
+  PROTOCOLIZE handoff. This prevents the generic runtime default from
+  contradicting `project-workspace.json`.
+- Remove the obsolete `execution.stage_handoff` runtime setting so it cannot
+  be mistaken for a second vNext authority.
+
+## 0.8.0-beta.78
+
+### Patch Changes
+
+- Treat a complete PLAN-REVIEW reviewer result with `blocked` as actionable
+  evidence, requiring a classified in-place correction, rather than a terminal
+  stage failure. Missing, malformed, or unfinished reviewer evidence still
+  blocks the stage.
+- Keep the PROTOCOLIZE PSET test fixture consistent with the fail-closed
+  acceptance-coverage contract.
+
+## 0.8.0-beta.77
+
+### Patch Changes
+
+- Make PROTOCOLIZE fail closed unless `acceptance_coverage` owns every
+  `AC-*` criterion in the accepted SPECIFY handoff exactly once.
+
+## 0.8.0-beta.76
+
+### Patch Changes
+
+- Make the PROTOCOLIZE workspace receipt a fail-closed gate for PLAN,
+  PLAN-REVIEW and CODE, and include the verified write workspace in every
+  generated worker packet.
+- Require disposable capacity probes and completed review workers to release
+  their harness slots before productive work continues.
+
+## 0.8.0-beta.75
+
+### Patch Changes
+
+- Render every vNext lifecycle command with the bound `DD_FLOW_HOME`, so a
+  worker can finish or hand off a stage from any shell environment.
+
+## 0.8.0-beta.74
+
+### Patch Changes
+
+- Measure fresh-subagent capacity at PLAN-REVIEW dispatch rather than reusing a
+  stale PLAN observation; PLAN now groups review aspects semantically only.
+
+## 0.8.0-beta.73
+
+### Patch Changes
+
+- Require self-contained CODE work batches at PLAN finish.
+
+## 0.8.0-beta.72
+
+### Patch Changes
+
+- Align the validated flow contract with the vNext route: a run-scoped feature
+  worktree is provisioned at PROTOCOLIZE start, before durable protocol files
+  are materialized.
+
+## 0.8.0-beta.71
+
+### Patch Changes
+
+- Keep the worktree route strict while allowing Desktop harnesses whose task
+  cwd cannot be dynamically changed: stage packets use absolute workspace
+  targets and hook cwd remains audit evidence rather than a false blocker.
+
+## 0.8.0-beta.70
+
+### Patch Changes
+
+- Provision the configured feature worktree and its bootstrap deterministically
+  at vNext PROTOCOLIZE start. PROTOCOLIZE finish now only validates the frozen
+  route and materializes durable documents there; PLAN and later writing stages
+  reject a session started outside the recorded workspace.
+
+## 0.8.0-beta.58
+
+### Patch Changes
+
+- Bind a portable fixture's synthetic root Work to the first real stage
+  session before starting its child PLAN Work, so a focused PLAN run retains
+  the normal parent-session invariant without importing old sessions.
+
+## 0.8.0-beta.57
+
+### Patch Changes
+
+- Preserve the final newline of `git diff --binary` in exported portable
+  fixtures so their project overlays can be imported by `git apply`.
+
+## 0.8.0-beta.56
+
+### Patch Changes
+
+- Report PROTOCOLIZE as the next legal stage after finished SPECIFY; PLAN is
+  now guided only after the PROTOCOLIZE stage is complete.
+
+## 0.8.0-beta.55
+
+### Patch Changes
+
+- Keep a finished SPECIFY stage isolated until its returned PROTOCOLIZE start
+  command is explicitly invoked; completion now records the hash of the actual
+  stored document and exposes acceptance/check checks in the stage report.
+
+## 0.8.0-beta.54
+
+### Patch Changes
+
+- Restore the accepted fixture's PLAN-REVIEW setting alongside its runtime
+  variables so isolated targets retain the configured flow behavior.
+
+## 0.8.0-beta.53
+
+### Patch Changes
+
+- Mark engine-exported stage fixtures as accepted, matching the strict
+  controller import gate.
+
+## 0.8.0-beta.52
+
+### Patch Changes
+
+- Add an operator-only portable stage-fixture export/import boundary for
+  stage-isolated evaluations. It restores accepted predecessor artifacts and
+  RUN variables into a fresh runtime, never old Sessions, Works, usage or
+  machine paths.
+
+## 0.8.0-beta.51
+
+### Patch Changes
+
+- Put the measured per-wave fresh-subagent capacity into the PLAN response,
+  rendered prompt and Work context. PLAN now explicitly minimizes review waves
+  before reviewer count while preserving real semantic boundaries.
+
+## 0.8.0-beta.49
+
+### Patch Changes
+
+- Prefix generated vNext inter-stage start commands with the selected
+  `DD_FLOW_HOME`, so their PreToolUse hook binds the same isolated RUN.
+- Allow a bounded capacity observation to replace an earlier observation when
+  the harness completes its probe window with a different factual count.
+
+## 0.8.0-beta.48
+
+### Patch Changes
+
+- Publish the coordinated engine snapshot for the vNext HITL flow-pack beta.48.
+
+## 0.8.0-beta.47
+
+### Patch Changes
+
+- Make user interaction an in-stage pause/resume lifecycle: preserve the same
+  Work, stage and attempt, store raw question/answer intake, and require a
+  trusted resume hook event.
+- Remove vNext `waiting_for_user` finish outcomes and fictitious
+  PROTOCOLIZE-to-SPECIFY answer routes. Generated prompts now return exact
+  pause/resume commands, including an isolated `DD_FLOW_HOME` where needed.
+
+## 0.8.0-beta.45
+
+### Patch Changes
+
+- Capture the immutable PLAN-REVIEW decision receipt only after a finish
+  payload passes the mechanical gate, so rejected attempts remain retryable.
+
+## 0.8.0-beta.44
+
+### Patch Changes
+
+- Record RUN capacity before PLAN and expose one consistent `run capacity
+record` command with the bounded 15-probe contract.
+- Preserve the proposed CODE batch through PLAN-REVIEW, validate it before
+  PLAN acceptance, and keep the temporary reviewer dispatch file ephemeral.
+- Keep per-Session stage state accurate, preserve immutable PLAN-REVIEW decision
+  payloads, and materialize reviewer findings into the aspect map.
+- Render a useful deterministic PLAN-REVIEW Markdown/HTML report and require
+  stable finding ids for mechanical decision coverage.
+
+## 0.8.0-beta.43
+
+### Patch Changes
+
+- Attribute transcript usage by the linked Work/Session id; Codex child
+  transcripts expose the child id in `session_meta.id` while the provider id
+  can remain the parent thread id.
+- Include initial/final PLAN revisions and checksums, correction paths and
+  `semantic_re_review` in the deterministic PLAN-REVIEW report.
+
+## 0.8.0-beta.42
+
+### Patch Changes
+
+- Make PLAN-REVIEW a single semantic review wave: reviewer `needs_changes` is
+  evidence, while the orchestrator applies accepted fixes in the same Work and
+  finishes once with an explicit correction receipt.
+- Remove automatic review retries and validate only mechanical correction
+  coherence; semantic re-review remains `not_run_by_policy`.
+
+## 0.8.0-beta.41
+
+### Patch Changes
+
+- Make capacity probing an explicit leaf-session measurement: probes wait 60
+  seconds, return `AGENT-NN`, use a 180-second total deadline, and count only
+  exact-token completions.
+
+## 0.8.0-beta.40
+
+### Patch Changes
+
+- Include the isolated `DD_FLOW_HOME` prefix in generated worker completion
+  and failure commands, matching the worker-start command in a fresh Desktop
+  session.
+
+## 0.8.0-beta.39
+
+### Patch Changes
+
+- Replace partial PLAN-review retries with a new complete review attempt after
+  any PLAN revision. The completed attempt is archived by the common stage
+  state machine; stale evidence cannot be reused.
+- Return the isolated runtime prefix in reviewer worker-start commands, so a
+  fresh Desktop worker reaches the same RUN without manual environment setup.
+
+## 0.8.0-beta.38
+
+### Patch Changes
+
+- Treat fresh-session capacity as one bounded harness observation rather than
+  fifteen registered probe Works. `plan-review capacity record` stores the
+  observed slot count once for the RUN and lets reviewer dispatch proceed.
+
+## 0.8.0-beta.33
+
+### Patch Changes
+
+- Replace beta-only Agent Turn, launch-token and adapter-binding mechanics with
+  hook-observed Work/Session links; add RUN variables, fresh-review capacity
+  probes and transcript-source usage recomputation.
+
+## 0.8.0-beta.32
+
+### Patch Changes
+
+- Split independent PLAN review into a first-class `plan-review` stage with an
+  atomic CODE opening gate and RUN-scoped review policy.
+
+## 0.8.0-beta.31
+
+### Patch Changes
+
+- Let PLAN dispatch a new review attempt only for groups whose latest completed verdict is `needs_changes`; PLAN acceptance uses the latest attempt for each group.
+
+## 0.8.0-beta.30
+
+### Patch Changes
+
+- Include the explicit project root in every generated worker start command, so a Desktop worker launched outside the target checkout can be observed and claimed by its Codex hook.
+
+## 0.8.0-beta.29
+
+### Patch Changes
+
+- Give each Work a one-time launch token, claim the exact matching PreToolUse
+  event, and let the trusted Desktop harness bind a returned child-task
+  identity before a parallel worker starts.
+
+## 0.8.0-beta.28
+
+### Patch Changes
+
+- Keep vNext RUNs live across same-session stage handoffs, dispatch grouped
+  PLAN reviews as real Work/Agent Turns before PLAN acceptance, and preserve
+  portable RUN references in semantic artifacts and worker packets.
+
+## 0.8.0-beta.27
+
+### Patch Changes
+
+- Materialize grouped PLAN aspect routes as prerequisite Work, normalize RUN
+  source provenance, and report PLAN guidance and artifacts without external
+  filesystem-relative paths.
+
+## 0.8.0-beta.26
+
+### Patch Changes
+
+- Keep PreToolUse hook rewriting scoped to one `dd-flow` invocation; compound
+  shell commands are recorded but never mutated.
+
+## 0.8.0-beta.25
+
+### Patch Changes
+
+- Route a Desktop PreToolUse event to an explicitly prefixed isolated
+  `DD_FLOW_HOME`, so beta evals keep trusted session binding without touching
+  the shared runtime database.
+
+## 0.8.0-beta.24
+
+### Patch Changes
+
+- Unify vNext Work/Turn authority, bind PLAN/CODE to trusted hook sessions,
+  enforce strict SPECIFY-to-PLAN traceability, and emit portable Work/usage
+  evidence with deterministic stage reports.
+
+## 0.8.0-beta.13
+
+### Patch Changes
+
+- Automatically apply safe, additive internal SQLite schema updates whenever a
+  write-capable engine command opens an existing runtime database. This keeps
+  hook-event binding compatible across beta engine upgrades without treating it
+  as a Memory Bank data migration.
+
+## 0.8.0-beta.12
+
+### Patch Changes
+
+- Bind vNext SPECIFY bootstrap to a one-time, fresh PreToolUse event using a
+  canonical invocation fingerprint when Codex Desktop ignores hook
+  `updatedInput` rewrites.
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -97,7 +97,7 @@ dd-flow prompt render \
 
 For a non-plan worker, replace `--plan-item` with `--task-file <path>` pointing to a `dd-flow/worker-task@1` manifest inside the selected RUN home. The manifest embeds one existing plan-item-shaped `task`, so validation and rendered artifacts remain identical to the compatibility route.
 
-The selected item must contain `execution_context` and `semantic_spine`. The renderer accepts only registered profiles, validates the active RUN/workspace and source paths, then persists `launch-prompt.md`, `prompt-stack.json` and `render-report.json` in the RUN stage. The stack and render report both retain the validated read/discovery/write references. It records project sources as paths rather than copying their contents. `required_read` and `discovery_boundary` may use a checked `run://<relative-path>` reference for a source inside the selected RUN home; write scopes remain project-local.
+The selected item must contain `execution_context` and `semantic_spine`. The renderer accepts only registered profiles, validates the active RUN/workspace and source paths, then persists `launch-prompt.md`, `prompt-stack.json` and `render-report.json` in the RUN stage. The stack and render report both retain the validated read/discovery/coordination references. It records project sources as paths rather than copying their contents. `required_read` and `discovery_boundary` may use a checked `run://<relative-path>` reference for a source inside the selected RUN home. The RUN workspace is the hard write boundary; `planned_write_areas` are optional soft hints for concurrent-work coordination, never a file allowlist.
 
 Human help is available for the operator-facing command groups:
 
@@ -362,7 +362,12 @@ Installed Codex hooks intentionally omit `--project-root`: Codex supplies the
 session `cwd` in the hook JSON on stdin, and the handler resolves the registered
 project from that path. The option remains available as a manual override. If
 the CLI is upgraded, reinstall the hook in each active `CODEX_HOME`, verify it
-with `dd-flow codex hooks status`, and start a new Codex session;
+with `dd-flow codex hooks status`, and start a new Codex session.
+
+The installed hook writes invocation markers, forwarded stderr, and the final
+exit code to `${DD_FLOW_HOME:-$HOME/.dd-flow}/logs/codex-hook.log`. An absent
+start marker means Codex did not invoke the hook; a start marker without a
+successful finish marker identifies a hook launch or handler failure.
 `--project-root` belongs to installer/status commands, not the stored handler.
 
 ## Verification