From 632bde77def8a05e52db3bdf8f6154315bfab081 Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Sat, 24 Oct 2026 16:55:21 -0700
Subject: [PATCH] v1.91.187.0 docs: unattended contract, gate reply grammar,
 session-kind override and voice triggers match the code (GSTA-69) (#3367)

* docs: unattended contract, gate reply grammar, session-kind override and voice triggers match the code (GSTA-69)

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

* v1.91.187.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>
---
 CHANGELOG.md                   | 11 +++++++++++
 README.md                      | 15 ++++++++++++---
 VERSION                        |  2 +-
 agents-digest/gstack-AGENTS.md |  2 +-
 bin/gstack-gate                |  2 +-
 docs/OPENCLAW.md               |  4 +++-
 docs/troubleshooting.md        |  6 +++---
 docs/unattended.md             | 29 +++++++++++++++++++++++++++--
 lib/owner-brief.ts             |  2 +-
 package.json                   |  2 +-
 10 files changed, 61 insertions(+), 14 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9652e71fd..5bb368b9f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,16 @@
 # Changelog
 
+## [1.91.187.0] - 2026-10-24
+
+**Four docs now say what the code does: the unattended run contract, the gate reply grammar, the session-kind override and voice triggers.** All four were reported by readers who checked the docs against the code. `docs/unattended.md` promised that every workflow skill ends an unattended run with a run directory and a `GSTACK_RESULT` line, but only `/autoplan` has the steps and helpers that write one (#3281, thanks @exGeni). `gstack-gate --help` still taught the reply grammar from before 1.91.107.0, without `rec` or `as-is`, while the render it relays leads with `rec` (#3282, thanks @exGeni). `docs/OPENCLAW.md` said only `spawned` is honored as a `GSTACK_SESSION_KIND` override, but `unattended` is honored too (#3287, thanks @exGeni). The README said natural phrases activate the right skill, without saying that only `voice-triggers:` aliases reach a host and that the plain `triggers:` list does not (#2118, thanks @jinzheio).
+
+### Fixed
+- **`docs/unattended.md`**: the terminal-line section lists who writes the line today: `/autoplan` (the only skill that writes a run directory), the workflow commands `gstack-pregate`, `gstack-regen`, `gstack-restamp` and `gstack-ship-queue` (each naming its own record), and a refused launch (`status=refused run=-`). For `/ship`, `/review`, `/qa` and the other workflow skills it says not to wait for a run directory and names each skill's own record to read instead. It also says `/eval-plan` has no `gate.json` writer yet and that `/cso` skips the shared unattended rules.
+- **`bin/gstack-gate --help`** and the `/autoplan` owner brief's answer hint (`lib/owner-brief.ts`) show the current grammar: `rec` (alias `all`), `rec except <tokens>`, `<id><option>` tokens and `as-is`. Display text only; the parser is unchanged and `all` still parses the same as `rec`.
+- **`docs/troubleshooting.md#gate-reply-unparsed`** gives the same grammar in its fix line.
+- **`docs/OPENCLAW.md`**: the `GSTACK_SESSION_KIND` section says `spawned` and `unattended` are honored, and links to `unattended.md`.
+- **`README.md`**: the voice input section says which phrases a host sees (`voice-triggers:` aliases, as router lines on Claude Code and in each description elsewhere) and that `triggers:` is metadata that does not make a skill activate.
+
 ## [1.91.186.0] - 2026-10-24
 
 **Approving an autoplan run no longer fails one time in ten because its run id looks like a card number.** Today's daily flaky-fix pass found `test/capy-captain-flow.test.ts` failing once and passing on the serial retry in 7 of the 57 Free Tests runs from 2026-10-21 to 2026-10-23, one of them a push to main (39878113535). Every failure had the same assertion: `gstack-approvals import` refused the approval row with "field ask: pii.cc". The default autoplan run id is `run-YYYYMMDDHHMMSS`, the import writes it into the row's ask and source, and the credit-card rule saw those 14 digits as a card number whenever they passed the Luhn check, which a timestamp does about one time in ten. A real user's approval import failed the same way.
diff --git a/README.md b/README.md
index 2e2fd0eaa..f09877d66 100644
--- a/README.md
+++ b/README.md
@@ -513,9 +513,18 @@ The sprint structure is what makes parallelism work. Without a process, ten agen
 
 ### Voice input (AquaVoice, Whisper, etc.)
 
-gstack skills have voice-friendly trigger phrases. Say what you want naturally —
-"run a security check", "test the website", "do an engineering review" — and the
-right skill activates. You don't need to remember slash command names or acronyms.
+Many gstack skills list speech-to-text aliases (`voice-triggers:` in their
+templates): "security check" for `/cso`, "run QA" or "test the app" for `/qa`,
+"tech review" for `/plan-eng-review`. Say one of those naturally and the right
+skill can be picked without the slash command name. On Claude Code the aliases
+are routing lines in the root `/gstack` router; on Codex and the other hosts
+they are appended to each skill's description, which is what those hosts match
+on.
+
+The separate `triggers:` list in a skill's frontmatter is gstack metadata, not a
+matching surface. Claude Code and Codex choose a skill from its name and
+description, so a phrase that appears only under `triggers:` does not activate
+the skill (Codex output drops the field; the GBrain host keeps it).
 
 ## Uninstall
 
diff --git a/VERSION b/VERSION
index ab330a4ad..7143a7b3a 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-1.91.186.0
+1.91.187.0
diff --git a/agents-digest/gstack-AGENTS.md b/agents-digest/gstack-AGENTS.md
index 177cc23f8..31778cde5 100644
--- a/agents-digest/gstack-AGENTS.md
+++ b/agents-digest/gstack-AGENTS.md
@@ -1,4 +1,4 @@
-# gstack digest v1.91.186.0 — regenerate/re-copy after upgrading gstack
+# gstack digest v1.91.187.0 — regenerate/re-copy after upgrading gstack
 
 Behavioral rules from gstack (https://github.com/garrytan/gstack), compressed
 for agent hosts without a full skill install. The full skills add workflows,
diff --git a/bin/gstack-gate b/bin/gstack-gate
index 1d71f4c87..4e8b15a68 100755
--- a/bin/gstack-gate
+++ b/bin/gstack-gate
@@ -22,7 +22,7 @@ const HELP = `gstack-gate — one gate list, one reply grammar
   decisions <gate.json> [--reply "<text>" --gate-rev N] [--answered-at ISO]
                                                         decisions.jsonl rows (pending, or applied when a reply is given)
 
-Reply grammar: \`all\` · \`<id><option>\` tokens (\`d3b uc1a\`) · \`all except <tokens>\`. Bare yes/no is rejected.
+Reply grammar: \`rec\` (alias \`all\`) · \`rec except <tokens>\` · \`<id><option>\` tokens (\`d3b uc1a\`) · \`as-is\` (the plan as written). Bare yes/no is rejected.
 gate.json: {"schema_version":1,"run":"<id>","gate_rev":1,"items":[{"id":"d1","title":"…","kind":"auto|approval","recommended":"a","options":[{"key":"a","text":"…"},…]}]}
 ${exitTableHelp()}`;
 
diff --git a/docs/OPENCLAW.md b/docs/OPENCLAW.md
index 2f1b162bb..498484621 100644
--- a/docs/OPENCLAW.md
+++ b/docs/OPENCLAW.md
@@ -152,7 +152,9 @@ gstack itself uses this: `/ship` Step 14.5 dispatches the `/document-release`
 subagent with this prefix before final commit, verification and publication.
 Its ship-owned scope overrides generic spawned auto-choice: risky or uncertain
 documentation changes return as blockers for the parent, without interactive
-questions or automatic approval. Deliberately narrow: only `spawned` is honored — `headless`
+questions or automatic approval. Deliberately narrow: only `spawned` and `unattended` are honored
+(`unattended` is a separate, explicitly selected contract for a parent that
+reads a run's artifacts; see [unattended.md](unattended.md)) — `headless`
 already has `GSTACK_HEADLESS`, and letting an env var force `interactive`
 over CI markers would be a misclassification footgun. Empty or other values
 are reserved and ignored (fall through to ambient detection). Note that hook
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 027d071eb..56f086d21 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -2440,9 +2440,9 @@ reply with the printed `gate_rev`.
 **Meaning.** Part of the reply matched no gate item or option. Nothing was
 applied; the unparsed tokens are listed.
 
-**Fix.** Reply with `all`, with `<id><option>` tokens (`d3b uc1a`), or with
-`all except <tokens>`. A bare `yes` or `no` is ambiguous across multi-option
-items and is never guessed.
+**Fix.** Reply with `rec` (alias `all`), with `rec except <tokens>`, with
+`<id><option>` tokens (`d3b uc1a`), or with `as-is` (the plan as written). A
+bare `yes` or `no` is ambiguous across multi-option items and is never guessed.
 
 <a id="answer-by-required"></a>
 ### `ANSWER_BY_REQUIRED`
diff --git a/docs/unattended.md b/docs/unattended.md
index 457a58896..b4f1c1fc1 100644
--- a/docs/unattended.md
+++ b/docs/unattended.md
@@ -57,18 +57,41 @@ An unknown `GSTACK_SESSION_KIND` value coerces to `interactive` and says so:
 
 ## The terminal line
 
-Every workflow skill ends an unattended run with one line the parent greps:
+A run that writes a record ends with one line the parent greps:
 
 ```
 GSTACK_RESULT: skill=<name> status=<status> run=<dir>
 ```
 
 `status` is one of `complete`, `gate_pending`, `incomplete`, `interrupted` or
-`refused`; `run` is the directory that holds the artifacts below. `/autoplan`
+`refused`; `run` is where the run's record is. `/autoplan`
 always ends `gate_pending` when it reaches the final gate, because the gate is
 written and never approved. Pure queries (`gstack-artifact schema`,
 `gstack-gate render`) print no result line.
 
+Not every workflow writes this line or a run directory today:
+
+- **`/autoplan`** writes the full run directory below through `gstack-autoplan`,
+  and `gstack-artifact validate` checks it. It is the only skill with steps
+  and helpers that write `run.json`, `decisions.jsonl` and `gate.json`.
+- **Workflow commands** `gstack-pregate`, `gstack-regen`, `gstack-restamp` and
+  `gstack-ship-queue` print their own line, with `run=` naming their own record
+  (the pregate receipt, the regen worktree, the restamp journal, the queue
+  record), not a run directory.
+- **A refused launch.** Any skill whose install check refuses it at startup
+  prints `GSTACK_RESULT: skill=<name> status=refused run=-` and stops.
+- **Every other workflow skill** (`/ship`, `/review`, `/qa`, `/design-review`,
+  `/spec`, `/land-and-deploy` and the rest) gets the session rules above (no
+  prompts, approvals stay pending, nothing published), but has no step that
+  writes a run directory or prints the line, so a parent should not wait for
+  either. `/eval-plan` asks for a `gate_pending` line at its spend gate, but no
+  helper writes its `gate.json` yet (`gstack-gate` renders and parses a gate
+  list; it does not create one). `/cso` skips the shared startup, so these
+  session rules do not reach it at all. Read each skill's own record instead:
+  the ship receipt in the PR body (`gstack-ship-receipt read --pr <n> --json`)
+  for `/ship`, the review-log rows (`gstack-review-read`) for `/review`, and the
+  `qa-report-*.md` file for `/qa`.
+
 Every workflow command shares one exit table: `0` ok, `1` fail, `2` usage,
 `3` refused or needs a flag. Error lines end with a result code in parentheses,
 for example `findings.jsonl:12: ... (ARTIFACT_SCHEMA)`; each code has an anchor
@@ -77,6 +100,8 @@ a `fix:` clause. Grep the code, not the prose.
 
 ## The run directory
 
+`/autoplan` writes these files; the next section shows how a parent reads them.
+
 | File | Schema | Contents |
 |------|--------|----------|
 | `run.json` | `run` v1 | The manifest: `run` id, `status`, `required_phases`, each phase's `native` and `outside` outcome (`status`, `model`, `provider`), input `snapshot` hashes, `counts`, every artifact's `path` (relative to the run directory) and `sha256`, `session_kind`, `gate_rev`, `deviations`, `consumed_by`. |
diff --git a/lib/owner-brief.ts b/lib/owner-brief.ts
index da9617c4b..27d643d59 100644
--- a/lib/owner-brief.ts
+++ b/lib/owner-brief.ts
@@ -90,7 +90,7 @@ export function renderBrief(inputs: BriefInputs, o: { page?: number; summary?: s
     '',
     renderDecisions(inputs, page).trimEnd(),
     '',
-    `Full review: ${record}${recordNote}. Answer with \`gstack-autoplan answer --out <dir> --gate-rev ${inputs.gate.gate_rev} --reply "<all | d3b uc1a | all except d3b>" --by human\`.`,
+    `Full review: ${record}${recordNote}. Answer with \`gstack-autoplan answer --out <dir> --gate-rev ${inputs.gate.gate_rev} --reply "<rec | rec except d3b | d3b uc1a | as-is>" --by human\`.`,
     '',
   ].join('\n');
 }
diff --git a/package.json b/package.json
index e1959b316..923c205ef 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "gstack",
-  "version": "1.91.186",
+  "version": "1.91.187",
   "description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.",
   "license": "MIT",
   "type": "module",