Version and validate the agent-context schema (6.2.2)#349
Conversation
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![codescene-delta-analysis[bot]](https://avatars.githubusercontent.com/in/53921?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
lodyai
Bot
force-pushed
the
6-2-2-version-and-validate-the-agent-context-schema
branch
from
87ea9ab to
90cd983
Compare
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
leynos
changed the title
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
lodyai
Bot
changed the title
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
…6.2.2) Draft execution plan for roadmap item 6.2.2. Covers schema shape and version guard tests in ortho_config, generator determinism and a default-display policy in cargo-orthohelp, three minimal golden fixtures (simple, enum, nested), the optional inclusion of agent-context in `--format all`, and the agent-context compatibility policy documentation. The plan is informed by a community-of-experts design review and surfaces open decisions about the exact v1 wire shape for approval before implementation. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Roadmap 6.1.2 (PR #340) merged to main during this branch's draft and was picked up by a rebase. It added a reusable nested clap tree (NestedFixtureConfig) to the existing orthohelp_fixture crate and established the --root-type multi-root convention, but covers only IR, roff, and PowerShell — not the agent-context format. Revise the plan to reuse that infrastructure instead of authoring new fixture crates: reuse NestedFixtureConfig (nested) and FixtureConfig (enum, the default root), and add only a minimal SimpleFixtureConfig root, each golden selected via --root-type. Narrow Risk 1 (the agent-context recursion is now the only unexercised part), reduce scope (one struct plus locale keys, no new workspace members), and add a 6.2.2-vs-6.1.2 render-assertion fence. A revision note records the change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Update the 6.2.2 ExecPlan to record D1, D2, D3, and D5 as accepted, and choose the D4 pre-1.0 enum casing change. Keep Milestone 1 and the compatibility-policy work aligned with the new decision to standardize agent-context enum wire strings to `snake_case` before locking the schema.
Record the execution start for the 6.2.2 ExecPlan, including the current branch, PR title, and Lody session context.
Standardize agent-context enum serialization on `snake_case` before locking the v1 wire contract. Add schema guard tests for the version and kind pins, comprehensive wire shape, unknown-field tolerance, and variant-exhaustive enum wire values. Record the Milestone 1 red/green evidence and gate results in the ExecPlan so later milestones can rely on the locked schema baseline.
Add generator-side guards for the agent-context transform before expanding the end-to-end golden matrix. The adapter now normalizes unstable proc-macro token spacing in default displays, so default-bearing goldens are not churned by `proc_macro2` formatting changes. The new tests prove deterministic pretty JSON output for the same bridge IR and pin nested command projection through a two-level command tree. The existing agent-context golden is re-baselined for the approved default-display normalization.
Cover agent-context generation for the three root shapes named by the plan: a minimal flat scalar root, the existing enum-bearing fixture root, and the nested command-tree fixture from 6.1.2. The golden test is now parametrized over root types and snapshots each shape independently. Add a nested BDD scenario that asserts generated command paths include both a top-level subcommand and the deeper admin audit path, proving the behaviour layer exercises nested agent-context output rather than only checking that JSON was written.
Treat `--format all` as additive over the now-locked agent-context contract by writing `agent-context.json` alongside the existing IR, man-page, and PowerShell artefacts. This fulfils the previous deferral without changing the legacy output paths or assertions. The all-formats BDD scenario now checks that the compact agent-context document is emitted in addition to the existing generated outputs.
Record the v1 compatibility rules, defaulting policy, and agent-context inclusion in format-all documentation.
Record the skill_manifests default added on main in the simple and nested agent-context snapshots after rebasing onto origin/main.
lodyai
Bot
force-pushed
the
6-2-2-version-and-validate-the-agent-context-schema
branch
from
57c9bd7 to
fb3ff68
Compare
There was a problem hiding this comment.
Gates Failed
(2 files with Large Method, Large Assertion Blocks, Code Duplication)
Our agent can fix these. Install it.
Gates Passed
Reason for failure
| Enforce advisory code health rules | Violations | Code Health Impact | |
|---|---|---|---|
| tests.rs | 2 advisory rules | 10.00 → 8.68 | Suppress |
| steps_agent_context.rs | 1 advisory rule | 10.00 → 9.39 | Suppress |
Quality Gate Profile: Pay Down Tech Debt
Install CodeScene MCP: safeguard and uplift AI-generated code. Catch issues early with our IDE extension and CLI tool.
|
|
||
| assert_snapshot!(json, @r###" | ||
| { | ||
| "schema_version": "1", | ||
| "kind": "example-cli.agent_context", | ||
| "package": "example-cli", | ||
| "commands": [ | ||
| { | ||
| "path": [ | ||
| "example-cli", | ||
| "list" | ||
| ], | ||
| "summary": "List configured resources.", | ||
| "canonical_verb": "list", | ||
| "inputs": [ | ||
| { | ||
| "name": "format", | ||
| "long": "format", | ||
| "value_type": "string", | ||
| "required": false, | ||
| "default": "json", | ||
| "enum_values": [ | ||
| "json" | ||
| ] | ||
| } | ||
| ], | ||
| "output_modes": [ | ||
| "json" | ||
| ], | ||
| "interaction_mode": "non_interactive", | ||
| "mutation_effect": "read_only", | ||
| "async_submission": { | ||
| "mode": "submit", | ||
| "noun": "job" | ||
| }, | ||
| "delivery_route": { | ||
| "supported": true, | ||
| "target": "file" | ||
| }, | ||
| "pagination": { | ||
| "limit_input": "limit", | ||
| "cursor_input": "cursor" | ||
| }, | ||
| "examples": [ | ||
| { | ||
| "command": "example-cli list --format json", | ||
| "output_mode": "json" | ||
| } | ||
| ] | ||
| } | ||
| ], | ||
| "profiles": { | ||
| "supported": false | ||
| }, | ||
| "feedback": { | ||
| "supported": false | ||
| }, | ||
| "policy": { | ||
| "agent_native": "warn" | ||
| }, | ||
| "skill_manifests": [ | ||
| { | ||
| "id": "example-list", | ||
| "path": "skills/example-list.md", | ||
| "manifest_schema_version": "v1", | ||
| "commands": [ | ||
| { | ||
| "path": [ | ||
| "example-cli", | ||
| "list" | ||
| ], | ||
| "flags": [ | ||
| "format" | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| "###); | ||
| } |
There was a problem hiding this comment.
❌ New issue: Large Method
agent_context_json_snapshot_covers_wire_contract has 83 lines, threshold = 70
1 participant
Summary
Implements roadmap item 6.2.2 — Version and validate the agent-context schema.
This locks the v1 agent-context wire contract, broadens generator coverage, and
updates the compatibility documentation now that
agent-context.jsonis part of--format all.What changed
snake_casebefore the v1contract is locked, including the intentional
read_onlyre-baseline.ortho_config: comprehensive wire snapshot coverage,version/kind pins, variant-exhaustive enum tests, unknown-field tolerance, and
documented null-versus-omitted optional-field behaviour.
cargo-orthohelpagent-context generation with default-displaynormalization, deterministic transform property coverage, and nested command
structural assertions.
fixture roots, plus BDD coverage for nested command paths.
cargo orthohelp --format allwriteagent-context.jsonbeside IR,man-page, and PowerShell artefacts.
docs/agent-native-cli-design.md,updated ADR-003/users/developers/cargo-orthohelp docs, and ticked 6.2.2 in the
roadmap and execplan.
Validation
Milestone gates were run before each CodeRabbit review. Final validation:
make check-fmtmake typecheckmake lintmake testmake markdownlintmake nixiecoderabbit review --agent(findings: 0)References
docs/execplans/6-2-2-version-and-validate-the-agent-context-schema.md