Skip to content

docs(#178): consolidate sibling-consistency rules in AGENTS.md - #181

Merged
JohnStrunk merged 3 commits into
mainfrom
agent/178-sibling-consistency-principle
Sep 23, 2026
Merged

JohnStrunk merged 3 commits into
mainfrom
agent/178-sibling-consistency-principle

Conversation

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor

Summary

Consolidate AGENTS.md's three duplicated sibling-consistency instruction sets into one canonical section.

Issues #58, #86, and #169 each added the same read-siblings / reuse-terminology / review-check pattern for a different surface (docs/, .agents/skills/, and AGENTS.md's own numbered lists). A later refinement to that pattern would have to be copied in three places.

The new section, "Rules for creating or modifying sibling entries", states the pattern once and applies it to those three surfaces plus any future surface added later. Surface-specific guidance is nested as examples (same-list numbered rules; governed Markdown documents under docs/; skill-file formatting and the structural-vs-behavioral distinction).

Specification-document coverage, topology, and staleness rules, and the skill-to-spec alignment rules, are unchanged aside from renumbering after the duplicated "read siblings first" items were removed.

CLAUDE.md is a symlink to AGENTS.md and inherits the change.

AGENTS.md is listed in REVIEW_PROTECTED_PATHS; extra review scrutiny is expected.

Testing

  • python scripts/lint.py --files AGENTS.md (offline pre-commit equivalent; pre-commit itself could not fetch hook repos in this sandbox — HTTP 403)
  • Direct secret scan of AGENTS.md and of staged content
  • Confirmed grep for "Read all sibling" and "Reuse established terminology" each returns a single match

Closes #178

Post-script verification

  • Branch is not main/master (agent/178-sibling-consistency-principle)
  • Secret scan passed (gitleaks — 2b1875b7556ed09e84803c0af786728716b925a9..HEAD)
  • PR body secret scan passed (gitleaks — no-git)

Replace the three near-duplicate read-siblings / reuse-terminology
/ review-check instruction sets with one canonical section that
applies to numbered rules in AGENTS.md, specification documents
under docs/, skill files under .agents/skills/, and any future
surface added later.

Surface-specific guidance is nested as examples under that
section: AGENTS.md siblings are the other rules in the same
list; docs/ siblings are every other governed Markdown document
under docs/; skill-file siblings keep the backtick-quoting and
structural-vs-behavioral distinction from the former skill-file
rules.

Specification-document coverage, topology, and staleness rules,
and the skill-to-spec alignment rules, are unchanged aside from
renumbering.

Note: pre-commit could not fetch remote hook repositories
(HTTP 403). Equivalent hooks were run via python
scripts/lint.py --files AGENTS.md and passed.

Closes #178
@fullsend-ai-coder
fullsend-ai-coder Bot requested a review from a team September 23, 2026 17:37
@fullsend-ai-coder fullsend-ai-coder Bot added the ready-for-review Triggers review agent dispatch label Sep 23, 2026
@coderabbitai

coderabbitai Bot commented Sep 23, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository: redhat-et/ProtoBot/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 49d4e9c7-6285-4e41-b7f4-f91bcd0d4d43

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

Comment @coderabbitai help to get the list of available commands.

@fullsend-ai-review

Copy link
Copy Markdown

🤖 Review · ⚠️ Cancelled · Ended 5:39 PM UTC

Commit: dbdfe3d · View workflow run →

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

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

Copy link
Copy Markdown

Risk Assessment: moderate (2/5)

Details

Tier 1 signals unchanged from the prior assessment (1 file, small blast radius, 1 protected path, no dependency/CI touch, bot author); Tier 2 remains elevated due to AGENTS.md high churn and multi-author history; Tier 3 stays low since the PR cleanly satisfies a well-scoped issue. Prior composite score of 2 (moderate) preserved per re-review anchoring.

Previous run

Risk Assessment: moderate (2/5)

Details

A bot-authored, single-file docs consolidation (90 lines, no CI/dependency/security touch) keeps Tier 1 low, but AGENTS.md is a high-churn, multi-author file with frequent fix commits and strong coupling to unmodified architecture docs, elevating Tier 2; Tier 3 is low since the PR precisely satisfies a fresh, unambiguous, unlabeled issue, yielding a composite of ~1.7 rounded to 2 (moderate).

@fullsend-ai-review

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

Copy link
Copy Markdown

Review

Findings

Medium

  • [protected-path] AGENTS.md — This PR modifies AGENTS.md, which is on the protected-paths list (REVIEW_PROTECTED_PATHS) and always requires human approval, regardless of context. The PR links to issue Consolidate AGENTS.md's three duplicated sibling-consistency rule sets into one general principle #178 and both the issue and the PR description explain the rationale for the consolidation (replacing three duplicated sibling-consistency rule sections with one canonical section), which provides sufficient context for the change — but this does not substitute for the required human sign-off on protected-path edits.

Prior review resolution: Both low-severity findings from the prior review round (the undefined two-level "governed scope" / "list or governed collection" vocabulary, and the intro's grammatical parallelism at the old AGENTS.md:21) are confirmed resolved in this revision — the new commit adds the defining sentence at line 19 and fixes the intro to read "an entry in any future governed scope added later."

A candidate new finding was investigated and rejected on evidence: the pre-existing "governed hierarchy member" / "governed Markdown document" phrasing (docs/ section) and the new "governed scope" / "governed collection" terms use "governed" in the same ordinary sense (subject to a stated rule set) and are not aliases for the same concept — Rule 2 of the new section scopes undeclared-alias checking to "the same list or governed collection," not the whole document, and this repository already used "governed" outside the hierarchy-member noun phrase before this PR (e.g., "governed Git and project-repository integration"). No terminology defect found.


Labels: AGENTS.md is a protected governance path modified in this PR; human approval is required before merge and this is not yet reflected in the PR labels.

Previous run

Review

Findings

Medium

  • [protected-path] AGENTS.md — This PR modifies AGENTS.md, which is on the protected-paths list (REVIEW_PROTECTED_PATHS) and always requires human approval, regardless of context. The PR links to issue Consolidate AGENTS.md's three duplicated sibling-consistency rule sets into one general principle #178 and both the issue and the PR description explain the rationale for the consolidation (replacing three duplicated sibling-consistency rule sections with one canonical section), which provides sufficient context for the change — but this does not substitute for the required human sign-off on protected-path edits.

Low

  • [terminology-coherence] AGENTS.md:21 — The new "Rules for creating or modifying sibling entries" section uses two related but undefined terms without stating how they relate: "governed scope" (intro line 21; rule 3 line 36; examples heading line 42) and "the same list or governed collection" (rules 1–3 at lines 26, 31–32, 39). Usage is complementary rather than interchangeable — "governed scope" names the domain (AGENTS.md numbered rules / docs/ / skills / future), while "list or governed collection" names the sibling set inside that domain — which matches the examples block. The gap is that this two-level vocabulary is never declared, and the intro treats "any future governed scope" as grammatically parallel to entry types ("any numbered rule", "any specification document", "any skill file") instead of "an entry in any future governed scope". That is a clarity defect in a section whose own Rule 2 requires established, non-aliased terminology.
    Remediation: Add one sentence defining the two levels (governed scope = domain of applicability; list or governed collection = the sibling set within that domain). Fix the intro parallelism at line 21 (e.g. "or an entry in any future governed scope added later"). Do not collapse the two terms into one — a single term would reintroduce the AGENTS.md-as-a-whole vs. per-list ambiguity that "list or governed collection" was introduced to close.

Prior review resolution: Both prior findings (the "surface" terminology overload at the old AGENTS.md:19, and the skill-file rules being demoted to an "Examples" bullet at the old AGENTS.md:47) are confirmed resolved in this revision — "surface" no longer appears, and the skill-file formatting/structural-vs-behavioral rules remain independent numbered obligations (renumbered 1–2), not folded into the illustrative examples block.


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 (2)

Review

Findings

Medium

  • [logic-error] AGENTS.md:24 — The consolidated numbered rules bind sibling scope to "the same surface" (rules 1-3), while the AGENTS.md example immediately below defines siblings for the AGENTS.md case as "the other numbered rules in that same list" (per-list, not per-file). AGENTS.md still contains multiple numbered lists (the sibling-entries rules themselves, the docs/ rules, and the skill-alignment items). If "surface" is read per the intro sentence as "AGENTS.md as a whole," an agent could apply one sibling-consistency check across unrelated lists, which the example then narrows back to "same list" — the rule and its own example are in tension. The same incomplete generalization shows up in rule 3's leftover clause "not only cross-document keyword checks" (written for the old AGENTS.md-only wording); on the docs/ surface, a same-surface check is itself a cross-document check.
    Remediation: State in the numbered rule text (not only in the example) that AGENTS.md has one sibling set per numbered list, or replace "surface" in rules 1-3 with a phrase that names the actual sibling set ("list or governed collection"). Revise rule 3's closing clause so it reads correctly on all three surfaces.

  • [code-organization] AGENTS.md:47 — Normative skill-file obligations that were previously independent numbered MUST rules (old "Rules for creating or modifying skill files," items 2-3: formatting conventions / "is a defect," and structural-vs-behavioral fields / do not copy dispatch parameters from siblings) are now appended to a bullet under "Examples of sibling entries on each surface listed above." That heading and its sibling bullets (for AGENTS.md rules and docs/) are definitional/illustrative. The numbered "agents must follow these rules" list (items 1-3) only covers read-siblings / reuse-terminology / review-terminology-drift, so an agent that follows the numbered list would not see the skill-specific formatting and anti-copy-behavioral-field obligations — the content survives but its enforceable status is weakened. (Independently flagged by both the correctness and style-conventions review dimensions.)
    Remediation: Move the skill-specific formatting and structural-vs-behavioral-fields requirements back into a numbered "agents must follow" list (e.g., sub-items under item 2, or a dedicated nested list). Keep the "Examples of sibling entries" skill bullet purely definitional ("every other skill file under .agents/skills/").

  • [protected-path] AGENTS.md — This PR modifies AGENTS.md, which is on the protected-paths list (REVIEW_PROTECTED_PATHS) and always requires human approval, regardless of context. The PR links to issue Consolidate AGENTS.md's three duplicated sibling-consistency rule sets into one general principle #178 and its description explains the rationale for the consolidation, which provides sufficient context for the change — but this does not substitute for the required human sign-off on protected-path edits.

Low

  • [naming-convention] AGENTS.md:19 — The PR introduces bare "surface" (lines 19, 22, 26, 30, 35, 38, 40) as the name for a governed sibling-consistency collection (AGENTS.md numbered lists / docs/ specification documents / skill files). Elsewhere in this repository's governed documentation (docs/architecture/components.md, docs/architecture/ears-manager-cli.md, docs/architecture/user-interaction-flow.md, docs/decisions/0002-...md, docs/architecture/validation-rules.md), "surface" is an established term meaning an external interface boundary (API surface, CLI/command surface, control surface, conversational surface), almost always qualified. Reusing the same bare noun for an unrelated concept is a clarity risk for agents who read AGENTS.md alongside the architecture docs, though it is not a violation of a reserved ProtoBot glossary term.
    Remediation: Avoid overloading "surface." Use an unambiguous term for the new concept, e.g. "governed scope," "rule set," or "entry collection" (e.g., "or any future governed scope added later").

Labels: Docs-only governance change (AGENTS.md) with no code/CI/security surface touched; the documentation label is not currently applied.


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-review fullsend-ai-review Bot added the documentation Improvements or additions to documentation label Sep 23, 2026
@fullsend-ai-review

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 5:40 PM UTC · Completed 5:59 PM UTC

Commit: dbdfe3d · View workflow run →

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

Address review findings regarding sibling entry scoping, terminology,
and normative skill-file obligations in AGENTS.md:

- Replace overloaded bare 'surface' with 'governed scope' and
  'list or governed collection'.
- Clarify sibling scope in rules 1-3 to explicitly bind to the same
  list or governed collection, resolving tension with per-list rules.
- Revise rule 3 review-check clause to reference specification-hierarchy
  keyword checks so it reads accurately across all governed scopes.
- Move normative skill formatting and structural-vs-behavioral rules
  back into a numbered 'agents must follow' list under Agent skills,
  leaving the examples list purely definitional.
- Acknowledge protected-path notification; AGENTS.md modification is
  the PR scope and awaits required human approval before merge.

Note: pre-commit could not fetch remote hook repositories (HTTP 403).
Equivalent hooks were run via python scripts/lint.py and passed.

Addresses #181
@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 Fix agent — iteration 1 (bot-triggered)

Addressed review findings by replacing overloaded bare 'surface' with 'governed scope' / 'list or governed collection', clarifying sibling scope to list-level in AGENTS.md, generalizing rule 3's review check clause, and restoring skill-file formatting and structural-vs-behavioral rules as an enforceable numbered list under Agent skills. Acknowledged the protected-path notification for AGENTS.md.

Fixed (3):

  1. Logic error in sibling scope and leftover clause in rule 3 (AGENTS.md:24) (AGENTS.md): Replaced 'surface' in rules 1-3 with 'list or governed collection' to explicitly match the per-list sibling scoping in AGENTS.md, and updated rule 3's review check clause to reference specification-hierarchy keyword checks so it applies accurately across all governed scopes.
  2. Normative skill-file obligations weakened in examples bullet (AGENTS.md:47) (AGENTS.md): Restored normative skill-file formatting and structural-vs-behavioral rules as an enforceable numbered MUST list under 'Agent skills' (Rules for creating or modifying skill files), leaving the 'Examples of sibling entries' skill bullet purely definitional.
  3. Overloading bare term 'surface' for sibling-consistency scope (AGENTS.md:19) (AGENTS.md): Replaced bare 'surface' across the sibling-entries rule section with 'governed scope' and 'list or governed collection', avoiding terminology collisions with architecture boundary terms.

Disagreed (1):

  1. Modification of protected path AGENTS.md requires human approval: Modifying AGENTS.md is the explicit scope and purpose of issue Consolidate AGENTS.md's three duplicated sibling-consistency rule sets into one general principle #178 and PR docs(#178): consolidate sibling-consistency rules in AGENTS.md #181; human reviewer approval is expected and required before merge as acknowledged in repository governance and PR description.

Tests: passed

Decision points
  • Restored 'Rules for creating or modifying skill files' under 'Agent skills' instead of embedding skill-specific rules in the generic sibling entries section (alternatives: Sub-items under rule 2 in sibling entries section, Dedicated nested list within the generic sibling section, Restored dedicated numbered section under Agent skills; rationale: Aligns with how specification documents retain their own dedicated section under Specification document hierarchy, keeps the generic sibling section purely general across all scopes, and restores enforceable numbered MUST rules where agents editing skills will find them.)

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

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 6:00 PM UTC · Completed 6:11 PM UTC

Commit: dbdfe3d · View workflow run →

Runtime: pi · Model: google-vertex/gemini-3.8-flash → gemini-3.8-flash · Effort: high · Cost: $0.65

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-review

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 6:12 PM UTC · Completed 6:25 PM UTC

Commit: 0cb8c20 · View workflow run →

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

Address review feedback on PR #181:
- Define the two-level vocabulary in "Rules for creating or modifying
  sibling entries": governed scope defines the domain of applicability,
  while list or governed collection defines the sibling set within that
  domain.
- Fix intro grammatical parallelism to reference an entry in any future
  governed scope.
- Note disagreement on protected-path notification: AGENTS.md modification
  is within the intended scope of PR #181 and requires human approval
  before merge.

Note: pre-commit could not fetch remote hook repositories (HTTP 403).
Equivalent hooks were run via python scripts/lint.py and passed.

Addresses #181
@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 Fix agent — iteration 2 (bot-triggered)

Addressed terminology coherence finding by explicitly defining governed scope and list or governed collection, and fixing grammatical parallelism in the intro sentence. Acknowledged protected-path finding for AGENTS.md awaiting human approval.

Fixed (1):

  1. [terminology-coherence] AGENTS.md:21 (AGENTS.md): Defined the two-level vocabulary in 'Rules for creating or modifying sibling entries' (governed scope as the domain of applicability; list or governed collection as the sibling set within that domain), and fixed intro grammatical parallelism to reference an entry in any future governed scope.

Disagreed (1):

  1. [protected-path] AGENTS.md: Modifying AGENTS.md is the explicit scope and purpose of issue Consolidate AGENTS.md's three duplicated sibling-consistency rule sets into one general principle #178 and PR docs(#178): consolidate sibling-consistency rules in AGENTS.md #181; human reviewer approval is expected and required before merge as acknowledged in repository governance and PR description.

Tests: passed

Decision points
  • Define two-level vocabulary explicitly in sibling-entries section intro (alternatives: Collapse governed scope and list or governed collection into a single term, Add an introductory sentence defining governed scope as domain of applicability and list or governed collection as sibling set within that domain; rationale: Collapsing terms would reintroduce ambiguity between AGENTS.md as a whole and per-list sibling scoping; defining the relationship explicitly resolves the terminology gap while preserving precise scoping.)

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

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 6:27 PM UTC · Completed 6:37 PM UTC

Commit: 0cb8c20 · View workflow run →

Runtime: pi · Model: google-vertex/gemini-3.8-flash → gemini-3.8-flash · Effort: high · Cost: $0.33

@fullsend-ai-review fullsend-ai-review Bot removed the risk/moderate PR risk: moderate label Sep 23, 2026
@fullsend-ai-review
fullsend-ai-review Bot dismissed stale reviews from themself September 23, 2026 18:52

Superseded by updated review

@fullsend-ai-review fullsend-ai-review Bot added requires-manual-review Review requires human judgment needs-human Agent loop needs human intervention labels Sep 23, 2026
@fullsend-ai-review

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 6:38 PM UTC · Completed 6:52 PM UTC

Commit: f049b46 · View workflow run →

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

@JohnStrunk
JohnStrunk added this pull request to the merge queue Sep 23, 2026
Merged via the queue into main with commit da1253b Sep 23, 2026
55 checks passed
@JohnStrunk
JohnStrunk deleted the agent/178-sibling-consistency-principle branch September 23, 2026 19:13
@fullsend-ai-retro

Copy link
Copy Markdown

PR #181 (redhat-et/ProtoBot) consolidated three duplicated "sibling-consistency" rule blocks in AGENTS.md (originally added piecemeal by #58, #86, #169) into one canonical section, closing #178 (itself auto-filed by a prior retro off PR #177). Pipeline: triage → one-shot code agent → 3 review rounds + 2 fix iterations → human approval → merge, all within ~1h36m (17:37–19:14 UTC on 2026-09-23).

Review quality was strong on substance: round 1 caught a genuine self-contradiction (the new rule bound sibling scope to "the same surface" while its own worked example scoped siblings per-list, not per-file), a normative-rule demotion (skill-file MUST rules had been moved into a non-normative "Examples" bullet, weakening enforceability), and an overloaded term ("surface" collided with the architecture docs' existing API/CLI/control-surface meaning). All three were real defects, correctly identified and fixed. Round 2 then caught a defect introduced by the round-1 fix itself: the fix replaced "surface" with two new related terms ("governed scope" and "list or governed collection") but never stated their relationship — an undefined co-reference, fixed in iteration 2 and confirmed clean in round 3. Notably, this PR's own subject matter is the very sibling-terminology-consistency rule that the fix agent momentarily violated while implementing it — a fitting self-referential near-miss, caught correctly by review.

The only human touchpoint was a single content-free APPROVED review from JohnStrunk, which satisfied the REVIEW_PROTECTED_PATHS gate on AGENTS.md. That protected-path finding (severity: medium) was raised and left unresolved across all three review rounds; the fix agent responded each time by logging a "Disagreed" note (reasoning that human approval was "expected and required" per the PR's own scope) rather than escalating, and merge proceeded once the human approval landed structurally, regardless of its content. This directly corroborates open issue #180 ("Gate merge on unresolved high-severity protected-path review findings"), which was filed the same day off a similar gap on PR #174. One nuance for whoever triages #180: this instance's protected-path finding was medium severity, not high, so it would fall outside #180's proposed high-severity-only gate as currently scoped — worth a second look at the severity threshold. No new issue is filed for this since #180 already covers the mechanism.

Separately, fullsend-ai/agents#1448 (open) already tracks the broader meta-pattern visible in the #58→#86→#169→#178 lineage (repeated narrow point-fixes instead of earlier generalization); PR #181 is the generalization that resulted, so no new proposal is needed there either.

One new proposal below addresses the round-1→round-2 rework: the fix agent should self-check newly introduced terminology for definedness before resubmitting, to avoid a preventable second review round.

Proposals filed

@fullsend-ai-retro

Copy link
Copy Markdown

🤖 Finished Retro · ✅ Success · Started 7:15 PM UTC · Completed 7:24 PM UTC

Commit: f049b46 · View workflow run →

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation needs-human Agent loop needs human intervention ready-for-review Triggers review agent dispatch requires-manual-review Review requires human judgment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Consolidate AGENTS.md's three duplicated sibling-consistency rule sets into one general principle

1 participant