Skip to content

[Phase 5] Wire the standard into AGENTS.md and per-agent docs, and reconcile the ci-failure-analyst spec vs deployed divergence #1409

Closed

Description

@github-actions

Story

As a engineer navigating the agentic docs,
I want AGENTS.md and each agent doc linking the interaction model, and the stale ci-failure-analyst spec reconciled to its deployed reality,
so that the standard is discoverable from every entry point and the one known spec/deploy divergence no longer misleads implementers.

Acceptance Criteria

  1. AGENTS.md gains an "Agentic interaction model" section linking docs/agentic-interaction-model.md.
  2. Each agent doc (docs/dev-lead/, docs/pr-review-agent/, docs/aw/ci-failure-analyst.md) gains an "Interaction contract" subsection linking the role's contract and the standard.
  3. The ci-failure-analyst spec/deploy divergence is reconciled: the deployed thin caller ci-failure-analyst.lock.yml triggers on check_run:completed and posts live (issues: write), while the ci-failure-analyst.md gh-aw source declares workflow_run + staged: true + max: 1 — the docs/spec are corrected to describe the deployed behaviour (or the orphaned source is removed), so they agree.
  4. The reconciliation does not change the deployed ci-failure-analyst runtime behaviour; it only makes the spec/doc match reality (the .lock.yml stub is a byte-frozen ring-0 caller and is not edited).
  5. No new schedule.cron or trigger is introduced by this documentation/reconciliation story.

Tasks / Subtasks

  • Add an "Agentic interaction model" section to AGENTS.md linking the standard, consistent with the existing standards sections. (AC: test issue from agent #1)
  • Add an "Interaction contract" subsection to docs/dev-lead/spec.md, docs/pr-review-agent/pr-review-agent.md, and docs/aw/ci-failure-analyst.md linking each role's contract + the standard. (AC: Go-live improvements for PR review agent #2)
  • Reconcile the ci-failure-analyst divergence: compare .github/workflows/ci-failure-analyst.md (workflow_run, staged:true, max:1, models: sonnet-4-6) against the deployed .github/workflows/ci-failure-analyst.lock.yml (check_run:completed, live, calls ci-failure-analyst-reusable.yml) and docs/aw/ci-failure-analyst.md; correct the stale spec/doc to the deployed reality or remove the orphaned source, without editing the frozen .lock.yml stub. (AC: Add @claude delegation, auto-merge, and rebase handling #3, Optimize review: small-PR and incremental fast paths #4)

Dev Notes

  • The divergence is concrete: ci-failure-analyst.md (gh-aw source) declares on: workflow_run + safe-outputs.add-comment{max:1, staged:true} + models.claude:[sonnet-4-6]; the deployed ci-failure-analyst.lock.yml is a thin caller triggering on check_run:completed with issues: write (live) delegating to ci-failure-analyst-reusable.yml pinned at ci-failure-analyst/v1-stable. The .md/doc is the stale artifact — reconcile to the deployed thin-caller reality.
  • ci-failure-analyst.lock.yml is a byte-frozen ring-0 caller stub (caller-stub-freeze covers ci-failure-analyst.lock.yml -> ci-failure-analyst.block). Do NOT edit its on:/with: block. The reconciliation corrects the SPEC/DOC (.md and docs/aw/ci-failure-analyst.md), not the deployed runtime.
  • If .github/workflows/ci-failure-analyst.md is an orphaned gh-aw source with no matching deployed compile, the lint.yml gh-aw-compile job's orphaned-lock detector and the caller architecture indicate it should be removed or corrected — decide based on whether it is still a live source; document the decision.
  • Verify doc paths before linking: docs/dev-lead/spec.md, docs/pr-review-agent/pr-review-agent.md, docs/aw/ci-failure-analyst.md all exist.
  • Testing standard: docs/spec-only; a link check + confirming the spec now matches the deployed on:/safe-output posture. No runtime behaviour change to assert.

Project Structure Notes

Touches AGENTS.md, docs/dev-lead/spec.md, docs/pr-review-agent/pr-review-agent.md, docs/aw/ci-failure-analyst.md, and the ci-failure-analyst gh-aw source/spec. The deployed ci-failure-analyst.lock.yml stub is untouched.

References

  • AGENTS.md
  • docs/dev-lead/spec.md
  • docs/pr-review-agent/pr-review-agent.md
  • docs/aw/ci-failure-analyst.md
  • .github/workflows/ci-failure-analyst.md
  • .github/workflows/ci-failure-analyst.lock.yml
  • .github/workflows/ci-failure-analyst-reusable.yml

Likely target surface

  • AGENTS.md
  • docs/aw/ci-failure-analyst.md
  • .github/workflows/ci-failure-analyst.md

Story prepared by the BMAD Scrum Master (Bob) for epic #1402. Status: ready-for-dev.

Activity

  1. don-petry commented on Aug 2, 2026

    @don-petry
    Collaborator

    Dev-Lead Implementation Plan

    Issue: #1409 — [Phase 5] Wire the standard into AGENTS.md and per-agent docs, and reconcile the ci-failure-analyst spec vs deployed divergence

    Scope

    Make the agentic interaction model discoverable from AGENTS.md and every per-agent doc, and correct the stale ci-failure-analyst.md gh-aw source so its declared trigger/posture matches the deployed thin-caller reality — without editing the byte-frozen .lock.yml.

    Implementation Checklist

    Reconciliation decision (AC #3/#4)

    The .md is corrected, not removed: ci-failure-analyst.lock.yml is the only committed *.lock.yml, and the gh-aw-compile job's orphaned-lock detector (lint.yml) fails a .lock.yml with no sibling .md. Removing the source would orphan the frozen ring-0 stub. The .lock.yml is untouched (caller-stub-freeze); only the spec/doc changes. No new schedule.cron/trigger is introduced (AC #5).

    Tests to Write

    • None (docs/spec-only per the issue's testing standard). Phase 2 TDD skipped per the doc-only exception; verified via link check + confirming the corrected spec matches the deployed on:/safe-output posture.

    Test Command

    bash .dev-lead/scripts/dev-lead-lint.sh + gh aw compile --no-emit (via the lint.yml gh-aw-compile job)

  2. don-petry commented on Aug 2, 2026

    @don-petry
    Collaborator

    Dev-Lead: Implementation Complete

    Plan Execution

    Reconciliation decision (AC #3/#4)

    Corrected the spec, did not remove the source. ci-failure-analyst.lock.yml is the only committed *.lock.yml in the repo, and the gh-aw-compile job's orphaned-lock detector (lint.yml) fails any .lock.yml lacking a sibling .md. Removing ci-failure-analyst.md would orphan the byte-frozen ring-0 stub and break CI — so the .md is retained and corrected instead:

    • on: workflow_run: {workflows:[CI,Lint,Tests]} → on: check_run: types:[completed] (matches the deployed stub)
    • dropped safe-outputs.add-comment.staged: true → deployed posts live (issues: write)
    • body/guards rewritten from github.event.workflow_run.* → github.event.check_run.*, added the anti-loop name guard + non-fork/commits-to-pulls fallback that the deployed reusable performs
    • added a "Deployed runtime" note stating the live runtime is the thin caller .lock.yml → ci-failure-analyst-reusable.yml@ci-failure-analyst/v1-stable, that this .md is the orphan-detector companion kept in sync with the stub, and that the frozen .lock.yml must not be edited (caller-stub-freeze)

    The deployed ci-failure-analyst.lock.yml is untouched (git diff shows no change). No new schedule.cron or automation trigger is introduced (AC #5).

    Test Results

    Testing standard per the issue: docs/spec-only — link check + confirming the spec matches the deployed on:/safe-output posture. Phase 2 (TDD) skipped per the doc-only exception (no observable runtime behaviour change to assert).

    $ bash .dev-lead/scripts/dev-lead-lint.sh
      [lint] all checks passed
    
    $ gh aw compile --no-emit          # pinned github/gh-aw v0.74.4 (as in lint.yml)
    ✓ .github/workflows/ci-failure-analyst.md
    ⚠ Compiled 2 workflow(s): 0 error(s), 1 warning(s)
      # exit 0; the 1 warning is the pre-existing issue-triage.md ANTHROPIC_API_KEY
      # notice, unrelated to this change. The corrected .md REMOVED the prior
      # "workflow_run trigger should include branch restrictions" warning.
    
    $ orphaned-lock detector (lint.yml gh-aw-compile logic)
    orphan=0                            # ci-failure-analyst.lock.yml keeps its sibling .md
    
    $ python3 interaction-contracts/validate-interaction-contracts.py
    OK: 11 interaction contract(s) valid, invariants hold.
    
    $ bash scripts/validate-workflow-schedules.sh
    schedule-lint: OK — no minute-0 (top-of-hour) scheduled crons found.
    
    $ markdownlint-cli2 <5 changed files>   # DavidAnson/markdownlint-cli2-action, as in ci.yml
    Summary: 0 issues
    
    $ link check (every added relative link resolves)
    all 11 added links OK
    

    Files Changed

    Notes

    • The deployed .lock.yml and ci-failure-analyst-reusable.yml already reflected the correct behaviour; docs/aw/ci-failure-analyst.md already described the check_run/reusable reality — the only stale artifact was .github/workflows/ci-failure-analyst.md, which is now consistent.
    • Because a gh-aw source can only compile to a full inlined lock (never a thin caller), ci-failure-analyst.md and the hand-maintained .lock.yml are structurally distinct by design; the new note makes that explicit so the retained source no longer misleads implementers.
  3. added a commit that references this issue on Aug 2, 2026
  4. added 8 commits that reference this issue on Aug 3, 2026
  5. added a commit that references this issue on Aug 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    dev-leadFor dev-lead agent pickupinitiativeEpic / initiative tracking issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions