[shafty023]

Purpose

This PR ships the last 2026-10-22 lessons and an operator ruling as one vibe 1.0.77 release, plus a trim pass. Each lesson gets a mechanical check, proven to fail without its fix. The trim brings 1.0.76 and 1.0.77 together to less instruction text than 1.0.75 had.

Release metadata

• One changelog entry: vibe v1.0.77. One version bump: 1.0.76 to 1.0.77 in both manifests.
• Contract coverage: plugins/vibe/tools/python/test_vibe_1077_lessons_contract.py.
• Net instruction length since 1.0.75 (fix(vibe): ship the 1.0.75 fleet lessons release #336): Markdown under plugins/vibe is about 830 words shorter (7,276 added, 8,108 removed across 1.0.76 and 1.0.77). This PR alone removes about 2,400 net words.
• The trim removes prose a script enforces, keeping the command and one clause of why, and states repeated rules once. No rule was dropped, no test was edited, and every phrase the contract tests pin is kept.

Affected files

• New: plugins/vibe/hooks/foreground-guard.mjs (in hooks/hooks.json), fleet-orchestrator/scripts/mock-gap.mjs, vibe/scripts/pre-pr-lanes.mjs, and their tests.
• Changed scripts: fleet-orchestrator/scripts/board.mjs, green-watch.mjs, codex-fleet-monitor/scripts/snapshot.sh and their tests.
• Trimmed: fleet-orchestrator SKILL.md and references/ (setup, state, templates), codex-fleet-monitor SKILL.md, handoff SKILL.md, vibe SKILL.md, references/quality-loop.md and references/guardrails.md.
• Wiring: agents/vibe-environment-worker.md.

Prevention closeouts

Answers to Claude writers had to be sent three times

Prevention

• Class: answered questions to Claude pane writers in long turns went unseen, because a pane teammate reads messages only between turns. Nothing showed that an answer was never seen, so answers were sent again.
• Instances: fixed fleet-orchestrator/scripts/board.mjs (question ids, answers, acknowledgements), new hooks/foreground-guard.mjs, fleet SKILL.md, references/templates.md.
• Search: rg -n "busy worker|turn ends|Esc|run_in_background|question" plugins/vibe/skills/fleet-orchestrator
• Rung: 1 via the foreground guard. It refuses a foreground Bash call with a timeout over 5 minutes in a vibe session's worktree. Rung 3 via the board:
  • question, answered and ack take --id;
  • status prints QUESTION-UNANSWERED <writer> <id>, and prints UNACKED <writer> <id> for an answer not acknowledged in 15 minutes.
• Proof: each mutation fails its suite.
  • Removing the UNACKED filter fails board.test.mjs.
  • Accepting a question with no id fails it too.
  • Removing the timeout check fails foreground-guard.test.mjs.
• Why not higher: Codex has no plugin hook, and its writers show their questions to the watcher instead.
• Follow-up: none.
• Event recorded: vibe lessons ledger.

The green watcher sat on finished red lanes while one lane was still running

Prevention

• Class: CI results were triaged per batch instead of per lane, so failed lanes sat untriaged behind a long-running lane. A mock check judged whole files instead of mock blocks.
• Instances: fixed fleet-orchestrator/scripts/green-watch.mjs (--state, NEW-RED), new scripts/mock-gap.mjs, fleet SKILL.md green watch practice.
• Search: rg -n "importOriginal|vi\.mock|conclusion" plugins/vibe/skills
• Rung: 3.
  • With --state, green-watch prints NEW-RED the first time a lane fails, while the rest of its batch runs.
  • mock-gap.mjs judges each vi.mock block on its own: it must spread the real module or name every export the code reads.
• Proof: the fixtures have one lane still running beside a failed lane, and a mixed mock file. Removing the NEW-RED marker fails green-watch.test.mjs. Dropping the per-block module match fails mock-gap.test.mjs.
• Why not higher: CI state and test files are outside the plugin.
• Follow-up: none.
• Event recorded: vibe lessons ledger.

Run the Vitest suites CI would run before raising a PR (operator ruling)

Prevention

• Class: PRs opened without running the test lanes PR CI skips, and main broke four times in those suites. The repository's written rule already required those runs.
• Instances: new vibe/scripts/pre-pr-lanes.mjs. It is run by agents/vibe-environment-worker.md (pull-request mode), handoff SKILL.md (its PR-open gate) and fleet SKILL.md (QA prep).
• Search: rg -n "gh pr create|test:lanes|opens the pull request" plugins/vibe
• Rung: 2 or 3. This moves up from the written rule.
  • check --report <lane report output> reads each lane command the report names; e2e lanes are skipped by default.
  • It refuses unless each lane has a passing run, recorded with record, at the current head.
  • A report it cannot read is an error, never "no lanes".
• Proof: the fixture's diff names desktop-renderer and has no record. Dropping the missing-lane filter fails pre-pr-lanes.test.mjs. Accepting a run from an older head fails it too.
• Why not higher: the lane report is the repository's own tool, and its output is text.
• Follow-up: a machine-readable --json from the repository's lane report would remove the text parsing.
• Event recorded: vibe lessons ledger.

The watcher never flagged a Claude writer silent for 1h40m on two open PRs

Prevention

• Class: the watcher's PR list was kept by hand. It held only merged PRs and missed live PRs on other branch prefixes, and Claude pane writers had no liveness check, so a silent writer on two PRs went unflagged.
• Instances: fixed codex-fleet-monitor/scripts/snapshot.sh, monitor SKILL.md, fleet SKILL.md.
• Search: rg -n "prs.txt|PR_SEARCH|WATCH_NEW_PR_REPOS" plugins/vibe/skills
• Rung: 3. The watch set is prs.txt plus every open PR in WATCH_NEW_PR_REPOS that PR_SEARCH lists or WATCH_PR_AUTHOR (default the gh account) opened, on any branch prefix.
  • A merged or closed PR is reported once, then dropped.
  • STALE-PR names the writer from an optional third prs.txt column.
  • The monitor skill names STALE-PR on a Claude pane writer's PR as that writer's liveness signal.
• Proof: the fixture has a stale fix/ PR that is not in prs.txt and a merged PR. It fails on the previous snapshot.sh, and fails again with the prune or the owner name removed.
• Why not higher: a pane teammate's turn state is not readable from a script.
• Follow-up: none.
• Event recorded: no ledger entry yet (a lesson sent by the orchestrator).

The away protocol was skipped after "brb"

Prevention

• Class: the orchestrator answered the operator's "stepping away. brb." with a summary and did not run the written away protocol (attention.md and a recurring check).
• Instances: fixed by a new plugins/vibe/hooks/away-protocol.mjs (UserPromptSubmit in hooks/hooks.json), and fleet SKILL.md.
• Search: rg -n "steps away|attention.md|away" plugins/vibe/skills/fleet-orchestrator
• Rung: 3. This moves up from the written rule, which already existed. On away phrases ("brb", "stepping away", "afk", "going to bed", "heading out", "back in ") the hook adds the away checklist to the turn's context, and on back phrases it adds the return checklist.
• Proof: fixtures cover both phrase sets and negatives such as "go back to the PR". Removing the away match fails away-protocol.test.mjs.
• Why not higher: the hook can remind, but not run the protocol itself.
• Follow-up: none.
• Event recorded: vibe lessons ledger.

Instruction text grew against fleet-orchestrator's own rule

Prevention

• Class: lessons releases added prose next to new checks without removing the prose those checks now enforce. 1.0.76 grew the text by about 1,550 words.
• Instances: fixed by trimming fleet-orchestrator SKILL.md and its references, codex-fleet-monitor SKILL.md, handoff SKILL.md, and vibe SKILL.md, quality-loop.md and guardrails.md.
• Search: the net-words measurement in Release metadata, run against 1.0.75.
• Rung: 4. The fleet-orchestrator rule that a lessons PR reports its net instruction length already exists, and this PR reports it.
• Proof: advisory rung, no proof possible. The contract tests pin the rules' wording, so the trim kept every pinned phrase.
• Why not higher: a word budget gate would fail useful additions; proposed as a follow-up.
• Follow-up: a contract test that fails a lessons release whose Markdown grows without a stated reason.
• Event recorded: no ledger entry (an operator instruction).

Commands run

• Locally, for the changed scripts: node --test on board, foreground-guard, green-watch, mock-gap and pre-pr-lanes, then python3 -m pytest plugins/vibe/tools/python (393 passed).
• On the second machine: ruff, pyright, pytest and every plugin node test, plus npm ci, typecheck, test and build for tools/vibe-workers.

[shafty023]

Local vitest check on tools/vibe-workers at 04dd1cc: 717 of 751 passed, 34 failed. Every failure was a timeout (a test timeout or a spawnSync ETIMEDOUT); none was an assertion failure. This machine was at load average 57 to 84 for the whole run. That means this run proves nothing either way, so the suite still has no clean local run. This PR changes nothing under tools/, and CI ran the same suite green (TypeScript (vibe-workers)).

[shafty023]

The local vibe-workers rerun was abandoned under load (57 to 84); CI's green TypeScript (vibe-workers) run is the evidence for this suite.