Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

docs(pr-delivery): separate gate evidence from user reports (#2684)

Call White4723deba40bb
diff --git a/.agents/skills/pr-delivery-loop/SKILL.md b/.agents/skills/pr-delivery-loop/SKILL.md
index d8f7d1f57..0df942b07 100644
--- a/.agents/skills/pr-delivery-loop/SKILL.md
+++ b/.agents/skills/pr-delivery-loop/SKILL.md
@@ -142,7 +142,8 @@ do not load them routinely. They introduce no additional delivery gates.
their drafts, report the blocker, keep observation live, and continue safe
work. Retry the reply after they submit/discard it; do not hide the open thread.
- Notify findings/errors promptly; keep half-success silent until CI/review
- both pass. Fix reports include PR/head; no round-summary PR comments.
+ both pass. Internal round notes name the PR/head, findings addressed, and
+ remaining gates in one or two lines; do not add round-summary PR comments.
## 4. Complete delivery
@@ -155,8 +156,12 @@ Before closing out, verify all review gates together:
evidence blocks the gate.
3. Zero unresolved threads across the entire PR, including older/outdated heads.
-The final report names the repository, PR URL, reviewed head, changes,
-validation layers, and residual manual/E2E work.
+Keep exact head-bound evidence in the internal gate record and lane reports.
+For the user, briefly explain residual issues (or none known), what changed and
+why it matters, and the next step/merge readiness. Include a clickable PR link.
+SHAs, run/check/thread/Watch counts, and gate-state dumps belong in the evidence,
+not the default reply; surface them only to explain a blocker or on request.
+Do not turn these questions into a rigid report template.
In a user-started orchestrator session, close out in the current turn: verify
the gates, remove the Watch, then send the final report to the user. Do not
@@ -190,15 +195,10 @@ deployment. Neither merge nor close-out authorizes deployment or a restart.
## 5. User-facing next actions
-Only the orchestrator's final **user-facing** report offers action buttons,
-never an internal lane report or GitHub comment. Name one repository/PR and its
-reviewed head. Use actual destination capability and reply-enhancement settings:
-when supported and enabled, append the trailing `---` and `[label]` syntax from
-Avibe's `core/prompts/quick-replies.md`, outside code fences. Otherwise, including
-unknown capability/settings, use ordinary visible prose with the PR URL in each
-suggested reply, without a trailing separator/bracket row that could be stripped.
-
-Use the conversation language, English when unknown, and honor explicit labels:
+Only the orchestrator's user-facing delivery report offers PR action buttons,
+not internal lane reports or GitHub comments. Use the conversation language and
+honor requested labels. When buttons are unsupported, disabled, or unknown,
+use ordinary visible prose with the target PR URL, not a strip-prone footer.
| Action | Chinese | English |
| --- | --- | --- |
@@ -206,63 +206,28 @@ Use the conversation language, English when unknown, and honor explicit labels:
| Update local master regression | 更新回归 | Update master |
| Update and verify end to end | 更新并验证 | Update + E2E |
-**Bind every action to its target before mutation.** The callback submits only
-the label; adjacent prose and Markdown links add no hidden payload. Recover the
-source report from actual source-message metadata when available. If unavailable
-or not uniquely bound to a repository/PR, ask for the PR URL. Never select the
-latest mention, current worktree, or only open PR. An explicit user target
-resolves ambiguity without extra confirmation; do not change requested labels
-or invent a payload format.
-
-- Offer **Merge** only when the review, CI, and thread gates pass and the PR is
- open, non-draft, and `CLEAN`. Offering it is not authorization. After binding a
- click, re-fetch the head and gates; if the offered head changed or readiness
- was lost, report that change and refresh the offer instead of using stale approval.
-- After GitHub confirms the named PR is **MERGED**, replace Merge with both
- regression choices and name the local target. Closed/unmerged is not merged.
- State in the report that both choices update from master; keep labels short.
- Update + E2E performs the same update, then relevant end-to-end verification.
- Both are separate opt-ins, not implied by merge. For Chinese reports:
-
- ```text
- ---
- [更新回归] | [更新并验证]
- ```
+- When review, CI, and thread gates pass and the PR is open, non-draft, and
+ `CLEAN`, offer Merge with the PR link unless the owner asked not to offer it.
+ Lack of auto-merge authority does not hide this option; offering is not
+ executing. A single Merge button is enough.
+- Before offering a mutating action, persist the target PR and exact offered head
+ in source-bound action metadata or the internal source report; the visible
+ report may omit the SHA, but the callback must be able to compare that bound
+ head with the freshly fetched head. If the destination cannot retain this
+ binding, do not offer a label-only mutation button.
+- Bind a click to its source report using actual source-message metadata, or to
+ an explicit user-named target. Labels and adjacent links carry no hidden PR or
+ SHA payload. If the target is ambiguous, ask for the PR URL; never guess from
+ the latest mention, current worktree, or only open PR. Re-fetch the bound head
+ and gates; if the offered head changed or readiness was lost, refresh the
+ offer instead of using stale approval.
+- After GitHub confirms **MERGED**, replace Merge with both regression choices
+ only where that repository documents a local workflow. Name the local target;
+ both update from master, and Update + E2E also verifies the affected flows.
+ Neither runs without a separate opt-in.
### Authorized local regression updates
-For Avibe, bind the action and recheck `MERGED`, then follow
-`docs/regression/README.md`. Other repos offer these choices only when their own
-documented local workflow applies; never invent a target.
-
-1. Fetch origin and fast-forward the **primary** checkout with `--ff-only`;
- verify `master` equals the fetched `origin/master` SHA. Establish that the
- actual `sync_source()` input, including ignored deployable files, matches that
- Git tree under the runner's sender exclusions, and keep it unchanged through
- the update. Git status or `dirty=false` alone is not proof. A mismatch or an
- unprovable match blocks mutation; never stash, discard, or commit user edits
- to bypass it. Invoke the runner from this verified checkout, not a task tree.
-2. Confirm the persistent **local** master environment (`avr-master` /
- `avibe-master` by default), product config, and runtime environment file exist
- and are readable. Missing state is a blocker, not provisioning/re-seeding
- authority. Use the documented local Lima route on macOS; preserve existing
- bind/port settings explicitly when different from defaults.
-3. For the existing target, run from the verified checkout:
-
- ```bash
- python3 scripts/incus_regression.py up --target master --reset-mode none --clean --env-file /dev/null
- ```
-
- `--env-file /dev/null` suppresses automatic env discovery and leaves
- `/etc/avibe-regression.env` untouched; an empty regular file does not.
- Stop before mutation if the checked-out runner cannot preserve this behavior.
- `--clean` reconciles disposable source/build output, including same-size,
- same-mtime stale bytes. Preserve credentials, runtime environment, product
- state, pairing, agent homes, and sessions; neither choice authorizes a reset.
-4. Let the runner rebuild assets. Verify the receipt and served source commit
- match the intended SHA and the runtime environment is unchanged without
- exposing values, before success or E2E checks. Report environment, deployed
- commit, and actual test results; health alone is not an end-to-end pass.
-
-Neither choice authorizes production, a remote tenant, or the running local Avibe
-to be updated or restarted.
+After the owner opts in, read [Local regression](references/local-regression.md)
+before any update. It preserves the existing local target, source-verification,
+and state-protection procedure; do not load it during routine PR review.
diff --git a/.agents/skills/pr-delivery-loop/references/local-regression.md b/.agents/skills/pr-delivery-loop/references/local-regression.md
new file mode 100644
index 000000000..e3081ec8d
--- /dev/null
+++ b/.agents/skills/pr-delivery-loop/references/local-regression.md
@@ -0,0 +1,35 @@
+# Local regression
+
+For Avibe, bind the action and recheck `MERGED`, then follow this procedure. Other repos offer these choices only when their own documented local workflow applies; never invent a target.
+
+1. Fetch origin and fast-forward the **primary** checkout with `--ff-only`;
+ verify `master` equals the fetched `origin/master` SHA. Establish that the
+ actual `sync_source()` input, including ignored deployable files, matches that
+ Git tree under the runner's sender exclusions, and keep it unchanged through
+ the update. Git status or `dirty=false` alone is not proof. A mismatch or an
+ unprovable match blocks mutation; never stash, discard, or commit user edits
+ to bypass it. Invoke the runner from this verified checkout, not a task tree.
+2. Confirm the persistent **local** master environment (`avr-master` /
+ `avibe-master` by default), product config, and runtime environment file exist
+ and are readable. Missing state is a blocker, not provisioning/re-seeding
+ authority. Use the documented local Lima route on macOS; preserve existing
+ bind/port settings explicitly when different from defaults.
+3. For the existing target, run from the verified checkout:
+
+ ```bash
+ python3 scripts/incus_regression.py up --target master --reset-mode none --clean --env-file /dev/null
+ ```
+
+ `--env-file /dev/null` suppresses automatic env discovery and leaves
+ `/etc/avibe-regression.env` untouched; an empty regular file does not.
+ Stop before mutation if the checked-out runner cannot preserve this behavior.
+ `--clean` reconciles disposable source/build output, including same-size,
+ same-mtime stale bytes. Preserve credentials, runtime environment, product
+ state, pairing, agent homes, and sessions; neither choice authorizes a reset.
+4. Let the runner rebuild assets. Verify the receipt and served source commit
+ match the intended SHA and the runtime environment is unchanged without
+ exposing values, before success or E2E checks. Report environment, deployed
+ commit, and actual test results; health alone is not an end-to-end pass.
+
+Neither choice authorizes production, a remote tenant, or the running local Avibe
+to be updated or restarted.
diff --git a/.agents/skills/pr-delivery-loop/references/rationale.md b/.agents/skills/pr-delivery-loop/references/rationale.md
index f4e9ce546..41d80b928 100644
--- a/.agents/skills/pr-delivery-loop/references/rationale.md
+++ b/.agents/skills/pr-delivery-loop/references/rationale.md
@@ -40,6 +40,14 @@ A lane Run marked `succeeded` proves only that invocation ended successfully.
It does not prove that the current-head review started, the Watch remains live,
or the orchestrator received a report. Those are separate observations.
+## Gate evidence and user reports are different surfaces
+
+Exact head, run, thread, and Watch evidence protects the delivery gate, but it is
+not the user-facing result. Keep that evidence in the internal record; the final
+report should state residual issues, the change and its benefit, the next action,
+and merge readiness. Expose identifiers only when they explain a blocker or the
+user asks for evidence.
+
## A repeated finding calls for diagnosis, not automatic expansion
If a reviewer flags a searchable row's projected title, similar fields may
diff --git a/core/prompts/quick-replies.md b/core/prompts/quick-replies.md
index 40673e6ea..e08a816c6 100644
--- a/core/prompts/quick-replies.md
+++ b/core/prompts/quick-replies.md
@@ -1,10 +1,12 @@
## Quick-reply buttons
-At the very end of the message, add a `---` separator followed by `[button text]` to provide clickable quick replies. Example:
+Offer buttons for useful next actions or decisions, not to fill every reply.
+When none is useful, omit the footer. A single relevant action is enough.
+
+When buttons are supported and enabled, put this exact multiline footer at the very end:
+```text
---
-[👌 Continue] | [✅ Submit PR] | [👀 Review first]
-Rules:
-- Think through the tacit knowledge behind the user's words, infer their deeper intent, and suggest likely next replies from the conversation context and the user's habits
-- Do not add filler unrelated to the user's likely next intent, such as: got it, received, thanks
-- They must appear at the very end of the message, after the `---` separator
-- Wrap each button in `[text]` and separate them with `|`; you may start with emoji to improve clarity
-- Use at most 2-4 buttons, each no longer than 20 characters
+[button text] | [another action]
+```
+Use at most four short labels, each no longer than 20 characters, in the
+conversation language. Do not invent filler choices or treat displaying an
+action as authorization to execute it.
diff --git a/tests/test_harness_skill_guidance.py b/tests/test_harness_skill_guidance.py
index 72f33e903..d8d12e77e 100644
--- a/tests/test_harness_skill_guidance.py
+++ b/tests/test_harness_skill_guidance.py
@@ -240,28 +240,45 @@ def test_background_watch_skill_uses_bundled_waiters_and_persists_managed_pr_sta
assert '--workflow lint' in body
-def test_pr_delivery_loop_keeps_one_optional_reference_out_of_routine_loading() -> None:
+def test_pr_delivery_loop_keeps_optional_references_out_of_routine_loading() -> None:
directory = ROOT / ".agents/skills/pr-delivery-loop"
body = (directory / "SKILL.md").read_text()
flat = " ".join(body.split())
references = re.findall(r"\]\((references/[^)]+\.md)\)", body)
- assert references == ["references/rationale.md"]
+ assert references == ["references/rationale.md", "references/local-regression.md"]
assert {path.relative_to(directory).as_posix() for path in directory.rglob("*.md")} == {
"SKILL.md", *references,
}
assert "are optional reading" in flat and "do not load them routinely" in flat
assert "They introduce no additional delivery gates." in flat
assert "sync the **whole maintained package**, including references, byte-for-byte" in flat
+ assert "Keep exact head-bound evidence in the internal gate record" in flat
+ assert "residual issues (or none known)" in flat
+ assert "gate-state dumps belong in the evidence" in flat
+ assert "offer Merge with the PR link" in flat
+ assert "persist the target PR and exact offered head" in flat
+ assert "visible report may omit the SHA" in flat
skill = parse_skill_file(directory / "SKILL.md", priority=(1, 0, 1))
assert skill is not None
rendered = render_skill_content(skill)
assert "## 4. Complete delivery" in rendered
assert "### Authorized local regression updates" in rendered
- reference = (directory / references[0]).read_text()
- assert reference.startswith("# Delivery Rationale and Examples")
- assert reference not in rendered
+ for reference_path in references:
+ reference = (directory / reference_path).read_text()
+ assert reference not in rendered
+
+
+def test_quick_replies_are_action_driven_not_mandatory() -> None:
+ body = _read("core/prompts/quick-replies.md")
+ flat = " ".join(body.split())
+ assert "Offer buttons for useful next actions or decisions" in body
+ assert "When buttons are supported and enabled, put this exact multiline footer" in body
+ assert "---\n[button text] | [another action]" in body
+ assert "When none is useful, omit the footer" in body
+ assert "Do not invent filler choices" in body
+ assert "treat displaying an action as authorization" in flat
def test_agent_prompt_audit_examples_parse_against_the_real_cli() -> None:
diff --git a/tests/test_prompt_render_export.py b/tests/test_prompt_render_export.py
index 96fb31436..260934b42 100644
--- a/tests/test_prompt_render_export.py
+++ b/tests/test_prompt_render_export.py
@@ -522,6 +522,7 @@ def test_approved_guidance_changes_preserve_all_other_injection_bytes(monkeypatc
"skills-prompt",
"skills-manual-prompt",
"codex-skill-reuse",
+ "quick-replies-prompt",
}
for backend, history, skill_mode in itertools.product(
("claude", "codex", "opencode"), ("off", "managed", "self-managed"), ("empty", "manual", "pages"),
@@ -536,10 +537,10 @@ def test_approved_guidance_changes_preserve_all_other_injection_bytes(monkeypatc
text = text.replace(_FOLLOW_THROUGH_PRINCIPLE, _PREVIOUS_FOLLOW_THROUGH_PRINCIPLE)
outputs.append(text.replace(_EVIDENCE_LED_PRINCIPLE, _PREVIOUS_VERIFICATION_PRINCIPLE))
digest = hashlib.sha256(json.dumps(outputs, ensure_ascii=False).encode()).hexdigest()
- # Captured before editing from 1e9ba96bc61b0e86027d4871553e68e8ed85c1ac,
- # omitting only the approved Computer Use and Skill-loading guidance blocks
- # (including the Codex-only reuse sentence) and restoring the previous
- # verification principle and conversation-history guidance and Follow-through
- # principle.
+ # Captured before editing from b4eb5cca140955d7e6f7f4206c793892cf19ef59,
+ # omitting only the approved quick-reply, Computer Use and Skill-loading
+ # guidance blocks (including the Codex-only reuse sentence) and restoring the
+ # previous verification principle and conversation-history guidance and
+ # Follow-through principle.
# Every other byte/order stays pinned, including all Claude/OpenCode output.
- assert digest == "262c7cbabbbb0bfefa4a69511d805d28f76a3559bd511184006242f831b4836e"
+ assert digest == "9475df69a6c14f6ddda396dc33d665f4ebda657517cd3ea3134d23d7f5c5c712"