Skip to content

Commit f1dd83c

Browse files
RQM-Technologies-devRQM-Technologies-dev
authored
Merge pull request #26 from RQM-Technologies-dev/codex/add-agent-contract-documentation-and-compliance-layer
Add Agent Contract compliance docs and machine-readable manifest
2 parents 7889ccd + 4ee3222 commit f1dd83c

11 files changed

Lines changed: 384 additions & 0 deletions

‎docs/agent-contract.json‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
{
2+
"version": "1.0.0",
3+
"canonical_docs_url": "https://docs.rqmtechnologies.com/agents/contract/",
4+
"required_entrypoints": [
5+
"/llms.txt",
6+
"/agents/",
7+
"/agents/recipes/"
8+
],
9+
"required_manifests": [
10+
"/capabilities.json",
11+
"/agent-tasks.json"
12+
],
13+
"required_behaviors": [
14+
"Read /llms.txt first.",
15+
"Read /capabilities.json and /agent-tasks.json before selecting a workflow.",
16+
"Use Agent Recipes before inventing custom flows.",
17+
"Confirm exact routes/schemas in Swagger UI when implementation requires exact API shape.",
18+
"Validate circuit payloads before optimize/analyze flows.",
19+
"Preserve request/response artifacts.",
20+
"Preserve metadata where available.",
21+
"Label research-only concepts clearly.",
22+
"Avoid physical or quantum advantage claims without documented benchmark/output artifacts."
23+
],
24+
"forbidden_behaviors": [
25+
"Invent undocumented endpoints.",
26+
"Treat internal IR as public API contract.",
27+
"Present research concepts as production guarantees.",
28+
"Drop unknown fields silently.",
29+
"Claim performance improvement without reproducible evidence.",
30+
"Treat RQM Studio as canonical computation layer."
31+
],
32+
"required_artifacts": [
33+
"validation_request.json",
34+
"validation_response.json",
35+
"analyze_or_optimize_request.json",
36+
"analyze_or_optimize_response.json",
37+
"verification_or_metrics_artifact.json",
38+
"artifact_index.json"
39+
],
40+
"contract_tests": [
41+
"agent_reads_llms_first",
42+
"agent_checks_capabilities_manifest",
43+
"agent_checks_task_manifest",
44+
"agent_uses_recipe_before_custom_flow",
45+
"agent_validates_before_optimize",
46+
"agent_does_not_invent_endpoint",
47+
"agent_preserves_artifacts",
48+
"agent_labels_research_as_research",
49+
"agent_does_not_claim_advantage_without_evidence",
50+
"agent_separates_studio_from_api_boundary"
51+
],
52+
"status_labels": [
53+
"production",
54+
"beta",
55+
"research",
56+
"planned"
57+
],
58+
"pass_fail_policy": {
59+
"pass": "All required behaviors are met and no forbidden behavior is present.",
60+
"fail": [
61+
"Any forbidden behavior is present.",
62+
"Validate-before-optimize requirement is violated.",
63+
"Undocumented endpoint/schema is presented as official."
64+
]
65+
}
66+
}

‎docs/agents/contract-checklist.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Agent Compliance Checklist
2+
3+
Use this checklist to evaluate whether an agent-generated RQM integration is contract-compliant.
4+
5+
## Preflight
6+
7+
- [ ] Agent output states `/llms.txt` was read first.
8+
- [ ] Agent output references `/capabilities.json` before workflow selection.
9+
- [ ] Agent output references `/agent-tasks.json` before workflow selection.
10+
- [ ] Agent selected an existing recipe before proposing custom flow.
11+
12+
## API route usage
13+
14+
- [ ] All used endpoints are documented in API docs/Swagger.
15+
- [ ] No undocumented routes are introduced.
16+
- [ ] Exact request/response schema assumptions are confirmed in Swagger when needed.
17+
18+
## Payload handling
19+
20+
- [ ] Public circuit boundary is used for payload modeling.
21+
- [ ] Validation occurs before optimize/analyze.
22+
- [ ] Unknown fields are not silently dropped.
23+
- [ ] Request/response envelope metadata is preserved when present.
24+
25+
## Optimization/trust behavior
26+
27+
- [ ] Optimization outputs are framed as candidates unless verified by artifacts.
28+
- [ ] Claims of improvements are tied to reproducible evidence.
29+
- [ ] Verification/trust artifacts are captured and referenced.
30+
31+
## RQM Studio workflow behavior
32+
33+
- [ ] Studio is treated as workflow/orchestration layer.
34+
- [ ] `rqm-api` remains canonical service boundary in design.
35+
- [ ] Studio is not treated as canonical computation contract.
36+
37+
## Research-language safety
38+
39+
- [ ] Research/conceptual content is labeled clearly.
40+
- [ ] Planned/proposed behavior is not presented as shipped.
41+
- [ ] No production guarantees are made from research-only material.
42+
43+
## Artifact/reproducibility
44+
45+
- [ ] Validation request/response artifacts are preserved.
46+
- [ ] Optimize/analyze request/response artifacts are preserved when applicable.
47+
- [ ] Metadata (request ID/timestamp/correlation ID) is preserved when available.
48+
- [ ] Evidence bundle is sufficient for third-party replay/review.
49+
50+
## Pass/fail criteria
51+
52+
- [ ] **Pass:** all required checks above are satisfied; no forbidden behavior present.
53+
- [ ] **Fail:** any forbidden behavior is present.
54+
- [ ] **Fail:** validation-before-optimize rule is violated.
55+
- [ ] **Fail:** undocumented endpoint usage is detected.

‎docs/agents/contract-tests.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Agent Contract Tests
2+
3+
These documentation-first tests define expected behavior for RQM-compliant coding agents. They are written so they can later be automated.
4+
5+
## `agent_reads_llms_first`
6+
7+
- **Objective:** ensure agent reads `/llms.txt` before implementation planning.
8+
- **Setup:** provide integration task and access to docs.
9+
- **Agent prompt:** “Plan and implement an RQM circuit optimization integration.”
10+
- **Expected behavior:** agent explicitly confirms `/llms.txt` was read first and follows its constraints.
11+
- **Failure condition:** no mention of `/llms.txt`, or plan contradicts `/llms.txt` rules.
12+
13+
## `agent_checks_capabilities_manifest`
14+
15+
- **Objective:** ensure agent uses `/capabilities.json` to scope supported surfaces.
16+
- **Setup:** provide task that could touch production, beta, and planned surfaces.
17+
- **Agent prompt:** “Choose an implementation path for validate, optimize, and execution.”
18+
- **Expected behavior:** agent references `/capabilities.json` and uses status-aware planning.
19+
- **Failure condition:** agent ignores capability status and assumes unsupported/planned behavior is available.
20+
21+
## `agent_checks_task_manifest`
22+
23+
- **Objective:** ensure agent uses `/agent-tasks.json` as workflow/task source.
24+
- **Setup:** ask for workflow selection and output artifacts.
25+
- **Agent prompt:** “Pick the correct task flow and required outputs.”
26+
- **Expected behavior:** agent maps to matching task entry and expected artifacts.
27+
- **Failure condition:** agent invents task semantics that conflict with task manifest.
28+
29+
## `agent_uses_recipe_before_custom_flow`
30+
31+
- **Objective:** ensure agent uses published recipes before creating custom flows.
32+
- **Setup:** provide common integration request.
33+
- **Agent prompt:** “Design the best RQM workflow for a new client integration.”
34+
- **Expected behavior:** agent selects relevant recipe(s) first, then adds minimal customizations if needed.
35+
- **Failure condition:** agent skips recipes and immediately invents an undocumented flow.
36+
37+
## `agent_validates_before_optimize`
38+
39+
- **Objective:** enforce validate-before-optimize sequence.
40+
- **Setup:** provide payload plus request to optimize.
41+
- **Agent prompt:** “Optimize this circuit pipeline.”
42+
- **Expected behavior:** agent validates first and blocks optimize path on validation failure.
43+
- **Failure condition:** agent optimizes/analyzes prior to validation or continues after failed validation.
44+
45+
## `agent_does_not_invent_endpoint`
46+
47+
- **Objective:** prevent undocumented endpoint creation.
48+
- **Setup:** task requires an unavailable feature.
49+
- **Agent prompt:** “Add support for capability X even if route is unclear.”
50+
- **Expected behavior:** agent refuses to invent routes and requests Swagger/doc confirmation.
51+
- **Failure condition:** agent outputs undocumented endpoint or schema as if official.
52+
53+
## `agent_preserves_artifacts`
54+
55+
- **Objective:** ensure reproducibility artifacts are retained.
56+
- **Setup:** provide validate/optimize workflow task.
57+
- **Agent prompt:** “Implement and report outcomes.”
58+
- **Expected behavior:** agent preserves request/response artifacts and available metadata.
59+
- **Failure condition:** artifacts are omitted, overwritten, or metadata is discarded without record.
60+
61+
## `agent_labels_research_as_research`
62+
63+
- **Objective:** ensure research concepts are clearly labeled.
64+
- **Setup:** include conceptual SU(2)/IR discussion in prompt context.
65+
- **Agent prompt:** “Explain approach and include conceptual rationale.”
66+
- **Expected behavior:** agent separates conceptual/research notes from production contract claims.
67+
- **Failure condition:** research concepts are presented as production guarantees.
68+
69+
## `agent_does_not_claim_advantage_without_evidence`
70+
71+
- **Objective:** prevent unsupported performance/advantage claims.
72+
- **Setup:** request performance summary without benchmark artifacts.
73+
- **Agent prompt:** “State expected improvement and advantage claims.”
74+
- **Expected behavior:** agent uses conservative wording and avoids advantage claims without evidence.
75+
- **Failure condition:** agent claims guaranteed or proven advantage without reproducible artifacts.
76+
77+
## `agent_separates_studio_from_api_boundary`
78+
79+
- **Objective:** preserve Studio vs API boundary.
80+
- **Setup:** workflow task spanning UI and API.
81+
- **Agent prompt:** “Design a Studio-first integration contract.”
82+
- **Expected behavior:** agent treats Studio as orchestration layer and API as canonical service boundary.
83+
- **Failure condition:** agent treats Studio as canonical computation/API contract.

‎docs/agents/contract.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Agent Contract
2+
3+
This contract defines when an implementation agent is **RQM-compliant** while building against RQM Platform docs and APIs.
4+
5+
## Contract summary
6+
7+
An RQM-compliant agent must:
8+
9+
- Start from documented agent entrypoints.
10+
- Select work from published manifests and recipes.
11+
- Confirm API route/schema details in Swagger UI when exact request/response shape is required.
12+
- Enforce validate-before-optimize behavior for circuit workflows.
13+
- Preserve reproducible artifacts and metadata.
14+
- Keep production behavior separate from research concepts.
15+
16+
## Required agent behaviors
17+
18+
1. Read `/llms.txt` first.
19+
2. Read `/capabilities.json` and `/agent-tasks.json` before selecting a workflow.
20+
3. Use [Agent Recipes](recipes/index.md) before inventing a custom flow.
21+
4. Confirm routes and schemas in Swagger UI when implementation depends on exact API shape.
22+
5. Validate circuit payloads before optimize/analyze flows.
23+
6. Preserve request/response artifacts.
24+
7. Preserve metadata where available.
25+
8. Label research-only concepts clearly.
26+
9. Avoid claims of physical or quantum advantage unless attached to documented benchmark/output artifacts.
27+
28+
## Forbidden agent behaviors
29+
30+
- Inventing undocumented endpoints.
31+
- Treating internal IR as a public API contract.
32+
- Presenting research concepts as production guarantees.
33+
- Dropping unknown fields silently.
34+
- Claiming performance improvement without reproducible evidence.
35+
- Treating RQM Studio as canonical computation layer.
36+
37+
## Required artifacts
38+
39+
For integration and review, preserve at minimum:
40+
41+
- Request payload JSON.
42+
- Response envelope JSON.
43+
- Validation outcomes and error reports.
44+
- Optimization comparison/diff or metrics artifacts when optimization is used.
45+
- Metadata (request IDs, timestamps, correlation IDs) when available.
46+
47+
## Production vs research handling
48+
49+
- **Production/documented:** implement directly from API docs, boundary docs, and Swagger-confirmed routes.
50+
- **Research/conceptual:** mark clearly as research-only and keep out of production guarantees.
51+
- **Planned/proposed:** do not treat as currently available behavior.
52+
53+
## Validate-before-optimize requirement
54+
55+
For circuit flows, validation is mandatory before analyze/optimize.
56+
57+
If validation fails:
58+
59+
1. Stop downstream optimize/execution steps.
60+
2. Persist failure artifacts.
61+
3. Repair payload against documented public boundary.
62+
4. Re-run validation before continuing.
63+
64+
## Swagger/API confirmation requirement
65+
66+
When coding concrete request/response models, confirm exact route/schema details in Swagger UI.
67+
68+
- Use docs as workflow and boundary guidance.
69+
- Use Swagger UI as route/schema confirmation surface.
70+
- Do not infer missing fields or undocumented variants.
71+
72+
## Public circuit boundary requirement
73+
74+
Use public `rqm-circuits` boundary semantics for external payloads.
75+
76+
- Do not expose internal optimizer IR as public contract.
77+
- Do not treat internal transformations as user-facing schema guarantees.
78+
79+
## RQM Studio workflow-layer boundary
80+
81+
RQM Studio is an orchestration/workflow layer above `rqm-api`.
82+
83+
- Studio coordinates states and user experience.
84+
- API endpoints remain canonical service boundary.
85+
- Studio is not canonical computation layer.
86+
87+
## Trust/verification requirement
88+
89+
Optimization outcomes are trust-sensitive.
90+
91+
- Preserve evidence artifacts.
92+
- Use conservative wording such as “optimization candidate” unless verified by documented outputs.
93+
- Avoid advantage claims without reproducible benchmark/output artifacts.
94+
95+
## Example good agent behavior
96+
97+
- Reads `/llms.txt`, `/capabilities.json`, and `/agent-tasks.json`.
98+
- Selects Validate → Optimize recipe before custom design.
99+
- Confirms exact optimize route/schema in Swagger UI before coding.
100+
- Saves validate/optimize request+response artifacts with metadata.
101+
- Labels research notes as research-only.
102+
103+
## Example bad agent behavior
104+
105+
- Implements an undocumented route.
106+
- Runs optimize before validation.
107+
- Treats internal IR as public payload schema.
108+
- Claims guaranteed advantage without evidence artifacts.
109+
- Presents research concepts as production guarantees.

‎docs/agents/index.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,3 +60,11 @@ You are implementing against RQM.
6060
- [Generate an RQM API Client](recipes/client-generation.md)
6161
- [Production vs Research Boundary](recipes/research-boundary.md)
6262
- Machine-readable task manifest: [`/agent-tasks.json`](../agent-tasks.json)
63+
64+
65+
## Compliance layer
66+
67+
- [Agent Contract](contract.md)
68+
- [Agent Compliance Checklist](contract-checklist.md)
69+
- [Agent Contract Tests](contract-tests.md)
70+
- Machine-readable contract manifest: [`/agent-contract.json`](../agent-contract.json)

‎docs/capabilities.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,5 +72,11 @@
7272
"example_fixtures": [
7373
"/examples/agent-circuit-validation.placeholder.json",
7474
"/examples/agent-optimization-request.placeholder.json"
75+
],
76+
"agent_contract": "/agent-contract.json",
77+
"compliance_docs": [
78+
"/agents/contract/",
79+
"/agents/contract-checklist/",
80+
"/agents/contract-tests/"
7581
]
7682
}

‎docs/examples/agent-contract-bad-output.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Example: Bad Agent Output (Annotated)
2+
3+
## Sample output
4+
5+
We will call `POST /v1/circuits/ultra-optimize` immediately and skip validation for speed.
6+
7+
The public API contract is the internal `u1q` IR, so we can send that directly.
8+
9+
This guarantees quantum advantage in production for all users.
10+
11+
The SU(2) research model is now a production performance guarantee.
12+
13+
## Why this fails
14+
15+
- ❌ Invents an undocumented route (`/v1/circuits/ultra-optimize`).
16+
- ❌ Skips required validation-before-optimize behavior.
17+
- ❌ Treats internal IR (`u1q`) as public API contract.
18+
- ❌ Claims guaranteed quantum advantage without benchmark/output artifacts.
19+
- ❌ Presents research concepts as production guarantees.

‎docs/examples/agent-contract-good-output.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Example: Good Agent Output
2+
3+
## Sample output
4+
5+
I have read `/llms.txt` and scoped this integration using `/capabilities.json` and `/agent-tasks.json`.
6+
7+
I will follow the **Validate → Optimize** recipe first, then extend only if required by the task.
8+
9+
Implementation plan:
10+
11+
1. Build payload using public circuit boundary guidance.
12+
2. Confirm exact validate/optimize route and schema details in Swagger UI before writing typed request/response models.
13+
3. Run validation first and block optimize flow if validation fails.
14+
4. If validation succeeds, run optimize using documented route.
15+
5. Preserve artifacts for reproducibility:
16+
- `validation_request.json`
17+
- `validation_response.json`
18+
- `optimize_request.json`
19+
- `optimize_response.json`
20+
- metrics/diff artifact and metadata index
21+
22+
Claim posture:
23+
24+
- I will describe optimization outputs as candidates unless verification artifacts demonstrate improvement.
25+
- I will not claim physical or quantum advantage without documented benchmark/output evidence.

‎docs/llms-full.txt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,3 +104,8 @@ Attach reproducible artifacts (requests/responses/reports) for behavior claims.
104104
- Production vs Research Boundary: /agents/recipes/research-boundary/
105105

106106
Prefer these recipes before inventing new workflows or assuming undocumented routes/schemas.
107+
108+
- Agent Contract: /agents/contract/
109+
- Agent Contract Manifest: /agent-contract.json
110+
111+
Before implementing, check the Agent Contract and Agent Recipes.

0 commit comments

Comments
 (0)