feat(loop): carry typed phase context through lifecycle hooks

[davdittrich]

Pre-submission checklist

• I have searched existing issues and discussions — this has not been proposed and declined before
• I have read CONTRIBUTING.md and understand that I must wait for approved-feature before writing any code
• I have read the existing GSD commands and workflows and confirmed this feature does not duplicate existing behavior
• This feature solves a problem for solo developers using AI coding tools, not a personal preference or workflow I happen to like

Feature name

Typed phase context for lifecycle hooks

Type of addition

Other — an additive typed field on the existing loop-extension-point contract and its workflow dispatch calls.

The solo developer problem

When a solo developer plans or reviews Phase 2 while Phase 1 remains the project's current executing phase, a phase-scoped capability receives only the lifecycle point and project cwd. It cannot identify the task-local phase. Extensions then either infer from STATE.md and operate on Phase 1, or invent artifact-order/mtime heuristics.

This is observed, not hypothetical: davdittrich/gsd-beads#5 reproduces plan:pre refreshing Phase 1's Beads recall while Phase 2 is being planned. That can hide relevant tickets and can send phase-scoped issue mutation or reconciliation to the wrong phase.

The existing resolver returns { point, activeHooks, rendered } and the workflow calls loop render-hooks <point> --raw without phase context. src/loop-resolver.cts at b811ea1, lines 478-619 and plan-phase.md, lines 353-357 show the missing seam.

Claude Code's documented PostToolUse input provides generic session/cwd fields plus the completed tool's input and response; it has no GSD phase field. A plugin cannot recover an authoritative task-local phase from that host payload alone: https://code.claude.com/docs/en/hooks#posttooluse-input

What this feature adds

Add an optional, typed phase context to phase-scoped loop render-hooks resolution and dispatch:

gsd_run loop render-hooks plan:pre \
  --phase "$PHASE" \
  --phase-dir "$PHASE_DIR" \
  --raw

The JSON envelope gains an additive field:

{
  "point": "plan:pre",
  "context": {
    "phase": "02",
    "phaseDir": "/project/.planning/phases/02-forecasting"
  },
  "activeHooks": [],
  "rendered": ""
}

The names above are a concrete proposal, not a demand for that exact spelling. The contract is:

1. Context is supplied by the invoking workflow, which already owns PHASE/PHASE_DIR.
2. Core validates the phase token and confines the resolved directory to the active project's .planning/phases/<direct-child> before publishing it.
3. Generic step/contribution dispatch makes the resolved typed context available to the invoked capability handler. Runtime adapters may project it into their native hook/tool payload, but extensions never scrape prose, STATE.md, directory order, or mtimes.
4. Omitted context preserves the current envelope and behavior for non-phase-scoped callers.
5. The field represents invocation context, not project lifecycle status; it does not update STATE.md.

Full scope of changes

Files/systems expected to change (exact generated-file handling should follow repository conventions):

• src/loop-resolver.cts — define/validate the optional phase-context value and add it to the resolved/output envelope.
• gsd-core/bin/gsd-tools.cjs — parse the additive typed arguments and pass them to cmdLoopRenderHooks.
• gsd-core/workflows/plan-phase.md — pass the phase being planned at plan:pre and plan:post call sites.
• gsd-core/workflows/execute-phase.md — pass the phase being executed at execute:wave:pre and execute:wave:post call sites.
• gsd-core/workflows/verify-work.md and other phase-scoped verify:* consumers — pass the verified phase.
• gsd-core/references/loop-hook-dispatch.md — specify how generic step/contribution handlers receive typed invocation context.
• tests/loop-render-hooks.test.cjs — pure resolver, CLI, validation, omission/backward-compatibility, and hostile-path cases.
• Existing workflow/loop-hook end-to-end suites — prove the selected phase reaches a capability handler at plan, wave, and verify points.
• Runtime adapter fixtures where the generic context is projected to a native hook surface.
• User-facing capability/extension documentation and inventory/generated attribution metadata required by repository checks.

Systems affected: loop resolver JSON schema, phase-scoped workflow call sites, generic capability dispatch, runtime hook projections, extension-author documentation. No new command, dependency, planning artifact, or persistent state field.

User stories

1. As a solo developer planning Phase 2 while Phase 1 is still executing, I want phase-scoped extensions to receive Phase 2 explicitly so they cannot read or mutate Phase 1 by mistake.
2. As a capability author, I want one validated core-owned invocation-context field so my extension works across runtimes without scraping workflow prose or inferring from mutable project state.
3. As a runtime adapter maintainer, I want phase context in the generic loop contract so I can project it through the host's native hook shape without capability-specific code.

Acceptance criteria

• Phase-scoped loop render-hooks accepts an explicit phase token and phase directory and returns them in a typed context field.
• The phase token follows GSD's existing phase-number contract, including decimal phases.
• phaseDir resolves to one direct child beneath the active project's .planning/phases; traversal, symlink escape, nonexistent paths, and foreign-project paths are rejected before hook dispatch.
• At every phase-scoped plan, execute-wave, and verify call site, the workflow-supplied phase reaches a synthetic third-party step handler unchanged.
• With STATE.current_phase: 01 and invocation context for Phase 2, the synthetic handler receives only Phase 2; STATE.md remains byte-identical.
• Omitting context preserves the current { point, activeHooks, rendered } behavior and does not invent a fallback context field.
• Non-phase-scoped loop points remain unchanged.
• Runtime adapter tests prove the context survives at least Claude Code and Codex projection; the core contract is runtime-neutral.
• Existing loop resolver, host contract, workflow, runtime, and capability suites pass.
• Extension-author documentation states that invocation context outranks recovery/project-status artifacts for task-local routing.

Which area does this primarily affect?

Multiple areas — core workflow, runtime integration, and the capability/loop extension-point contract.

Applicable runtimes

• All runtimes

Breaking changes assessment

None intended. The CLI arguments and JSON context member are additive and optional. Existing callers that omit them keep current output and behavior. Existing capability handlers continue to run; handlers may adopt context incrementally. No STATE, ROADMAP, plan, or capability-manifest schema is changed.

Maintenance burden

• No external dependency.
• One small typed context structure, argument parser branch, and validation path.
• Phase-scoped workflow call sites must keep passing the phase they already resolve.
• Runtime adapters must preserve the generic field when projecting loop dispatch; the field must be included in future parity tests.
• If canonical phase-token/path rules change, this validator must reuse that single source rather than fork it.
• Documentation and end-to-end fixtures add ongoing but bounded maintenance.

The maintenance cost is lower than each capability independently implementing state inference or runtime-specific transcript parsing.

Alternatives considered

1. Update STATE.current_phase before planning another phase. Rejected: it falsifies project lifecycle status to steer one invocation and breaks concurrent work.
2. Infer the phase from newest artifacts, directory order, PLAN presence, or mtimes. Rejected: nondeterministic under concurrent work, preserved artifacts, clock skew, and partial writes.
3. Capability-specific sidecars/environment variables. Rejected: runtime-specific, collision-prone, stale after crashes, and duplicates plumbing in every extension.
4. Typed core invocation context. Preferred. It is deterministic, validates once at the trust boundary, and is reusable by every capability/runtime.

Decision ranking:

1. Performance — one already-known pair of scalar fields; no filesystem scan or transcript parse.
2. Simplicity/LOC — one generic seam replaces per-capability inference and sidecars.
3. Ecosystem support — runtime-neutral core field can be projected through each host adapter.
4. Maintenance — additive schema with centralized phase validation; no new dependency or persistent state.

Prior art and references

• Existing loop.render-hooks resolver: enhancement: loop.render-hooks resolver (consume the Capability Registry) — ADR-857 phase 3c #918.
• Generic-dispatch wiring defects are tracked separately in capability-validator: hook call-site check validates existence, not dispatch — a wired+enabled capability can silently never run #3606 and obs(dispatch): capability lifecycle-dispatch steps intermittently skipped (beads capability, 3/4 wave-close dispatches missed) #3647. Those issues concern whether declared hook kinds run; this proposal concerns the task-local phase value available after they run.
• Related concrete consumer bug and local explicit-phase validation seam: Lifecycle dispatch targets STATE.current_phase instead of the phase being planned davdittrich/gsd-beads#5
• Claude Code PostToolUse input contract: https://code.claude.com/docs/en/hooks#posttooluse-input
• Discussion Proposal: surface-scoped gate routing + auto-derived depth for per-phase pipelines #3837 mentions per-phase routing, but proposes surface/depth pipelines and artifact-based resume. It does not propose typed loop invocation context.

Additional context

This proposal deliberately excludes Beads-specific behavior. Beads exposed the missing generic contract, but the field belongs to core because any phase-scoped capability can otherwise target stale project state.

No gsd-core implementation or PR will be started before approved-feature.

[trek-e]

This was generated by AI during triage.

Feature Review Report — #4030 "feat(loop): carry typed phase context through lifecycle hooks"

Ask / Type / Prior art. Proposes an additive, optional context: { phase, phaseDir } field on the loop render-hooks JSON envelope and its CLI (--phase, --phase-dir), so a phase-scoped capability hook can identify the task-local phase when it differs from STATE.current_phase (e.g. planning Phase 2 while Phase 1 is still executing). Confirmed against the live source: cmdLoopRenderHooks (src/loop-resolver.cts:478-620) currently builds exactly { point, activeHooks, rendered, warnings? } with no phase field — the issue's citation of the envelope shape and line range is accurate (off by one vs. the pinned sha, immaterial). Checked the two "related but distinct" issues cited: #918 (closed) is the original resolver this issue extends — legitimate prior art, not overlap. #3606 (closed) and #3647 (open) are both about whether a wired/enabled capability's hooks actually fire (validator-vs-dispatch gaps, intermittent skip) — orthogonal to this issue's ask, which only concerns what context a hook receives once it does fire. The distinction holds. No related entry in .out-of-scope/ — the one hit (commit-gate-reuse-capability-loop-point.md) is about adding a new commit:pre loop point, unrelated to this envelope-shape proposal.

Maturity. N/A — internal architecture proposal, not a third-party integration.

Integration cost. Confirmed call sites: gsd-core/bin/gsd-tools.cjs:2587-2649 (routeLoop) hand-parses --config-dir, --active-cap, --runtime — each flag duplicates ~15 lines for the --flag value / --flag=value dual form with no shared helper. Adding --phase/--phase-dir is two more near-identical blocks in the same pattern (mechanical, low risk, but confirms no reusable arg-parsing seam exists to lean on). Downstream: plan-phase.md, execute-phase.md at the cited plan:pre/plan:post and wave points, and verify-work.md at verify:pre/verify:post all already resolve a phase number/dir before calling loop render-hooks, so the source data the new flags need already exists at every call site — the change is plumbing, not new phase-resolution logic. gsd-core/references/loop-hook-dispatch.md and tests/loop-render-hooks.test.cjs both already exist (confirmed via listing, not new files), alongside loop-host-contract.test.cjs and three loop-hook e2e suites (ship-pre, verify-post, empty-points) that would need an additional case each to prove non-omission doesn't regress. The additive/optional framing holds: every current caller that omits the new flags gets the identical existing envelope, since the new field would only be added conditionally.

Compatibility & risk. src/loop-resolver.cts is not mid-refactor — last touched 2026-07-07 (fix(#2009), fail-open warning), a stable, incrementally-extended file since #918 (2026-02, roughly, per the ADR-857 phase-3c commit chain) with no destabilizing rewrite in flight. However, the three consuming workflow files are hot: plan-phase.md and execute-phase.md were both touched 2026-08-27 (#3763) and 2026-08-25 (#3841), and verify-work.md on 2026-08-25 by #3866, which itself just added step/contribution dispatch at verify:pre — i.e., the exact call sites this issue would edit are under active, very recent development, raising ordinary merge-conflict/rebase risk (not a design risk) for whoever implements this. Separately, #3647 remains open (capability lifecycle-dispatch steps intermittently skipped) — a live reliability defect in the same dispatch pipeline this issue extends. It doesn't block this proposal (context-shape and dispatch-reliability are genuinely separate, per the Ask analysis above), but it means the extended contract will inherit a known-flaky delivery guarantee until #3647 lands. On path validation: inspected the closest existing candidate, src/gate-predicate-evaluator.cts — it consumes a phaseDir string via ${PHASE_DIR} interpolation (line 44/78-88) but performs no traversal/symlink/containment validation itself; it trusts the caller-supplied context object. No reusable "confine path to .planning/phases/<direct-child>, reject traversal/symlink escape" helper was found in the reachable modules (Memtrace's MemDB backend returned 0 indexed nodes/episodes for this repo throughout this review — a genuine backend outage, confirmed via list_indexed_repositories and get_repository_stats, not a scoping mistake — so this could not be exhaustively graph-verified beyond the modules inspected directly). Practical implication: the new validator most likely needs to be written from scratch as realpath(path.join(phasesRoot, phaseToken)) checked for prefix-containment under realpath(phasesRoot), after rejecting any phaseToken containing a path separator or .. — a small, well-understood pattern, but not a drop-in reuse.

Artifacts required. Resolver unit tests (existing tests/loop-render-hooks.test.cjs, extended), CLI arg tests, omission/backward-compat tests, and hostile-path tests (traversal, symlink escape, nonexistent path, foreign-project path) per the acceptance criteria — all automatable via gsd-test. gsd-core/references/loop-hook-dispatch.md needs an update describing how generic step/contribution handlers receive the typed context. Runtime-adapter fixture updates for at least Claude Code and Codex projection, per the issue's own acceptance criteria. An ADR is arguably warranted (this changes a core extension-point contract, and this project's own review convention treats "feature requires ADR" as a blocker for exactly this class of change) — but precedent cuts the other way: prior contract-adjacent changes to this same resolver (#1244 registry overlay, #1459 consent gating, #2009 fail-open) all shipped as regular feat/fix commits under the existing ADR-857 umbrella without a new ADR each time. Recommend the implementer confirm with maintainers whether an ADR-857 addendum note suffices or a fresh ADR is expected, rather than defaulting either way.

Architecture fork. Lens A — extend the existing generic loop.render-hooks contract with an additive field (this proposal). Lens B — n/a; this is not a monolith-vs-plugin decision, it's a scoped extension of one already-generic extension point, and the issue's own "alternatives considered" section (STATE mutation, mtime/order inference, capability-specific sidecars) already rules out the plausible competing shapes for reasons that hold up (nondeterminism, state-falsification, per-capability duplication). Lens A is the only architecturally coherent option.

Verdict: Go-with-conditions. The additive/optional framing is real and verified against the live envelope shape — no existing caller is broken by this change. The scope (resolver + CLI + 3 workflow files + docs + tests) is proportionate to a concrete, reproduced bug (davdittrich/gsd-beads#5) and matches the size of prior incremental resolver extensions. Conditions before implementation: (1) the path-validation logic must be authored fresh with explicit traversal/symlink/foreign-project test cases — there is no existing helper to reuse, so under-specifying this at PR time is the main real risk; (2) implementer should rebase onto latest next immediately before starting, given how recently and how directly plan-phase.md/execute-phase.md/verify-work.md have all been edited; (3) confirm with maintainers whether this needs a standalone ADR or an ADR-857 addendum before or during the PR, rather than deciding unilaterally.

[trek-e]

This was generated by AI during triage.

Verdict: Go-with-conditions

The Feature Review Report above verified the additive/optional framing is genuinely safe: the current resolver (cmdLoopRenderHooks, src/loop-resolver.cts:478-620) returns exactly {point, activeHooks, rendered, warnings?} with no phase field, so every existing caller that omits the new flags is provably unaffected.

Conditions to satisfy before/while implementing:

1. No reusable path-traversal/symlink-confinement helper exists in this codebase for the phaseDir validation this proposal requires (src/gate-predicate-evaluator.cts consumes a phaseDir today but never validates it). This must be authored fresh, with explicit hostile-path tests (../, symlink escape, absolute-path substitution, nonexistent paths) — do not assume an existing helper covers this.
2. Rebase immediately before starting. All three workflow call sites (plan-phase.md, execute-phase.md, verify-work.md) were edited within the last 2-4 days by other in-flight work (bug(config-get): missing --raw on several workflow config-get call sites breaks bash string comparisons #3763, enh(workflows): assert gsd-tools identity on every state-mutating verb (withdrawn half of #3146) #3841, enh(verify:pre): dispatch step + contribution hooks, not gates only — verify lane is closed to capabilities #3866) — check for conflicts before writing the phase-context plumbing.
3. Confirm ADR-vs-addendum status with the maintainer directly before writing docs — this changes a core extension-point contract, and whether it needs a full ADR or an addendum to an existing one should be settled up front, not assumed.

Approved to proceed under these conditions.