[brunovicco]

Phase 55 — current capability documentation alignment

This docs-only phase updates the portfolio landing pages and canonical engineering documents to match the actual current main behavior after v1.2/v1.3 and the post-v1.3 hardening through Phase 54.

Concrete gap

Several public documents still described the active security surface as the v1.1 governed-action snapshot or stopped at the earlier authenticated MCP experiment, while the code and canonical Governed Agent Actions document already include approval lifecycle/revocation, approver authorization, typed executor-failure evidence, authenticated failure composition, MCP uncertain-execution protocol handling, Agno failure-provenance preservation, and cross-framework failure conformance.

Updated documentation

• README.md and README.pt-br.md are synchronized around the current trust model and project status;
• docs/README.md now maps authentication, source-aware authorization, approval lifecycle, approver authorization, and typed executor-failure evidence;
• docs/EXECUTIVE_OVERVIEW.md now presents the current governed-runtime capabilities and evidence boundaries;
• docs/ARCHITECTURE.md now documents the complete authority chain from presented credential/authentication through authorization, approval lifecycle, approver authorization, execution, and typed governed failure evidence;
• docs/MCP.md now documents the authenticated experiment and uncertain post-executor MCPError protocol classification;
• docs/DEVELOPMENT.md now defines mutable executor-failure provenance and retry-ownership invariants;
• docs/AGENTIC_FAST_TRACK.md now summarizes the current implemented state;
• docs/FRAMEWORK_DECISION_MATRIX.md now incorporates governed-action conformance into its qualitative framework/security interpretation.

docs/security/GOVERNED_AGENT_ACTIONS.md remains the detailed canonical source because it was already current and no factual inconsistency was found.

Release/evidence discipline

The documentation explicitly distinguishes:

• latest published release: v1.3.0 — Human Approval Lifecycle;
• current main: v1.1/v1.2/v1.3 capabilities plus post-v1.3 hardening for approver authorization, typed executor-failure provenance, authenticated failure composition, MCP uncertain-execution handling, Agno failure-provenance preservation, and cross-framework failure conformance.

No published release metadata or accepted historical provider-backed evaluation artifact is rewritten.

Security boundaries preserved

The updated docs do not claim remote transport-bound identity, OAuth/OIDC/JWT/mTLS, durable/distributed approval, production IAM, idempotency, rollback/compensation, two-phase commit, external transactionality, or signed/tamper-proof audit evidence.

They preserve the current invariants that:

• raw credentials remain outside model-visible Tool input and structured execution evidence;
• authentication, authorization, approval, approver authorization, execution attempt, and successful side effect remain distinct facts;
• post-executor failure keeps execution_attempted=true, failure_reason=executor_error, and external_side_effect_state=unknown;
• raw executor text remains outside structured governed evidence;
• MCP protocol-error classification for uncertain execution is a transport boundary, not a universal no-retry guarantee;
• framework orchestration must not erase application-owned failure provenance.

Final scope

The clean PR diff contains exactly nine documentation files:

• README.md;
• README.pt-br.md;
• docs/AGENTIC_FAST_TRACK.md;
• docs/ARCHITECTURE.md;
• docs/DEVELOPMENT.md;
• docs/EXECUTIVE_OVERVIEW.md;
• docs/FRAMEWORK_DECISION_MATRIX.md;
• docs/MCP.md;
• docs/README.md.

No production code, dependency, workflow helper, historical artifact, tag, or published release remains changed.

CI evidence

Final clean CI #495 passed on exact head:

383f73012e840ae9deddf09540d02efb1c74a312

Quality evidence:

• Ruff check: all checks passed;
• Ruff format: 298 files already formatted;
• architecture dependency check: passed;
• Pyright: 0 errors, 0 warnings, 0 informations;
• pytest: 544/544 passed;
• coverage: 95.49%;
• Bandit: no issues identified;
• pip-audit: no known vulnerabilities, with the repository's existing 5 explicit ignores;
• MCP v2 compatibility + STDIO: green;
• governed MCP v2 compatibility + STDIO: green;
• authenticated governed MCP v2 compatibility + STDIO: green;
• OpenTelemetry safe observation contract: green.

Temporary guarded documentation helpers were removed before this final CI.

Closes #190