Skip to content

docs(spec): record the enforcement mode vocabulary crosswalk in 6.2.1 - #402

Merged
imran-siddique merged 1 commit into
agentrust-io:mainfrom
zohebk8s:spec/enforcement-mode-crosswalk-344
Sep 7, 2026
Merged

docs(spec): record the enforcement mode vocabulary crosswalk in 6.2.1#402
imran-siddique merged 1 commit into
agentrust-io:mainfrom
zohebk8s:spec/enforcement-mode-crosswalk-344

Conversation

@zohebk8s

@zohebk8s zohebk8s commented Sep 7, 2026

Copy link
Copy Markdown
Collaborator

What

Adds an informative section 6.2.1 recording how the three enforcement mode vocabularies correspond, and points the alignment sentence in 3.2.2 at it.

Why

Closes #344. Section 6.2 requires the cMCP attested enforcement mode and artifacts.policy_bundle.enforcement_mode to match, and 3.2.2 says the two fields align, but neither says which name denotes which state. Three vocabularies are in play:

State Agent Manifest cMCP runtime TRACE claim
Decisions applied enforce enforcing enforce
Decisions surfaced, call proceeds advisory advisory advisory
Decisions recorded, reporting suppressed audit-only silent silent

Until now the only written statement of the correspondence was a mapping table inside a consumer, agentrust-io/cmcp#584, so a second implementer had to rediscover it or guess. On cmcp main at 5b63642, 346 of its 385 files decode as text and the string audit-only appears in exactly one of them.

The section records the correspondence without asserting the states are identical. silent suppresses operational reporting while still recording each decision, so silent satisfies audit-only and audit-only does not imply silent. Keeping that difference explicit is what the review comment asked for; the direction of the implication is my reading and is flagged below.

Spec impact

Section 6.2.1 is new and informative. Section 3.2.2 gains a pointer clause. No RFC 2119 keyword is added, no requirement changes, and no conformance test is affected, so no sponsor is required under GOVERNANCE. CHANGELOG.md updated under Unreleased.

One sentence needs an author's eye. The specification has never defined what its three modes mean; enforce, advisory and audit-only appear only in two schema blocks and the 3.2.2 sentence. To keep the suppressed-reporting difference explicit I had to write what audit-only means, which makes this the first written definition of it in the spec:

audit-only describes evaluating and recording without applying, and says nothing about whether the decision is reported.

That reading follows the argument in the issue, but it is an interpretation rather than a transcription. Happy to reword it.

Test plan

Run on this branch, not assumed from the fact that only documentation changed.

  • pytest -v passes: 1481 passed, 6 skipped, 1 xfailed
  • mypy src/agent_manifest passes: no issues found in 26 source files
  • ruff check src/ tests/ --select E,F,W --ignore E501 passes (the CI invocation, ruff 0.16.6 as pinned in requirements/dev.txt): all checks passed
  • New or updated tests cover the change: not applicable, no normative text changed and no code touched
  • If spec change: CHANGELOG.md updated

DCO

All commits in this PR are signed off (git commit -s). By submitting this PR I certify the Developer Certificate of Origin.

Section 6.2 requires the cMCP attested enforcement mode and the manifest's
artifacts.policy_bundle.enforcement_mode to match, and section 3.2.2 claims
the two fields align, but neither says which name denotes which state. Three
vocabularies are in play: the manifest's enforce/advisory/audit-only, the
cMCP runtime's enforcing/advisory/silent, and the TRACE claim schema's
enforce/advisory/silent, which takes two names from the first and one from
the second. The only written statement of the correspondence was a mapping
table inside a consumer, so a second implementer had to rediscover it.

Adds an informative 6.2.1 giving the three way crosswalk, citing cMCP and
TRACE section 4.3 as the authority for what each runtime mode means, and
keeping the suppressed-reporting difference between silent and audit-only
explicit rather than asserting the states are identical. Points the
alignment sentence in 3.2.2 at it. No RFC 2119 keyword is added and no
requirement changes, so no conformance test is affected.

Closes agentrust-io#344

Signed-off-by: Mohammed Zoheb Shaik <zoheb.shaik7@gmail.com>
@zohebk8s
zohebk8s requested review from a team as code owners September 7, 2026 15:50
@github-actions

github-actions Bot commented Sep 7, 2026

Copy link
Copy Markdown
Contributor

🟡 Contributor Check: MEDIUM

Check Result
Profile MEDIUM
Credential LOW
Overall MEDIUM

Automated check by AgenTrust Contributor Check.

@imran-siddique imran-siddique left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Reviewed df0a026.

This implements the informative mapping requested in #344. I checked the table against cMCP's centralized manifest mapping and TRACE claim emitter. The text preserves the distinction between recording without enforcement and suppressing operational reporting, explains the caller-side translation, and leaves a normative vocabulary extension open. Accepting the stated audit-only interpretation for this informative crosswalk. No executable behavior changes; current hosted tests, lint and type checks pass.

@imran-siddique
imran-siddique merged commit ac0a0ae into agentrust-io:main Sep 7, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-review:MEDIUM Contributor check flagged MEDIUM risk

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: reconcile enforcement-mode vocabulary across Agent Manifest, cMCP, and TRACE

3 participants