lastlight 0.1.8 → 0.2.0

package/workflows/build.yaml

@@ -2,6 +2,10 @@ kind: build
 name: build
 description: "Architect -> Executor -> Reviewer build cycle"
 trigger: build
+# Render progress as a single in-place task-list comment/message that updates
+# as phases run, instead of a new comment per phase. The per-phase
+# `messages.on_*` below become the one-line detail on each checklist step.
+status_checklist: true
 
 phases:
   - name: phase_0
@@ -12,6 +16,7 @@ phases:
     label: Guardrails
     prompt: prompts/guardrails.md
     model: "{{models.guardrails}}"
+    variant: "{{variants.guardrails}}"
     on_output:
       contains_BLOCKED:
         action: fail
@@ -27,7 +32,7 @@ phases:
       contains_READY:
         action: continue
     messages:
-      on_success: "**Guardrails check: READY** — verified. Starting architect analysis..."
+      on_success: "READY — foundational tooling verified — [guardrails-report.md]({{artifactUrl guardrails-report.md}})"
       on_blocked: |
         **Guardrails check: BLOCKED** — missing foundational tooling.
 
@@ -38,67 +43,72 @@ phases:
     label: Architect
     prompt: prompts/architect.md
     model: "{{models.architect}}"
+    variant: "{{variants.architect}}"
     approval_gate: post_architect
+    approval_artifact: architect-plan.md
     approval_gate_message: |
       **Architect analysis complete** — approval required before implementation.
 
       - Branch: `{{branch}}`
       - Plan: `{{issueDir}}/architect-plan.md`
 
-      **To proceed:** comment `@last-light approve`
-      **To abort:** comment `@last-light reject [reason]`
+      **Review & decide:** {{approvalUrl}}
+      **Or comment:** `@last-light approve` / `@last-light reject [reason]`
     messages:
-      on_success: |
-        **Architect analysis complete.**
-        - Branch: `{{branch}}`
-        - Plan: `{{issueDir}}/architect-plan.md`
-
-        Starting implementation...
+      # Single-line messages become the one-line detail on the checklist step,
+      # so keep them concise and link the artifact on the branch.
+      on_success: "Plan ready — [architect-plan.md]({{artifactUrl architect-plan.md}})"
 
   - name: executor
     label: Executor
     prompt: prompts/executor.md
+    skill: building
     model: "{{models.executor}}"
+    variant: "{{variants.executor}}"
     messages:
-      on_start: "**Starting executor** — implementing the architect's plan..."
-      on_skipped_done: "**Executor** already completed — proceeding to review..."
-      on_success: |
-        **Implementation complete.** Running independent review...
-        - Branch: `{{branch}}`
-        - Summary: `{{issueDir}}/executor-summary.md`
+      on_start: "implementing the architect's plan…"
+      on_skipped_done: "already completed"
+      on_success: "Implemented — [executor-summary.md]({{artifactUrl executor-summary.md}})"
 
   - name: reviewer
     label: Reviewer
     prompt: prompts/reviewer.md
+    # code-review: rubric for the review + re-review prompts.
+    # building: the fix cycle (fix.md) runs under this node and needs the gate.
+    skills: [code-review, building]
     model: "{{models.reviewer}}"
+    variant: "{{variants.reviewer}}"
     output_var: review
     loop:
       max_cycles: 2
       on_request_changes:
         fix_prompt: prompts/fix.md
         fix_model: "{{models.fix}}"
+        fix_variant: "{{variants.fix}}"
         re_review_prompt: prompts/re-reviewer.md
       approval_gate: post_reviewer
+      approval_artifact: reviewer-verdict.md
       messages:
-        on_cycle_start: "**Starting reviewer** (cycle {{cycle}}) — independent verification..."
-        on_approved: "**Review: APPROVED** — proceeding to PR."
-        on_request_changes: "**Review: REQUEST_CHANGES** — fixing issues (cycle {{cycle}}/{{maxCycles}})..."
+        on_cycle_start: "independent verification (cycle {{cycle}})…"
+        on_approved: "Approved — [reviewer-verdict.md]({{artifactUrl reviewer-verdict.md}})"
+        on_request_changes: "**Review: REQUEST_CHANGES** — [reviewer-verdict.md]({{artifactUrl reviewer-verdict.md}}) — fixing issues (cycle {{cycle}}/{{maxCycles}})..."
         on_fix_start: "**Starting fix loop** (cycle {{cycle}}/{{maxCycles}}) — addressing reviewer feedback..."
         on_fix_failed: "Fix cycle {{cycle}} failed. Proceeding to PR with known issues."
-        on_max_cycles: "**Review: REQUEST_CHANGES** after {{maxCycles}} fix cycles. Proceeding with remaining issues noted."
+        on_max_cycles: "**Review: REQUEST_CHANGES** after {{maxCycles}} fix cycles — see [reviewer-verdict.md]({{artifactUrl reviewer-verdict.md}}). Proceeding with remaining issues noted."
         on_pause_for_approval: |
           **Review: REQUEST_CHANGES** — approval required before fix loop.
 
           - Verdict: `{{issueDir}}/reviewer-verdict.md`
 
-          **To proceed with fixes:** comment `@last-light approve`
-          **To abort:** comment `@last-light reject [reason]`
+          **Review & decide:** {{approvalUrl}}
+          **Or comment:** `@last-light approve` / `@last-light reject [reason]`
 
   - name: pr
     label: PR
     prompt: prompts/pr.md
     model: "{{models.pr}}"
+    variant: "{{variants.pr}}"
     on_success:
       set_phase: complete
     messages:
-      on_start: "**Creating PR** — packaging changes for review..."
+      on_start: "packaging changes for review…"

package/workflows/cron-security.yaml

@@ -0,0 +1,6 @@
+kind: cron
+name: weekly-security-scan
+schedule: "0 10 * * 1"
+workflow: security-review
+context:
+  deliverSlackSummary: true

package/workflows/demo.yaml

@@ -0,0 +1,55 @@
+kind: demo
+name: demo
+description: |
+  Record a short demo VIDEO of a PR or feature and post it. Drives the repo's
+  web UI in a real headless browser, screen-records the session, and composites
+  a titled, size-capped mp4 with ffmpeg — delivered inline on the originating
+  issue/PR (and in the dashboard Artifacts view). Does not modify code.
+
+  This workflow's demo phase runs ENTIRELY on the docker backend with the
+  browser-QA image (Playwright + Chromium + ffmpeg baked in). On gondolin, or a
+  docker host without that image, the demo phase is silently SKIPPED (graceful
+  degradation) and the run completes without a video — it never fails the
+  trigger. Compositing is ffmpeg-only (title card, optional before/after,
+  trim/speed, size cap) — there is no Remotion / cinematic pipeline.
+
+  Delivery is a single in-place status comment (`status_checklist`): the run
+  shows its phases ticking off, then the demo phase's report — with the playable
+  video embedded — becomes the comment footer via `final_message`. The agent
+  does NOT post anything itself.
+
+  Triggered by:
+    - a `@last-light demo [notes]` comment on an issue/PR
+    - manual CLI: tsx src/cli.ts demo owner/repo#N [-- "notes"]
+
+status_checklist: true
+final_message: "{{demoResult}}"
+
+phases:
+  - name: phase_0
+    label: Context
+    type: context
+    depends_on: []
+
+  # The demo phase. Gated to the docker backend AND the enriched
+  # `lastlight-sandbox-qa:latest` image (Playwright + Chromium + ffmpeg). On
+  # gondolin, or a docker host without that image, the scheduler silently skips
+  # it (the run still completes — there is no text fallback for a video).
+  - name: demo
+    label: Demo
+    depends_on: [phase_0]
+    prompt: prompts/demo.md
+    # demo: the director procedure + compose-demo.sh wrapper (primary).
+    # browser-qa: the headless driver (agent-browser.mjs) with --record-dir.
+    # building: install + run the repo's dev-server to drive.
+    skills: [demo, browser-qa, building]
+    model: "{{models.demo}}"
+    variant: "{{variants.demo}}"
+    requires_sandbox: docker
+    sandbox_image: qa
+    output_var: demoResult
+    messages:
+      on_start: "Recording a demo — installing, running the app, and capturing the UI..."
+      on_success: "Demo recorded — see the video below."
+      on_failure: "I couldn't record the demo — see the logs for details."
+      on_skipped_done: "Demo unavailable on this host (needs the docker browser-QA image)."

package/workflows/explore.yaml

@@ -8,6 +8,9 @@ description: |
   for Slack-initiated runs).
 
 trigger: explore
+# Single in-place task-list comment/message instead of a comment per phase.
+# Reply-gate questions and the published spec still post as standalone notes.
+status_checklist: true
 
 phases:
   - name: phase_0
@@ -19,6 +22,8 @@ phases:
     prompt: prompts/explore-read.md
     model: "{{models.explore}}"
     output_var: baseline
+    unrestricted_egress: true
+    web_search: true
     messages:
       on_start: "Cloning `{{owner}}/{{repo}}` and reading the codebase..."
 
@@ -26,6 +31,8 @@ phases:
     label: Socratic questioning
     prompt: prompts/explore-ask.md
     model: "{{models.explore}}"
+    unrestricted_egress: true
+    web_search: true
     generic_loop:
       max_iterations: 8
       until: "output.contains('READY')"
@@ -41,6 +48,8 @@ phases:
     prompt: prompts/explore-synthesize.md
     model: "{{models.architect}}"
     output_var: spec
+    unrestricted_egress: true
+    web_search: true
     messages:
       on_start: "Writing up the spec from our conversation..."
 

package/workflows/pr-comment.yaml

@@ -0,0 +1,16 @@
+kind: comment
+name: pr-comment
+description: |
+  Answer a maintainer's question about an open PR with concrete, code-cited
+  evidence. The PR-side counterpart to `issue-comment` — distinguished
+  because PR questions need the diff and a higher file-read cap.
+
+  Triggered by:
+    - issue_comment.created webhook on a PR (when classifier returns a
+      non-build intent and prNumber is set)
+
+phases:
+  - name: respond
+    label: Respond
+    skill: pr-comment
+    model: "{{models.comment}}"

package/workflows/pr-fix.yaml

@@ -2,11 +2,14 @@ kind: pr-fix
 name: pr-fix
 description: "Lightweight PR fix — no architect/reviewer, just fix and push"
 trigger: pr-fix
+# Single in-place task-list comment/message instead of a comment per phase.
+status_checklist: true
 
 phases:
   - name: fix
     label: Fix
     prompt: prompts/pr-fix.md
+    skill: building
     model: "{{models.pr-fix}}"
     messages:
       on_start: "On it — fixing PR #{{prNumber}}..."

package/workflows/pr-review.yaml

@@ -13,5 +13,8 @@ description: |
 phases:
   - name: review
     label: Review
-    skill: pr-review
+    # pr-review: the PR procedure (primary). building: install + test gate.
+    # code-review: the finding-tier + what-to-check rubric.
+    skills: [pr-review, building, code-review]
     model: "{{models.review}}"
+    variant: "{{variants.review}}"

package/workflows/prompts/answer.md

@@ -0,0 +1,67 @@
+You are answering a **question** — the user wants information, an explanation,
+or a comparison, not a code change. Read the `issue-answer` skill for the full
+procedure and rules, then follow it. This prompt gives you the specific question
+and how your answer is delivered.
+
+## The question
+
+{{#if issueTitle}}**Issue title:** {{issueTitle}}{{/if}}
+{{#if issueBody}}
+**Issue body:**
+{{issueBody}}
+{{/if}}
+{{#if commentBody}}
+**Question:**
+{{commentBody}}
+{{/if}}
+
+Target repo: **{{owner}}/{{repo}}**
+{{#if issueNumber}}Originating GitHub issue: **#{{issueNumber}}**{{/if}}
+
+## Workspace
+
+The repo is (or will be) in a `{{repo}}/` subdirectory under your cwd:
+
+```
+ls -la
+```
+
+If you see `{{repo}}/.git/`, the harness pre-cloned it — `cd {{repo}}`.
+Otherwise `git clone https://github.com/{{owner}}/{{repo}}.git {{repo}}` and
+`cd` in. Read what the question needs (`CONTEXT.md`, `README`, `docs/`,
+`spec/`, code) — don't survey the whole tree. Use the `web_search` /
+`web_fetch` tools for anything outside this repo (other tools, frameworks,
+"X vs Y" comparisons); cite what you use.
+
+## How your answer is delivered — read carefully
+
+Your **final message is the answer**, and the harness posts it for you:
+{{#if issueNumber}}
+- as a comment on issue #{{issueNumber}}.
+{{/if}}
+{{#if !issueNumber}}
+- back into the Slack thread this question came from.
+{{/if}}
+
+So make your final message the complete, self-contained answer in clean
+markdown — no "here's what I'll do" preamble, no meta-commentary.
+
+**Converge — don't get cut off.** Your tool budget is bounded. The moment you
+think "I have enough" or "let me just confirm one more thing", stop researching
+and write the answer in that same turn — do **not** fire another tool call
+first. A reply truncated mid-research is worse than one that omits a minor
+detail; flag anything unverified as unverified rather than chasing it with your
+last turn.
+
+**Do NOT post the answer yourself** (no `github_add_issue_comment`) — that would
+double-post. The only GitHub write you make is the label:
+
+{{#if issueNumber}}
+- Apply the `question` label to issue #{{issueNumber}} with `github_add_labels`
+  (create it first with `github_create_label`, color `d876e3`; ignore a 422).
+  Leave the issue open.
+{{/if}}
+{{#if !issueNumber}}
+- This is a Slack-initiated question — there is no issue to label. Just produce
+  the answer.
+{{/if}}

package/workflows/prompts/architect.md

@@ -1,9 +1,11 @@
 You are the ARCHITECT. Analyze the codebase and produce an implementation plan.
 
-SETUP (git is pre-configured, you are in a sandbox workspace):
-1. git clone --branch {{branch}} https://github.com/{{owner}}/{{repo}}.git && cd {{repo}}
-2. Read CLAUDE.md and AGENTS.md if they exist
-3. Read {{issueDir}}/guardrails-report.md for pre-flight results
+You are already inside the {{repo}} repo at branch {{branch}} — the harness
+pre-cloned it and your cwd is the repo root. Git is configured.
+
+Before planning:
+1. Read CLAUDE.md (and CONTRIBUTING.md if present) for project-specific guidance.
+2. Read {{issueDir}}/guardrails-report.md for the test/lint/typecheck commands.
 
 CONTEXT:
 {{contextSnapshot}}
@@ -11,9 +13,24 @@ CONTEXT:
 OUTPUT — write the plan to {{issueDir}}/architect-plan.md:
 - Problem Statement (2-5 sentences with file:line references)
 - Summary of what needs to change
-- Files to modify (with line numbers and what to change)
+- Files to modify — an EXHAUSTIVE manifest the executor implements verbatim:
+  - List EVERY file to change, with the exact path, line/symbol anchor, and what
+    to change. The executor should not need to go hunting for files.
+  - Enumerate ALL members of any multi-file group. If a change touches one
+    member of a set, glob/`ls` the set and list them ALL — e.g. every i18n
+    locale under the locales dir, every adapter/provider variant, every test
+    file for the touched module. Name the exact keys/identifiers to add (e.g.
+    the precise i18n keys). Missing a sibling here forces the executor to
+    rediscover it mid-implementation.
+- Commands — copy the exact test / lint / typecheck commands from
+  guardrails-report.md into the plan so the executor uses them directly.
 - Implementation approach (step-by-step)
 - Risks and edge cases
+  - For every input the design does NOT fully support, specify **warn-and-skip**
+    or **warn-and-surface** behaviour explicitly. A silent default, a silently
+    skipped case, or a dropped output is a correctness bug — never plan for one.
+    If an input can't be handled, the plan must say how the user is told (a
+    warning, a surfaced error), not let it disappear.
 - Test strategy
 - Estimated complexity: simple / medium / complex
 
@@ -21,7 +38,7 @@ AFTER WRITING:
 1. mkdir -p {{issueDir}}
 2. Write architect-plan.md
 3. Write status.md with current_phase: architect
-4. git add .lastlight/ && git commit -m "docs: architect plan for #{{issueNumber}}"
-5. git push -u origin HEAD
+{{#if !externalizeArtifacts}}4. git add .lastlight/ && git commit -m "docs: architect plan for #{{issueNumber}}"
+5. git push -u origin HEAD{{/if}}{{#if externalizeArtifacts}}4. Do NOT git add or commit {{issueDir}}/ — the harness persists it to the Last Light server automatically.{{/if}}
 
 OUTPUT: The branch name and a brief summary (3-5 lines).

package/workflows/prompts/demo.md

@@ -0,0 +1,100 @@
+You are recording a short **demo video** of a PR or feature — driving the
+repo's web UI in a **real headless browser**, screen-recording the session, and
+compositing a titled mp4. Read the `demo` skill for the director procedure and
+the `compose-demo.sh` wrapper, the `browser-qa` skill for the driver contract,
+and the `building` skill for install/run — then follow them.
+
+**Stay in the browser.** Your deliverable is a *moving* demonstration of
+behaviour, not a code walkthrough. Don't quote or analyse source files — show
+what the running app does.
+
+## What to demo
+
+{{#if commentBody}}
+**Request / notes:**
+{{commentBody}}
+{{/if}}
+{{#if issueTitle}}**Issue/PR title:** {{issueTitle}}{{/if}}
+{{#if issueBody}}
+**Issue/PR body:**
+{{issueBody}}
+{{/if}}
+
+Target repo: **{{owner}}/{{repo}}** at branch {{branch}}
+{{#if issueNumber}}Target issue/PR: **#{{issueNumber}}**{{/if}}
+
+Read the PR (description, diff, linked issue) from the context above. Decide the
+single thing the video must prove — the moment that only happens if the change
+works as claimed — and whether the story is a `single` walkthrough (default) or a
+`side-by-side` before/after comparison (only for a genuine regression/refactor).
+
+## First: confirm the browser + ffmpeg are available
+
+Run the driver's probe before anything else (the `browser-qa` skill is staged
+into this phase's bundle — find its absolute path from the available-skills
+catalogue):
+
+```
+node <browser-qa skill dir>/scripts/agent-browser.mjs doctor
+```
+
+If `doctor` exits non-zero, the toolchain isn't present: say so plainly and
+stop — **do not fake a recording.** This phase only runs on the docker QA image,
+so `doctor` should pass.
+
+## Workspace + run the app
+
+You are already inside the **{{repo}}** repo at branch {{branch}} — the harness
+pre-cloned it and your cwd is the repo root (no `cd`). Follow the `building`
+skill to install dependencies and start the dev-server in the background; poll
+with `curl` until it answers on `localhost:<port>`. For a before/after demo,
+run each branch in turn and record the same scripted interaction against each.
+
+## Capture and compose
+
+Author a `flow.json` (shape in the `browser-qa` skill) that scripts the
+interaction like a director — record the baseline first, hold after state
+changes, verify between steps. Record with `--record-dir`:
+
+```
+node <browser-qa skill dir>/scripts/agent-browser.mjs run flow.json \
+  --base-url http://localhost:<port> --record-dir /tmp/demo-cap
+```
+
+Then composite the raw webm into the final mp4 with the `demo` skill's wrapper,
+writing it into **`{{issueDir}}/demo.mp4`** (the harness harvests that dir):
+
+```
+<demo skill dir>/scripts/compose-demo.sh \
+  --output {{issueDir}}/demo.mp4 --title "<PR # — what it does>" \
+  --subtitle "<one line>" --layout single --speed 1.5 --target-size-mb 5 \
+  /tmp/demo-cap/session.webm
+```
+
+Self-check the result with `ffprobe` (the wrapper prints a summary): resolution
+sane, duration watchable (~15–90s), and **size ≤ 5 MB** so GitHub embeds it. If
+it's over, re-run with a lower `--target-size-mb` or a higher `--speed`.
+
+## How your report is delivered — read carefully
+
+Your **final message is the report**, and the harness posts it for you{{#if issueNumber}} as a
+comment on **#{{issueNumber}}**{{/if}}{{#if !issueNumber}} back into the thread this request came from{{/if}}.
+Use the `demo` skill's report shape — a one-line environment summary, a sentence
+on what the video shows and the moment to watch, the video, and a one-line
+"not covered". **Keep it tight.**
+
+**Embed the video inline so it plays in the comment.**
+{{#if artifactBaseUrl}}Your `{{issueDir}}/demo.mp4` is served publicly at
+`{{artifactBaseUrl}}/demo.mp4`. Include a raw HTML video tag on its own line —
+`<video src="{{artifactBaseUrl}}/demo.mp4" controls></video>` — plus a plain
+link beneath it as a fallback: `[demo.mp4]({{artifactBaseUrl}}/demo.mp4)`. GitHub
+renders `<video>` in comments. Do **NOT** wrap the tag in backticks or a code
+fence (inside a code span it shows as literal text instead of playing).{{/if}}{{#if !artifactBaseUrl}}No
+public URL is configured, so reference the video by filename (`demo.mp4`) and
+note it's in the run's Artifacts view.{{/if}}
+
+**Do NOT post it yourself** with `github_add_issue_comment` — that would
+double-post. Never stage or fabricate a result the feature didn't produce; if
+something doesn't work, the honest demo shows it. If the video couldn't be
+recorded or persisted (no server-mode build assets), say so plainly and describe
+what you observed instead of pretending a clip exists.

package/workflows/prompts/executor.md

@@ -1,27 +1,36 @@
 You are the EXECUTOR. Implement precisely what the architect's plan requires.
 
-SETUP (git is pre-configured, you are in a sandbox workspace):
-1. git clone --branch {{branch}} https://github.com/{{owner}}/{{repo}}.git && cd {{repo}}
-2. Read {{issueDir}}/architect-plan.md
-
-EXECUTION:
-- Follow TDD: write failing test first, then implement, then verify
-- Run tests and verify they pass
-
-BEFORE COMMITTING — ALL GUARDRAILS MUST PASS:
-1. Read {{issueDir}}/guardrails-report.md to find the exact commands
-2. Run the test command and verify ALL tests pass (zero failures)
-3. Run the lint command (if present) and fix ALL lint errors
-4. Run the typecheck command (if present) and fix ALL type errors
-5. If any guardrail fails, fix the issue and re-run until clean
-DO NOT commit or claim done until tests, lint, and typecheck all pass.
-
-AFTER ALL GUARDRAILS PASS:
+You are already inside the {{repo}} repo at branch {{branch}} — the harness
+pre-cloned it and your cwd is the repo root. Git is configured.
+
+Start by reading {{issueDir}}/architect-plan.md.
+
+WORK FROM THE PLAN — it contains an exhaustive file manifest and the exact
+commands:
+- Implement the plan's file manifest directly. Read a file only immediately
+  before you edit it; do NOT re-explore areas the plan already mapped.
+- Use grep/find only to fill genuine gaps the plan didn't cover (if the plan
+  is missing a sibling file, fix it there and proceed).
+- Use the test/lint/typecheck commands the plan copied from the guardrails
+  report — no need to re-open guardrails-report.md unless the plan omitted them.
+
+Follow the **building** skill for the mechanics: install dependencies first,
+write the failing test before implementing (TDD), and run the full
+test/lint/typecheck gate once before committing — all of it must pass before you
+commit or claim done.
+
+Before committing, also honour the building skill's **decomposition budget** and
+**type-safety** rules: keep functions under ~15 cyclomatic complexity (a
+function that parses, validates, and emits is three functions — extract helpers),
+and never use `as any` or other compiler-silencing assertions to pass the gate or
+to skip a validator the same code defines. If the repo's only test path needs an
+unavailable external service, add a runnable unit/CLI test with in-memory
+fixtures rather than declaring the change unverified.
+
+AFTER THE GATE PASSES:
 1. Write {{issueDir}}/executor-summary.md:
    - What was done, files changed
-   - Test results (paste actual output)
-   - Lint results (paste actual output)
-   - Typecheck results (paste actual output)
+   - Test / lint / typecheck results (paste actual output)
    - Any deviations from the plan, known issues
 2. Update {{issueDir}}/status.md: current_phase = executor
 3. git add -A && git commit -m "feat: implement #{{issueNumber}}

package/workflows/prompts/explore-ask.md

@@ -2,11 +2,12 @@ You are running a socratic questioning loop to help a maintainer shape a
 half-formed idea into a detailed spec. This is iteration {{iteration}} of
 {{maxIterations}}.
 
-The **{{owner}}/{{repo}}** repo is cloned in your workspace.
+The **{{owner}}/{{repo}}** repo is checked out at `{{repo}}/` (a
+subdirectory of your cwd) — the previous read phase ensured it.
 
-**Important paths** (all absolute — use these exactly):
-- Repo root: `/home/agent/workspace/{{repo}}`
-- Context doc: `/home/agent/workspace/{{repo}}/{{issueDir}}/explore-context.md`
+**Important paths** (relative to the workspace cwd):
+- Repo root: `{{repo}}/` (cd into it to use git)
+- Context doc: `{{issueDir}}/explore-context.md`
 
 Start by reading the context doc for architecture, key code excerpts, and
 existing patterns. Only read additional source files if the context doc
@@ -34,24 +35,46 @@ good spec:
 
 ### If you DON'T have enough signal yet
 
-Read relevant code if it helps sharpen your questions. Then write a short
-message to the user asking **1 to 3 focused clarifying questions**. Keep it
-conversational — the user will reply in the same thread with their answers.
-Good questions:
-
-- pin down scope ("is this only for X, or also for Y?")
-- surface hidden constraints ("does this need to be backwards-compatible
-  with the existing Z?")
-- flush out users / success criteria ("who would use this, and what
-  would make them say 'this worked'?")
-- reference specific code you found ("I see `FooService` handles this
-  today — should the new feature extend it or replace it?")
+Walk down the design tree one branch at a time, resolving dependencies
+between decisions in order — answering an upstream decision often changes
+what the downstream questions even are.
+
+**First, try to answer the question yourself.** If reading the code would
+settle it, read the code instead of asking. Only put a question to the user
+when the codebase genuinely can't decide it.
+
+**Then, of the questions that remain, only ASK about the high-stakes ones**
+— decisions where guessing wrong would be costly or hard to reverse, or
+where the design genuinely forks. **Low-stakes decisions you decide
+yourself**: pick the sensible default (usually "follow the existing
+pattern"), and record it in `{{issueDir}}/explore-context.md` under a
+`## Decisions made during exploration` section (create it if absent), as
+`<decision> → <what you chose> (<one-line why>)`. The user can override
+any of these later; surfacing them in the spec is enough.
+
+When you do ask, ask **one primary question per turn**, and **always give
+your recommended answer** with a one-line rationale grounded in the code
+you read. If a second question is trivially coupled to the first (you can't
+sensibly answer one without the other), you may tack it on as a short
+follow-up — but never a flat list of unrelated questions. Keep it
+conversational; the user replies in the same thread.
+
+Shape of a good turn:
+
+> I see `FooService` already handles this today. I'd **extend** it rather
+> than add a parallel service — it already owns the auth path. Sound right?
+> ↳ If we extend, I'd reuse its existing 5-min cache rather than add a new
+> one (assuming that's fine).
+
+Good questions pin down scope ("only X, or also Y?"), surface hidden
+constraints ("must this stay backwards-compatible with Z?"), flush out
+users / success criteria ("who uses this, and what makes them say it
+worked?"), and reference specific code you found.
 
 If you discover new relevant code, **append it to
-`/home/agent/workspace/{{repo}}/{{issueDir}}/explore-context.md`** so the
-synthesize phase has it too.
+`{{issueDir}}/explore-context.md`** so the synthesize phase has it too.
 
-**Do NOT output the word READY** on this path. Just the questions.
+**Do NOT output the word READY** on this path. Just the question.
 
 ### If you DO have enough signal
 
@@ -63,8 +86,14 @@ advances to the synthesis phase.
 ## Rules
 
 - Never ask the same question twice — check the accumulated Q&A first.
-- Never ask more than 3 questions per iteration.
-- If the user says "we're done" or "just write it up" in their most
-  recent answer, output READY immediately.
+- Ask **one** primary question per turn (plus an optional tightly-coupled
+  follow-up). Never dump a list of unrelated questions.
+- Every question carries your recommended answer — never ask open-endedly
+  without saying what you'd do.
+- Prefer deciding low-stakes items yourself (recorded in the context doc)
+  over asking. Only escalate genuinely high-stakes / forking decisions.
+- If the user says "we're done", "just write it up", or "your
+  recommendations look good" in their most recent answer, output READY
+  immediately.
 - Don't preamble or recap — the user can see the thread already.
 - Use the cloned repo to make your questions specific and grounded.