Skip to content

docs(#102): add trust cross-references to ADR-0002 - #7115

Merged
maruiz93 merged 5 commits into
mainfrom
agent/102-adr-trust-cross-refs
Sep 16, 2026
Merged

maruiz93 merged 5 commits into
mainfrom
agent/102-adr-trust-cross-refs

Conversation

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor

Summary

Add cross-reference annotations to ADR-0002 (Initial Fullsend Design) pointing to the four ADRs that implement the defense-in-depth trust strategy for agent-generated comments. This makes the trust strategy discoverable from the original design document.

Related Issue

Changes

  • Added a blockquote annotation in the Data flow / Sandboxing section of ADR-0002 with cross-references to:
    • ADR 0007 (per-role GitHub Apps for verifiable bot identities)
    • ADR 0017 (credential isolation — post-scripts write comments outside sandbox)
    • ADR 0022 (harness-level output schema enforcement)
    • ADR 0054 (authorization required on all dispatch paths)
  • Added all four ADRs to the References section with short descriptions of their trust relevance

Testing

  • All ADR linters pass (lint-adr-status, lint-adr-numbers, lint-adr-frontmatter)
  • All markdown link checks pass (lint-docs-links, lychee)
  • No trailing whitespace, file ends with newline
  • Secret scan passes
  • make lint could not complete due to sandbox network restrictions; hooks were run directly

Checklist

  • PR title follows Conventional Commits (correct type)
  • Changes are minor annotations to an Accepted ADR (cross-references and short notes), consistent with ADR immutability policy

Closes #102

Post-script verification

  • Branch is not main/master (agent/102-adr-trust-cross-refs)
  • Secret scan passed (gitleaks — 41e7a66769cb7e3989b6da2b067f442e9fda64a5..HEAD)
  • PR body secret scan passed (gitleaks — no-git)

@github-actions

github-actions Bot commented Sep 8, 2026 •

Copy link
Copy Markdown

Site preview

Preview: https://aea48b9a-site.fullsend-ai.workers.dev

Commit: 836abbc6ad6ee43b48e05343940da441fb372136

@codecov

codecov Bot commented Sep 8, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@fullsend-ai-review

fullsend-ai-review Bot commented Sep 8, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 6:50 PM UTC · Completed 7:03 PM UTC

Commit: 7af5c17 · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $3.42

@fullsend-ai-review fullsend-ai-review Bot added the risk/low PR risk: low label Sep 8, 2026
@fullsend-ai-review

fullsend-ai-review Bot commented Sep 8, 2026 •

Copy link
Copy Markdown

Risk Assessment: low (1/5)

Details

Docs-only single-file additive change by a bot fully satisfying the linked issue acceptance criteria; all Tier 1 signals are minimal, Tier 2 shows zero recent churn and a single author in 90 days, and Tier 3 confirms full AC coverage with only an advisory security label, yielding a composite score of 1 — unchanged from the prior assessment.

Previous run

Risk Assessment: low (1/5)

Details

Docs-only single-file additive change by a bot author fully satisfying the linked issue's acceptance criteria; all Tier 1 and Tier 2 signals are minimal, and while Tier 3 shows modest signals from a security label and discussion history, these are offset by full AC coverage, yielding a composite score of 1.

Previous run (2)

Risk Assessment: low (1/5)

Details

Docs-only additive change to a single ADR file by a bot author directly satisfying the linked issue acceptance criteria; all Tier 1 signals minimal, Tier 2 shows no churn or regression history, and Tier 3 shows full AC coverage despite minor issue-age and label context signals, yielding a composite score of 1.

Previous run (3)

Risk Assessment: low (1/5)

Details

Docs-only additive change to a single ADR file by a bot author, directly satisfying the linked issue acceptance criteria with no security, dependency, CI, or blast-radius concerns; all signals unchanged from prior assessment.

Previous run (4)

Risk Assessment: low (1/5)

Details

Docs-only additive change to a single ADR file by a bot author, directly satisfying the linked issue acceptance criteria with no security, dependency, CI, or blast-radius concerns.

@fullsend-ai-review

fullsend-ai-review Bot commented Sep 8, 2026 •

Copy link
Copy Markdown

Looks good to me

Previous run

Looks good to me

Previous run (2)

Looks good to me

Previous run (3)

Review

Findings

Low

  • [stale-reference] docs/ADRs/0002-initial-fullsend-design.md:470 — The link text for ADR 0007 in the References section reads "Per-role GitHub Apps", but the ADR's actual title is "Per-role GitHub Apps with manifest-based creation". The qualifier is dropped, making the reference slightly inaccurate. The other three new ADR references (0017, 0022, 0054) all match their respective titles, so this is an inconsistency rather than a deliberate convention.
    Remediation: Change the link text to match the full title: - [ADR 0007 — Per-role GitHub Apps with manifest-based creation](./0007-per-role-github-apps.md)

Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR
Previous run (4)

Review

Findings

Low

  • [documentation comment format] docs/ADRs/0002-initial-fullsend-design.md:271 — The new blockquote uses a full-sentence bold opener ending with a period (**Trust mechanisms for agent-generated content.**) rather than the **Label:** pattern used by the two other blockquotes in this file (lines 57 and 163: **Note:**, **Note (2026-06):**). The established convention is a short noun/adjective label followed by a colon.
    Remediation: Change the opener to follow the established label-colon pattern, e.g. **Trust:** Subsequent decisions implement the defense-in-depth strategy for ensuring agent comments and output can be trusted:.

Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR
Previous run (5)

Review

Findings

Low

  • [Inaccurate reference label] docs/ADRs/0002-initial-fullsend-design.md:474 — The References section adds [ADR 0054 — Require authorization on all dispatch paths] but the actual ADR title is "54. Require authorization on all agent dispatch paths" — the word "agent" is omitted from the link label. The link target resolves correctly, but the label does not match the canonical title.
    Remediation: Change the label to ADR 0054 — Require authorization on all agent dispatch paths to match the ADR’s actual title.

Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR
Previous run (6)

Review

Findings

Low

  • [naming-convention] docs/ADRs/0002-initial-fullsend-design.md:471 — The four new References entries use a trailing annotation pattern ( — <annotation> after the link) not established by the existing ADR-0001 entry, creating an inconsistent dual em-dash pattern.
    Remediation: Either expand the link text to include the annotation, or use full ADR titles without trailing annotations.

Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-coder

fullsend-ai-coder Bot commented Sep 8, 2026 •

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 7:05 PM UTC · Completed 7:11 PM UTC

Commit: 7af5c17 · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $1.04

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 Fix agent — iteration 1 (bot-triggered)

Removed trailing annotation pattern from four new References entries in ADR-0002 to match the existing entry style (ADR 0001 has no trailing annotation after the link).

Fixed (1):

  1. The four new References entries use a trailing annotation pattern not established by the existing ADR-0001 entry, creating an inconsistent dual em-dash pattern (docs/ADRs/0002-initial-fullsend-design.md): Removed trailing annotations from the four new ADR references to match the existing entry style. The trust-relevance context is already captured in the inline blockquote in the Data flow section.

Tests: passed

Decision points
  • Chose to remove trailing annotations rather than expand link text (alternatives: Expand link text to include annotations, Remove trailing annotations to match existing pattern; rationale: Removing trailing annotations is the minimal change that achieves consistency with the existing ADR-0001 reference entry. The trust-relevance information is already conveyed in the blockquote annotation added earlier in the document.)

Next steps:

  • /fs-review — request a re-review of the changes
  • /fs-fix <your instruction> — run another fix pass with specific guidance
  • Push commits directly — review re-runs automatically on push
    Updated by fullsend fix agent

fullsend-ai-coder Bot added a commit that referenced this pull request Sep 8, 2026
Drop the trailing ` — <annotation>` from the four new ADR references
to match the existing entry style (ADR 0001 has no trailing annotation).
The trust-relevance context is already captured in the inline blockquote
in the Data flow / Sandboxing section.

Note: pre-commit hooks were not run. `pre-commit` could not complete
(infrastructure failure); hooks were run directly instead.

Addresses #7115
@fullsend-ai-review

fullsend-ai-review Bot commented Sep 8, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 7:13 PM UTC · Completed 7:26 PM UTC

Commit: 0db8a5f · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $3.02

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-coder

fullsend-ai-coder Bot commented Sep 8, 2026 •

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 7:28 PM UTC · Completed 7:33 PM UTC

Commit: 0db8a5f · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $0.85

fullsend-ai-coder Bot added a commit that referenced this pull request Sep 8, 2026
Add missing word "agent" to the ADR 0054 reference label in the
References section so it matches the canonical title: "Require
authorization on all agent dispatch paths".

Note: pre-commit hooks were not run via `pre-commit`; hooks were
executed directly due to sandbox network restrictions. All relevant
hooks (ADR linters, link checkers, lychee) passed.

Addresses #7115
@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 Fix agent — iteration 2 (bot-triggered)

Fixed the ADR 0054 reference label in the References section of ADR-0002 to include the missing word "agent", matching the canonical title in the ADR's frontmatter.

Fixed (1):

  1. Inaccurate reference label — ADR 0054 link label omits the word "agent" (docs/ADRs/0002-initial-fullsend-design.md): Changed the ADR 0054 reference label from "Require authorization on all dispatch paths" to "Require authorization on all agent dispatch paths" to match the canonical ADR title.

Tests: passed

Next steps:

  • /fs-review — request a re-review of the changes
  • /fs-fix <your instruction> — run another fix pass with specific guidance
  • Push commits directly — review re-runs automatically on push
    Updated by fullsend fix agent

@fullsend-ai-review

fullsend-ai-review Bot commented Sep 8, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 7:35 PM UTC · Completed 7:47 PM UTC

Commit: 7b1637f · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $2.92

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-coder

fullsend-ai-coder Bot commented Sep 8, 2026 •

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 7:49 PM UTC · Completed 7:55 PM UTC

Commit: 7b1637f · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $0.94

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 Fix agent — iteration 3 (bot-triggered)

Changed blockquote opener to use Trust: label-colon pattern matching established convention in ADR-0002

Fixed (1):

  1. Blockquote opener uses full-sentence bold format instead of label-colon pattern (docs/ADRs/0002-initial-fullsend-design.md): Changed the blockquote opener from 'Trust mechanisms for agent-generated content.' to 'Trust:' to match the established label-colon convention used by other blockquotes in this file (Note:, Note (2026-06):).

Tests: passed

Decision points
  • Chose the reviewer's suggested label 'Trust:' over alternatives (alternatives: Use Trust: as suggested by reviewer, Use Note: to exactly match existing labels, Use Cross-references: as a descriptive label; rationale: Trust: is the most accurate short label for the content (defense-in-depth trust mechanisms) and was explicitly suggested by the reviewer. It follows the label-colon convention while being semantically distinct from the existing Note: labels.)

Next steps:

  • /fs-review — request a re-review of the changes
  • /fs-fix <your instruction> — run another fix pass with specific guidance
  • Push commits directly — review re-runs automatically on push
    Updated by fullsend fix agent

fullsend-ai-coder Bot added a commit that referenced this pull request Sep 8, 2026
Change the trust blockquote opener from a full-sentence bold format
to the **Trust:** label-colon pattern, matching the established
convention used by other blockquotes in this file (**Note:**,
**Note (2026-06):**).

Addresses #7115
maruiz93 pushed a commit that referenced this pull request Sep 15, 2026
Update the ADR 0007 entry in the References section to include the
full title Per-role GitHub Apps with manifest-based creation,
matching the canonical title in the ADRs frontmatter.

Note: pre-commit hooks were not run via pre-commit. Hooks were run
directly instead due to sandbox network restrictions.

Addresses #7115
@maruiz93
maruiz93 force-pushed the agent/102-adr-trust-cross-refs branch from 5769a7e to 49dd3b6 Compare September 15, 2026 12:38
@fullsend-ai-review

fullsend-ai-review Bot commented Sep 15, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 12:40 PM UTC · Completed 12:55 PM UTC

Commit: 49dd3b6 · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $2.26

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-review
fullsend-ai-review Bot dismissed their stale review September 15, 2026 12:55

Superseded by updated review

ADR-0002 described the initial Fullsend design including data flow
and prompt injection assumptions, but lacked cross-references to the
ADRs that implement the defense-in-depth trust strategy for
agent-generated comments.

Add a blockquote annotation in the Data flow / Sandboxing section
pointing to the four ADRs that address comment trust:
- ADR 0007 (per-role GitHub Apps — verifiable bot identities)
- ADR 0017 (credential isolation — post-scripts write comments)
- ADR 0022 (harness-level output schema enforcement)
- ADR 0054 (authorization on all dispatch paths)

Also add these four ADRs to the References section with short
descriptions of their trust relevance.

These are minor annotations to an Accepted ADR, consistent with the
ADR immutability policy (cross-references to related ADRs and short
notes linking to newer decisions are permitted).

Note: pre-commit run could not complete in the sandbox
(network restriction blocked remote hook fetching). All applicable
hooks were run directly and passed: trailing-whitespace,
end-of-file-fixer, lint-adr-status, lint-adr-numbers,
lint-adr-frontmatter, lint-docs-links, and lychee (lint-md-links).
The git pre-commit hook was bypassed with --no-verify for the same
infrastructure reason.

Closes #102
Drop the trailing ` — <annotation>` from the four new ADR references
to match the existing entry style (ADR 0001 has no trailing annotation).
The trust-relevance context is already captured in the inline blockquote
in the Data flow / Sandboxing section.

Note: pre-commit hooks were not run. `pre-commit` could not complete
(infrastructure failure); hooks were run directly instead.

Addresses #7115
Add missing word "agent" to the ADR 0054 reference label in the
References section so it matches the canonical title: "Require
authorization on all agent dispatch paths".

Note: pre-commit hooks were not run via `pre-commit`; hooks were
executed directly due to sandbox network restrictions. All relevant
hooks (ADR linters, link checkers, lychee) passed.

Addresses #7115
Change the trust blockquote opener from a full-sentence bold format
to the **Trust:** label-colon pattern, matching the established
convention used by other blockquotes in this file (**Note:**,
**Note (2026-06):**).

Addresses #7115
Update the ADR 0007 entry in the References section to include the
full title Per-role GitHub Apps with manifest-based creation,
matching the canonical title in the ADRs frontmatter.

Note: pre-commit hooks were not run via pre-commit. Hooks were run
directly instead due to sandbox network restrictions.

Addresses #7115
@fullsend-ai-review

fullsend-ai-review Bot commented Sep 16, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 9:07 AM UTC · Completed 9:19 AM UTC

Commit: 836abbc · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $1.67

@maruiz93
maruiz93 added this pull request to the merge queue Sep 16, 2026
Merged via the queue into main with commit 95f8bc2 Sep 16, 2026
32 checks passed
@maruiz93
maruiz93 deleted the agent/102-adr-trust-cross-refs branch September 16, 2026 09:40
@fullsend-ai-retro

fullsend-ai-retro Bot commented Sep 16, 2026 •

Copy link
Copy Markdown

🤖 Finished Retro · ✅ Success · Started 9:41 AM UTC · Completed 9:50 AM UTC

Commit: 836abbc · View workflow run →

Runtime: claude · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $1.71

@fullsend-ai-retro

Copy link
Copy Markdown

Retro on PR #7115 (docs-only cross-reference annotations to ADR-0002, closing issue #102). The pipeline worked correctly end-to-end (triage → code → review/fix → merge) and the change itself was low-risk and appropriately scoped by the triage agent's re-triage of a dormant issue. However the review/fix loop ran 5 review passes and 4 fix iterations, every single finding Low-severity and purely cosmetic (reference-label wording not matching target ADR titles verbatim, and a References-entry formatting pattern inconsistent with the file's existing style). No human ever left substantive review content — both human approvals were bodiless. Root cause: docs/contributing/adrs.md and skills/writing-adrs/SKILL.md document the ADR immutability policy well but have no written convention for how References-section entries should be formatted or that reference labels must match frontmatter titles verbatim; existing ADRs in the repo are themselves inconsistent on this, so the code agent had no reliable signal to get it right on commit 1. Separately, the 4th fix iteration crossed the fix-agent's iteration-warning threshold and auto-applied needs-human — correct per policy — but the very next review pass approved cleanly, and the label was never cleared. The PR then sat idle for ~6.75 days before a human (maruiz93) did two content-free rebase+approve actions; this dead time, not agent work, accounts for nearly all of the 7.6-day wall-clock time. Filing two proposals below. Also found evidence relevant to two already-open agents-repo issues rather than filing new ones: agents#885 ("Review correctness sub-agent should search for parallel instances of the bug class on first review") and agents#1220 ("Fix agent should generalize review findings to all instances of the same pattern") — this PR is a clean real-world instance of the same underlying gap (serial one-nit-per-round discovery instead of a holistic sweep), just in a docs/formatting context rather than a code bug-fix context; notably the fix agent did self-escalate to a holistic audit at iteration 4, showing the generalization behavior these issues ask for is achievable but not happening early enough or on the review side.

Proposals filed

This branch was successfully deployed

1 active and 1 inactive deployments
site-preview — 836abbc6 Deployed Sep 16, 2026 by github-actions[bot]
dev — 836abbc6 Deployed Sep 16, 2026 by maruiz93 via behaviour #12928
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-human Agent loop needs human intervention ready-for-merge All reviewers approved — ready to merge ready-for-review Triggers review agent dispatch

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Ensure that comments by agents can be trusted.

2 participants