Skip to content

docs(governance): propose communication-protocol rule (Ask/Question/Propose/Alert) #795

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jordyamoedo wants to merge 2 commits into
base: main
Choose a base branch
from
+94 −0
Open

docs(governance): propose communication-protocol rule (Ask/Question/Propose/Alert) #795

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8d2071d
docs(governance): propose communication-protocol FrameworkProposal
jordyamoedo Jun 15, 2026
692d671
docs(governance): add source AuditFinding for communication-protocol
jordyamoedo Jun 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions audits/promoted/AF-20260614-communication-protocol.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
audit_finding:
version: "1.0"
id: "AF-20260614-communication-protocol"
date: "2026-06-14"
auditor: "external-contributor (@aiox-master in a consumer project)"
source_session: "Comparative audit of a hardened consumer fork against aiox-core v5.2.9"

context:
project: "a production consumer project (anonymized)"
epic: "framework learning-loop audit"
triggered_by: "Agents executing blindly under ambiguity, or staying silent on risks, for lack of a shared communication protocol"

finding:
summary: "There is no shared protocol for how agents communicate when they hit insufficient context, a flawed requirement, a better alternative, or a risk — so agents tend to execute blindly or stay silent to look efficient."
evidence:
- "No rule defines when an agent should ASK / QUESTION / PROPOSE / ALERT"
- "No alert-severity ladder (critical = HALT; high / medium / low)"
- "Without it, agents assume unprovided context, invent requirements, or ship incomplete output silently"
impact_observed:
blast_radius: "medium"
affected_artifacts: ["every agent interaction", "any task run under ambiguity"]
cost: "Wrong work shipped confidently; risks discovered late; rework"

framework_candidate: true
framework_candidate_rationale: |
Project-agnostic and posture-level: any agentic framework benefits from agents that
ask, question, propose, and alert instead of executing blindly. It's guidance (advisory),
not a gate — it raises quality without constraining freedom.
references:
- kind: pattern
path: "Agents are specialists, not blind executors — four modes"
Comment on lines +31 to +32

@coderabbitai coderabbitai Bot Jun 15, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🌐 Web query:

What are the current allowed reference kinds in the aiox-core audit-finding schema?

💡 Result:

Based on the available documentation and codebase for aiox-core as of June 2026, there is no explicit entity titled "audit-finding schema" that defines a standardized list of "reference kinds." The aiox-core framework utilizes a multi-layered quality gate system [1][2] and specific workflow task definitions [3][4] to manage audits. Audit results and findings are typically structured as markdown reports (e.g., SCHEMA.md, DB-AUDIT.md) or processed via quality gate JSON schemas [3][1][5]. In these workflows, "references" are generally handled through: 1. Task and Action References: Workflows refer to external task definitions (e.g., db-schema-audit.md) and checklists (e.g., database-design-checklist.md) [5]. 2. Output Destinations: Findings are categorized by their output destination, which includes Memory, File, API, or Database [3]. 3. Quality Metrics: Automated audit metrics are governed by the quality-metrics.schema.json, which defines structure for layers, trends, and history, rather than specific "reference kinds" for findings [1]. If you are encountering a specific error message or schema validation requirement regarding "reference kinds," it may be related to custom implementation logic within your specific squad or project-level configuration, rather than a global schema definition in the core framework.

Citations:

🏁 Script executed:

#!/bin/bash

# Find the audit file mentioned in the review
find . -name "AF-20260614-communication-protocol.yaml" -o -name "*audit-finding-tmpl*" 2>/dev/null | head -20

Repository: SynkraAI/aiox-core

Length of output: 167

🏁 Script executed:

#!/bin/bash

# Search for governance templates directory
find . -type d -name "governance" 2>/dev/null | head -10

Repository: SynkraAI/aiox-core

Length of output: 94

🏁 Script executed:

#!/bin/bash

# Search for any files with "template" or "tmpl" in audit/promoted directory
find . -path "*/audits/promoted*" -type f 2>/dev/null | head -20

Repository: SynkraAI/aiox-core

Length of output: 242

🏁 Script executed:

#!/bin/bash
cat -n ./audits/promoted/AF-20260614-communication-protocol.yaml

Repository: SynkraAI/aiox-core

Length of output: 2309

🏁 Script executed:

#!/bin/bash
cat -n ./governance/templates/audit-finding-tmpl.yaml

Repository: SynkraAI/aiox-core

Length of output: 2532

Change reference kind from "pattern" to "existing-pattern-source".

The references section at lines 31–32 uses kind: pattern, but the audit-finding template specifies allowed kinds as: ADR | code | hook | governance-doc | existing-pattern-source | voice-clone-finding | voice-clone-personas | handoff-contract | audit | proposal (governance/templates/audit-finding-tmpl.yaml, lines 38–39).

Based on the reference content, existing-pattern-source is the appropriate kind. Update line 31 accordingly.

🤖 Prompt for 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.

In `@audits/promoted/AF-20260614-communication-protocol.yaml` around lines 31 -
32, The references section uses an invalid kind value "pattern" which is not in
the allowed list specified by the audit-finding template. Update the kind field
in the references section from "pattern" to "existing-pattern-source" to comply
with the template specification that only allows: ADR, code, hook,
governance-doc, existing-pattern-source, voice-clone-finding,
voice-clone-personas, handoff-contract, audit, or proposal.


proposed_disposition:
- "Add a communication-protocol rule with the four modes (Ask / Question / Propose / Alert)"
- "Add an alert-severity ladder (critical = HALT; high / medium / low)"
- "State the anti-patterns agents must avoid (silent execution under ambiguity, inventing requirements, hiding incomplete output)"
57 changes: 57 additions & 0 deletions governance/proposals/PROP-20260614-communication-protocol.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
framework_proposal:
version: "1.0"
id: "PROP-20260614-communication-protocol"
date: "2026-06-14"
proposer: "external-contributor (consumer-project audit)"
source_finding: "AF-20260614-communication-protocol"

target:
layer: "L2"
artifact_type: "rule"
artifact_path: ".claude/rules/communication-protocol.md (NEW)"
operation: "create"

generalization:
pattern_name: "Agents are specialists, not blind executors — four modes (Ask / Question / Propose / Alert)"
when_to_apply: |
Any agentic framework where agents execute tasks. Agents should not run blindly:
- ASK when context is insufficient (missing acceptance criteria, unknown stack, ambiguous scope)
- QUESTION when a requirement is flawed (unfeasible, disproportionate, obvious tech debt, regression risk)
- PROPOSE when a better path exists (an existing pattern, a more specialized agent, a quick win)
- ALERT when a risk is identified, by severity (critical = HALT for explicit confirmation; high/medium/low)
Focus is value delivery, not execution for its own sake. Agents never assume unprovided
context, never invent requirements, never execute silently under critical ambiguity, and
never deliver incomplete output without flagging it.
examples_from_other_domains:
- "A blind executor under ambiguous scope ships the wrong thing confidently"
- "An agent that spots a regression risk but stays silent to look efficient causes the regression"
- "An agent that proposes an existing pattern instead of re-creating one saves the whole team"

migration_path:
breaking_change: false
affected_consumers: []
rollout_plan: |
Additive. Adds a posture/method rule for agents. No existing behavior changes;
it is guidance, not a blocking gate.
deprecation_plan:
deprecates: []
sunset_window: "n/a"

cost_benefit:
cost: "~1 documentation rule"
benefit: |
Raises the quality of every agent in the framework: less blind execution under
ambiguity, fewer silent incomplete outputs, risks surfaced early. Universal and cheap.
risk: "low — additive; it is posture/method, advisory by nature"

approval:
eliel_decision: "PENDING"
eliel_decision_at: null
eliel_decision_rationale: ""
revision_request: []

implementation:
pr_url: ""
merged_at: ""
distributed_to: []