diff --git a/.changeset/gallant-geese-wave.md b/.changeset/gallant-geese-wave.md new file mode 100644 index 000000000..161ad1049 --- /dev/null +++ b/.changeset/gallant-geese-wave.md @@ -0,0 +1,5 @@ +--- +type: Changed +pr: 3154 +--- +**`/gsd:debug` now initializes in one round-trip instead of three** — the workflow previously made three separate `gsd-tools` calls to assemble its context (`state.load`, `resolve-model`, and `config-get workflow.tdd_mode`); it now makes a single `init.debug` call carrying the same resolved values. (#3149) diff --git a/docs/reference/workflow-fragments.md b/docs/reference/workflow-fragments.md index 3e570754a..f2c23841d 100644 --- a/docs/reference/workflow-fragments.md +++ b/docs/reference/workflow-fragments.md @@ -159,6 +159,17 @@ own dedicated `cmdInit*` entry points (`cmdInitReview`, (`cmdInitDocsUpdate`, `cmdInitUpdate`, `cmdInitTransition`) plus an extension of the pre-existing `cmdInitNewMilestone`. +An entry point can also land **ahead of** the atom it will unblock. `#3149` +gives `debug` a dedicated `cmdInitDebug` (`init.debug`) with no vocabulary +change at all: `/gsd-debug` previously made three separate `gsd_run` +round-trips and had no `cmdInit*` of its own, so gate (2) could never be +satisfied for any debug-scoped fact. Shipping the entry point first satisfies +gate (2) on its own schedule and leaves gate (1) — a consuming section of at +least 400 bytes — to the change that actually adds the section. `debug` has no +`` markers yet, so it contributes no key to +`section-manifest.json` and `init.debug`'s `section_manifest` field degrades to +`null` (read everything) until it does. + ### Compound conditions are resolved in the fact, never the grammar `state:chunked-mode` looks, at the section-body level, like it should be a diff --git a/gsd-core/workflows/debug.md b/gsd-core/workflows/debug.md index d84d8866b..497c24653 100644 --- a/gsd-core/workflows/debug.md +++ b/gsd-core/workflows/debug.md @@ -17,24 +17,21 @@ Valid GSD subagent types (use exact names — do not fall back to 'general-purpo ```bash _GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi -INIT=$(gsd_run query state.load) +INIT=$(gsd_run query init.debug) if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi ``` -Extract `commit_docs` and `config.response_language` from init JSON. Extract `debug_dir` from init JSON — an absolute path anchored on `project_root` (#2376: `debug_file_path` values handed to the spawned `gsd-debug-session-manager` must resolve regardless of that subagent's own cwd, which may differ from the orchestrator's — build them as `{debug_dir}/{slug}.md`, never a bare `.planning/debug/...` literal). +One round-trip carries everything this workflow needs (#3149 — this call replaces the former `state.load` + `resolve-model` + `config-get` trio). Extract from init JSON: + +- `commit_docs` — whether planning docs are committed. +- `response_language` — TOP-LEVEL field, present ONLY when configured. Absent means English; absence is not a degraded read. +- `debug_dir` — an absolute path anchored on `project_root` (#2376: `debug_file_path` values handed to the spawned `gsd-debug-session-manager` must resolve regardless of that subagent's own cwd, which may differ from the orchestrator's — build them as `{debug_dir}/{slug}.md`, never a bare `.planning/debug/...` literal). +- `debugger_model` — the resolved model for `gsd-debugger` spawns; used as `{debugger_model}` below and governed by the model-omission rule in step 2. +- `tdd_mode` — used as `{TDD_MODE}` in the session parameter blocks below. +- `section_manifest` — `null` today, because this workflow declares no applicability-section markers of its own. **When it is `null`, read this workflow in full.** When it is present, read only the files named in its `read` array. `null` and an empty `included` array are NOT the same: `null` means "no manifest for this workflow", an empty `included` means "nothing applies". **If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated. -Resolve debugger model: -```bash -debugger_model=$(gsd_run query resolve-model gsd-debugger --pick model 2>/dev/null || true) -``` - -Read TDD mode from config: -```bash -TDD_MODE=$(gsd_run query config-get workflow.tdd_mode --raw 2>/dev/null || echo "false") -``` - ## 1a. LIST subcommand When SUBCMD=list: diff --git a/scripts/lint-test-file-count.allowlist.json b/scripts/lint-test-file-count.allowlist.json index 15c2ede9d..358e4a13f 100644 --- a/scripts/lint-test-file-count.allowlist.json +++ b/scripts/lint-test-file-count.allowlist.json @@ -22,6 +22,15 @@ ], "issue": "622" }, + "init": { + "files": [ + "init-debug-workflow-contract.test.cjs", + "init-debug.test.cjs", + "init-manager.test.cjs", + "init.test.cjs" + ], + "issue": "3149" + }, "milestone": { "files": [ "milestone-archive.test.cjs", diff --git a/src/command-aliases.cts b/src/command-aliases.cts index d95785ec9..4babab2bc 100644 --- a/src/command-aliases.cts +++ b/src/command-aliases.cts @@ -448,6 +448,14 @@ export const INIT_COMMAND_ALIASES: CommandAlias[] = [ "subcommand": "transition", "mutation": false }, + { + "canonical": "init.debug", + "aliases": [ + "init debug" + ], + "subcommand": "debug", + "mutation": false + }, { "canonical": "init.new-workspace", "aliases": [ diff --git a/src/init-command-router.cts b/src/init-command-router.cts index 03f578266..2aee51368 100644 --- a/src/init-command-router.cts +++ b/src/init-command-router.cts @@ -47,6 +47,7 @@ interface InitModule { cmdInitDocsUpdate(cwd: string, raw: boolean, options?: Record): void; cmdInitUpdate(cwd: string, raw: boolean, options?: Record): void; cmdInitTransition(cwd: string, raw: boolean, options?: Record): void; + cmdInitDebug(cwd: string, raw: boolean, options?: Record): void; cmdInitNewWorkspace(cwd: string, raw: boolean): void; cmdInitListWorkspaces(cwd: string, raw: boolean): void; cmdInitRemoveWorkspace(cwd: string, name: string | undefined, raw: boolean): void; @@ -171,6 +172,10 @@ function routeInitCommand({ init, args, cwd, raw, error }: RouteInitCommandOptio init.cmdInitUpdate(cwd, raw, { next: namedArgs['next'], rc: namedArgs['rc'] }); }, transition: () => init.cmdInitTransition(cwd, raw, {}), + debug: () => { + const namedArgs = parseNamedArgs(args, [], ['diagnose']); + init.cmdInitDebug(cwd, raw, { diagnose: namedArgs['diagnose'] }); + }, 'new-workspace': () => init.cmdInitNewWorkspace(cwd, raw), 'list-workspaces': () => init.cmdInitListWorkspaces(cwd, raw), 'remove-workspace': () => init.cmdInitRemoveWorkspace(cwd, args[2], raw), diff --git a/src/init.cts b/src/init.cts index b642fb690..bd3f45fe0 100644 --- a/src/init.cts +++ b/src/init.cts @@ -2690,6 +2690,68 @@ function cmdInitTransition(cwd: string, raw: boolean, options: Record = {}): void { + const config = loadConfig(cwd); + const wf = (config.workflow ?? {}) as Record; + + const result: Record = { + commit_docs: config.commit_docs, + // #2376: absolute — debug.md builds `debug_file_path` as + // `{debug_dir}/{slug}.md` for its gsd-debug-session-manager spawns, whose + // own cwd may differ from the orchestrator's. + debug_dir: toPosixPath(planningPaths(cwd).debug), + debugger_model: resolveModelInternal(cwd, 'gsd-debugger'), + tdd_mode: Boolean(wf['tdd_mode']), + diagnose: options['diagnose'] === true, + }; + + // Additive, optional field — degrades to null while `debug` has no key in + // `gsd-core/workflows/section-manifest.json` (it has no `gsd:section` markers + // until #3128). null means "read everything", which is NOT the same as a + // computed empty selection. + result['section_manifest'] = buildSectionManifestField(cwd, null, options, 'debug', {}); + + output(withProjectRoot(cwd, result), raw); +} + function cmdInitProgress(cwd: string, raw: boolean, options: Record = {}): void { try { (pruneOrphanedWorktrees as (cwd: string) => void)(cwd); @@ -3708,6 +3770,7 @@ export = { cmdInitDocsUpdate, cmdInitUpdate, cmdInitTransition, + cmdInitDebug, cmdInitNewWorkspace, cmdInitListWorkspaces, cmdInitRemoveWorkspace, diff --git a/src/planning-workspace.cts b/src/planning-workspace.cts index b64ab47fd..ef3502883 100644 --- a/src/planning-workspace.cts +++ b/src/planning-workspace.cts @@ -166,6 +166,7 @@ interface PlanningPaths { config: string; phases: string; requirements: string; + debug: string; } function planningPaths(cwd: string, ws?: string | null): PlanningPaths { @@ -178,6 +179,10 @@ function planningPaths(cwd: string, ws?: string | null): PlanningPaths { config: path.join(base, 'config.json'), phases: path.join(base, 'phases'), requirements: path.join(base, 'REQUIREMENTS.md'), + // #3149: the debug-session directory. Single source for both `state.load`'s + // `debug_dir` field and `init.debug`'s — previously each composed its own + // `path.join(planning, 'debug')` (DEFECT.GENERATIVE-FIX). + debug: path.join(base, 'debug'), }; } diff --git a/src/state.cts b/src/state.cts index b8e84bb3d..803db8439 100644 --- a/src/state.cts +++ b/src/state.cts @@ -335,7 +335,8 @@ const STOP_H2_ONLY = (lv: number): boolean => lv === 2; function cmdStateLoad(cwd: string, raw: boolean): void { const config = loadConfig(cwd); - const planDir = planningPaths(cwd).planning; + const paths = planningPaths(cwd); + const planDir = paths.planning; const stateRaw = platformReadSync(path.join(planDir, 'STATE.md')) || ''; @@ -351,10 +352,12 @@ function cmdStateLoad(cwd: string, raw: boolean): void { config_exists: configExists, // #2376: absolute (anchored on cwd), not orchestrator-cwd-relative — a // spawned subagent's own cwd may differ from the orchestrator's. - // debug.md has no init.* call of its own; it reads this field from - // `state load` to build debug_file_path for its gsd-debug-session-manager - // spawns instead of hardcoding '.planning/debug/{slug}.md'. - debug_dir: toPosixPath(path.join(planDir, 'debug')), + // #3149: debug.md now has its own `init.debug` entry point and reads this + // field from there, not from `state load`. This stays on the state.load + // bundle regardless: it is a shipped query surface with its own test anchor + // (tests/state.test.cjs), so narrowing it would break unseen consumers for + // no gain (Hyrum's Law). Both emit the SAME `planningPaths(cwd).debug`. + debug_dir: toPosixPath(paths.debug), }; // For --raw, output a condensed key=value format diff --git a/tests/debug-session-management.test.cjs b/tests/debug-session-management.test.cjs index 8936cf72d..29e450b1f 100644 --- a/tests/debug-session-management.test.cjs +++ b/tests/debug-session-management.test.cjs @@ -76,13 +76,21 @@ describe('debug session management implementation', () => { path.join(process.cwd(), 'gsd-core/workflows/debug.md'), 'utf8' ); + // #3149: tdd_mode now arrives on the `init.debug` bundle rather than a + // `config-get` call in this workflow, so the old literal-call assertion no + // longer describes reality. The invariant it protected is unchanged and is + // asserted at its new home: `cmdInitDebug` resolves `config.workflow`'s + // `tdd_mode`, never a bare top-level key — proven behaviorally in + // tests/init-debug.test.cjs ('honors workflow.tdd_mode, ignores a bare + // top-level tdd_mode'). What must remain true HERE is only that this + // workflow never reintroduces a bare-key read of its own. assert.ok( !content.includes('config-get tdd_mode'), 'debug.md must not use bare "tdd_mode" key — use "workflow.tdd_mode" to match every other consumer' ); assert.ok( - content.includes('config-get workflow.tdd_mode'), - 'debug.md must read tdd_mode via the "workflow.tdd_mode" key' + content.includes('tdd_mode'), + 'debug.md must still consume tdd_mode (now from the init.debug bundle)' ); }); diff --git a/tests/emitted-drift-acks/3149-init-debug-entry-point.json b/tests/emitted-drift-acks/3149-init-debug-entry-point.json new file mode 100644 index 000000000..3612e2f6f --- /dev/null +++ b/tests/emitted-drift-acks/3149-init-debug-entry-point.json @@ -0,0 +1,6 @@ +{ + "version": 1, + "paths": { + "debug.md": "#3149 (prerequisite for #3128, ADR-1671 admission gate 2): debug.md gains a dedicated `init.debug` entry point (cmdInitDebug) and its Step 0 collapses THREE separate `gsd_run` round-trips into one. Removed: `gsd_run query state.load` (line 20, replaced in place), the `resolve-model gsd-debugger --pick model` block, and the `config-get workflow.tdd_mode --raw` block — 2 prose lead-ins and 2 fenced code blocks in total. Added: a 6-bullet extraction list documenting the bundle's fields (`commit_docs`, the now TOP-LEVEL `response_language`, `debug_dir`, `debugger_model`, `tdd_mode`, `section_manifest`) plus the `section_manifest: null` -> read-everything rule and the null-vs-empty-included distinction. Net SOURCE growth is +618 bytes (20,555 -> 21,173): the bullets that document one bundle cost more bytes than the two shell round-trips they replace, which is the intended trade — the round-trips cost three subprocess spawns at RUN time on every /gsd:debug invocation. No applicability-section marker is added and WHEN_VOCABULARY is unchanged at 29, so the composeWorkflow emission path is byte-identical in shape to before; only this file's own content moved. The `{TDD_MODE}` and `{debugger_model}` placeholders in the session-parameter blocks (lines ~137-145, ~226-234) are deliberately left byte-identical — they now resolve from the init bundle instead of shell variables, and rewording them would ripple into tests/fix-2257-debug-nonterminal-resume.test.cjs and tests/debug-session-manager-commit.test.cjs for no behavioral gain." + } +} diff --git a/tests/init-debug-workflow-contract.test.cjs b/tests/init-debug-workflow-contract.test.cjs new file mode 100644 index 000000000..4436deead --- /dev/null +++ b/tests/init-debug-workflow-contract.test.cjs @@ -0,0 +1,87 @@ +// allow-test-rule: source-text-is-the-product (see #3149) +// gsd-core/workflows/debug.md is shipped prompt content: the text IS what the +// runtime loads, so its Step 0 contract can only be asserted against the text. +// The behavioral half of this change lives in tests/init-debug.test.cjs, which +// carries no exemption. + +'use strict'; + +/** + * `debug.md` Step 0 contract after the `init.debug` consolidation (#3149). + * + * Matrix: `.gsd/phase/feat-3149-cmdinitdebug/50-test-matrix.md` group F. + * + * Guards the four ways this consolidation can silently regress: + * F1/F2 — a replaced round-trip creeping back, or the new one being lost. + * F3 — reading `config.response_language` (the nested state.load shape) + * instead of the flat top-level field withProjectRoot injects. This + * is the #2402 defect class: the workflow silently stays English. + * F4 — losing the `@file:` unwrap, which large init payloads still need. + * F5 — dropping the `section_manifest: null` -> read-everything rule, + * without which a null manifest reads as "read nothing". + */ + +const { describe, test } = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('fs'); +const path = require('path'); + +const WORKFLOW_PATH = path.join(__dirname, '..', 'gsd-core', 'workflows', 'debug.md'); +const workflow = fs.readFileSync(WORKFLOW_PATH, 'utf-8'); + +/** Every `gsd_run query ` invocation in the workflow, in document order. */ +function queryInvocations(text) { + return [...text.matchAll(/gsd_run query ([\w.-]+)/g)].map((m) => m[1]); +} + +describe('debug.md Step 0 init contract (#3149, matrix §F)', () => { + test('calls init.debug exactly once (row F1)', () => { + const initDebugCalls = queryInvocations(workflow).filter((q) => q === 'init.debug'); + assert.equal(initDebugCalls.length, 1, 'exactly one init.debug round-trip'); + }); + + test('no longer makes the three replaced calls (row F2)', () => { + const queries = queryInvocations(workflow); + + assert.equal(queries.includes('state.load'), false, 'state.load is replaced by init.debug'); + assert.equal( + workflow.includes('resolve-model gsd-debugger'), + false, + 'debugger_model now rides the init bundle' + ); + assert.equal( + workflow.includes('config-get workflow.tdd_mode'), + false, + 'tdd_mode now rides the init bundle' + ); + }); + + test('reads the flat response_language, not the nested state.load shape (row F3)', () => { + assert.equal( + workflow.includes('config.response_language'), + false, + 'withProjectRoot injects response_language at the TOP level; reading config.response_language ' + + 'against an init bundle resolves undefined and silently drops translated output (#2402)' + ); + assert.ok( + workflow.includes('`response_language`'), + 'the field is still documented, just at its new location' + ); + }); + + test('still unwraps an @file: payload (row F4)', () => { + assert.ok( + workflow.includes('@file:'), + 'init payloads can spill to a file; dropping the unwrap leaves INIT holding a path, not JSON' + ); + }); + + test('documents the null-manifest read-everything fallback (row F5)', () => { + assert.ok(workflow.includes('section_manifest'), 'the field is documented'); + assert.ok( + /`null`[^\r\n]*read this workflow in full/i.test(workflow), + 'a null section_manifest must be documented as "read everything" — without the rule, ' + + 'a null manifest reads as an empty selection and the workflow reads nothing' + ); + }); +}); diff --git a/tests/init-debug.test.cjs b/tests/init-debug.test.cjs new file mode 100644 index 000000000..2c6d5e654 --- /dev/null +++ b/tests/init-debug.test.cjs @@ -0,0 +1,470 @@ +'use strict'; + +/** + * `init.debug` — the dedicated init entry point for `/gsd:debug` (#3149). + * + * Prerequisite for #3128 condition 1: ADR-1671 admission gate (2), "a fact the + * init seam demonstrably computes at a real entry point" + * (`docs/adr/1671-dynamic-context-management-platform.md:122-131`). Before this, + * `gsd-core/workflows/debug.md` was one of the last workflows with no `cmdInit*` + * of its own, so no debug-scoped fact could ever be computed and any `when=` atom + * naming one would have evaluated FALSE forever — the silent-exclusion bug that + * rule exists to prevent. + * + * Matrix: `.gsd/phase/feat-3149-cmdinitdebug/50-test-matrix.md` groups A-E, G3. + * + * Every test drives the REAL CLI (`runGsdTools` spawns `gsd-tools.cjs`) rather + * than requiring `cmdInitDebug` directly — the handler is not exported, and the + * flag plumbing under test exists only at the `init-command-router.cjs` seam. + * Same rationale recorded in `tests/section-manifest-init-facts.test.cjs:10-14`. + * + * Group A is the load-bearing half: this change's entire claim is "one round-trip + * instead of three, with identical resolved values", so each A-row cross-checks + * `init.debug` against the exact command it replaced. + */ + +const { describe, test, beforeEach, afterEach } = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('fs'); +const path = require('path'); + +const { runGsdTools, cleanup, createTempDir, createTempProject } = require('./helpers.cjs'); + +function writeConfig(tmpDir, config, { ws = null } = {}) { + const dir = ws + ? path.join(tmpDir, '.planning', 'workstreams', ws) + : path.join(tmpDir, '.planning'); + fs.mkdirSync(dir, { recursive: true }); + fs.writeFileSync(path.join(dir, 'config.json'), JSON.stringify(config, null, 2)); +} + +/** Runs a gsd-tools query and parses its JSON, asserting a clean exit first. */ +function runJson(argv, cwd, env = {}) { + const result = runGsdTools(argv, cwd, env); + assert.ok(result.success, `Command failed: ${result.error}`); + return JSON.parse(result.output); +} + +// ─── Group A: equivalence with the three calls init.debug replaces ────────── + +describe('init.debug resolves identically to the three calls it replaces (matrix §A)', () => { + let tmpDir; + + beforeEach(() => { + tmpDir = createTempProject('init-debug-a-'); + }); + + afterEach(() => { + cleanup(tmpDir); + }); + + test('debug_dir matches state.load exactly (row A1)', () => { + const viaInit = runJson(['init', 'debug'], tmpDir); + const viaState = runJson(['query', 'state.load'], tmpDir); + + assert.equal( + viaInit.debug_dir, + viaState.debug_dir, + 'init.debug must resolve the same debug directory state.load does — debug.md builds ' + + 'debug_file_path from it (#2376) and a divergence silently writes sessions elsewhere' + ); + }); + + test('debug_dir agrees with state.load under an active workstream (row A2)', () => { + fs.mkdirSync(path.join(tmpDir, '.planning', 'workstreams', 'ws1'), { recursive: true }); + + const viaInit = runJson(['init', 'debug'], tmpDir, { GSD_WORKSTREAM: 'ws1' }); + const viaState = runJson(['query', 'state.load'], tmpDir, { GSD_WORKSTREAM: 'ws1' }); + + assert.equal(viaInit.debug_dir, viaState.debug_dir); + assert.match( + viaInit.debug_dir, + /\/workstreams\/ws1\/debug$/, + 'an active workstream must scope debug_dir into that workstream, not the project root' + ); + }); + + test('commit_docs matches state.load (row A3)', () => { + writeConfig(tmpDir, { planning: { commit_docs: false } }); + + const viaInit = runJson(['init', 'debug'], tmpDir); + const viaState = runJson(['query', 'state.load'], tmpDir); + + assert.equal(viaInit.commit_docs, viaState.config.commit_docs); + assert.equal(viaInit.commit_docs, false, 'sanity: the configured value, not the default'); + }); + + test('response_language matches state.load config (row A4)', () => { + writeConfig(tmpDir, { response_language: 'es' }); + + const viaInit = runJson(['init', 'debug'], tmpDir); + const viaState = runJson(['query', 'state.load'], tmpDir); + + assert.equal(viaInit.response_language, viaState.config.response_language); + assert.equal(viaInit.response_language, 'es'); + }); + + test('debugger_model matches the resolve-model query (row A5)', () => { + const viaInit = runJson(['init', 'debug'], tmpDir); + const viaResolve = runJson(['query', 'resolve-model', 'gsd-debugger'], tmpDir); + + assert.equal( + viaInit.debugger_model, + viaResolve.model, + 'debug.md omits the model param when this is empty or "inherit" (#2517) — the value ' + + 'must be the same one resolve-model produced, not a re-derived default' + ); + }); + + test('tdd_mode matches config-get when set (row A6)', () => { + writeConfig(tmpDir, { workflow: { tdd_mode: true } }); + + const viaInit = runJson(['init', 'debug'], tmpDir); + const viaConfigGet = runGsdTools(['query', 'config-get', 'workflow.tdd_mode', '--raw'], tmpDir); + + assert.ok(viaConfigGet.success); + assert.equal(viaInit.tdd_mode, true); + assert.equal(String(viaInit.tdd_mode), viaConfigGet.output.trim()); + }); + + test('tdd_mode matches config-get when the key is absent (row A7)', () => { + writeConfig(tmpDir, {}); + + const viaInit = runJson(['init', 'debug'], tmpDir); + const viaConfigGet = runGsdTools(['query', 'config-get', 'workflow.tdd_mode', '--raw'], tmpDir); + + assert.equal(viaInit.tdd_mode, false); + assert.equal(String(viaInit.tdd_mode), viaConfigGet.output.trim()); + }); + + test('tdd_mode matches config-get under workstream inheritance (row A8)', () => { + // The one case where the two resolution paths could genuinely disagree: + // `config-get` inherits from the ROOT config when an active workstream has + // no config.json of its own (#2702, src/config.cts), while the init seam + // reads loadConfig's root+workstream merge (src/config-loader.cts). Both + // must land on the same boolean or the consolidation changes behavior for + // workstream users. + writeConfig(tmpDir, { workflow: { tdd_mode: true } }); + fs.mkdirSync(path.join(tmpDir, '.planning', 'workstreams', 'ws1'), { recursive: true }); + + const viaInit = runJson(['init', 'debug'], tmpDir, { GSD_WORKSTREAM: 'ws1' }); + const viaConfigGet = runGsdTools( + ['query', 'config-get', 'workflow.tdd_mode', '--raw'], + tmpDir, + { GSD_WORKSTREAM: 'ws1' } + ); + + assert.equal(viaInit.tdd_mode, true, 'the root value must be inherited, not lost'); + assert.equal(String(viaInit.tdd_mode), viaConfigGet.output.trim()); + }); + + test('honors workflow.tdd_mode, ignores a bare top-level tdd_mode (row A9)', () => { + // The invariant tests/debug-session-management.test.cjs used to guard by + // grepping debug.md for `config-get workflow.tdd_mode`. Asserted here + // behaviorally instead, which is strictly stronger: a bare top-level key + // must NOT be honored, whatever the read mechanism. + writeConfig(tmpDir, { tdd_mode: true }); + assert.equal( + runJson(['init', 'debug'], tmpDir).tdd_mode, + false, + 'a bare top-level tdd_mode key must be ignored — the canonical key is workflow.tdd_mode' + ); + + writeConfig(tmpDir, { workflow: { tdd_mode: true } }); + assert.equal( + runJson(['init', 'debug'], tmpDir).tdd_mode, + true, + 'the canonical workflow.tdd_mode key must be honored' + ); + }); +}); + +// ─── Group B: bundle shape ───────────────────────────────────────────────── + +describe('init.debug bundle shape (matrix §B)', () => { + let tmpDir; + + beforeEach(() => { + tmpDir = createTempProject('init-debug-b-'); + }); + + afterEach(() => { + cleanup(tmpDir); + }); + + test('emits the documented field set (row B1)', () => { + const output = runJson(['init', 'debug'], tmpDir); + + for (const key of ['project_root', 'debug_dir', 'commit_docs', 'debugger_model', 'tdd_mode', 'diagnose']) { + assert.ok( + Object.prototype.hasOwnProperty.call(output, key), + `init.debug must emit "${key}"` + ); + } + assert.ok( + Object.prototype.hasOwnProperty.call(output, 'section_manifest'), + 'section_manifest must be present even when it degrades to null' + ); + }); + + test('omits response_language entirely when unset (row B2)', () => { + writeConfig(tmpDir, {}); + const output = runJson(['init', 'debug'], tmpDir); + + assert.equal( + Object.prototype.hasOwnProperty.call(output, 'response_language'), + false, + 'withProjectRoot injects response_language ONLY when configured — an absent key means ' + + '"English", and emitting null/"" instead would make absence look like a degraded read' + ); + }); + + test('debug_dir is an absolute POSIX path (row B3)', () => { + const output = runJson(['init', 'debug'], tmpDir); + + assert.equal(output.debug_dir.includes('\\'), false, 'no backslash separators (#2376)'); + assert.ok(output.debug_dir.endsWith('/debug'), 'points at the debug directory'); + assert.notEqual(output.debug_dir, 'debug'); + assert.notEqual(output.debug_dir, '.planning/debug', 'must be absolute, never a bare relative literal'); + }); + + test('succeeds with no .planning directory (row B4)', () => { + const bare = createTempDir('init-debug-bare-'); + try { + const result = runGsdTools(['init', 'debug'], bare); + assert.ok(result.success, `must not require an initialized project: ${result.error}`); + const output = JSON.parse(result.output); + assert.ok(output.debug_dir.endsWith('/debug')); + } finally { + cleanup(bare); + } + }); + + test('succeeds on an empty config object (row B5)', () => { + writeConfig(tmpDir, {}); + const output = runJson(['init', 'debug'], tmpDir); + assert.equal(output.tdd_mode, false); + }); + + test('survives valid-JSON-not-an-object config (row B6)', () => { + // Valid JSON that is not an object is the input class nobody enumerates: + // every one of these parses cleanly and then fails on property access. + for (const body of ['0', '"str"', '[]', 'null', 'true']) { + fs.mkdirSync(path.join(tmpDir, '.planning'), { recursive: true }); + fs.writeFileSync(path.join(tmpDir, '.planning', 'config.json'), body); + + const result = runGsdTools(['init', 'debug'], tmpDir); + assert.ok(result.success, `config.json = ${body} must degrade, not crash: ${result.error}`); + const output = JSON.parse(result.output); + assert.equal(output.tdd_mode, false, `config.json = ${body} must resolve tdd_mode to false`); + assert.ok(output.debug_dir.endsWith('/debug')); + } + }); + + test('survives a present-but-empty config file (row B7)', () => { + fs.mkdirSync(path.join(tmpDir, '.planning'), { recursive: true }); + fs.writeFileSync(path.join(tmpDir, '.planning', 'config.json'), ''); + + const result = runGsdTools(['init', 'debug'], tmpDir); + assert.ok(result.success, `an empty config file must degrade, not crash: ${result.error}`); + assert.equal(JSON.parse(result.output).tdd_mode, false); + }); + + test('is insensitive to CRLF in config.json (row B8)', () => { + fs.mkdirSync(path.join(tmpDir, '.planning'), { recursive: true }); + fs.writeFileSync( + path.join(tmpDir, '.planning', 'config.json'), + '{\r\n "workflow": {\r\n "tdd_mode": true\r\n }\r\n}\r\n' + ); + + const output = runJson(['init', 'debug'], tmpDir); + assert.equal(output.tdd_mode, true, 'CRLF must not change how the config parses'); + }); +}); + +// ─── Group C: --diagnose forwarding + CLI negative matrix ────────────────── + +describe('init.debug --diagnose forwarding and hostile argv (matrix §C)', () => { + let tmpDir; + + beforeEach(() => { + tmpDir = createTempProject('init-debug-c-'); + }); + + afterEach(() => { + cleanup(tmpDir); + }); + + test('--diagnose surfaces as diagnose:true (row C1)', () => { + const output = runJson(['init', 'debug', '--diagnose'], tmpDir); + assert.equal(output.diagnose, true); + }); + + test('absent --diagnose is false, not undefined (row C2)', () => { + const output = runJson(['init', 'debug'], tmpDir); + assert.equal(output.diagnose, false); + assert.notEqual(output.diagnose, undefined, 'parseNamedArgs materializes false; never leak undefined'); + }); + + test('duplicate --diagnose is idempotent (row C3)', () => { + const output = runJson(['init', 'debug', '--diagnose', '--diagnose'], tmpDir); + assert.equal(output.diagnose, true); + }); + + test('ignores an unrecognized flag (row C4)', () => { + const result = runGsdTools(['init', 'debug', '--nope'], tmpDir); + assert.ok(result.success, `an unknown flag must not fail the command: ${result.error}`); + const output = JSON.parse(result.output); + assert.equal(output.diagnose, false); + }); + + test('survives a flag-shaped trailing token (row C5)', () => { + const result = runGsdTools(['init', 'debug', '--diagnose', '--weird'], tmpDir); + assert.ok(result.success, `must not crash on a flag-shaped token: ${result.error}`); + assert.equal(JSON.parse(result.output).diagnose, true); + }); + + test('does not interpolate shell metacharacters (row C6)', () => { + const canary = path.join(tmpDir, 'PWNED'); + const hostile = `; touch ${canary}; $(touch ${canary}) \`touch ${canary}\` && touch ${canary}`; + + const result = runGsdTools(['init', 'debug', hostile], tmpDir); + + assert.ok(result.success, `hostile argv must not fail the command: ${result.error}`); + assert.equal(fs.existsSync(canary), false, 'no shell interpolation of an attacker-controlled argument'); + assert.equal(result.output.includes(' at '), false, 'no stack trace in non-debug output'); + }); + + test('survives a very long argument (row C7/C8)', () => { + const long = 'x'.repeat(8192); + const unicode = 'ünïcødé-🐛-测试'; + + for (const arg of [long, unicode]) { + const result = runGsdTools(['init', 'debug', arg], tmpDir); + assert.ok(result.success, `argument of length ${arg.length} must not crash: ${result.error}`); + assert.equal(JSON.parse(result.output).diagnose, false); + } + }); +}); + +// ─── Group D: section_manifest, null vs [] ───────────────────────────────── + +describe('init.debug section_manifest degradation (matrix §D)', () => { + let tmpDir; + let manifestDir; + + beforeEach(() => { + tmpDir = createTempProject('init-debug-d-'); + manifestDir = createTempDir('init-debug-d-manifest-'); + }); + + afterEach(() => { + cleanup(tmpDir); + cleanup(manifestDir); + }); + + function withManifest(body) { + const manifestPath = path.join(manifestDir, 'manifest.json'); + fs.writeFileSync(manifestPath, typeof body === 'string' ? body : JSON.stringify(body)); + return { GSD_SECTION_MANIFEST: manifestPath }; + } + + test('section_manifest is null while debug has no manifest key (row D1)', () => { + // Drives the SHIPPED artifact deliberately: `debug` carries no gsd:section + // markers until #3128, so the shipped manifest has no `debug` key and the + // field must degrade to null — which debug.md reads as "read everything". + const output = runJson(['init', 'debug'], tmpDir); + assert.equal(output.section_manifest, null); + }); + + test('an explicit empty debug key computes [], not null (row D2)', () => { + const output = runJson(['init', 'debug'], tmpDir, withManifest({ workflows: { debug: [] } })); + + assert.notEqual(output.section_manifest, null, 'a present key must never collapse to the degraded value'); + assert.deepEqual(output.section_manifest.included, []); + assert.deepEqual(output.section_manifest.excluded, []); + }); + + test('selects an always-section for the debug workflow (row D3)', () => { + // Proves the workflow key really is 'debug' — a handler passing the wrong + // name would silently return null forever and look identical to D1. + const output = runJson(['init', 'debug'], tmpDir, withManifest({ + workflows: { + debug: [{ id: 'probe-protocol', when: 'always', read: 'gsd-core/workflows/debug/steps/probe-protocol.md' }], + }, + })); + + assert.notEqual(output.section_manifest, null); + assert.equal(output.section_manifest.workflow, 'debug'); + assert.deepEqual(output.section_manifest.included, ['probe-protocol']); + assert.deepEqual(output.section_manifest.read, ['gsd-core/workflows/debug/steps/probe-protocol.md']); + }); + + test('a missing manifest file degrades to null (row D4)', () => { + const missing = path.join(manifestDir, 'does-not-exist.json'); + assert.equal(fs.existsSync(missing), false, 'sanity: file must not exist'); + + const result = runGsdTools(['init', 'debug'], tmpDir, { GSD_SECTION_MANIFEST: missing }); + assert.ok(result.success, `a missing manifest must not crash: ${result.error}`); + assert.equal(JSON.parse(result.output).section_manifest, null); + }); + + test('a malformed manifest degrades to null (row D5)', () => { + const result = runGsdTools(['init', 'debug'], tmpDir, withManifest('{ not json')); + assert.ok(result.success, `a malformed manifest must not crash: ${result.error}`); + assert.equal(JSON.parse(result.output).section_manifest, null); + }); + + test('a pre-6.1 flat manifest shape degrades to null (row D6)', () => { + // The pre-#2992 shape had no workflow key at all. Accepting it would + // mis-attribute some other workflow's sections to debug. + const result = runGsdTools(['init', 'debug'], tmpDir, withManifest({ sections: [{ id: 'x', when: 'always' }] })); + assert.ok(result.success); + assert.equal(JSON.parse(result.output).section_manifest, null); + }); +}); + +// ─── Group E: PlanningPaths.debug ────────────────────────────────────────── + +describe('planningPaths exposes the debug directory (matrix §E)', () => { + const { planningPaths } = require('../gsd-core/bin/lib/planning-workspace.cjs'); + let tmpDir; + + beforeEach(() => { + tmpDir = createTempDir('init-debug-e-'); + }); + + afterEach(() => { + cleanup(tmpDir); + }); + + test('planningPaths exposes debug (row E1)', () => { + assert.equal(planningPaths(tmpDir).debug, path.join(tmpDir, '.planning', 'debug')); + }); + + test('planningPaths.debug is workstream-scoped (row E2)', () => { + assert.equal( + planningPaths(tmpDir, 'feature-x').debug, + path.join(tmpDir, '.planning', 'workstreams', 'feature-x', 'debug') + ); + }); + + test('planningPaths.debug does not weaken the traversal guard (row E4)', () => { + assert.throws(() => planningPaths(tmpDir, '../../etc'), /invalid path characters/); + assert.throws(() => planningPaths(tmpDir, 'foo/bar'), /invalid path characters/); + }); +}); + +// ─── Group G: regressions this change must not cause ─────────────────────── + +describe('init.debug does not widen the applicability grammar (matrix §G)', () => { + test('WHEN_VOCABULARY is unchanged at 29 entries (row G3)', () => { + // ADR-1671: the vocabulary is CLOSED and widening it is a coordinated + // amendment. This PR delivers admission gate (2) only — the atom that + // consumes it belongs to #3128, which owns the amendment. + const { WHEN_VOCABULARY } = require('../gsd-core/bin/lib/workflow-fragments.cjs'); + assert.equal(WHEN_VOCABULARY.length, 29); + assert.equal(WHEN_VOCABULARY.includes('flag:--diagnose'), false); + assert.equal(WHEN_VOCABULARY.includes('flag:--runtime-probes'), false); + }); +});