Add missing protocol documentation for QA, Contracts, and AI categories

[Copilot]

Documentation gap analysis revealed 10 undocumented protocols across the spec. This adds comprehensive reference documentation to achieve full protocol coverage.

Changes

New Protocol Categories (2)

• QA Protocol (content/docs/references/qa/)

  • Testing protocol: test suites, scenarios, steps, actions, assertions

• Contracts (content/docs/references/contracts/)

  • TypeScript interfaces for plugin implementations
  • Data Engine: IDataEngine, DriverInterface
  • Plugin Validator: IPluginValidator, ValidationResult
  • 7 additional contract interfaces

Completed AI Protocols (2)

• DevOps Agent: Autonomous CI/CD with GitHub/Vercel integration
• Feedback Loop: Runtime issue detection and self-healing architecture

Updated References

• Main index updated: 109 → 119 documented protocols
• Added navigation for new categories

Example Usage

import { TestSuiteSchema } from '@objectstack/spec/qa';
import type { IDataEngine } from '@objectstack/spec/contracts';

// QA Protocol
const testSuite: TestSuite = {
  name: 'CRM Tests',
  scenarios: [{
    id: 'test-001',
    steps: [{ name: 'Create contact', action: { type: 'create_record', ... }}]
  }]
};

// Contracts
class PostgresEngine implements IDataEngine {
  async find(objectName: string, query?: DataEngineQueryOptions) { ... }
}

All documentation follows existing patterns with TypeScript examples, use cases, and best practices.

Original prompt

扫描所有软件包代码和spec协议，对官网文档进行必要的更新

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Feb 2, 2026 11:05am

[Copilot]

Pull request overview

This PR fills documentation gaps by adding reference docs for the QA testing protocol, contracts layer, and two AI protocols (DevOps Agent and Feedback Loop), and wires them into the main reference index.

Changes:

• Added a new QA protocol section (index + Testing reference) describing TestSuite, TestScenario, TestStep, actions, assertions, and context usage.
• Introduced a Contracts section with per-interface pages (data engine, logger, HTTP server, plugin validator, schema driver, service registry, lifecycle events, startup orchestrator) and linked it from the global reference index.
• Documented the AI DevOps Agent and Feedback Loop schemas with TypeScript usage examples and use cases, and updated the global reference index counts and navigation.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
content/docs/references/qa/testing.mdx	New QA Testing protocol reference describing TestContext, action/assertion enums, and TestSuite/TestScenario/TestStep structures, aligned with packages/spec/src/qa/testing.zod.ts.
content/docs/references/qa/meta.json	Registers QA reference pages (index, testing) for the docs navigation.
content/docs/references/qa/index.mdx	QA protocol overview page summarizing capabilities and linking to the Testing reference.
content/docs/references/index.mdx	Updates protocol index with QA and Contracts sections, increases total protocol count, and adds a table for contract interfaces (note: currently mislabels Logger and IHttpServer names).
content/docs/references/contracts/data-engine.mdx	Detailed docs for IDataEngine and DriverInterface, including method-by-method explanations and examples matching data-engine.ts.
content/docs/references/contracts/http-server.mdx	Overview of the HTTP server contract (IHttpRequest, IHttpResponse, RouteHandler, Middleware, IHttpServer) with correct source pointer.
content/docs/references/contracts/index.mdx	Contracts overview explaining the concept of contracts vs Zod schemas and linking to all individual contract pages.
content/docs/references/contracts/logger.mdx	Logger contract reference with a TypeScript example (currently imports/implements ILogger instead of the actual Logger interface).
content/docs/references/contracts/meta.json	Contracts section metadata listing all contract pages for the sidebar/navigation.
content/docs/references/contracts/plugin-lifecycle-events.mdx	High-level description of plugin lifecycle event interfaces, tied to plugin-lifecycle-events.ts.
content/docs/references/contracts/plugin-validator.mdx	Extensive Plugin Validator docs and examples (currently out of sync with IPluginValidator regarding validateSignature signature and missing validateDependencies in example implementations).
content/docs/references/contracts/schema-driver.mdx	Schema driver contract overview for DDL/migration operations.
content/docs/references/contracts/service-registry.mdx	Service registry contract overview for registering and resolving services.
content/docs/references/contracts/startup-orchestrator.mdx	Startup orchestrator contract overview for plugin startup ordering and health-check orchestration.
content/docs/references/ai/feedback-loop.mdx	Feedback Loop protocol reference for runtime issues and AI-driven resolutions, with examples (one changeSet example does not match the actual ChangeSetSchema shape).
content/docs/references/ai/devops-agent.mdx	DevOps Agent protocol reference describing configuration for codegen, CI/CD, deployment, monitoring, and integrations, broadly consistent with devops-agent.zod.ts.

[Copilot]

The metadata_change example for Resolution.fix builds a changeSet object with fields like operation, object, and field, but FeedbackLoopSchema requires changeSet to conform to ChangeSetSchema from packages/spec/src/system/migration.zod.ts (with identifiers and an operations array). To ensure this example actually validates, please update the changeSet shape here to a valid ChangeSetSchema instance or reference.

Suggested change

	operation: 'update',
	object: 'contact',
	field: 'email',
	changes: {
	validation: {
	pattern: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$',
	message: 'Please enter a valid email address'
	}
	}
	id: 'change-contact-email-validation',
	operations: [
	{
	id: 'op-update-contact-email-validation',
	operation: 'update',
	object: 'contact',
	field: 'email',
	changes: {
	validation: {
	pattern: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$',
	message: 'Please enter a valid email address'
	}
	}
	}
	]

[Copilot]

This method reference documents validateSignature(plugin: Plugin, signature: string): boolean, but IPluginValidator in packages/spec/src/contracts/plugin-validator.ts defines validateSignature?(plugin: Plugin): Promise<boolean> with a single plugin parameter. Please align this signature and return type with the actual interface (async, single parameter) or adjust the interface if the two-argument sync form is what you intend to expose.

[Copilot]

BasicPluginValidator implements validateSignature(plugin: Plugin, signature: string): boolean, but the IPluginValidator contract in packages/spec/src/contracts/plugin-validator.ts defines validateSignature?(plugin: Plugin): Promise<boolean> with a single plugin parameter. This example should be updated to use the async single-parameter signature so it type-checks against IPluginValidator.

Suggested change

	validateSignature(plugin: Plugin, signature: string): boolean {
	// Placeholder - implement cryptographic verification
	// This would verify the plugin code against the signature
	return signature.startsWith('sha256:');
	async validateSignature(plugin: Plugin): Promise<boolean> {
	// Placeholder - implement cryptographic verification
	// This would verify the plugin code's integrity and authenticity
	return true;

[Copilot]

The usage example imports and implements ILogger, but the actual contract exported from packages/spec/src/contracts/logger.ts is the Logger interface. To keep the docs type-correct and consistent with the code, this snippet should import and implement Logger instead of ILogger.

Suggested change

	import type { ILogger } from '@objectstack/spec/contracts';
	class MyLogger implements ILogger {
	import type { Logger } from '@objectstack/spec/contracts';
	class MyLogger implements Logger {

[Copilot]

The Contracts overview table lists interface names ILogger and IHTTPServer, but the actual interfaces in packages/spec/src/contracts/logger.ts and http-server.ts are named Logger and IHttpServer respectively. Please update these interface names in the table to match the real contract types so the docs stay consistent with the code.

Suggested change

	| `logger.ts` | `ILogger` | Logging interface |
	| `http-server.ts` | `IHTTPServer` | HTTP server interface |
	| `logger.ts` | `Logger` | Logging interface |
	| `http-server.ts` | `IHttpServer` | HTTP server interface |

[Copilot]

The MyPluginValidator example omits the required validateDependencies(plugin: Plugin, registry: Map<string, Plugin>): void method from the IPluginValidator contract in packages/spec/src/contracts/plugin-validator.ts, so the class as written would not satisfy the interface. Consider adding a minimal validateDependencies implementation (or clearly marking it as omitted) to keep the example type-correct.