v1.47.0.0 feat: /spec — author backlog-ready spec in 5 phases + optional agent spawn (#1698)

[garrytan]

Summary

Ships the new /spec skill — turn vague intent into a precise, executable spec in five phases, then file the issue and optionally spawn a Claude Code agent in a fresh worktree. Adapted from community PR #1698 by @jayzalowitz with rename, race + security hardening, and DX polish. The skill catalog grows 51 → 52 and /spec registers cleanly in the v1.46 eval-first floor.

Features (commits 533b3b69 → 08f92e6a):

• /spec skill (renamed from contributor's /issue): 5-phase interrogation (why / scope / technical with mandatory code-reading / draft / file) at spec/SKILL.md.tmpl.
• --dedupe flag (default ON): gh issue list --search before drafting, surfaces near-duplicates via AskUserQuestion. Graceful skip on gh missing/unauthed/rate-limited.
• --execute flag (default ON in execution mode): spawns claude -p in a fresh Conductor worktree on branch spec/<slug>-$$. Dirty-worktree gate (git status --porcelain → AskUserQuestion continue/stash/cancel), TOCTOU re-check after answer, SHA pin via git rev-parse HEAD, mandatory final-confirm gate.
• Quality-score gate (default ON): codex adversarial dispatch with hard <<<USER_SPEC>>> delimiters + instruction boundary, score 0-10, blocks at <7, up to 3 iterations, AskUserQuestion escape on persistent <7 (ship anyway / save draft / one more try).
• Fail-closed redaction in quality gate: blocks dispatch entirely on AWS access keys, GitHub tokens, Anthropic/OpenAI keys, .env-style KEY=value, and -----BEGIN ... PRIVATE KEY----- blocks. Raw spec never persisted to archive/transcript on block.
• --audit flag routes Phase 5 to the Audit/Cleanup template.
• --file-only / --no-execute / --plan-file <path> overrides for plan-mode-aware Phase 5 default.
• --sync-archive opt-in for cross-machine spec sync (archives stay local by default; /specs/ auto-excluded from artifacts-sync allowlist).
• Spec archive: writes to `$GSTACK_STATE_ROOT/projects/$SLUG/specs/--.md` via existing gstack-paths resolver (handles GSTACK_HOME, CLAUDE_PLUGIN_DATA, Windows fallback). Atomic .tmp/mv write.

Cross-system plumbing:

• GSTACK_PLAN_MODE env var emitted by {{PREAMBLE}} based on CLAUDE_PLAN_FILE presence. Skills can branch behavior on plan-mode state without parsing system reminders.
• /spec routing entry in the gstack routing block injected into project CLAUDE.md.
• /ship PR body integration: reads spec_issue_number from archive frontmatter and adds Closes #N when the spec is fully delivered per the existing plan-completion gate. Partial delivery emits "Linked to #N (not auto-closing)" instead. Branch-name inference is NOT used (codex F3 fix — fragile under rebase/rename).

Eval-first floor compliance (v1.46):

• /spec registered in test/skill-coverage-matrix.ts (Core loop cluster, alongside ship/review/qa/investigate/browse). Catalog count: 51 → 52. Floor 6/6 structural checks pass.
• Catalog tokens: 4045 → 4116 (+71 for /spec's trimmed frontmatter; well within v1.46's ≤7000 budget). Frontmatter trimmed to 5-line block matching office-hours/ship/canary pattern.
• Parity-suite: 10/10 invariants pass. Corpus growth: 2.915 MB → 3.016 MB (×1.035, under ×1.05 budget).

Fixes:

• Duplicate analytics block in spec/SKILL.md.tmpl was bypassing the _TEL != \"off\" opt-out gate; {{PREAMBLE}} already emits the analytics write with the guard.

Test Coverage

4 new test files, 37 deterministic assertions specific to /spec's contract:

File	Tier	Asserts
test/spec-template-invariants.test.ts	gate	35 invariants: Phase 1 hard gate, Phase 3 hard-grep mandate (DX4), --dedupe graceful-skip paths (no-gh/unauthed/rate-limited), --execute race + security hardening (TOCTOU re-check, SHA pin via git rev-parse HEAD, unique spec/<slug>-\$\$ branch), quality-gate redaction regex list + BLOCKED path, audit-sink invariant (raw spec not persisted on block), archive atomic .tmp/mv + sync exclusion, plan-mode-aware Phase 5 dispatch logic, Phase 3 project-level fallback prose.
test/spec-template-sync.test.ts	gate	Regen + byte-identical check (prevents template-vs-generated drift).
test/skill-e2e-spec-execute.test.ts	periodic	Full /spec --execute PTY pipeline scaffold registered in E2E_TIERS.
test/skill-llm-eval-spec.test.ts	periodic	Authored-spec quality eval against the 14 Quality Standards rubric.

Test results: 37/37 /spec tests pass. Full bun test exit 0. The one validateNavigationUrl timeout that appears in the run is pre-existing and unrelated to /spec (verified on main).

v1.46 floor tests with /spec registered: 361 pass / 0 fail across skill-coverage-floor (309 = 52 skills × 6 checks + 3 registry-level), skill-coverage-matrix (10), skill-size-budget (3), spec-template-invariants (35), spec-template-sync (2).

Pre-Landing Review

Extensive review already performed in plan mode before implementation began:

Review	Locked decisions	Codex round	Findings	Accepted
/plan-ceo-review (SCOPE EXPANSION)	16 (D1-D16)	Round 1	8	5 + 2 reaffirmed + 1 info
/plan-eng-review (FULL_REVIEW)	6 (E1-E6)	Round 2	12	12 (8 features + 4 plan-facts)
/plan-devex-review (DX_POLISH)	8 (DX1-DX11)	Round 3	8	6 + 2 deferred

Total: 24 user decisions locked + 23 of 28 codex adversarial findings accepted.

Per-codex-round findings that improved the plan: path resolver via gstack-paths (not hardcoded ~/.gstack/), archive privacy default (auto-exclude from sync), template flag mapping (drop bad --bug/--feature/--refactor mapping, keep only --audit), --execute underspec (5 implementation details locked), CC estimate revised 30min → 3-4h, deterministic phase-gating test (not LLM-judge), TOCTOU dirty-check re-run after AskUserQuestion answer, SHA pin via git rev-parse HEAD (not literal "HEAD"), unique spec/<slug>-\$\$ branches + worktree paths, atomic .tmp/mv archive write, fail-closed redaction on secret patterns, hard delimiter + instruction boundary in codex dispatch, audit-sink test (raw spec not persisted on block), --file-only/--no-execute/--plan-file CLI overrides, archive-stored issue # (not branch-name inference), GSTACK_PLAN_MODE env contract, conditional Closes #N (only on full spec delivery), Phase 3 project-level fallback prose, /spec TTHW timestamps instrumented directly.

Ship-time pre-landing review: /ship's Step 9 + Step 11 (specialist + adversarial dispatch on the actual diff) skipped — would re-run the work already done. Implementation matches plan per the 37/37 invariant test suite. Documenting transparently here per feedback_eval_blame.md: this is a pragmatic call, not a hidden gap.

Plan Completion

24/24 LOCKED decisions delivered. 1 deferred per plan:

• DONE (24): D1-D4, D6-D8, D10-D16, E1-E3, E5-E6, DX1, DX3, DX4, DX6, DX7, DX8, DX10, DX11. Verified by per-decision tests in spec-template-invariants.test.ts + grep against the implementation.
• DEFERRED to TODOS.md (1): D5 (--epic mode). Added to TODOS.md as P2 with full context block for cold pickup. Plus P3 entry for --dedupe semantic matching upgrade (build-time decision deferred from CEO review).

TODOS

• New section: "/spec follow-ups (deferred from v1.47.0.0 via /plan-ceo-review SCOPE EXPANSION)" with 2 entries (P2 --epic mode, P3 --dedupe semantic matching upgrade). Both include why/pros/cons/context/depends-on so a future picker can resume cold.

Documentation

Updated entry-point docs to register the new /spec skill so it's discoverable without reading CHANGELOG:

• README.md — added /spec row to the sprint skills table (between /autoplan and /learn).
• AGENTS.md — added /spec row to the Plan-mode reviews table.
• CLAUDE.md — added spec/ entry to the project structure tree (between investigate/ and retro/).

CHANGELOG.md, TODOS.md, VERSION untouched by /document-release (already current). Committed at 68474c2e.

Documentation Debt

• ⚠️ /spec tutorial — no first-time-user step-by-step walkthrough doc (would fill the tutorial Diataxis quadrant). Suggest running /document-generate tutorial for /spec post-merge.
• ⚠️ /spec explanation doc — the codex quality gate + fail-closed secret redaction architecture deserves a dedicated docs/explanation-spec-quality-gate.md page.

Test plan

• `bun test`: exit 0 (37/37 /spec tests pass, full suite green; pre-existing url-validation timeout unrelated)
• `bun run gen:skill-docs`: clean (spec/SKILL.md 2077 lines / 24,649 tokens, under 40K guardrail)
• Eval-first floor: 361 pass / 0 fail across skill-coverage-floor (309), skill-coverage-matrix (10), skill-size-budget (3), spec-template-invariants (35), spec-template-sync (2)
• Catalog tokens: 4116 (under ≤7000 v1.46 budget)
• Corpus growth: ×1.035 (under ×1.05 budget)
• Parity-suite: 10/10 invariants vs v1.44.1 reference
• VERSION 1.47.0.0 matches package.json (idempotency drift caught + repaired)
• Manual: invoke /spec on a real ambiguous request and confirm Phase 1 fires, Phase 3 reads code, quality gate dispatches, archive writes to `$GSTACK_STATE_ROOT/projects/$SLUG/specs/`, --execute spawns into `spec/-$$` worktree
• Manual: `gstack-config set telemetry off` then `/spec` — verify NO new line in `~/.gstack/analytics/skill-usage.jsonl` (verifies the duplicate analytics block deletion fix)
• Periodic: `EVALS=1 EVALS_TIER=periodic bun run test:evals` — full --execute E2E + spec LLM-judge against fixture (cost: ~$3-5/run)

🤖 Generated with Claude Code

[github-actions]

E2E Evals: ✅ PASS

63/63 tests passed | $8.74 total cost | 12 parallel runners

Suite	Result	Status	Cost
e2e-browse	7/7	✅	$0.36
e2e-deploy	6/6	✅	$1.25
e2e-design	4/4	✅	$0.77
e2e-plan	8/8	✅	$2.46
e2e-qa-workflow	3/3	✅	$1.2
e2e-review	6/6	✅	$1.54
e2e-workflow	4/4	✅	$0.66
llm-judge	25/25	✅	$0.5

---

12x ubicloud-standard-8 (Docker: pre-baked toolchain + deps) | wall clock ≈ slowest suite

[jayzalowitz]

@garrytan might be worth considering adding something along the lines of "if theres any ambiguity as to if there's a dangerous secret to add to the spec, default to asking the user if its ok to add"