From 21d428637b939c69eab3294460e41f6fe200eadc Mon Sep 17 00:00:00 2001
From: garrytan <garrytan@gmail.com>
Date: Fri, 30 Oct 2026 22:01:11 +0000
Subject: [PATCH] feat(captain): an ask that needs the owner to act carries the
 exact link and simple steps (R43)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
---
 captain/SKILL.md                       |  5 ++++-
 captain/SKILL.md.tmpl                  |  5 ++++-
 captain/templates/merge-ask.md         |  3 +++
 captain/templates/plan-ask.md          |  6 ++++++
 capy/skill/gstack/factory.md           | 12 ++++++------
 changelog.d/garrytan-r41-ask-format.md |  3 ++-
 docs/captain.md                        | 16 ++++++++++++++++
 7 files changed, 41 insertions(+), 9 deletions(-)

diff --git a/captain/SKILL.md b/captain/SKILL.md
index f249b5cbb..419f294fd 100644
--- a/captain/SKILL.md
+++ b/captain/SKILL.md
@@ -362,7 +362,10 @@ the owner is five: the Captain's name, then one lettered line per decision, lett
 across the list: `- A: <code> hit problem p, which happens when h. We could fix it in these
 ways: 1) x; 2) y; 3) z. Recommendation: x because why. A1 to take recommendation.` The
 recommendation is option 1; "do it" takes every recommendation in the last list, and a named
-option ("A2") takes that option instead. Home: `docs/captain.md`, The ask format.
+option ("A2") takes that option instead. When the owner has to do something, the line
+carries the exact link to the page (never a menu path; a Capy app page gets its exact path
+and field), numbered steps in the simplest words, and the one word to reply when done.
+Home: `docs/captain.md`, The ask format.
 
 **Plan before build.** A lane that builds something runs a sized `/autoplan` on its brief as
 its first act after the session-start check and sends the controller the plan ask above; the controller relays it, and the
diff --git a/captain/SKILL.md.tmpl b/captain/SKILL.md.tmpl
index 27926b03b..4ccf4b36e 100644
--- a/captain/SKILL.md.tmpl
+++ b/captain/SKILL.md.tmpl
@@ -290,7 +290,10 @@ the owner is five: the Captain's name, then one lettered line per decision, lett
 across the list: `- A: <code> hit problem p, which happens when h. We could fix it in these
 ways: 1) x; 2) y; 3) z. Recommendation: x because why. A1 to take recommendation.` The
 recommendation is option 1; "do it" takes every recommendation in the last list, and a named
-option ("A2") takes that option instead. Home: `docs/captain.md`, The ask format.
+option ("A2") takes that option instead. When the owner has to do something, the line
+carries the exact link to the page (never a menu path; a Capy app page gets its exact path
+and field), numbered steps in the simplest words, and the one word to reply when done.
+Home: `docs/captain.md`, The ask format.
 
 **Plan before build.** A lane that builds something runs a sized `/autoplan` on its brief as
 its first act after the session-start check and sends the controller the plan ask above; the controller relays it, and the
diff --git a/captain/templates/merge-ask.md b/captain/templates/merge-ask.md
index 6ec91f2ad..19e6cc3b6 100644
--- a/captain/templates/merge-ask.md
+++ b/captain/templates/merge-ask.md
@@ -26,3 +26,6 @@ flaky: <cases, both runs, ledger date | none> · pregate: pass tree=<tree12>
 The controller's merge report: the PR link, the key image inline, the version it will
 take, the slot, and, if a decision is attached, its lettered line in the ask format
 (gstack docs/captain.md): "A: … Recommendation: x because why. A1 to take recommendation."
+If the merge needs the owner to act (approve a deployment, grant access), the line carries
+the exact link to that page and numbered steps in the simplest words, ending with the one
+word to reply when done (a Capy app page: its exact path and field instead of a link).
diff --git a/captain/templates/plan-ask.md b/captain/templates/plan-ask.md
index 4ef5369f6..ba34245c8 100644
--- a/captain/templates/plan-ask.md
+++ b/captain/templates/plan-ask.md
@@ -32,6 +32,12 @@ output, a screen, a cost or time number>
 **do it** = take every recommendation in this list at full scope, including <the follow-ons
 named: docs, trains, cleanups>, and carry them through to done with no further ask. A named
 option ("A2") takes that option instead.
+
+<only when the owner must act; the exact link, never a menu path (a Capy app page: its exact path and field)>
+- C: <code> needs you to <action>, because <why>. Open <exact URL>, then:
+  1. Click <button>.
+  2. Type <value> in <field>.
+  3. Reply **done**.
 ```
 
 When the answer comes back, record it before the work starts. For an autoplan gate:
diff --git a/capy/skill/gstack/factory.md b/capy/skill/gstack/factory.md
index 061a2a9f1..37323489c 100644
--- a/capy/skill/gstack/factory.md
+++ b/capy/skill/gstack/factory.md
@@ -3,15 +3,15 @@
 What seven Captain crews converged on (2026-10-29). Your crew's CREW.md and recorded approvals decide who may merge, update a base, spend or touch production; urgency changes priority, never permissions or gates. With no Captain, ask the person and never merge without their word. Story: capy/README.md; examples: your org Drive's software-factory/README.md, if any.
 
 1. **Plan, then a yes.** New functionality starts with /autoplan sized to the work; the build waits for "do it". [SKILL.md: Plan, approve, ship]
-2. **Someone else merges.** Run /ship to a receipt on your final pushed head, send one READY quoting gstack's verify output word for word, and stop. The merge owner merges on green and assigns versions. [docs/captain.md: The READY contract, Merge trains]
+2. **Someone else merges.** Run /ship to a receipt on your final pushed head, send one READY quoting gstack's verify output word for word, and stop. The merge owner merges on green and assigns versions. [docs/captain.md: The READY contract]
 3. **Block only on the floor.** A finding blocks if it would fail a test, break production, or lose data or secrets; the rest goes in the PR body or the next wave. [docs/review-policy.md]
-4. **Fix waves.** When main goes red, hold /ship while one owner finds the root cause; bring main in once, as your crew's rules allow. Fold deferred findings and test follow-ups into one wave PR. [docs/triage.md]
+4. **Fix waves.** When main goes red, hold /ship while one owner finds the root cause; bring main in once, as your rules allow. Fold deferred findings and test follow-ups into one wave PR. [docs/triage.md]
 5. **Severe first, same gates.** A severe user-facing bug jumps the queue; the plan can be short, but receipt, checks and merge owner stay.
 6. **Trade findings, not small talk.** A finding that belongs to another crew goes to its Captain, through yours, with the evidence.
-7. **Measure before you act.** Time it, count it, run the real system on the merged tree you ship; a real run outranks a reviewed plan. Each number names its run, commit or uncapped query; say what you did not verify.
+7. **Measure before you act.** Run the real system on the merged tree you ship; a real run outranks a reviewed plan. Each number names its run, commit or uncapped query; say what you did not verify.
 8. **Evals decide, and losses get reported.** Preregister bars, cap and stop rule before paying [/eval-plan]. Cheap proof (a keyless fake, a smoke) before the paid run. Use controls (no-skill and placebo arms, clean decoys). Report use and pass separately; quote spend from the meter.
-9. **Flakes: one rerun, a ledger, a daily fix.** Only the rerun the policy allows, never a harness or infra red; a second red is real; no test is loosened. [AGENTS.md: Validation discipline; docs/captain.md: The daily flaky pass]
+9. **Flakes: one rerun, a ledger, a daily fix.** Only the rerun the policy allows, never a harness or infra red; a second red is real; no test is loosened. [docs/captain.md: The daily flaky pass]
 10. **Quiet.** Message on a decision, a blocker, a READY or a finished phase. A broadcast that needs no reply goes in the Captain's notes; never reply just to acknowledge.
-11. **Ask once, plainly.** One ask per decision, explained like the owner is five: your Captain's name, then a lettered line each: "A: <code> hit problem p, which happens when h. We could do 1) x, 2) y or 3) z. Recommendation x because why. A1 to take recommendation." "do it" takes every recommendation; "A2" takes option 2. Never re-ask a standing rule; check what you can yourself. [docs/captain.md: The ask format]
-12. **Fresh threads, closed out.** One thread per unit of work (crew threads ask their Captain); past the context threshold, hand off. Its Captain archives the threads it, its crew or automations start. Size reviews to the diff; read the token counter, don't estimate. [docs/ship-budget.md]
+11. **Ask once, plainly.** One ask per decision, explained like the owner is five: your Captain's name, then a lettered line each: "A: <code> hit problem p, which happens when h. We could do 1) x, 2) y or 3) z. Recommendation x because why. A1 to take recommendation." "do it" takes every recommendation; "A2" takes option 2. Owner tasks: the exact link (in Capy: path and field), numbered simple steps, the reply word. Never re-ask a standing rule; check what you can yourself. [docs/captain.md: The ask format]
+12. **Fresh threads, closed out.** One thread per unit of work (crew threads ask their Captain); past the context threshold, hand off. Its Captain archives the threads it, its crew or automations start. Size reviews to the diff; read the token counter. [docs/ship-budget.md]
 13. **The owner's model preference.** `gstack-models resolve --role agent` picks agent models, except cross-family voices and eval subjects. [docs/model-policy.md: Your model preference]
diff --git a/changelog.d/garrytan-r41-ask-format.md b/changelog.d/garrytan-r41-ask-format.md
index b6bafae5c..c794c1f55 100644
--- a/changelog.d/garrytan-r41-ask-format.md
+++ b/changelog.d/garrytan-r41-ask-format.md
@@ -1,7 +1,8 @@
-**Every ask to the owner now uses one lettered format (R41): the Captain's name, then one line per decision with the problem, the options and the recommendation, so the owner can answer "do it" or a letter like "B2" from a phone.**
+**Every ask to the owner now uses one lettered format (R41): the Captain's name, then one line per decision with the problem, the options and the recommendation, so the owner can answer "do it" or a letter like "B2" from a phone. When the owner has to do something, the ask links the exact page and lists the steps (R43).**
 
 ### Changed
 - **The plan ask lists each gate choice as a lettered line** (`lib/captain-brief.ts`, `gstack-owner-brief render --captain`): "What we need from you" prints one line per choice with the recommended option first and the plan approval as the last letter. The header and the closing line invite **do it** or a named option, and a new `--captain-name <name>` heads the list. The relaying agent's last line maps every letter to its gate token next to `rec resolves to …` and says a named option answers as `rec except <token>`, so a reply like "B2" translates exactly. A plan that is missing a section still invites no reply.
+- **An ask that needs the owner to do something carries the exact link and simple steps (R43).** The ask format says so: the full URL of the page where it happens (never a menu path like "Settings → Tokens"; a Capy app page gets its exact path and field), numbered steps saying what to click and type, and the one word to reply when done. `docs/captain.md`, `plan-ask.md`, `merge-ask.md`, `captain/SKILL.md` and `factory.md` point 11 carry it.
 - **docs/captain.md has a new section, The ask format**, and the plan ask, the controller's relay and the digest's Needs you point to it. The captain templates (`plan-ask.md`, `DIGEST.md`, `merge-ask.md`, `AGENTS.md`, `report.md`), `captain/SKILL.md`, the Capy gstack skill (`SKILL.md`, `captain.md`, `factory.md`) and `docs/recommended-harness.md` state the same format.
 
 ### Tests
diff --git a/docs/captain.md b/docs/captain.md
index 997c0db7a..ed8c1003c 100644
--- a/docs/captain.md
+++ b/docs/captain.md
@@ -354,6 +354,22 @@ The recommendation is always option 1. "do it" takes every recommendation in the
 list; a named option ("A2") takes that option instead. `<code>` is the issue, PR or thread
 the decision is about. An ask that cannot be put this way is not ready to send.
 
+**When the owner has to do something** (create a token, approve a deployment, accept an
+invite, change a setting), the line carries the exact link to the page where it happens, a
+full URL and never a menu path like "Settings → Tokens", then numbered steps in the
+simplest words: what to click, what to type, what to name it, and the one word to reply
+when it is done. A page inside the Capy app is the one exception, because it has no stable
+link: name the exact path and field instead ("Settings → Integrations → Slack, the Channel
+field").
+
+```text
+<Captain name>
+- A: <code> needs you to <action>, because <why>. Open <exact URL>, then:
+  1. Click <button>.
+  2. Type <value> in <field> and name it <name>.
+  3. Reply **done**.
+```
+
 ## The digest
 
 `DIGEST.md` is rewritten every controller turn: **Needs you** (decisions only the owner