54: Add agent-readable gate result envelope and parsers

[sandsower]

Summary

• Add a shared Gate result envelope shape for Beislið gate-running orchestrators.
• Define generic text and pytest-oriented parser guidance.
• Update ship-it and heard-chef gate failure handling to prompt from structured envelopes.
• Document gate result envelopes in configuration docs.

Verification

• python3 scripts/validate_skills.py
• python3 scripts/check_skill_size_budgets.py
• git diff --check $(git merge-base HEAD main)...HEAD
• Cross-host smoke: python3 tests/agent-smoke/run.py gate ship-it --hosts claude,codex --timeout 900 --changed-only

Review

• Fast-ship combined review/fresh-eyes completed.
• Post-fix review found no Critical or Important findings.

Closes #54

Summary by CodeRabbit

• New Features

  • Standardized "Gate result envelope" for structured gate results: status, duration, one-line summary, typed failure entries, retryable/environment flags, suggested next action, and raw-log reference.
  • Expanded probe/gate failure prompts with explicit next-step choices (fix / retry / print manual next steps / abort).
  • Autofix behavior clarified: only allowed for retryable non-environment failures; environment/error cases prompt repair/abort.

• Documentation

  • Updated execution/output templates, parser guidance (pytest and generic), phase gate specs, and transcript persistence to include gate envelopes.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9bb7843c-1029-462b-9129-4455a4d04e11

📥 Commits

Reviewing files that changed from the base of the PR and between 56b0e0b and 01d15a1.

📒 Files selected for processing (1)

• docs/configuration.md

✅ Files skipped from review due to trivial changes (1)

• docs/configuration.md

---

📝 Walkthrough

Walkthrough

Adds a structured Gate result envelope and parsers, surfaces the envelope in heard-chef and ship-it templates, updates Phase 2/Phase 3 gate flows to parse/store envelopes and gate autofix/decision paths, and records envelope summaries in transcripts and configuration docs.

Changes

Gate Result Envelope Integration

Layer / File(s)	Summary
Envelope Schema & Parsing Rules .beislid/output-templates.md	Introduces YAML Gate result envelope schema with gate, status, duration_ms, summary, failures, retryable, environment_failure, suggested_next_action, and raw-log reference; adds generic and pytest parsing/prompting rules.
Heard-chef Templates .beislid/heard-chef-templates.md	Replaces/extends probe failure prompts and adds a gate execution failure prompt that consumes the Gate result envelope and renders structured diagnostics plus next-step choices.
Ship-it Templates & Transcript .beislid/ship-it-templates.md	Adds envelope-formatted gate execution failure block and records gate envelope summaries as a distinct transcript event category.
Phase 3 Skill Integration skills/heard-chef/phase-3-push.md	Phase 3 gates now capture duration, parse stdout/stderr into the envelope (pytest or generic), store raw logs/summaries, and only allow autofix for status: fail with environment_failure: false.
Phase 2b Skill Integration skills/ship-it/phase-2-gates.md	Standardizes selection/probing, parses outputs into envelopes (pytest-aware), constrains autofix eligibility, aggregates parallel failures, requires re-runs after fixes, and expands phase tracking to include gate envelopes and approved exceptions.
Configuration Documentation docs/configuration.md	Documents orchestrators emitting gate-result envelopes and selecting parsers (generic or pytest) and updates output.parser guidance accordingly.

Sequence Diagram(s)

sequenceDiagram
  participant Orchestrator
  participant Runner
  participant Parser
  participant Template
  participant Transcript
  Orchestrator->>Runner: execute gate command
  Runner->>Parser: stdout/stderr
  Parser->>Template: Gate result envelope (summary, failures, flags)
  Template->>Orchestrator: render prompt / next-step options
  Template->>Transcript: append gate envelope summary event

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A rabbit hops through gates of code,
I tidy logs and carry the load.
Failures boxed, a clear small note,
Retry, fix, or safely bloat.
Envelope sealed — the route is known.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly describes the main change: adding an agent-readable gate result envelope and parsers, which is the core objective of the PR.
Linked Issues check	✅ Passed	All acceptance criteria from issue #54 are met: gate result envelope fields are documented, generic text and pytest parsers are specified, raw logs are addressed, and orchestrator prompts are updated to use structured envelopes.
Out of Scope Changes check	✅ Passed	All changes are directly aligned with issue #54 objectives: template updates, documentation changes, and phase specifications all implement the gate result envelope and parser requirements.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue-54-gate-result-envelope

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.beislid/heard-chef-templates.md:
- Around line 126-130: Add fenced-code block languages ("text") to the two
language-less code fences shown in the diff: the block that starts with "⚠️ The
gate command `<name>` failed to resolve: <reason>." and the block that starts
with "⚠️ Gate `<name>` failed: <envelope.summary>." Replace each triple-backtick
fence with a language-specified fence (```text) so the blocks satisfy MD040;
ensure both the opening and closing fences are updated and that the inner
content is unchanged.

In @.beislid/ship-it-templates.md:
- Around line 46-51: The fenced-code block containing the gate-failure snippet
starting with "⚠️ Gate `<gate-name>` failed: <envelope.summary>." should be
labeled with a language to satisfy MD040; change the opening fence from ``` to
```text (and keep the existing closing fence) so the block becomes a ```text
fenced code block.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4f1d6de3-9200-4743-9ae4-249abff8cab9

📥 Commits

Reviewing files that changed from the base of the PR and between 04ae1c3 and 824067c.

📒 Files selected for processing (6)

• .beislid/heard-chef-templates.md
• .beislid/output-templates.md
• .beislid/ship-it-templates.md
• docs/configuration.md
• skills/heard-chef/phase-3-push.md
• skills/ship-it/phase-2-gates.md

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/configuration.md`:
- Around line 159-160: The prose describing the agent-readable "envelope" is
ambiguous and omits canonical field names; update the envelope documentation to
list the exact contract keys and types (e.g., gate_name:string, status:string,
duration_ms:integer, failures:array, retryable:boolean, env_failure:boolean,
summary:string, suggested_action:string, raw_log_path:string|null,
transcript_summary:string|null) and show a clear example JSON envelope and how
`output.parser` metadata connects to built-in parsers; update the "envelope"
paragraph and any shared output templates or examples (references: the described
"envelope" and `output.parser`) so parsers/orchestrators consume deterministic
keys.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 453de653-eb07-4a89-a7d0-940bc5bc230c

📥 Commits

Reviewing files that changed from the base of the PR and between 824067c and 56b0e0b.

📒 Files selected for processing (5)

• .beislid/heard-chef-templates.md
• .beislid/ship-it-templates.md
• docs/configuration.md
• skills/heard-chef/phase-3-push.md
• skills/ship-it/phase-2-gates.md

✅ Files skipped from review due to trivial changes (3)

• skills/heard-chef/phase-3-push.md
• .beislid/ship-it-templates.md
• .beislid/heard-chef-templates.md