v1.91.240.0 feat(proactive): default to the four core skills (core | all | off), with docs, prompt and tests (GSTA-99) (#3432)

* feat(proactive): default to the four core skills (core | all | off); docs, prompt and tests (GSTA-99)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(proactive): gstack-skill-start falls back to core, not true, when gstack-config is missing

The PROACTIVE status line's fallback literal still said true (= all) after the default moved to core. Found by /ship's coverage audit; the regression test fails at the previous head and passes at main.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* test(proactive): STATUS line carries the stored value; every surface names the same core four and three values

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(proactive): off gates the office-hours handoff; the preamble and router scope the setting to unasked suggestions

The office-hours next-review handoff gated on the legacy false only, so an off user was still asked to launch /plan-eng-review. The per-skill preamble now says the setting governs unasked suggestions and this skill's own steps still run (a handoff, a review gate, a dispatched /document-release is not a suggestion), at exactly the previous length, so the 89 size pins return to main's values; the router says the same in full. Found by /ship's specialist and red-team review.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(skill-start): unknown proactive values read as core; first-run tips name core skills and stay quiet under off

A hand-edited config can hold any value and only set validates, so STATUS normalizes anything but core|all|off|true|false to core. The first-run and first-loop tips named /spec, /investigate and /plan-eng-review whatever the setting; they now name the core four and are skipped under off. The fallback regression test folds into test/proactive-skill-start.test.ts, the duplicate header assertion leaves proactive-config, and the frozen-length preamble test is retired (the size guard enforces it).

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* docs(proactive): scope note, the unknown-value rule, and the CLAUDE.md routing follow-up; CHANGELOG

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(skill-start): no CLAUDE.md routing offer under proactive off

The one-time offer to append ## Skill routing to the project's CLAUDE.md fired whatever the proactive value, and its rules are the auto-invocation an off user turned off. The offer is skipped under off and the legacy false; a section already in CLAUDE.md is left alone. Under core the offered section still routes every skill, which docs/proactive.md records as the follow-up. Found by /ship's red team.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(proactive): STATUS says only core | all | off, and the preamble carves out only named skills

gstack-skill-start reads the legacy true/false as all/off and tolerates a quoted, upper-case or commented hand edit (proactive: OFF # mine read as core before), so every surface sees one of three values and the off gating lives in one flag. The per-skill preamble drops the legacy spellings and replaces 'This skill's steps still run', which licensed any in-skill offer under off, with 'Skills the user or this skill's steps name run', at the same length, so the 89 size pins stay at main's. Tests run the script for the tips and the routing offer under core and off instead of grepping the source. Found by /ship's fix-range repeat (red team, testing, maintainability).

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(config): set proactive is case-insensitive; follow-up #3446 cited; test hygiene

set proactive OFF warned and stored core, the opposite of the opt-out typed; the value is lowercased first, as gstack-skill-start does for a hand edit. The fixture git init carries the tripwire timeout, the source-shape assertion on the private _PROACTIVE_OFF line goes (the routing-offer test proves the behavior), and the CHANGELOG Tests bullets collapse to one per file with the known gap pointing at #3446. Found by /ship's full repeat pass and its tests lane.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(proactive): a stored off answers the one-time prompt; the router names /browse and /investigate under core instead of invoking them

Red team, full repeat pass: with proactive: off stored before the prompt, skill-start still emitted the opt-in prompt; it now writes the marker and asks nothing. The router's Route-first browser step and the Failures branches invoked non-core skills under core while the core block said to answer directly; one sentence in the core block resolves it, pinned by the core-set tests. CHANGELOG and docs/proactive.md say both.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* docs(proactive): the full-catalog skill descriptions are the second surface that still routes every skill under core (#3446)

From /ship's document-release audit: a --catalog-mode=full build and the non-Claude hosts keep the "Proactively suggest when ..." description sentences, which do not follow the setting; the default Claude build trims them.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* test(proactive): the tips test runs skill-start as an interactive session

GitHub CI sets CI/GITHUB_ACTIONS, which gstack-session-kind reads as headless, and a headless start skips first-task detection, so the first-run tip never fires there (Free Tests shard 16 red at 0d7dbe6; green locally and on the Ubicloud pregate, which have no CI marker). The fixture now sets CLAUDE_CODE_ENTRYPOINT=cli, the positive interactive signal; reproduced locally with CI=1 and fixed.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(proactive): an opt-out never fails open; the preamble carves out invocations, not offers

The YAML yes/no family (yes/on/1, no/none/0/disabled/never) reads as all/off in both gstack-skill-start and gstack-config set, so a typed or hand-edited opt-out cannot land on core. The per-skill preamble says "Skills the user names or this one invokes run" (same 168-char length, pins unchanged): a skill dispatching another is not a suggestion, an in-skill offer to run one still is under off. The stored-off prompt marker is written before STATUS prints PROACTIVE_PROMPTED, so the line is true. docs/proactive.md's table row carves out in-skill handoffs.

Fourth /ship fix cycle, past the skill's three-cycle cap by GStack Minder's decision (2026-10-26) under Garry's "do it" on the proactive core set; items from the Step 11 adversarial pass.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* v1.91.240.0 stamp

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

docs/proactive.md

@@ -0,0 +1,58 @@
+# Proactive skill suggestions
+
+gstack notices what stage you are in (a new idea, a diff to review, "does this
+work?", time to land it) and can invoke the matching skill without you typing
+its slash command. The `proactive` config key says how far that goes.
+
+| Value | What auto-invokes | Who it is for |
+|-------|-------------------|---------------|
+| `core` (default) | `/office-hours`, `/review`, `/qa` and `/ship` only. Every other skill waits for you to type it, unless a skill you ran hands off to it (`/office-hours` offering the next review). | Most people, and anyone running gstack beside another skill pack: the four core skills are the ones users praise, and the others no longer compete with another pack's niche skills. |
+| `all` | Any skill whose purpose matches your request. | You use gstack on its own and want the whole sprint suggested. |
+| `off` | Nothing. gstack never suggests or auto-invokes a skill, not even by asking "want me to run /X?". | You type every command yourself. |
+
+`true` and `false` still work as the older spellings of `all` and `off`, so a
+config written before the `core` default keeps its behavior; `gstack-skill-start`
+reports them to the skill as `all` and `off`. A hand edit may be quoted, upper-case
+or commented (`proactive: "OFF" # mine`), and the YAML yes/no family (`yes`, `on`,
+`1`; `no`, `none`, `0`, `disabled`, `never`) reads as `all` or `off`, in
+`gstack-config set` as well, so a typed opt-out never fails open.
+
+```bash
+gstack-config get proactive          # core, all, off (or a legacy true/false)
+gstack-config set proactive all      # suggest every matching skill
+gstack-config set proactive off      # suggest nothing
+gstack-config set proactive core     # back to the default
+```
+
+A skill you name is always invoked, whatever the setting, and so is a skill that
+a running skill invokes itself (`/ship` dispatching `/document-release`). The
+setting governs unasked suggestions, and an in-skill *offer* to run another skill
+is one: under `off`, `/office-hours` recommends the next review in one line
+instead of offering to launch it, and the one-time first-run
+tips stay quiet. The change takes effect on the next skill run; no `./setup` is
+needed, because every skill reads `PROACTIVE` from `gstack-skill-start` at the
+start of each run and the router (`/gstack`) applies it to its routing rules. A
+value gstack does not know (a hand-edited `proactive: maybe`) reads as `core`.
+
+Two surfaces follow the setting only in part. The first is the `## Skill routing`
+section gstack offers to append to your project's CLAUDE.md. Under `off` the offer is
+not made, because those rules are the auto-invocation you turned off (a section
+already in CLAUDE.md stays; delete it yourself). Under `core` the offered
+section still lists every routing rule and tells the host to invoke any
+matching skill. If you accepted it before the `core` default, trim that section
+to the four core rules (or delete it and let gstack offer it again); making the
+offered section follow `core` is tracked in #3446.
+
+The second is the full skill descriptions, which a `--catalog-mode=full` build
+and the non-Claude hosts keep. Non-core skills still say "Proactively suggest
+when ..." there, and that text does not change with the setting, so a host
+that picks skills from those descriptions can still reach them under `core`.
+The default Claude build uses one-line descriptions without that sentence.
+#3446 tracks that too.
+
+gstack asks once, after the telemetry question, which of the three you want;
+if you stored `off` before that, it takes the answer as given and does not ask.
+"Say stop suggesting" in a session runs `gstack-config set proactive off` for you.
+
+If collisions with other skill packs keep coming up under `core`, the fallback
+Garry approved on 2026-10-25 is `off` by default.

docs/skills.md

@@ -1236,6 +1236,10 @@ Outside-review routing follows the harness, independently of the configured mode
 
 `/claude` was renamed to `/claude-code` without an alias. Run `./setup --host <name>` to migrate managed installations, including installations sharing that checkout. Setup retains a working old installation when replacement generation or installation fails.
 
+## Proactive skill suggestions
+
+gstack can invoke a skill for you when your request matches one. By default (`proactive: core`) only `/office-hours`, `/review`, `/qa` and `/ship` auto-invoke; `all` frees every skill and `off` suggests nothing. See [docs/proactive.md](proactive.md).
+
 ## Safety & Guardrails
 
 Four skills that add safety rails to any Claude Code session. They work via Claude Code's PreToolUse hooks — transparent, session-scoped, no configuration required.