Skip to content
  • Garry Tan's avatar
    11de390b
    v1.58.5.0 feat: first-run activation scaffold + gstack router front door (#2078) · 11de390b
    Garry Tan authored
    
    
    * feat: first-run activation — project-aware scaffold, router front door, onboarding nudges
    
    Adds the activation system that drives a new install toward a concrete first move:
    - bin/gstack-first-task-detect: local-git+filesystem repo classifier emitting one
      validated enum bucket (greenfield/code_<lang>/branch_ahead/dirty_default/clean_default),
      portable timeouts, fail-safe empty output.
    - generate-first-run-guidance.ts: unified preamble section — first-run project-aware
      scaffold + returning-session plan->review->ship tip, gated on a persistent .activated
      marker and never run in headless. Detection wired lazily in generate-preamble-bash.ts.
    - SKILL.md.tmpl: top-level gstack skill is now a pure router (browse body removed; it
      lives in /browse), routing any request and sending browser/QA work to /browse.
    - setup: first-move nudge on first install. office-hours: closing handoff that launches
      the next review via the Skill tool.
    - telemetry-ingest: accept onboarding/first_task_scaffold_shown/handoff/route event types.
    
    * test: cover first-run detection + repoint browse-content assertions to /browse
    
    - New unit tests for every detection bucket, the eval-safe enum contract, and the
      first-run gating (test/preamble-first-task-scaffold.test.ts); periodic E2E that runs
      the detector through the real harness (test/skill-e2e-first-task-scaffold.test.ts).
    - Repoint browse-content assertions (gen-skill-docs, audit-compliance, skill-validation,
      LLM-judge eval) from the root skill to browse/SKILL.md following the router split;
      add a regression pinning that the router carries no browse body.
    - Register first-task-scaffold touchfiles + periodic tier; bump parity/carve size caps
      ~1-2KB per skill for the shared first-run-guidance preamble section.
    - Refresh ship golden fixtures for the preamble addition.
    
    * chore: regenerate SKILL.md + llms.txt for first-run activation
    
    * chore: bump version and changelog (v1.58.5.0)
    
    Co-Authored-By: default avatarClaude Opus 4.8 (1M context) <noreply@anthropic.com>
    
    * fix(test): repoint bws skillmd-* setup-block assertions to browse/SKILL.md
    
    The skillmd-setup-discovery / -no-local-binary / -outside-git E2E tests extracted
    the `## SETUP`→`## IMPORTANT` browse binary-discovery block from the root SKILL.md.
    P2 moved that block to browse/SKILL.md (end anchor is now `## Core QA Patterns`),
    so the slice came back empty and the `browse/dist/browse` guard failed. Repoint to
    browse/SKILL.md. Verified: 7/7 e2e-browse pass locally.
    
    * fix(test): tolerate skill-discovery race in PTY plan-mode smoke
    
    The e2e-pty-plan-smoke suite (office-hours / plan-mode-no-op) failed in CI with
    `Unknown command: /office-hours` (claude exited ~10s) while passing locally. Root
    cause: a cold CI container's overlay-FS scan of the symlinked ~/.claude/skills
    registry finishes AFTER the runner's 8s boot grace, so the first `/skill` send
    reaches claude before the skill is indexed and is rejected as unknown. The runner
    gave up on the first "Unknown command:" line.
    
    runPlanSkillObservation now re-sends the skill command up to 3x (6s apart),
    re-marking the buffer each time so stale scrollback can't re-trip the check,
    before concluding the skill is genuinely unregistered. A real dangling-symlink /
    missing-skill still surfaces as 'exited' (after retries), preserving the original
    diagnostic. Pure-helper contract unchanged: 95/95 unit tests pass.
    
    This is a pre-existing harness bug (fails identically on #2077's own branch, which
    introduced the suite) surfaced while shipping the activation feature.
    
    * debug(ci): temporarily instrument pty-smoke skill discovery
    
    Capture claude version, env, registry tree, and a claude -p discovery probe to
    pin why /office-hours isn't discovered in CI (retries proved it's not a race).
    Temporary — revert once the registry fix is identified.
    
    * chore: revert pty-smoke harness experiments (race-retry + CI debug step)
    
    Diagnosis is conclusive and the experiments aren't the fix, so restore the
    harness to its original state (net-zero diff vs main for both files).
    
    What the CI debug step proved: `claude -p` returns READY — claude v2.1.187 fully
    DISCOVERS /office-hours from the symlinked registry. Only the interactive PTY TUI
    rejects it as "Unknown command" (and it received the full command text). So the
    e2e-pty-plan-smoke failure is a claude 2.1.187 interactive-TUI regression (skills
    discovered by `claude -p` aren't exposed as TUI slash commands), pre-existing in
    the #2077 harness and failing identically on its own origin branch — unrelated to
    this activation PR. The race-retry can't help (the TUI genuinely lacks the
    command); the debug step also tripped actionlint (shellcheck SC2012). Both reverted.
    
    * fix(ci): copy SKILL.md as real files in pty-smoke registry (cross-mount symlink)
    
    The e2e-pty-plan-smoke suite failed with "Unknown command: /office-hours" in CI
    while passing locally. Root cause (proven, not guessed): claude 2.1.187's
    interactive-TUI skill scanner does not follow the /github/home -> /__w cross-mount
    symlink the registry used for per-skill SKILL.md. Evidence: a CI debug step showed
    `claude -p` discovered the skill (printed READY), and a local macOS repro with the
    identical symlinked registry recognized /office-hours — isolating the failure to
    the container's cross-mount symlink, not registration content, claude version,
    duplicate names, or a race.
    
    Fix: register the per-skill SKILL.md + sections as REAL copies (same mount as
    $HOME) so the TUI reads them directly. The gstack root stays a symlink — the
    preamble's runtime bash resolves bin/* and sections/* through it and bash follows
    cross-mount symlinks fine.
    
    * fix(ci): guard rm expansion in pty-smoke registry (shellcheck SC2115)
    
    * fix(ci): also register pty-smoke skills project-scoped (cwd/.claude/skills)
    
    The real-file user-dir registration still left the TUI rejecting /office-hours in
    the container. claude's interactive TUI surfaces /slash commands from the PROJECT
    dir (<cwd>/.claude/skills); the smokes run with cwd=$REPO whose .claude/skills is
    gitignored (absent on a fresh CI checkout), so the user-dir registry feeds
    `claude -p` (READY) but not the TUI. Populate $REPO/.claude/skills with real
    SKILL.md + sections copies (no gstack symlink there — it would point at its own
    parent; runtime paths use the user-dir gstack symlink).
    
    ---------
    
    Co-authored-by: default avatarClaude Opus 4.8 (1M context) <noreply@anthropic.com>
    11de390b
    v1.58.5.0 feat: first-run activation scaffold + gstack router front door (#2078)
    Garry Tan authored
    
    
    * feat: first-run activation — project-aware scaffold, router front door, onboarding nudges
    
    Adds the activation system that drives a new install toward a concrete first move:
    - bin/gstack-first-task-detect: local-git+filesystem repo classifier emitting one
      validated enum bucket (greenfield/code_<lang>/branch_ahead/dirty_default/clean_default),
      portable timeouts, fail-safe empty output.
    - generate-first-run-guidance.ts: unified preamble section — first-run project-aware
      scaffold + returning-session plan->review->ship tip, gated on a persistent .activated
      marker and never run in headless. Detection wired lazily in generate-preamble-bash.ts.
    - SKILL.md.tmpl: top-level gstack skill is now a pure router (browse body removed; it
      lives in /browse), routing any request and sending browser/QA work to /browse.
    - setup: first-move nudge on first install. office-hours: closing handoff that launches
      the next review via the Skill tool.
    - telemetry-ingest: accept onboarding/first_task_scaffold_shown/handoff/route event types.
    
    * test: cover first-run detection + repoint browse-content assertions to /browse
    
    - New unit tests for every detection bucket, the eval-safe enum contract, and the
      first-run gating (test/preamble-first-task-scaffold.test.ts); periodic E2E that runs
      the detector through the real harness (test/skill-e2e-first-task-scaffold.test.ts).
    - Repoint browse-content assertions (gen-skill-docs, audit-compliance, skill-validation,
      LLM-judge eval) from the root skill to browse/SKILL.md following the router split;
      add a regression pinning that the router carries no browse body.
    - Register first-task-scaffold touchfiles + periodic tier; bump parity/carve size caps
      ~1-2KB per skill for the shared first-run-guidance preamble section.
    - Refresh ship golden fixtures for the preamble addition.
    
    * chore: regenerate SKILL.md + llms.txt for first-run activation
    
    * chore: bump version and changelog (v1.58.5.0)
    
    Co-Authored-By: default avatarClaude Opus 4.8 (1M context) <noreply@anthropic.com>
    
    * fix(test): repoint bws skillmd-* setup-block assertions to browse/SKILL.md
    
    The skillmd-setup-discovery / -no-local-binary / -outside-git E2E tests extracted
    the `## SETUP`→`## IMPORTANT` browse binary-discovery block from the root SKILL.md.
    P2 moved that block to browse/SKILL.md (end anchor is now `## Core QA Patterns`),
    so the slice came back empty and the `browse/dist/browse` guard failed. Repoint to
    browse/SKILL.md. Verified: 7/7 e2e-browse pass locally.
    
    * fix(test): tolerate skill-discovery race in PTY plan-mode smoke
    
    The e2e-pty-plan-smoke suite (office-hours / plan-mode-no-op) failed in CI with
    `Unknown command: /office-hours` (claude exited ~10s) while passing locally. Root
    cause: a cold CI container's overlay-FS scan of the symlinked ~/.claude/skills
    registry finishes AFTER the runner's 8s boot grace, so the first `/skill` send
    reaches claude before the skill is indexed and is rejected as unknown. The runner
    gave up on the first "Unknown command:" line.
    
    runPlanSkillObservation now re-sends the skill command up to 3x (6s apart),
    re-marking the buffer each time so stale scrollback can't re-trip the check,
    before concluding the skill is genuinely unregistered. A real dangling-symlink /
    missing-skill still surfaces as 'exited' (after retries), preserving the original
    diagnostic. Pure-helper contract unchanged: 95/95 unit tests pass.
    
    This is a pre-existing harness bug (fails identically on #2077's own branch, which
    introduced the suite) surfaced while shipping the activation feature.
    
    * debug(ci): temporarily instrument pty-smoke skill discovery
    
    Capture claude version, env, registry tree, and a claude -p discovery probe to
    pin why /office-hours isn't discovered in CI (retries proved it's not a race).
    Temporary — revert once the registry fix is identified.
    
    * chore: revert pty-smoke harness experiments (race-retry + CI debug step)
    
    Diagnosis is conclusive and the experiments aren't the fix, so restore the
    harness to its original state (net-zero diff vs main for both files).
    
    What the CI debug step proved: `claude -p` returns READY — claude v2.1.187 fully
    DISCOVERS /office-hours from the symlinked registry. Only the interactive PTY TUI
    rejects it as "Unknown command" (and it received the full command text). So the
    e2e-pty-plan-smoke failure is a claude 2.1.187 interactive-TUI regression (skills
    discovered by `claude -p` aren't exposed as TUI slash commands), pre-existing in
    the #2077 harness and failing identically on its own origin branch — unrelated to
    this activation PR. The race-retry can't help (the TUI genuinely lacks the
    command); the debug step also tripped actionlint (shellcheck SC2012). Both reverted.
    
    * fix(ci): copy SKILL.md as real files in pty-smoke registry (cross-mount symlink)
    
    The e2e-pty-plan-smoke suite failed with "Unknown command: /office-hours" in CI
    while passing locally. Root cause (proven, not guessed): claude 2.1.187's
    interactive-TUI skill scanner does not follow the /github/home -> /__w cross-mount
    symlink the registry used for per-skill SKILL.md. Evidence: a CI debug step showed
    `claude -p` discovered the skill (printed READY), and a local macOS repro with the
    identical symlinked registry recognized /office-hours — isolating the failure to
    the container's cross-mount symlink, not registration content, claude version,
    duplicate names, or a race.
    
    Fix: register the per-skill SKILL.md + sections as REAL copies (same mount as
    $HOME) so the TUI reads them directly. The gstack root stays a symlink — the
    preamble's runtime bash resolves bin/* and sections/* through it and bash follows
    cross-mount symlinks fine.
    
    * fix(ci): guard rm expansion in pty-smoke registry (shellcheck SC2115)
    
    * fix(ci): also register pty-smoke skills project-scoped (cwd/.claude/skills)
    
    The real-file user-dir registration still left the TUI rejecting /office-hours in
    the container. claude's interactive TUI surfaces /slash commands from the PROJECT
    dir (<cwd>/.claude/skills); the smokes run with cwd=$REPO whose .claude/skills is
    gitignored (absent on a fresh CI checkout), so the user-dir registry feeds
    `claude -p` (READY) but not the TUI. Populate $REPO/.claude/skills with real
    SKILL.md + sections copies (no gstack symlink there — it would point at its own
    parent; runtime paths use the user-dir gstack symlink).
    
    ---------
    
    Co-authored-by: default avatarClaude Opus 4.8 (1M context) <noreply@anthropic.com>
Loading