Skip to content

Concentrate agent autofix-boundary and report-reading guidance#55

Merged
pengfei-threemoonslab merged 4 commits intomainfrom
claude/sweet-mcclintock-c3ba52
May 8, 2026
Merged

Concentrate agent autofix-boundary and report-reading guidance#55
pengfei-threemoonslab merged 4 commits intomainfrom
claude/sweet-mcclintock-c3ba52

Conversation

@pengfei-threemoonslab
Copy link
Copy Markdown
Contributor

@pengfei-threemoonslab pengfei-threemoonslab commented May 8, 2026

Summary

  • Add four agent-facing docs that concentrate guidance previously scattered across AGENTS.md, agent-contract-current.md, autofix-policy.md, agent-recipes.md, and target-repo-agent-snippets.md
  • Cross-link sweep across seven existing files so any agent-facing entry point reaches the new pages in two hops or fewer

Type

  • Check or risk-model change
  • Input adapter change
  • CLI or GitHub Action behavior
  • Report, schema, or SARIF output
  • Documentation only

Why

A new agent or CI integrator coming to Agents Shipgate had to read five files in the right order to learn (a) what an agent may safely do mechanically, (b) what conclusions an agent must defer to a human reviewer, and (c) how to walk report.json correctly. The guidance was complete but spread thin. This PR concentrates it into purpose-built pages and wires every agent-facing entry point through to them.

What's in each new doc

  • docs/agent-autofix-boundary.md — behavioral counterpart to the mechanical autofix-policy.md. Opens with the load-bearing distinction (autofix-policy.md answers "will apply-patches run this?"; this page answers "what may an agent assert in a PR comment?"). Includes a check-ID mapping table covering the seven categories (approval, confirmation, idempotency, broad-scope, prohibited-action, runtime trace evidence, plus an override-refusal script).
  • docs/report-reading-for-agents.md — reader's primer that walks report.json in order: release_decision.decision first, then supporting fields, then findings, then per-finding autofix flags, then packet human_in_the_loop. Anti-patterns include a concrete summary.status → release_decision.decision code rewrite. Full schema-version table.
  • docs/agents/use-with-codex.md — mirror of use-with-claude-code.md for OpenAI Codex. On-ramp is the canonical AGENTS.md snippet from target-repo-agent-snippets.md; no slash command or skill bundle to install.
  • docs/agents/use-with-cursor.md — mirror for Cursor. On-ramp is the auto-attach .cursor/rules/agents-shipgate.mdc rule; explains the globs: + alwaysApply: false mechanism.

Cross-link sweep

  • docs/INDEX.md — "For agents" lists all four new docs plus the previously-missing use-with-claude-code.md and agent-contract-current.md.
  • AGENTS.md — Task 2 points at the report primer; "What you can't do" leads with a CLI-vs-agent boundary clarification; the Claude Code paragraph at line 415 is now an "Editor / agent integrations" subsection covering all three editors.
  • docs/agent-contract-current.md — new "See also" section beneath "Authoritative references" (kept separate so schemas stay in the authoritative list and reader's-guides land in see-also).
  • docs/autofix-policy.md — "See also" leads with the boundary doc as the behavioral counterpart.
  • docs/agent-recipes.md — "Reference" list expanded.
  • prompts/README.md and docs/agents/use-with-claude-code.md — Codex/Cursor punts replaced with real links; Aider stays paste-only.

Vocabulary discipline

The canonical six-item phrase ("approval, confirmation, idempotency, broad-scope, or prohibited-action policy decisions") that already lived in target-repo-agent-snippets.md is now used verbatim in the four new docs, with runtime trace evidence added as the seventh category per the brief — flipping a trace patches the evidence record, not the runtime gate.

Verification

CI is authoritative for python -m ruff check ., python -m compileall -q src tests, and python -m pytest.

Additional local checks run:

  • Link integrity: extracted every relative link from the four new docs (grep -oE '\]\([^)]+\)') and confirmed every target file/anchor exists. All ten check-ID anchors (#ship-policy-approval-missing etc.) match ### SHIP-... headers in docs/checks.md.
  • Vocabulary parity: the canonical six-item phrase appears verbatim in the four new docs plus the existing target-repo-agent-snippets.md; "runtime trace evidence" is called out as the seventh.
  • Discoverability: release_decision.decision is now mentioned in 13 files across docs/, AGENTS.md, and prompts/README.md. Sampled three entry points (AGENTS.md Task 2, docs/INDEX.md "For agents", prompts/README.md) — each reaches both new top-level docs in one hop.
  • No regressions: git diff on the seven modified existing files is additive only (new lines, new bullets, new "See also" entries) plus the targeted "Editor / agent integrations" subsection split in AGENTS.md.

Release-readiness notes

  • No user-code import added to default scan paths
  • No network access added to default scan paths
  • New or changed check IDs are documented in docs/checks.md (no new check IDs; existing IDs are referenced)
  • Report/schema changes are additive or documented in STABILITY.md (no schema changes)

🤖 Generated with Claude Code

pengfei-threemoonslab and others added 4 commits May 8, 2026 15:34
@pengfei-threemoonslab @claude
Concentrate agent autofix-boundary and report-reading guidance
5fcfa0c 
Boundary and report-reading guidance was scattered across AGENTS.md,
agent-contract-current.md, autofix-policy.md, agent-recipes.md, and
target-repo-agent-snippets.md, so a new agent integrator had to hop
between files to learn what is mechanically safe vs. what requires
human review and how to walk report.json. Concentrate that guidance
into purpose-built pages and cross-link every agent-facing entry
point so the right reading order is hard to miss.

Add four docs: agent-autofix-boundary.md (behavioral counterpart to
the mechanical autofix-policy.md, with a check-ID mapping table and
override-refusal script), report-reading-for-agents.md (reader's
primer that walks report.json starting from release_decision.decision,
with concrete summary.status -> release_decision.decision rewrite),
agents/use-with-codex.md, and agents/use-with-cursor.md (mirrors of
use-with-claude-code.md for editors that lack a slash-command/skill
bundle; on-ramps are the existing AGENTS.md and .cursor/rules
snippets in target-repo-agent-snippets.md).

Cross-link sweep: docs/INDEX.md "For agents" lists all four new docs
plus the previously-missing use-with-claude-code.md and
agent-contract-current.md; AGENTS.md Task 2 points at the report
primer; AGENTS.md "What you can't do" leads with a CLI-vs-agent
boundary clarification; AGENTS.md gains an "Editor / agent
integrations" subsection covering all three editors;
agent-contract-current.md gets a See-also section; autofix-policy.md
See-also leads with the boundary doc as the behavioral counterpart;
agent-recipes.md References gains both new docs;
prompts/README.md and use-with-claude-code.md replace their Codex/
Cursor punts with real links.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@pengfei-threemoonslab @claude
Address review: correct check-ID classifications and Cursor verify step
ed74088 
Three corrections to the new agent docs in PR #55:

- agent-autofix-boundary.md: SHIP-EVIDENCE-APPROVAL-TRACE-MISSING was
  miscategorized under "Approval policy." It fires when an
  approval-required tool is missing local HITL trace evidence — the
  boundary is about trace artifacts, not about the policy declaration.
  Move it to the runtime trace evidence row and broaden that row's
  handoff text to cover "trace evidence missing OR trace shows
  policy-controlled call without approval/confirmation."
- agent-autofix-boundary.md: prohibited-action row promised check IDs
  but listed only the manifest field. Add SHIP-SCOPE-PROHIBITED-TOOL-
  PRESENT as the canonical check ID an agent walking findings[] will
  actually see, with handoff text matching the check description.
- use-with-cursor.md: Cursor's auto-attach rules require a matching
  file in chat context (alwaysApply: false). The verify step said "in
  a fresh chat" which would not trigger the rule. Make the second
  step explicitly require the matching file be open or @-referenced,
  and add a sentence explaining alwaysApply: false is the intended
  behavior.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@pengfei-threemoonslab @claude
Address review: acknowledge Codex Skills exist; reframe as no skill yet
13ea5e1 
The Codex integration guide claimed Codex has no slash-command or
skill mechanism. That is stale: Codex Skills ship in the CLI, IDE
extension, and app, with bundles installable at .codex/skills/
(project-scoped) or ~/.codex/skills/ (user-scoped), invoked via
/skill-name or implicitly when Codex decides.

Reframe the integration story: this repo does not currently ship a
Codex skill bundle (the parallel to skills/agents-shipgate/ for
Claude Code has not been authored), so the AGENTS.md snippet is the
minimal on-ramp that works today — not an inherent Codex limitation.
Add a "What's next" section documenting the SKILL.md path
(.codex/skills/agents-shipgate/SKILL.md) and the building blocks
(prompts/ recipes, advisory CI workflow, agent-autofix-boundary.md)
for assembling one locally before this repo ships an official one.

Update AGENTS.md "Editor / agent integrations" entry to match.

Source: https://developers.openai.com/codex/skills

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@pengfei-threemoonslab @claude
Address review: correct Codex skill paths/invocation and EvidenceCove…
93c1642 
…rageDecision fields

Two factual errors in PR #55:

- Codex skill paths/invocation. The doc said .codex/skills/ and
  ~/.codex/skills/ with /skill-name invocation. Per current OpenAI
  docs, Codex scans .agents/skills/ in every directory from the
  working directory up to the repo root, plus $HOME/.agents/skills/
  for user-scoped skills, and invocation is /skills or $<skill-name>
  (or implicit when Codex matches the task). Following the wrong
  paths would put SKILL.md in a directory Codex never scans. Fix all
  four occurrences (use-with-codex.md intro, surface table, What's
  next install location, AGENTS.md Editor integrations entry).

- EvidenceCoverageDecision schema. report-reading-for-agents.md
  documented release_decision.evidence_coverage.{level,
  human_review_recommended, warnings} but the v0.10 schema has no
  warnings field. The actual fields are level,
  human_review_recommended, low_confidence_tool_count, and
  source_warning_count (docs/report-schema.v0.10.json:275-302).
  Replace warnings with the two real count fields.

Source: https://developers.openai.com/codex/skills

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@pengfei-threemoonslab pengfei-threemoonslab merged commit e00ddc5 into main May 8, 2026
1 check passed
@pengfei-threemoonslab pengfei-threemoonslab deleted the claude/sweet-mcclintock-c3ba52 branch May 8, 2026 23:31
pengfei-threemoonslab added a commit that referenced this pull request May 8, 2026
@pengfei-threemoonslab @claude
Merge main into v0.11 source-provenance branch
ab21c6d 
Picks up: contract CLI command (#52), v0.10.0 release tag (#53),
init --agent-instructions (#54), HITL evidence provenance (#50),
agent autofix-boundary docs (#55), packet schema v0.3.

Conflict resolution: kept v0.11 report-schema references on top of
main's v0.10.0 release / packet-schema v0.3 / contract-command
additions. AGENTS.md and SKILL.md adopt main's centralized
"contract lives in agent-contract-current.md" pattern; the v0.11
provenance line lives there now. test_public_surface_contract.py
adopts main's derive-from-model approach for the current schema
constants and just adds v0.10 to the legacy-pattern list.

Also fixes a SARIF regression flagged in review: ``_location()``
chose the structured branch whenever ``source.path`` was set, so a
finding with ``path="foo.py"`` and legacy
``location="foo.py:10"`` emitted no ``region``. Hybrid / plugin
findings now fall back to ``_split_location(source.location or
source.ref)`` when ``start_line`` is absent. Adds a regression
test.

After merge: 805 passed (+3 skipped), ruff clean,
``agents-shipgate contract --json`` reports
``report_schema_version: "0.11"``.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@pengfei-threemoonslab