From 44170d67916dc80a008803f7b3f7cbf7dbe32ea7 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Wed, 18 Nov 2026 16:47:07 +0800 Subject: [PATCH] Unattended /autoplan on Claude Code says its phase guard is on, and a report hidden in reasoning gets a clear fix (GST-3062) (#4481) An unattended /autoplan run on Claude Code now says its phase guard is on, instead of saying it is off while the guard blocks it. A phase report written only in reasoning now gets a denial that says so and names the exact command to send. Why: in the day-one eval, two runs were blocked by a guard their own record called off, and one run ended blocked after four publish attempts whose report was invisible. Nothing to do. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- autoplan/bin/guard-reasons.ts | 11 ++- autoplan/bin/phase-publication-hook.ts | 10 ++- bin/gstack-doctor-components.sh | 1 + bin/gstack-skill-start | 20 +++-- .../autoplan-guard-says-when-it-is-on.md | 2 + docs/autoplan-guard-troubleshooting.md | 17 +++- docs/troubleshooting.md | 29 +++++-- docs/unattended.md | 15 ++-- lib/autoplan-export.ts | 2 +- lib/autoplan-guard-status.ts | 29 +++++++ lib/autoplan-run.ts | 3 +- lib/headless-artifacts.ts | 4 +- lib/result-codes-autoplan.ts | 8 +- lib/result-codes.ts | 4 +- test/autoplan-publication-payload.test.ts | 4 +- test/autoplan-publication-visible.test.ts | 84 +++++++++++++++++++ test/gstack-skill-start.test.ts | 17 ++++ test/headless-artifacts.test.ts | 16 ++++ test/helpers/autoplan-run-fixture.ts | 2 + 19 files changed, 244 insertions(+), 34 deletions(-) create mode 100644 changelog.d/autoplan-guard-says-when-it-is-on.md create mode 100644 lib/autoplan-guard-status.ts create mode 100644 test/autoplan-publication-visible.test.ts diff --git a/autoplan/bin/guard-reasons.ts b/autoplan/bin/guard-reasons.ts index ad143c2d5..e61500132 100644 --- a/autoplan/bin/guard-reasons.ts +++ b/autoplan/bin/guard-reasons.ts @@ -18,8 +18,11 @@ interface Reason { disposition: Disposition; text: (d: Detail) => string } export const FALLBACK = 'Fallback: run /plan-ceo-review, then /plan-devex-review, then /plan-eng-review by hand; ' + 'or run /context-save, start a new Claude Code session (not --resume), run /context-restore, then /autoplan .'; -const PUBLISH_SEPARATELY = (d: Detail) => `Publish the filled Phase ${d.phase} report as your own parent assistant text in a message ` + - `whose only tool call is the Bash no-op \`true autoplan-published \`, then make this phase-entry call in a later message.`; +const PHASE_NAME: Record = { 1: 'ceo', 2: 'design', 2.5: 'dx', 3: 'eng' }; +const PUBLISH_SEPARATELY = (d: Detail) => `Next step: send one message whose visible text is the filled Phase ${d.phase} report, ` + + `starting with the line **Phase ${d.phase} complete.**, and whose only tool call is the Bash no-op ` + + `\`true autoplan-published ${PHASE_NAME[String(d.phase)] ?? ''}\`. A report written only in reasoning (thinking) is not visible ` + + 'and does not count. Then make this phase-entry call in a later message.'; export const REASONS = { // Journal ownership (lib/claude-public-transcript.ts OwnedTranscriptReason). @@ -68,7 +71,9 @@ export const REASONS = { close_stale: { disposition: 'corrective', text: d => `${d.cause}. Finish the existing close procedure with a fresh packet.` }, close_edits: { disposition: 'corrective', text: d => `${d.cause}. Repeat the existing close procedure.` }, mutation_pending: { disposition: 'transient', text: () => 'An active-plan mutation is pending after the close Read. Wait for its result, then verify the current close input.' }, - publication_missing: { disposition: 'corrective', text: d => `Publish the filled Phase ${d.phase} report as your own parent assistant text now. The close packet or a saved report does not publish it. ` + PUBLISH_SEPARATELY(d) }, + publication_missing: { disposition: 'corrective', text: d => `Publish the filled Phase ${d.phase} report: none follows its close packet Read, and the close packet or a saved report does not publish it. ` + PUBLISH_SEPARATELY(d) }, + publication_not_visible: { disposition: 'corrective', text: d => `The Phase ${d.phase} publish message (\`true autoplan-published\`) carried no visible text, ` + + 'so no report was published. Text written in reasoning is visible to neither the user nor this guard. ' + PUBLISH_SEPARATELY(d) }, publication_unflushed: { disposition: 'corrective', text: d => `The Phase ${d.phase} report is not yet followed by a journaled record, so Claude Code may not have written it. ` + PUBLISH_SEPARATELY(d) }, publication_repeat: { disposition: 'fallback', text: d => `The Phase ${d.phase} report still cannot be verified after it was published separately once in this invocation.` }, } satisfies Record; diff --git a/autoplan/bin/phase-publication-hook.ts b/autoplan/bin/phase-publication-hook.ts index 1cb6b8347..d09e8e6b5 100644 --- a/autoplan/bin/phase-publication-hook.ts +++ b/autoplan/bin/phase-publication-hook.ts @@ -471,7 +471,15 @@ function requirePublication(phase: Phase, entryOrder: number, entered: Event[], if (current) verifyCloseEdits(entered, closeOrder, init, cwd); const reports = entered.filter((e): e is Event & { kind: 'message' } => e.kind === 'message' && e.order > closeOrder && autoplanPhaseCompletions({ status: 'ready', calls: [], assistantMessages: [e] }, 0).some(hit => hit.phase === number[phase])); - if (!reports.length) fail('publication_missing', { phase: number[phase] }); + if (!reports.length) { + // A no-op publish whose message carries no visible text published nothing: + // its report went into reasoning, which the journal never shows (GST-3062). + const noops = entered.filter(e => e.kind === 'use' && e.order > closeOrder && e.name === 'Bash' && + typeof e.input?.command === 'string' && /^\s*true\s+autoplan-published\b/.test(e.input.command)); + if (noops.length && !noops.some(use => entered.some(e => e.kind === 'message' && sameMessage(e, use)))) + fail('publication_not_visible', { phase: number[phase] }); + fail('publication_missing', { phase: number[phase] }); + } if (!flush) return; // Text in the same assistant message as a guarded call can be invisible to // PreToolUse. A report counts only when it is outside the journaled current diff --git a/bin/gstack-doctor-components.sh b/bin/gstack-doctor-components.sh index a66a19b59..3bea4d141 100644 --- a/bin/gstack-doctor-components.sh +++ b/bin/gstack-doctor-components.sh @@ -442,6 +442,7 @@ gstack_result_anchor() { OFFICE_HOURS_PROBE_REFUSED) printf '%s' 'office-hours-probe-refused' ;; TASKS_SUPERSEDE_REFUSED) printf '%s' 'tasks-supersede-refused' ;; REALITY_RECEIPT_UNRESOLVED) printf '%s' 'reality-receipt-unresolved' ;; + GUARD_ENFORCED) printf '%s' 'guard-enforced' ;; CEO_ONLY_CONFLICT) printf '%s' 'ceo-only-conflict' ;; CEO_ONLY_AFTER_INIT) printf '%s' 'ceo-only-after-init' ;; CEO_ONLY_NO_GATE) printf '%s' 'ceo-only-no-gate' ;; diff --git a/bin/gstack-skill-start b/bin/gstack-skill-start index 105c1d5c5..7bc9f2ad5 100755 --- a/bin/gstack-skill-start +++ b/bin/gstack-skill-start @@ -302,15 +302,19 @@ fi if [ "$_SESSION_KIND" = "unattended" ] && [ "$_DURABLE" = "no" ]; then echo "learnings: skipped (state root is ephemeral; set GSTACK_STATE_ROOT)" fi -# Plan B1: the autoplan publication hook executes only inside Claude Code -# (CLAUDECODE is set there; GSTACK_ACTIVE_HOST names an env-var host). On -# every other host, and in every unattended session, the hook is rendered but -# never runs, so publication order rests on the per-phase snapshot hashes. -# Claude Code's deny-on-absent behavior is untouched: this line is printed, -# never used to allow anything. B0's validator requires it in an unattended -# run's review-record.md. +# The autoplan publication guard is the PreToolUse hook the Claude render of +# autoplan/SKILL.md declares in its frontmatter. Claude Code (CLAUDECODE is +# set there; GSTACK_ACTIVE_HOST names an env-var host) runs it whatever the +# session kind, so an unattended Claude Code run is guarded too (GST-3062). +# Every other host never runs it, and publication order rests on the per-phase +# snapshot hashes. The line is printed, never used to allow anything; B0's +# validator requires one of the two in an unattended run's review-record.md. +# lib/autoplan-guard-status.ts holds the same rule. if [ "$SKILL_NAME" = "autoplan" ]; then - if [ "$_SESSION_KIND" = "unattended" ] || [ -z "${CLAUDECODE:-}" ] || { [ -n "${GSTACK_ACTIVE_HOST:-}" ] && [ "${GSTACK_ACTIVE_HOST:-}" != "claude" ]; }; then + if [ -n "${CLAUDECODE:-}" ] && { [ -z "${GSTACK_ACTIVE_HOST:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = "claude" ]; } && + awk 'NR == 1 { if ($0 !~ /^---\r?$/) exit 1; next } /^---\r?$/ { exit found ? 0 : 1 } /autoplan\/bin\/phase-publication-hook/ { found = 1 } END { exit found ? 0 : 1 }' "$(dirname "$_BIN")/autoplan/SKILL.md" 2>/dev/null; then + echo "autoplan guard: enforced by Claude Code's /autoplan hook at phase Reads and reviewer dispatch; publish each phase report as visible message text, not reasoning, before the next phase (GUARD_ENFORCED)" + else echo "autoplan guard: not enforced by this host; publication order is unverified (GUARD_NOT_INSTALLED)" fi fi diff --git a/changelog.d/autoplan-guard-says-when-it-is-on.md b/changelog.d/autoplan-guard-says-when-it-is-on.md new file mode 100644 index 000000000..61c9503de --- /dev/null +++ b/changelog.d/autoplan-guard-says-when-it-is-on.md @@ -0,0 +1,2 @@ +- **An unattended /autoplan run on Claude Code no longer says the publication guard is off while it is on.** `gstack-skill-start` printed `autoplan guard: not enforced by this host ... (GUARD_NOT_INSTALLED)` for every unattended session, but Claude Code runs /autoplan's phase hook whatever the session kind, so runs were blocked by a guard their own record said was off. The line now follows the host. On Claude Code with the hook installed it reads `... (GUARD_ENFORCED)`, elsewhere it keeps `GUARD_NOT_INSTALLED`, and `gstack-artifact validate` accepts either in an unattended run's record. +- **A phase report written only in reasoning now gets a denial that says so and names the fix.** When a `true autoplan-published ` message carries no visible text, the guard denies with the new `publication_not_visible` code instead of the generic `publication_missing`, and every publication denial names the exact command (for example `true autoplan-published dx`) and says reasoning does not count. A saved report file still does not count as publication. diff --git a/docs/autoplan-guard-troubleshooting.md b/docs/autoplan-guard-troubleshooting.md index b4778a16a..fe12cef60 100644 --- a/docs/autoplan-guard-troubleshooting.md +++ b/docs/autoplan-guard-troubleshooting.md @@ -214,8 +214,23 @@ be verified, so Claude Code is not writing it to the journal in time. ### `publication_missing` No filled report for the previous phase appears after its close packet Read. -Publish it as your own assistant text in a message whose only tool call is +Publish it as your own visible assistant text, starting with the line +`**Phase complete.**`, in a message whose only tool call is `true autoplan-published `, then enter the next phase in a later message. +The close packet, the active plan or any saved report file does not publish it: +the guard's job is to see the report in the conversation, and a file the model +can write without sending the report would let a phase start unpublished. + + +### `publication_not_visible` +A `true autoplan-published` message came after the close packet Read, but +none of those messages carried visible text, so nothing was published. Text +written in reasoning (thinking) is visible to neither the user nor the guard; +an unattended run that keeps putting its report there gets this denial on +every attempt instead of a fallback. Send one message whose visible text is the +filled report, starting with `**Phase complete.**`, with +`true autoplan-published ` as its only tool call, then enter the next +phase in a later message. The denial names the exact command. ### `publication_unflushed` diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index ffb1045e9..ae0b0d8de 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -3495,14 +3495,31 @@ keep the line in the review record. ### `autoplan guard: not enforced by this host; publication order is unverified (GUARD_NOT_INSTALLED)` **Meaning.** The autoplan publication hook only executes inside Claude Code. -On every other host, and in every `unattended` session, the hook is present -but never runs, so phase publication order rests on the snapshot hashes -recorded per phase rather than on the guard. +On every other host (Capy, Codex and the other env-var hosts), or when the +installed `autoplan/SKILL.md` does not declare the hook, it never runs, so +phase publication order rests on the snapshot hashes recorded per phase +rather than on the guard. **Fix.** Nothing on this host. The line is printed once per run and belongs -in the review record; `gstack-artifact validate` requires it for an -unattended run. On Claude Code a *missing* hook file still denies every -guarded call (a broken install must not pass as an absent one). +in the review record; `gstack-artifact validate` requires it (or +`GUARD_ENFORCED`) for an unattended run. On Claude Code a *missing* hook file +still denies every guarded call (a broken install must not pass as an absent one). + + +### `autoplan guard: enforced by Claude Code's /autoplan hook ... (GUARD_ENFORCED)` + +**Meaning.** `gstack-skill-start` runs inside Claude Code (`CLAUDECODE` is set +and no other host is active) and the installed `autoplan/SKILL.md` declares +the publication hook. Claude Code runs that hook whenever `/autoplan` was +started as a skill (the slash command or the Skill tool), in an unattended +session too: a phase-entry Read or reviewer dispatch is denied until the +previous phase's report is published. A session that only reads SKILL.md +with the Read tool does not register skill hooks. + +**Fix.** Nothing to change. Publish each phase report as visible message text +(not reasoning) in a message whose only tool call is +`true autoplan-published `; the denial codes are in +[autoplan-guard-troubleshooting.md](autoplan-guard-troubleshooting.md). ### `review-log: status mismatch ... (REVIEW_STATUS_MISMATCH)` diff --git a/docs/unattended.md b/docs/unattended.md index 64feaca8e..e7b4163c2 100644 --- a/docs/unattended.md +++ b/docs/unattended.md @@ -47,12 +47,15 @@ it, so `headless` keeps its BLOCK semantics. `timing: analytics skipped (...)` instead of writing to a disk that vanishes. Point `GSTACK_STATE_ROOT` at a durable directory when you want cross-run history (see [state-root.md](state-root.md)). -- **The autoplan publication guard is named, not faked.** On hosts that do not - execute Claude Code hooks, and in every unattended session, `gstack-skill-start` - prints `autoplan guard: not enforced by this host; publication order is - unverified (GUARD_NOT_INSTALLED)` once. `gstack-artifact validate` requires - that line in an unattended run's `review-record.md`. Claude Code's - deny-on-absent behavior is unchanged. +- **The autoplan publication guard is named, not faked.** `gstack-skill-start` + prints one guard line for /autoplan, chosen by host, not by session kind. On + Claude Code with the hook declared in `autoplan/SKILL.md` it prints + `autoplan guard: enforced by Claude Code's /autoplan hook ... (GUARD_ENFORCED)`, + because the hook denies phase entry there in unattended sessions too. On hosts + that do not execute Claude Code hooks it prints `autoplan guard: not enforced + by this host; publication order is unverified (GUARD_NOT_INSTALLED)`. + `gstack-artifact validate` requires one of the two in an unattended run's + `review-record.md`. Claude Code's deny-on-absent behavior is unchanged. An unknown `GSTACK_SESSION_KIND` value coerces to `interactive` and says so: `SESSION_KIND: interactive (unknown kind '')`. diff --git a/lib/autoplan-export.ts b/lib/autoplan-export.ts index 30b58a725..2e5b65c1a 100644 --- a/lib/autoplan-export.ts +++ b/lib/autoplan-export.ts @@ -3,7 +3,7 @@ * B2): `plan.md` (the `## URGENT, outside this plan` block above the * `## Implementation plan` section; warns above 30 KB), `review-record.md` * (the `## Review record` section plus the run log: phases, voices, consensus - * tables, the gate and the GUARD_NOT_INSTALLED line the validator requires), + * tables, the gate and the guard line the validator requires), * `findings.jsonl`, `tasks.jsonl`, `decisions.jsonl` (already written by the * gate), `timing.json`, and `run.json` with every artifact's path and hash * and the counts `gstack-artifact validate` checks against the files, plus diff --git a/lib/autoplan-guard-status.ts b/lib/autoplan-guard-status.ts new file mode 100644 index 000000000..755b8e058 --- /dev/null +++ b/lib/autoplan-guard-status.ts @@ -0,0 +1,29 @@ +/** + * What gstack-skill-start and the gstack-autoplan run record say about the + * /autoplan publication guard. The guard is the PreToolUse hook that the + * Claude render of autoplan/SKILL.md declares in its frontmatter + * (scripts/resolvers/composition.ts). Claude Code runs it whenever /autoplan + * was started as a skill, whatever GSTACK_SESSION_KIND says, so the line + * follows the host and the installed skill, never the session kind (GST-3062). + * bin/gstack-skill-start carries the same rule in bash; test/autoplan-guard-status.test.ts holds them equal. + */ +import * as fs from 'node:fs'; +import * as path from 'node:path'; + +export const GUARD_NOT_INSTALLED_LINE = 'autoplan guard: not enforced by this host; publication order is unverified (GUARD_NOT_INSTALLED)'; +export const GUARD_ENFORCED_LINE = "autoplan guard: enforced by Claude Code's /autoplan hook at phase Reads and reviewer dispatch; " + + 'publish each phase report as visible message text, not reasoning, before the next phase (GUARD_ENFORCED)'; + +/** True when the installed autoplan/SKILL.md declares the publication hook in its frontmatter. */ +export function publicationHookDeclared(root: string): boolean { + let text: string; + try { text = fs.readFileSync(path.join(root, 'autoplan', 'SKILL.md'), 'utf8'); } catch { return false; } + const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text)?.[1] ?? ''; + return frontmatter.includes('autoplan/bin/phase-publication-hook'); +} + +/** The one guard line for this process: enforced only on Claude Code with the hook declared. */ +export function autoplanGuardLine(env: Record, root: string): string { + const claude = !!env.CLAUDECODE && (!env.GSTACK_ACTIVE_HOST || env.GSTACK_ACTIVE_HOST === 'claude'); + return claude && publicationHookDeclared(root) ? GUARD_ENFORCED_LINE : GUARD_NOT_INSTALLED_LINE; +} diff --git a/lib/autoplan-run.ts b/lib/autoplan-run.ts index 49ffe23c7..eb7d74018 100644 --- a/lib/autoplan-run.ts +++ b/lib/autoplan-run.ts @@ -26,6 +26,7 @@ import { GSTACK_VERSION } from './autoplan-migrate'; import { driftLine, normalizeFindingFile, reviewHash, scaffold } from './autoplan-plan-text'; import { PHASES, SNAPSHOT_TOOL, attemptFile, bindPromptResult, detectScope, driverFile, extractHeading, phaseOrder, reviewSkillFile, scopeLines, scopeSourceLabel, sectionLoadFor, snapshotTool, writePrompts, type Phase, type Scope, type ScopeFlags } from './autoplan-prompts'; import { recoverRevise } from './autoplan-revise'; +import { autoplanGuardLine } from './autoplan-guard-status'; import { FILES, RunError, journal, now, pendingAmendments, readDecisions, readJournal, readState, voiceTerminal, writeState, type AttemptState, type PhaseState, type RunState, type Voice, type VoiceState } from './autoplan-state'; import { checkPlanReality, checkRealityRows, PLAN_REALITY_CHECKER } from './plan-reality'; import type { RunStatus } from './headless-artifacts'; @@ -129,7 +130,7 @@ export function initRun(o: InitOptions, lines: string[] = []): RunState { outside_enabled: (o.outsideEnabled ?? true) && !consentMissing && !lean, attempt_counter: 0, spend_cap_usd: o.spendCap ?? null, ...(consentMissing ? { outside_not_run: { reason: 'consent_missing', detail: consentMissing } } : {}), session_kind: sessionKind, host: 'gstack-autoplan', max_rounds: o.maxRounds ?? (lean ? 1 : sessionKind === 'unattended' ? DEFAULT_MAX_ROUNDS : null), history: [], created_at: now(), updated_at: now(), - deviations: ['autoplan guard: not enforced by this host; publication order is unverified (GUARD_NOT_INSTALLED)'], + deviations: [autoplanGuardLine(process.env, path.resolve(import.meta.dir, '..'))], ...(o.deadlineMin ? { deadline_at: new Date(Date.now() + o.deadlineMin * 60_000).toISOString() } : {}), ...(o.light ? { light: true } : {}), ...(o.ceoOnly ? { ceo_only: true } : {}), ...(o.shadow ? { shadow: o.shadow } : {}), gstack_version: GSTACK_VERSION, plan_input: input, scope_flags: { ...(o.scope ?? {}) }, diff --git a/lib/headless-artifacts.ts b/lib/headless-artifacts.ts index bd8df14b8..00f98b612 100644 --- a/lib/headless-artifacts.ts +++ b/lib/headless-artifacts.ts @@ -502,7 +502,7 @@ export interface ValidationResult { valid: boolean; errors: ValidationError[]; m * that is missing, stale (hash) or escapes the run directory, malformed JSONL, * schema violations, duplicate or unbound ids, dangling references, task * dependency cycles, count mismatches, and an unattended run whose - * review-record.md lacks the GUARD_NOT_INSTALLED line. + * review-record.md lacks its GUARD_ENFORCED or GUARD_NOT_INSTALLED line. */ export function validateRun(runJson: string): ValidationResult { const runDir = path.dirname(path.resolve(runJson)); @@ -549,7 +549,7 @@ export function validateRun(runJson: string): ValidationResult { const record = manifest.artifacts['review-record.md']; const abs = record ? resolveInside(runDir, record.path).abs : ''; const text = abs && fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : ''; - if (!text.includes('GUARD_NOT_INSTALLED')) errors.push({ code: 'ARTIFACT_GUARD_LINE_MISSING', path: 'review-record.md', message: 'unattended run without the guard line' }); + if (!/\((?:GUARD_ENFORCED|GUARD_NOT_INSTALLED)\)/.test(text)) errors.push({ code: 'ARTIFACT_GUARD_LINE_MISSING', path: 'review-record.md', message: 'unattended run without the guard line' }); } return { valid: errors.length === 0, errors, manifest, runDir, attested: countAttested(manifest) }; } diff --git a/lib/result-codes-autoplan.ts b/lib/result-codes-autoplan.ts index 3d97d2880..fdab4981b 100644 --- a/lib/result-codes-autoplan.ts +++ b/lib/result-codes-autoplan.ts @@ -1,5 +1,6 @@ /** - * Result codes for the CEO-only driver run (`gstack-autoplan next --ceo-only`, + * Result codes for the /autoplan publication guard line (GUARD_ENFORCED, printed by + * gstack-skill-start; lib/autoplan-guard-status.ts), the CEO-only driver run (`gstack-autoplan next --ceo-only`, * lib/autoplan-ceo-only.ts) and its shadow-mode reader (`gstack-autoplan shadow`, * lib/autoplan-shadow-reader.ts). Kept beside lib/result-codes.ts, which spreads * this table into RESULT_CODES; the same rules apply: one stable @@ -9,6 +10,11 @@ import type { ResultCode } from './result-codes'; export const AUTOPLAN_RESULT_CODES = { + GUARD_ENFORCED: { + anchor: 'guard-enforced', + summary: 'Claude Code runs the autoplan publication hook, so a phase Read or reviewer dispatch is denied until the previous phase report is published', + fix: 'publish each phase report as visible message text, not reasoning, in a message whose only tool call is `true autoplan-published `', + }, CEO_ONLY_CONFLICT: { anchor: 'ceo-only-conflict', summary: '--ceo-only was combined with a flag that adds a phase (--ui, --developer-tool, --agent-primary), or a plan\'s scope marker names it', diff --git a/lib/result-codes.ts b/lib/result-codes.ts index 512833c93..ae294da79 100644 --- a/lib/result-codes.ts +++ b/lib/result-codes.ts @@ -101,8 +101,8 @@ export const RESULT_CODES = { }, ARTIFACT_GUARD_LINE_MISSING: { anchor: 'artifact-guard-line-missing', - summary: 'an unattended run’s review-record.md does not state that the publication guard was not enforced', - fix: 'start the run through gstack-skill-start so the GUARD_NOT_INSTALLED line is recorded', + summary: 'an unattended run’s review-record.md does not state whether the publication guard was enforced', + fix: 'start the run through gstack-skill-start so its GUARD_ENFORCED or GUARD_NOT_INSTALLED line is recorded', }, GUARD_NOT_INSTALLED: { anchor: 'guard-not-installed', diff --git a/test/autoplan-publication-payload.test.ts b/test/autoplan-publication-payload.test.ts index 0515e426f..6b8c93542 100644 --- a/test/autoplan-publication-payload.test.ts +++ b/test/autoplan-publication-payload.test.ts @@ -115,7 +115,7 @@ describe('Cause B: the current call is not journaled at hook time (payload path) expect(codeOf(await f.hook(f.input('b', 'Agent', dispatch(f, { model: 'haiku' }))))).toBe('agent_key'); const next = await f.hook(f.input('c', 'Read', { file_path: section('design-phase.md') })); expect(codeOf(next)).toBe('publication_missing'); - expect(denial(next)).toContain('true autoplan-published '); + expect(denial(next)).toContain('true autoplan-published ceo'); }); }); @@ -126,7 +126,7 @@ describe('Publication flush: a report counts only once a later journaled record const f = make(); f.report(f.nextMessage()); f.journal(); const output = await f.hook(next(f)); expect(codeOf(output)).toBe('publication_unflushed'); - expect(denial(output)).toContain('`true autoplan-published `'); + expect(denial(output)).toContain('`true autoplan-published ceo`'); expect(denial(output)).not.toMatch(/\bretry\b/i); }); diff --git a/test/autoplan-publication-visible.test.ts b/test/autoplan-publication-visible.test.ts new file mode 100644 index 000000000..de9a0d099 --- /dev/null +++ b/test/autoplan-publication-visible.test.ts @@ -0,0 +1,84 @@ +/** + * GST-3062 (GEVA-549): an unattended /autoplan session sent four publish messages whose + * only content was reasoning plus `true autoplan-published dx`. The guard denied the next + * phase each time with a generic publication_missing and the run ended blocked. A no-op + * publish with no visible text now gets its own corrective code that names the exact next + * step, and the guard still denies until a visible report is really published. + */ +import { afterEach, describe, expect, test } from 'bun:test'; +import * as fs from 'node:fs'; +import * as path from 'node:path'; +import { REASONS, anchor } from '../autoplan/bin/guard-reasons'; +import { guardFixture, section, denial, codeOf, type GuardFixture } from './helpers/autoplan-guard-fixture'; + +const fixtures: GuardFixture[] = []; +afterEach(() => { for (const f of fixtures.splice(0)) f.cleanup(); }); +const make = () => { const f = guardFixture(); fixtures.push(f); return f; }; +const nextPhase = (f: GuardFixture, id = 'next') => f.input(id, 'Read', { file_path: section('design-phase.md') }); + +/** Phase-close step 6 as the stuck session journaled it: reasoning, the no-op and its result; no text block. */ +function reasoningOnlyPublish(f: GuardFixture) { + const id = f.nextMessage(); + f.say('**Phase 1 complete.**\nConsensus: 3/3 confirmed.', id); + f.use(`noop-${id}`, 'Bash', { command: 'true autoplan-published ceo' }, id); + f.result(`noop-${id}`, { content: '' }); + return id; +} +/** Turn every text block that holds `marker` into a private (untagged) thinking block, as Claude Code journals reasoning. */ +function intoReasoning(f: GuardFixture, marker: string) { + const rows = fs.readFileSync(f.transcript, 'utf8').trim().split('\n').map(line => JSON.parse(line)); + for (const row of rows) if (row.message?.content?.[0]?.type === 'text' && row.message.content[0].text.includes(marker)) + row.message.content = [{ type: 'thinking', thinking: row.message.content[0].text, signature: 'c2lnbmF0dXJl' }]; + fs.writeFileSync(f.transcript, rows.map(r => JSON.stringify(r) + '\n').join('')); +} + +describe('a publish message whose report is only in reasoning', () => { + test('is denied as publication_not_visible with the exact next step, on every attempt', async () => { + const f = make(); + for (let attempt = 0; attempt < 4; attempt++) reasoningOnlyPublish(f); + f.journal(); intoReasoning(f, 'Phase 1 complete'); + const output = await f.hook(nextPhase(f)); + expect(codeOf(output)).toBe('publication_not_visible'); + const text = denial(output)!; + expect(text).toContain('carried no visible text'); + expect(text).toContain('reasoning'); + expect(text).toContain('starting with the line **Phase 1 complete.**'); + expect(text).toContain('`true autoplan-published ceo`'); + expect(REASONS.publication_not_visible.disposition).toBe('corrective'); + expect(text).toContain(`docs/autoplan-guard-troubleshooting.md#${anchor('publication_not_visible')}`); + expect(text).not.toMatch(/\bretry\b/i); + }); + + test('a visible report afterwards lets the next phase start', async () => { + const f = make(); + reasoningOnlyPublish(f); f.journal(); intoReasoning(f, 'Phase 1 complete'); + expect(codeOf(await f.hook(nextPhase(f)))).toBe('publication_not_visible'); + f.publish(); f.journal(); intoReasoning(f, 'Consensus: 3/3'); + expect(denial(await f.hook(nextPhase(f, 'next-2')))).toBeUndefined(); + }); +}); + +describe('negative controls: the guard still denies a phase whose report is really missing', () => { + test('no publish message at all stays publication_missing', async () => { + const f = make(); f.journal(); + const output = await f.hook(nextPhase(f)); + expect(codeOf(output)).toBe('publication_missing'); + expect(denial(output)).toContain('`true autoplan-published ceo`'); + }); + + test('a visible publish message without the phase declaration stays publication_missing', async () => { + const f = make(); + const id = f.nextMessage(); + f.say('Done with the review.', id); + f.use(`noop-${id}`, 'Bash', { command: 'true autoplan-published ceo' }, id); + f.result(`noop-${id}`, { content: '' }); f.journal(); + expect(codeOf(await f.hook(nextPhase(f)))).toBe('publication_missing'); + }); + + test('a report saved to a file, with a reasoning-only publish, does not publish it', async () => { + const f = make(); + fs.writeFileSync(path.join(f.cwd, 'ceo-report.md'), '**Phase 1 complete.**\nConsensus: 3/3 confirmed.\n'); + reasoningOnlyPublish(f); f.journal(); intoReasoning(f, 'Phase 1 complete'); + expect(codeOf(await f.hook(nextPhase(f)))).toBe('publication_not_visible'); + }); +}); diff --git a/test/gstack-skill-start.test.ts b/test/gstack-skill-start.test.ts index 2b4887a59..f3f8be40c 100644 --- a/test/gstack-skill-start.test.ts +++ b/test/gstack-skill-start.test.ts @@ -24,6 +24,7 @@ import * as path from 'path'; import { generatePreamble } from '../scripts/resolvers/preamble'; import { HOST_PATHS, type TemplateContext } from '../scripts/resolvers/types'; import { expectAbsent, expectMentions } from './helpers/prompt-structure'; +import { GUARD_ENFORCED_LINE, GUARD_NOT_INSTALLED_LINE, autoplanGuardLine } from '../lib/autoplan-guard-status'; const ROOT = path.resolve(import.meta.dir, '..'); const START = path.join(ROOT, 'bin', 'gstack-skill-start'); @@ -388,6 +389,22 @@ describe('gstack-skill-start behavior', () => { } }); + // GST-3062 (GEVA-549): an unattended Claude Code run printed GUARD_NOT_INSTALLED while autoplan's + // PreToolUse hook denied its phase Reads. The line follows the host and the installed skill, not the session kind. + test('the autoplan guard line says enforced whenever Claude Code runs the declared hook, unattended included', () => { + const line = (env: Record) => (runStart(['--skill', 'autoplan'], env).match(/^autoplan guard: .*$/gm) ?? []); + const unattendedClaude = line({ CLAUDECODE: '1', GSTACK_SESSION_KIND: 'unattended' }); + expect(unattendedClaude).toEqual([GUARD_ENFORCED_LINE]); + expect(unattendedClaude.join('\n')).not.toContain('GUARD_NOT_INSTALLED'); + const matrix: Record[] = [ + { CLAUDECODE: '1' }, { CLAUDECODE: '1', GSTACK_ACTIVE_HOST: 'claude' }, + { CLAUDECODE: '1', GSTACK_ACTIVE_HOST: 'codex' }, { GSTACK_SESSION_KIND: 'unattended' }, {}, + ]; + for (const env of matrix) expect({ env, line: line(env) }).toEqual({ env, line: [autoplanGuardLine(env, ROOT)] }); + expect(line({ CLAUDECODE: '1', GSTACK_ACTIVE_HOST: 'codex', GSTACK_SESSION_KIND: 'unattended' })).toEqual([GUARD_NOT_INSTALLED_LINE]); + expect(runStart(['--skill', 'review'], { CLAUDECODE: '1' })).not.toContain('autoplan guard:'); + }); + test('unattended block promises GSTACK_RESULT only to skills that write it; the rest name their record (#3281)', () => { const block = (skill: string) => { const out = runStart(['--skill', skill], { GSTACK_SESSION_KIND: 'unattended' }); diff --git a/test/headless-artifacts.test.ts b/test/headless-artifacts.test.ts index d082b9d97..e9f91652a 100644 --- a/test/headless-artifacts.test.ts +++ b/test/headless-artifacts.test.ts @@ -14,6 +14,7 @@ import { renderUrgentBlock, urgentBlockPrecedes, validateRun, validateFile, } from '../lib/headless-artifacts'; import { RESULT_CODES } from '../lib/result-codes'; +import { GUARD_ENFORCED_LINE } from '../lib/autoplan-guard-status'; const ROOT = path.resolve(import.meta.dir, '..'); const BIN = path.join(ROOT, 'bin', 'gstack-artifact'); @@ -186,6 +187,21 @@ describe('validate fails on', () => { expect(r.out.trim()).toBe('ARTIFACT_INVALID: 1 error(s)'); }); + test('an unattended run whose review-record.md lacks its guard line; GUARD_ENFORCED counts as one (GST-3062)', () => { + const enforced = copyRun((m, dir) => { + m.session_kind = 'unattended'; + fs.writeFileSync(path.join(dir, 'review-record.md'), `# Review record\nDeviation: ${GUARD_ENFORCED_LINE}\n`); + m.artifacts['review-record.md'] = { path: 'review-record.md', sha256: sha(path.join(dir, 'review-record.md')) }; + }); + expect(codes(enforced)).toEqual([]); + const bareCode = copyRun((m, dir) => { + m.session_kind = 'unattended'; + fs.writeFileSync(path.join(dir, 'review-record.md'), '# Review record\nThe GUARD_ENFORCED_LINE constant is defined in lib.\n'); + m.artifacts['review-record.md'] = { path: 'review-record.md', sha256: sha(path.join(dir, 'review-record.md')) }; + }); + expect(codes(bareCode)).toEqual(['ARTIFACT_GUARD_LINE_MISSING']); + }); + test('an unattended run whose review-record.md lacks the GUARD_NOT_INSTALLED line', () => { const without = copyRun((m, dir) => { m.session_kind = 'unattended'; diff --git a/test/helpers/autoplan-run-fixture.ts b/test/helpers/autoplan-run-fixture.ts index e651305a2..89e7f035b 100644 --- a/test/helpers/autoplan-run-fixture.ts +++ b/test/helpers/autoplan-run-fixture.ts @@ -29,6 +29,8 @@ export function env(extra: Record = {}): Record const out: Record = {}; for (const [k, v] of Object.entries(process.env)) if (v !== undefined) out[k] = v; out.GSTACK_EPHEMERAL = '1'; + // The run record's guard line follows the host (lib/autoplan-guard-status.ts); keep it the CI host's. + delete out.CLAUDECODE; delete out.GSTACK_ACTIVE_HOST; // The runner's default kind; spelled through the bin's own flag table so the // free-suite environment scan (test/gstack-session-kind.test.ts) stays clean. out[SESSION_KIND_VAR] = RUNNER_KIND;