feat: define canonical client surface roles and capability matrix#306
Conversation
- Add client-surfaces spec with 3-tier architecture (Runtime Core, Gateway Layer, Client Surfaces) - Define 7 surface contracts: agent-runtime-cli, web-chat, web-dashboard, composeapp-mobile, composeapp-shared, web-docs, web-marketing - Document transport rules (web→HTTP Gateway, mobile→RustCliBridge) - Create surface-specific CLAUDE.md files with transport rules - Update .gitignore for AgentSync symlinks - Archive SDD artifacts (proposal, design, tasks, verify-report) Closes #275
Fixes E0382: use of moved value: tmp Closes pre-push hook
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (10)
📝 WalkthroughWalkthroughThis PR establishes a canonical client surfaces capability matrix and transport architecture for Corvus. It adds comprehensive specifications defining surface roles (end-user, operator, supporting), capability tiers (mandatory/optional/out-of-scope), transport rules (HTTP Gateway for web, RustCliBridge for mobile, direct CLI for operators), and migration tasks. Minor code updates include a Cargo.toml dependency version change and reference-passing fixes. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested labels
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
✅ Contributor ReportUser: @yacosta738
Contributor Report evaluates based on public GitHub activity. Analysis period: 2025-03-22 to 2026-03-22 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 15
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.agents/AGENTS.md (1)
1-37:⚠️ Potential issue | 🟠 MajorAdd required agent metadata block to AGENTS.md.
This revision omits explicit agent metadata fields (name, description, purpose, capabilities, version, compatibility) required for this file.
As per coding guidelines
.agents/AGENTS.md: "Maintain comprehensive agent metadata including name, description, purpose, and capabilities" and "Include version information and compatibility details for agents."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.agents/AGENTS.md around lines 1 - 37, Add a required agent metadata block to the top of .agents/AGENTS.md containing explicit fields: name, description, purpose, capabilities, version, and compatibility; ensure each field is present and filled with a short human-readable value (e.g., “name: ...”, “description: ...”, “purpose: ...”, “capabilities: ...”, “version: ...”, “compatibility: ...”) so the file meets the repository guideline that .agents/AGENTS.md "Maintain comprehensive agent metadata"; place this metadata block before the existing "Agent Instructions" header and keep formatting consistent with the surrounding markdown.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.agents/AGENTS.md:
- Around line 13-29: The "Core Principles" section has mixed blockquote markers
(">") interleaved with list markers which breaks markdown structure; edit the
Core Principles list to remove stray ">" characters and normalize indentation so
each top-level bullet (e.g., "Never trust user input", "Extreme Performance
Second") is a proper list item and nested items (e.g., "Use parameterized
queries, never string concatenation for SQL", "Think about algorithmic
complexity") are indented consistently as sublists; ensure all list markers use
the same style (either "-" or "*") and that nested bullets are indented by two
or four spaces so the items render and lint correctly.
- Around line 222-225: Remove the duplicated table header and separator that
repeat the "Skill | Description | Trigger" row and its following dashed
separator; keep a single header row and one separator line for the skills table
so the table renders correctly (remove the second occurrence of the header row
and its matching dashed separator).
In `@clients/agent-runtime/crates/robot-kit/Cargo.toml`:
- Line 33: The robot-kit crate is pinning toml = "0.8" which conflicts with the
workspace parent clients/agent-runtime that expects toml 1.0; update the
dependency declaration in robot-kit's Cargo.toml from toml = "0.8" to toml =
"1.0" (matching the workspace), then run cargo update / regenerate the workspace
Cargo.lock so only toml 1.0 is resolved; if you intentionally need 0.8, instead
add an explicit justification in the PR and document why two versions are
required—otherwise align robot-kit's toml version to the workspace to remove the
duplicate resolution.
In
`@openspec/changes/archive/2026-03-21-client-surfaces-capability-matrix/design.md`:
- Around line 493-495: The design text currently allows an "optional" gateway
mode for composeApp which violates the one-transport-per-surface invariant and
the mobile RustCliBridge-first contract; update the paragraph so composeApp does
not offer an inline optional mobile gateway mode—either remove the optional mode
entirely or reframe it as an explicit exception process that requires documented
justification and approval; mention the affected symbols/terms ("composeApp",
"HTTP Gateway", "Web chat", "one-transport-per-surface", "RustCliBridge") so
reviewers can locate and verify the change and ensure the docs align with the
code guidelines for markdown files.
- Around line 563-565: The "Session format" open question should be closed by
stating that CLI bridge sessions must use UUID v4 to match the canonical matrix
spec: update the checklist item and surrounding text to mark the decision as
resolved (checked) and explicitly specify "use UUID v4" for CLI bridge session
IDs (remove or strike the integer-counter alternative), and update any mention
of "gateway" and "RustCliBridge" examples to reflect UUID v4 as the required
format to avoid ambiguity.
In
`@openspec/changes/archive/2026-03-21-client-surfaces-capability-matrix/tasks.md`:
- Around line 9-12: Update the Status section in tasks.md so it accurately
reflects the checkbox state: inspect the checklist items referenced (the
unchecked boxes around lines noted in the review) and change "**Status**: In
implementation (Tasks 1-5 complete)" to match actual progress (e.g., "In
progress" or list which tasks are complete). Ensure any other
duplicated/conflicting status statements (the paragraphs around the 274-285 and
301-305 ranges) are reconciled so the document’s status consistently matches the
checked/unchecked task items; update wording and task numbers in the Status
header and any summary lines to remove the inconsistency.
In
`@openspec/changes/archive/2026-03-21-client-surfaces-capability-matrix/verify-report.md`:
- Around line 25-49: The report's verification summary is inconsistent:
reconcile the total "Tasks incomplete" count (~8) with the actual checklist
under "Verification (non-blocking)" (items 1.6–1.8), "Surface CLAUDE.md" items
(3.4, 3.5, 3.7) and "Archiving (required for close)" items (6.1–6.3) so the
totals match the checklist; explicitly mark which checklist groups or individual
items are blocking vs non-blocking (update the "Verification (non-blocking)"
header if any of 1.6–1.8 are actually blocking and ensure archiving items remain
required for close), correct the numeric summary at the top to reflect the true
incomplete count, and add the guideline note about "**/*.{md,mdx}" verification
to the referenced section lines (174–183) so the docs-check requirement is
recorded alongside the relevant tasks.
In `@openspec/specs/client-surfaces/migrations.md`:
- Around line 69-72: The migration doc has broken links: replace the placeholder
"#" for "Gateway API" with the actual spec path (use the correct relative link,
e.g., ./gateway-api.md) and fix the incorrect relative paths referenced on lines
141-142 by pointing them to the files that live in the same client-surfaces
directory (use ./<filename>.md). Update the "Gateway API" and the other
client-surfaces links so they use correct relative paths (e.g.,
./gateway-api.md, ./<other-spec>.md) and then run a quick check across
**/*.{md,mdx} to ensure no other broken or incorrect spec links remain.
In `@openspec/specs/client-surfaces/spec.md`:
- Line 247: The markdown link "[Gateway API Specification](#)" is a placeholder
causing MD042; update that link to point to the actual specification URL or
relative path (or remove the link entirely until the spec exists). Locate the
literal link text "[Gateway API Specification](#)" in the document and replace
the "#" with the correct target (e.g., the actual spec path) so the link is not
empty, or delete the link markup and keep plain text if the spec is not yet
available.
- Around line 224-230: The spec asserts modules/agent-core-kmp must contain only
type defs and bridges but the implementation includes runtime logic in
RustCliBridge (RustCliBridge.kt) which spawns processes and does I/O; either
mark this spec section as target-state with a migration status and note the
current non-conformance, or change the spec wording to allow runtime bridge
implementations here, or relocate the runtime code (the RustCliBridge
implementation) out of modules/agent-core-kmp into a runtime-specific module and
keep only the bridge interface (AgentCoreBridge, CliBridgeSession,
CoreInvocation/CoreOutput/CoreResult) in agent-core-kmp; update the spec text to
reflect whichever choice so documentation and code are aligned.
In `@openspec/specs/client-surfaces/surface-contracts/composeapp-mobile.md`:
- Around line 75-79: Update the normative transport rule to remove the absolute
“MUST use RustCliBridge” mandate and instead require that mobile implementations
conform to a single MobileBridgeContract (or "mobile bridge contract") whose
platform-specific implementations may vary; state that RustCliBridge remains the
reference implementation for Android/desktop, while iOS must use a non-process
implementation (e.g., companion daemon over IPC or embedded Rust via
FFI/Swift‑Rust bindings). Replace references to RustCliBridge as the only mobile
option with this MobileBridgeContract wording and add explicit examples:
RustCliBridge (Android/desktop), Companion daemon (macOS/iOS near-term),
Embedded Rust via FFI or Swift‑Rust bindings (iOS long-term).
In `@openspec/specs/client-surfaces/surface-contracts/composeapp-shared.md`:
- Around line 106-108: The three bullets "Patch versions", "Minor versions", and
"Major versions" are internally inconsistent: update them so the semantic labels
match standard semver patterns—change "Patch versions (0.1.x)" to "Patch
versions (x.y.z) or 0.1.z" and state these are non-breaking bugfixes; change
"Minor versions (0.x.1)" to "Minor versions (x.y.0) or 0.y.0" and say these add
backwards-compatible features (increment the minor), removing the contradictory
"new major version" phrase; keep "Major versions (x.0.0)" as breaking changes
and reserved for redesigns. Ensure the three headings (Patch versions, Minor
versions, Major versions) and their version-format examples are consistent and
the wording clearly maps which numeric position (x,y,z) is being incremented.
- Around line 56-64: The doc snippet under "Module Metadata (AgentKernel.kt)" is
out of sync: update the markdown to reflect the actual implementation in
modules/agent-core-kmp where the object exposes name and contractVersion (not
MODULE_NAME and CONTRACT_VERSION). Replace the documented constants
(MODULE_NAME, CONTRACT_VERSION, KOTLIN_VERSION) with the real public properties
(name, contractVersion) and their current values or placeholders that match the
code, and ensure the snippet references AgentKernel by its actual symbol names
(AgentKernel.name, AgentKernel.contractVersion).
In `@openspec/specs/client-surfaces/surface-contracts/web-docs.md`:
- Around line 18-37: The markdown has MD022 (missing blank lines around
subheadings) and MD040 (fenced code block missing a language); fix by ensuring
there is a blank line before and after each subheading line in the
"Documentation Content", "Site Features", and "Static Asset Serving" sections
and by annotating the fenced block with a language (e.g., change ``` to ```text)
in the suggested doc-lint snippet; update the occurrences referenced (the block
around lines 18–37 and the similar block at 54–67) so all subheadings have
surrounding blank lines and all fenced code blocks include a language token.
In `@openspec/specs/client-surfaces/surface-contracts/web-marketing.md`:
- Around line 38-41: The "Lead Capture" section currently lists contact forms,
email signup, and demo request while the "Security notes" / "No user input
processing" statement contradicts that; update the spec to reconcile these:
either remove/mark lead-capture items as out-of-scope or expand the Lead Capture
subsection to document required controls (input validation rules, allowed field
boundaries, storage/retention policy, consent/opt-in text and opt-out handling,
and abuse protections/rate-limiting and spam filtering) and reference the
security guidance in the Security notes section so both "Lead Capture" and the
"No user input processing" statements are consistent.
---
Outside diff comments:
In @.agents/AGENTS.md:
- Around line 1-37: Add a required agent metadata block to the top of
.agents/AGENTS.md containing explicit fields: name, description, purpose,
capabilities, version, and compatibility; ensure each field is present and
filled with a short human-readable value (e.g., “name: ...”, “description: ...”,
“purpose: ...”, “capabilities: ...”, “version: ...”, “compatibility: ...”) so
the file meets the repository guideline that .agents/AGENTS.md "Maintain
comprehensive agent metadata"; place this metadata block before the existing
"Agent Instructions" header and keep formatting consistent with the surrounding
markdown.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 0a64ad5b-69dc-49a1-af09-637acccb7e2e
⛔ Files ignored due to path filters (1)
clients/agent-runtime/Cargo.lockis excluded by!**/*.lock
📒 Files selected for processing (17)
.agents/AGENTS.md.gitignoreclients/agent-runtime/crates/robot-kit/Cargo.tomlclients/agent-runtime/src/main.rsopenspec/changes/archive/2026-03-21-client-surfaces-capability-matrix/design.mdopenspec/changes/archive/2026-03-21-client-surfaces-capability-matrix/proposal.mdopenspec/changes/archive/2026-03-21-client-surfaces-capability-matrix/tasks.mdopenspec/changes/archive/2026-03-21-client-surfaces-capability-matrix/verify-report.mdopenspec/specs/client-surfaces/migrations.mdopenspec/specs/client-surfaces/spec.mdopenspec/specs/client-surfaces/surface-contracts/agent-runtime-cli.mdopenspec/specs/client-surfaces/surface-contracts/composeapp-mobile.mdopenspec/specs/client-surfaces/surface-contracts/composeapp-shared.mdopenspec/specs/client-surfaces/surface-contracts/web-chat.mdopenspec/specs/client-surfaces/surface-contracts/web-dashboard.mdopenspec/specs/client-surfaces/surface-contracts/web-docs.mdopenspec/specs/client-surfaces/surface-contracts/web-marketing.md
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
- GitHub Check: sonar
- GitHub Check: pr-checks
- GitHub Check: pr-checks
- GitHub Check: Cloudflare Pages
🧰 Additional context used
📓 Path-based instructions (8)
clients/agent-runtime/**/Cargo.toml
📄 CodeRabbit inference engine (clients/agent-runtime/AGENTS.md)
clients/agent-runtime/**/Cargo.toml: Preserve release-size profile assumptions inCargo.tomland avoid adding heavy dependencies unless clearly justified
Do not add heavy dependencies for minor convenience; justify new crate additions
Files:
clients/agent-runtime/crates/robot-kit/Cargo.toml
**/*
⚙️ CodeRabbit configuration file
**/*: Security first, performance second.
Validate input boundaries, auth/authz implications, and secret management.
Look for behavioral regressions, missing tests, and contract breaks across modules.
Files:
clients/agent-runtime/crates/robot-kit/Cargo.tomlclients/agent-runtime/src/main.rsopenspec/changes/archive/2026-03-21-client-surfaces-capability-matrix/proposal.mdopenspec/specs/client-surfaces/surface-contracts/web-dashboard.mdopenspec/specs/client-surfaces/migrations.mdopenspec/changes/archive/2026-03-21-client-surfaces-capability-matrix/tasks.mdopenspec/specs/client-surfaces/surface-contracts/composeapp-shared.mdopenspec/specs/client-surfaces/surface-contracts/web-marketing.mdopenspec/specs/client-surfaces/spec.mdopenspec/specs/client-surfaces/surface-contracts/web-docs.mdopenspec/changes/archive/2026-03-21-client-surfaces-capability-matrix/verify-report.mdopenspec/specs/client-surfaces/surface-contracts/web-chat.mdopenspec/specs/client-surfaces/surface-contracts/composeapp-mobile.mdopenspec/changes/archive/2026-03-21-client-surfaces-capability-matrix/design.mdopenspec/specs/client-surfaces/surface-contracts/agent-runtime-cli.md
clients/agent-runtime/src/**/*.rs
📄 CodeRabbit inference engine (clients/agent-runtime/AGENTS.md)
clients/agent-runtime/src/**/*.rs: Never log secrets, tokens, raw credentials, or sensitive payloads in any logging statements
Avoid unnecessary allocations, clones, and blocking operations to maintain performance and efficiency
Files:
clients/agent-runtime/src/main.rs
clients/agent-runtime/**/*.rs
📄 CodeRabbit inference engine (clients/agent-runtime/AGENTS.md)
Run
cargo fmt --all -- --check,cargo clippy --all-targets -- -D warnings, andcargo testfor code validation, or document which checks were skipped and why
Files:
clients/agent-runtime/src/main.rs
clients/agent-runtime/src/main.rs
📄 CodeRabbit inference engine (clients/agent-runtime/AGENTS.md)
clients/agent-runtime/src/main.rs: Preserve CLI contract unless change is intentional and documented; prefer explicit errors over silent fallback for unsupported critical paths
Keep startup path lean and avoid heavy initialization in command parsing flow
Files:
clients/agent-runtime/src/main.rs
**/*.rs
⚙️ CodeRabbit configuration file
**/*.rs: Focus on Rust idioms, memory safety, and ownership/borrowing correctness.
Flag unnecessary clones, unchecked panics in production paths, and weak error context.
Prioritize unsafe blocks, FFI boundaries, concurrency races, and secret handling.
Files:
clients/agent-runtime/src/main.rs
**/*.{md,mdx}
⚙️ CodeRabbit configuration file
**/*.{md,mdx}: Verify technical accuracy and that docs stay aligned with code changes.
For user-facing docs, check EN/ES parity or explicitly note pending translation gaps.
Files:
openspec/changes/archive/2026-03-21-client-surfaces-capability-matrix/proposal.mdopenspec/specs/client-surfaces/surface-contracts/web-dashboard.mdopenspec/specs/client-surfaces/migrations.mdopenspec/changes/archive/2026-03-21-client-surfaces-capability-matrix/tasks.mdopenspec/specs/client-surfaces/surface-contracts/composeapp-shared.mdopenspec/specs/client-surfaces/surface-contracts/web-marketing.mdopenspec/specs/client-surfaces/spec.mdopenspec/specs/client-surfaces/surface-contracts/web-docs.mdopenspec/changes/archive/2026-03-21-client-surfaces-capability-matrix/verify-report.mdopenspec/specs/client-surfaces/surface-contracts/web-chat.mdopenspec/specs/client-surfaces/surface-contracts/composeapp-mobile.mdopenspec/changes/archive/2026-03-21-client-surfaces-capability-matrix/design.mdopenspec/specs/client-surfaces/surface-contracts/agent-runtime-cli.md
.agents/AGENTS.md
📄 CodeRabbit inference engine (AGENTS.md)
.agents/AGENTS.md: Document agent configurations and capabilities in AGENTS.md
Maintain comprehensive agent metadata including name, description, purpose, and capabilities
Include version information and compatibility details for agents
Files:
.agents/AGENTS.md
🧠 Learnings (13)
📓 Common learnings
Learnt from: CR
Repo: dallay/corvus PR: 0
File: clients/agent-runtime/AGENTS.md:0-0
Timestamp: 2026-02-17T12:31:17.076Z
Learning: Applies to clients/agent-runtime/src/main.rs : Preserve CLI contract unless change is intentional and documented; prefer explicit errors over silent fallback for unsupported critical paths
Learnt from: CR
Repo: dallay/corvus PR: 0
File: clients/agent-runtime/AGENTS.md:0-0
Timestamp: 2026-02-17T12:31:17.076Z
Learning: Applies to clients/agent-runtime/src/{security,gateway,tools}/**/*.rs : Treat `src/security/`, `src/gateway/`, `src/tools/` as high-risk surfaces and never broaden filesystem/network execution scope without explicit policy checks
Learnt from: CR
Repo: dallay/corvus PR: 0
File: clients/agent-runtime/AGENTS.md:0-0
Timestamp: 2026-02-17T12:31:17.076Z
Learning: Applies to clients/agent-runtime/src/{security,gateway,tools,config}/**/*.rs : Do not silently weaken security policy or access constraints; keep default behavior secure-by-default with deny-by-default where applicable
Learnt from: CR
Repo: dallay/corvus PR: 0
File: clients/agent-runtime/AGENTS.md:0-0
Timestamp: 2026-02-17T12:31:17.076Z
Learning: Applies to clients/agent-runtime/src/channels/**/*.rs : Implement `Channel` trait in `src/channels/` with consistent `send`, `listen`, and `health_check` semantics and cover auth/allowlist/health behavior with tests
📚 Learning: 2026-02-17T12:31:17.076Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: clients/agent-runtime/AGENTS.md:0-0
Timestamp: 2026-02-17T12:31:17.076Z
Learning: Applies to clients/agent-runtime/**/Cargo.toml : Do not add heavy dependencies for minor convenience; justify new crate additions
Applied to files:
clients/agent-runtime/crates/robot-kit/Cargo.toml
📚 Learning: 2026-02-17T12:31:17.076Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: clients/agent-runtime/AGENTS.md:0-0
Timestamp: 2026-02-17T12:31:17.076Z
Learning: Applies to clients/agent-runtime/**/Cargo.toml : Preserve release-size profile assumptions in `Cargo.toml` and avoid adding heavy dependencies unless clearly justified
Applied to files:
clients/agent-runtime/crates/robot-kit/Cargo.toml
📚 Learning: 2026-02-17T12:31:17.076Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: clients/agent-runtime/AGENTS.md:0-0
Timestamp: 2026-02-17T12:31:17.076Z
Learning: Applies to clients/agent-runtime/**/*.rs : Run `cargo fmt --all -- --check`, `cargo clippy --all-targets -- -D warnings`, and `cargo test` for code validation, or document which checks were skipped and why
Applied to files:
clients/agent-runtime/crates/robot-kit/Cargo.tomlclients/agent-runtime/src/main.rs.agents/AGENTS.md
📚 Learning: 2026-02-17T12:31:17.076Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: clients/agent-runtime/AGENTS.md:0-0
Timestamp: 2026-02-17T12:31:17.076Z
Learning: Applies to clients/agent-runtime/src/main.rs : Preserve CLI contract unless change is intentional and documented; prefer explicit errors over silent fallback for unsupported critical paths
Applied to files:
clients/agent-runtime/crates/robot-kit/Cargo.tomlclients/agent-runtime/src/main.rsopenspec/changes/archive/2026-03-21-client-surfaces-capability-matrix/design.mdopenspec/specs/client-surfaces/surface-contracts/agent-runtime-cli.md.agents/AGENTS.md
📚 Learning: 2026-02-17T12:31:17.076Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: clients/agent-runtime/AGENTS.md:0-0
Timestamp: 2026-02-17T12:31:17.076Z
Learning: Applies to clients/agent-runtime/src/**/*.rs : Avoid unnecessary allocations, clones, and blocking operations to maintain performance and efficiency
Applied to files:
clients/agent-runtime/src/main.rs.agents/AGENTS.md
📚 Learning: 2026-02-17T12:31:17.076Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: clients/agent-runtime/AGENTS.md:0-0
Timestamp: 2026-02-17T12:31:17.076Z
Learning: Applies to clients/agent-runtime/src/main.rs : Keep startup path lean and avoid heavy initialization in command parsing flow
Applied to files:
clients/agent-runtime/src/main.rs
📚 Learning: 2026-02-17T12:31:17.076Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: clients/agent-runtime/AGENTS.md:0-0
Timestamp: 2026-02-17T12:31:17.076Z
Learning: Applies to clients/agent-runtime/src/{security,gateway,tools,config}/**/*.rs : Do not silently weaken security policy or access constraints; keep default behavior secure-by-default with deny-by-default where applicable
Applied to files:
clients/agent-runtime/src/main.rsopenspec/changes/archive/2026-03-21-client-surfaces-capability-matrix/design.md.agents/AGENTS.md
📚 Learning: 2026-02-17T07:28:38.934Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-02-17T07:28:38.934Z
Learning: Applies to .agents/AGENTS.md : Document agent configurations and capabilities in AGENTS.md
Applied to files:
.gitignoreopenspec/specs/client-surfaces/surface-contracts/agent-runtime-cli.md.agents/AGENTS.md
📚 Learning: 2026-02-17T07:28:38.934Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-02-17T07:28:38.934Z
Learning: Applies to .agents/AGENTS.md : Maintain comprehensive agent metadata including name, description, purpose, and capabilities
Applied to files:
.gitignoreopenspec/specs/client-surfaces/surface-contracts/agent-runtime-cli.md.agents/AGENTS.md
📚 Learning: 2026-02-17T07:28:38.934Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-02-17T07:28:38.934Z
Learning: Applies to .agents/AGENTS.md : Include version information and compatibility details for agents
Applied to files:
.gitignore.agents/AGENTS.md
📚 Learning: 2026-02-17T12:31:17.076Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: clients/agent-runtime/AGENTS.md:0-0
Timestamp: 2026-02-17T12:31:17.076Z
Learning: Applies to clients/agent-runtime/src/{security,gateway,tools}/**/*.rs : Treat `src/security/`, `src/gateway/`, `src/tools/` as high-risk surfaces and never broaden filesystem/network execution scope without explicit policy checks
Applied to files:
openspec/changes/archive/2026-03-21-client-surfaces-capability-matrix/design.mdopenspec/specs/client-surfaces/surface-contracts/agent-runtime-cli.md.agents/AGENTS.md
📚 Learning: 2026-02-17T12:31:17.076Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: clients/agent-runtime/AGENTS.md:0-0
Timestamp: 2026-02-17T12:31:17.076Z
Learning: Prefer deterministic behavior over clever shortcuts; do not 'ship and hope' on security-sensitive paths
Applied to files:
.agents/AGENTS.md
🪛 markdownlint-cli2 (0.21.0)
openspec/specs/client-surfaces/surface-contracts/web-dashboard.md
[warning] 18-18: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 25-25: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 30-30: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 35-35: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 40-40: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 45-45: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 50-50: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 55-55: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
openspec/specs/client-surfaces/migrations.md
[warning] 19-19: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 26-26: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 32-32: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 38-38: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 46-46: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 50-50: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 54-54: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
openspec/changes/archive/2026-03-21-client-surfaces-capability-matrix/tasks.md
[warning] 20-20: Multiple spaces after blockquote symbol
(MD027, no-multiple-space-blockquote)
[warning] 21-21: Multiple spaces after blockquote symbol
(MD027, no-multiple-space-blockquote)
[warning] 22-22: Ordered list item prefix
Expected: 1; Actual: 2; Style: 1/1/1
(MD029, ol-prefix)
[warning] 30-30: Multiple spaces after blockquote symbol
(MD027, no-multiple-space-blockquote)
[warning] 31-31: Multiple spaces after blockquote symbol
(MD027, no-multiple-space-blockquote)
[warning] 150-150: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
openspec/specs/client-surfaces/surface-contracts/composeapp-shared.md
[warning] 80-80: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 86-86: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 90-90: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 117-117: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
openspec/specs/client-surfaces/surface-contracts/web-marketing.md
[warning] 18-18: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 26-26: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 31-31: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 38-38: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 43-43: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 64-64: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
openspec/specs/client-surfaces/spec.md
[warning] 97-97: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 103-103: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 113-113: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 119-119: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 125-125: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 136-136: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 142-142: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 152-152: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 158-158: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 164-164: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 170-170: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 180-180: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 192-192: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 198-198: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 208-208: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 214-214: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 226-226: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 232-232: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 247-247: No empty links
(MD042, no-empty-links)
openspec/specs/client-surfaces/surface-contracts/web-docs.md
[warning] 18-18: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 27-27: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 33-33: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 54-54: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
openspec/changes/archive/2026-03-21-client-surfaces-capability-matrix/verify-report.md
[warning] 20-20: Multiple spaces after blockquote symbol
(MD027, no-multiple-space-blockquote)
[warning] 21-21: Multiple spaces after blockquote symbol
(MD027, no-multiple-space-blockquote)
[warning] 22-22: Ordered list item prefix
Expected: 1; Actual: 2; Style: 1/1/1
(MD029, ol-prefix)
[warning] 30-30: Multiple spaces after blockquote symbol
(MD027, no-multiple-space-blockquote)
[warning] 31-31: Multiple spaces after blockquote symbol
(MD027, no-multiple-space-blockquote)
[warning] 150-150: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
openspec/changes/archive/2026-03-21-client-surfaces-capability-matrix/design.md
[warning] 18-18: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 24-24: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 31-31: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 38-38: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 45-45: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
.agents/AGENTS.md
[warning] 18-18: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 24-24: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
🔇 Additional comments (6)
clients/agent-runtime/src/main.rs (1)
1233-1236: Good ownership fix for retry path.Line 1233 and Line 1236 now borrow
tmp, so the temp path remains available for theAlreadyExistsretry and avoids moved-value failures..gitignore (1)
166-221: LGTM! Comprehensive backup handling for agent configurations.The additions systematically ignore backup files (
.bak.*) for agent symlinks and add surface-specific CLAUDE.md ignores that align with the PR's client surface architecture. The patterns cover multiple agent systems (.agent, .claude, .codex, .gemini, .github, .opencode) consistently.Note: Line 175 uses
*.bak(for files within.agents/skills/) while other patterns use.bak.*(for symlink backups themselves)—this difference appears intentional based on context.openspec/specs/client-surfaces/surface-contracts/agent-runtime-cli.md (1)
58-76: Runtime-only and transport boundaries are clearly specified.The CLI contract cleanly separates runtime-only capabilities from client surfaces and keeps transport expectations explicit.
openspec/changes/archive/2026-03-21-client-surfaces-capability-matrix/proposal.md (1)
167-197: Parity and runtime-only boundary definitions look consistent.The proposal keeps platform parity requirements explicit while preserving the runtime-only safety boundary.
Also applies to: 198-215
openspec/specs/client-surfaces/surface-contracts/web-dashboard.md (1)
80-89: Gateway-only admin boundary is well-defined.The transport and security constraints are explicit and aligned with the operator/admin surface role.
openspec/specs/client-surfaces/surface-contracts/web-chat.md (1)
68-79: Good gap disclosure and migration path.The current-state note and completion checklist are concrete and aligned with the actual stub status.
- .agents/AGENTS.md: add metadata block, fix Core Principles list structure, remove non-existent skill links - robot-kit/Cargo.toml: align toml dependency to workspace version 1.0 - design.md: remove optional gateway mode, close session format question with UUID v4 - tasks.md: update status to reflect actual implementation state - verify-report.md: reconcile counts and clarify blocking/non-blocking items - migrations.md: fix broken links and relative paths - spec.md: fix placeholder link, clarify agent-core-kmp two-tier structure - composeapp-mobile.md: update transport rule to MobileBridgeContract - composeapp-shared.md: fix semver patterns, update AgentKernel metadata to match code - web-docs.md: fix MD022/MD040 markdown lint issues - web-marketing.md: reconcile Lead Capture with Security Notes
Deploying corvus with
|
| Latest commit: |
04fa487
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://aa800c89.corvus-42x.pages.dev |
| Branch Preview URL: | https://feature-275-define-canonical.corvus-42x.pages.dev |
|
yacosta738
deleted the
feature/275-define-canonical-client-surface-roles-and-capability-matrix
branch
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
1 participant
This pull request updates documentation and dependencies, clarifies architecture, and makes a minor bug fix. The most important changes are:
Documentation and Architecture Updates:
.agents/AGENTS.mddocumentation to clearly describe the 3-tier client surfaces architecture, specifying transport rules for each client type and linking to surface contracts for implementation details..agents/AGENTS.mdfor accuracy, fixed links, and removed redundant or outdated testing/license sections..agents/AGENTS.md.Dependency and Code Fixes:
tomlcrate dependency from version1.0to0.8inclients/agent-runtime/crates/robot-kit/Cargo.tomlfor compatibility or stability reasons.clients/agent-runtime/src/main.rsby ensuringstd::fs::renamealways receives a reference to the temporary file path, preventing possible issues during file operations.Closes: #275