`state add-decision` persists a literal `[Phase ?]` when `--phase` is omitted, though STATE.md frontmatter carries `current_phase`

[LayerC0de]

GSD Version

1.10.0 (reproduced on next @ 86bebce; originally hit on an installed 1.6.0)

Runtime

Claude Code

Operating System

Windows

Node.js Version

v24.18.0

Shell

Git Bash

Installation Method

npx @opengsd/gsd-core

What happened?

state add-decision without --phase writes a literal - [Phase ?]: entry into
STATE.md, even when STATE.md's own frontmatter carries current_phase.

The ? is persisted. A decision entry is a permanent record, so the provenance of
that decision is lost unless a human notices the placeholder and hand-edits it.

I hit this across an 11-plan phase. Every executor agent that recorded a decision
without passing --phase produced a [Phase ?] entry, and each one hand-repaired
it — so the same defect was silently paid for eleven times. The information needed
to render it correctly was in the file being written, three lines above the
insertion point.

Root cause is a single expression at src/state.cts:835:

const entry = `- [Phase ${phase || '?'}]: ${summaryText}...`;

cmdStateAddDecision never consults frontmatter. state-command-router.cts:142
passes --phase straight through with no fallback. The codebase already has the
resolution it needs — cmdStatePruneDecisions reads fm.current_phase with a
scalar guard at src/state.cts:3111-3117 — it just isn't reused here.

What did you expect?

--phase omitted → resolve from frontmatter current_phase, so the entry reads
- [Phase 3]: ....

Explicit --phase should still win. And ? should still be written when no phase
is resolvable anywhere — an unknown phase should stay visibly unknown, never
guessed.

Steps to reproduce

mkdir -p repro/.planning && cd repro
cat > .planning/STATE.md <<'MD'
---
gsd_state_version: 1.0
current_phase: 3
current_phase_name: Sourcing Coverage
status: executing
---

# Project State

## Decisions

MD

gsd-tools state add-decision --summary "Dedup threshold set to 0.85 by sweep"
sed -n '/^## Decisions/,$p' .planning/STATE.md

Error output / logs

{
  "added": true,
  "decision": "- [Phase ?]: Dedup threshold set to 0.85 by sweep"
}

## Decisions

- [Phase ?]: Dedup threshold set to 0.85 by sweep

Expected - [Phase 3]: ... — current_phase: 3 is in the frontmatter of the very
file being written.

GSD Configuration

Not relevant — reproduces on a bare STATE.md with no config.json present.

GSD State (if relevant)

The four-line STATE.md in the repro above is sufficient.

How often does this happen?

Always

Impact

Medium — wrong output, silently persisted

Workaround (if any)

Always pass --phase explicitly, or hand-edit STATE.md afterwards. Neither
survives an agent that does not know to do it, which is the case the command is
mostly invoked from.

Additional context

This is the same family as #2400 (frontmatter/body state contradictions), which
was fixed for one writer. It may also be in scope for the #3180 epic on giving the
.planning/ semantic model a single owner — happy to close this if it is already
covered there.

I have a fix ready (three-line resolution reusing the existing scalar guard, plus
three regression tests: the fix, an explicit---phase precedence guard, and a
control asserting ? is retained when genuinely unresolvable). Full state.test.cjs
passes at 330/330. Will open a PR once this carries confirmed-bug, per
CONTRIBUTING.

Privacy Checklist

• I have removed all secrets, tokens, API keys, and credentials
• I have removed or anonymized personal/company identifying information

[trek-e]

This was generated by AI during triage.

Diagnosis

Reproduced: yes — built npm run build:lib, ran the real gsd-tools.cjs state add-decision --summary "..." (no --phase) against a scratch .planning/STATE.md with current_phase: 3 in frontmatter. Got - [Phase ?]: ..., matching the issue's claimed output exactly. Also confirmed explicit --phase still wins today, and that ? is correctly retained when no phase is resolvable anywhere.

Root cause: cmdStateAddDecision builds the decision entry from the raw --phase CLI flag only, with no fallback to STATE.md's own frontmatter, in src/state.cts:835 (function cmdStateAddDecision, src/state.cts:817-886). The flag itself is a straight pass-through with no fallback logic at src/state-command-router.cts:142. Correction to the issue: the sibling function that already does the frontmatter scalar resolution is named cmdStatePrune, not cmdStatePruneDecisions — but its cited line numbers (3111-3117, verified as 3116-3120 for the actual guard) are accurate, and the resolution pattern it demonstrates is real and reusable.

Introduced by: long-standing — traced via git blame through the ADR-457 .cjs→.cts migration to the predecessor repo, commit 77d434709d (get-shit-done/bin/lib/state.cjs, 2026-02-23). Not a recent regression.

Blast radius: Memtrace get_impact rates the raw graph radius of cmdStateAddDecision as CRITICAL (200+ affected symbols), but that's fan-out through shared low-level utilities (output, readModifyWriteStateMd, extractFrontmatter, etc.) used by every state.cts command — not risk specific to this fix. A correctly scoped fix touches one function, one file, one CLI command path; effective risk is Low.

Coupled (must not miss): the codebase already has three independent frontmatter-scalar-resolution implementations in src/state.cts — the guard inside cmdStatePrune, a nested fmScalar helper inside cmdStateSnapshot (with a longer frontmatter → body field → prose fallback chain), and buildStateFrontmatter. A fix should reuse one of these (or factor a shared helper) rather than hand-rolling a fourth divergent copy.

Regression test: behavior, not implementation — (1) frontmatter current_phase: 3, add-decision with no --phase → entry reads - [Phase 3]:; (2) same file, --phase 7 passed explicitly → entry reads - [Phase 7]: (explicit still wins); (3) no phase resolvable anywhere (no frontmatter current_phase, no body Current Phase, no prose Phase: under ## Current Position) → entry still reads - [Phase ?]:.

No recorded Memtrace decision covers the current ?-on-omitted---phase behavior as intentional — this is an oversight, not a by-design choice.

Agent Brief

Category: bug
Summary: state add-decision writes a literal [Phase ?] when --phase is omitted, even though STATE.md's own frontmatter carries a resolvable current_phase.
Current behavior: Omitting --phase on state add-decision always writes - [Phase ?]: ..., regardless of what STATE.md's frontmatter says about the current phase.
Desired behavior: When --phase is omitted, resolve the phase from STATE.md's own frontmatter (and other already-established fallback sources used elsewhere in this codebase for the same purpose) before falling back to ?. An explicitly passed --phase must always take precedence over any resolved value. When no phase is resolvable from any source, the entry must still read - [Phase ?]: — never guessed or defaulted.
Key interfaces: the state add-decision CLI command (and its underlying decision-entry-writing behavior); STATE.md's frontmatter current_phase field as a resolution source; the existing phase-resolution behavior used by state prune and state snapshot for consistency.
Acceptance criteria:

• Omitting --phase with a resolvable frontmatter current_phase produces - [Phase <value>]:, not - [Phase ?]:.
• Passing --phase explicitly always wins over any frontmatter-resolved value, with no change in current behavior.
• When no phase is resolvable from any source, the entry still reads - [Phase ?]: — never inferred, guessed, or defaulted to a number.
• Non-scalar (list/object) current_phase frontmatter values are treated as unresolvable, consistent with existing scalar-guard behavior elsewhere in the codebase.
  Out of scope: changing the resolution/fallback behavior of state prune or state snapshot; changing STATE.md's frontmatter schema; any change to how --phase itself is parsed or validated.