first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-07
@@ -0,0 +1,26 @@
+## Overview
+
+This is a documentation synchronization change. The codebase already implements the capabilities being clarified; the work is to remove stale "gap" and "deferred" language where it contradicts the current route catalog and tests, while leaving real future-work boundaries visible.
+
+## Scope
+
+- Update stale route/protocol/frontend/plugin documentation and API comments.
+- Do not alter request/response contracts, validators, services, frontend components, plugin SDK behavior, or run execution logic.
+- Do not mark future features as implemented unless an implemented route/client/test already exists.
+
+## Target Corrections
+
+- Frontend API contracts should show platform and server metrics endpoints as implemented.
+- AI provider protocol docs should show platform-mediated invocation as implemented while keeping live connectivity and remote model discovery deferred.
+- Run artifact protocol docs should show browser download as implemented while keeping platform-to-run download, browser upload, external object storage, presigned URLs, and production throttling as future work.
+- Platform API route docs should remove already-implemented config diff/file dispatch from deferred route groups.
+- Handler Swagger comments for artifact/log metadata should not claim implemented chunk ingest or durable log ingest remains deferred.
+- Plugin README should no longer describe marketplace, hosted plugin pages, or real lifecycle execution as future OpenSpec work when those flows now exist in bounded platform-mediated form.
+
+## Validation
+
+- Run a focused stale-marker scan for the corrected files.
+- Run `scripts/check-structure.sh`.
+- Run `openspec validate sync-implemented-docs-and-comments --strict`.
+
+No browser walkthrough is required because this change does not edit frontend pages or visual behavior.
@@ -0,0 +1,28 @@
+## Why
+
+Recent implementation changes completed platform metrics, config write/file dispatch, plugin bridge execution, mediated AI invocation, artifact browser download, and log/artifact transport behavior, but several route catalogs, protocol notes, frontend contracts, and handler comments still describe those capabilities as gaps or deferred work. Those stale references make it harder to tell which features are actually missing and which are already implemented.
+
+## What Changes
+
+- Update documentation and handler comments so implemented APIs are described as implemented.
+- Preserve explicit future-work boundaries for live external AI connectivity, remote model discovery, external storage adapters, browser upload, platform-to-run download, production throttling, server-side log filters, package acquisition, and remote plugin hosting.
+- Keep this change documentation-only; it does not add routes, runtime behavior, UI behavior, dependencies, or schema-breaking changes.
+
+## Capabilities
+
+### New Capabilities
+- `implemented-documentation-sync`: Keeps implementation-facing documentation and generated API comments aligned with completed platform/run/frontend/plugin capabilities.
+
+### Modified Capabilities
+- None.
+
+## Impact
+
+- Affected documentation and comments:
+  - `platform/api/routes.md`
+  - `platform/protocol/ai-provider-contracts.md`
+  - `run/protocol/artifact.md`
+  - `platform_web/api/contracts.md`
+  - `plugins/README.md`
+  - Swagger comments in `platform/api/resource_handlers.go`
+- No API, DTO, service, repository, frontend runtime, plugin SDK, or run executor behavior changes.
@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: Documentation Reflects Implemented Capabilities
+
+Implementation-facing documentation and API comments SHALL describe completed platform, run, frontend, and plugin capabilities as implemented when route registrations, clients, and tests already exist for those capabilities.
+
+#### Scenario: Previously deferred route is implemented
+
+- **GIVEN** a route or capability is listed in implemented route catalogs or has active client/API tests
+- **WHEN** documentation or handler comments describe that same route or capability
+- **THEN** they SHALL identify it as implemented instead of as a gap, placeholder, or deferred behavior.
+
+#### Scenario: Future work remains explicit
+
+- **GIVEN** a related capability is still intentionally out of scope
+- **WHEN** documentation is synchronized
+- **THEN** it SHALL keep that capability listed as future work without implying current implementation.
+
+#### Scenario: Documentation-only synchronization
+
+- **GIVEN** stale documentation is corrected
+- **WHEN** the change is implemented
+- **THEN** it SHALL NOT introduce runtime behavior, API contract, frontend page, plugin SDK, or run executor changes.
@@ -0,0 +1,16 @@
+## 1. OpenSpec Artifacts
+
+- [x] 1.1 Create proposal, design, spec, and tasks artifacts for a documentation-only synchronization change.
+- [x] 1.2 Validate the new change with `openspec validate sync-implemented-docs-and-comments --strict`.
+
+## 2. Documentation Synchronization
+
+- [x] 2.1 Update platform API route documentation to remove stale deferred/gap language for implemented metrics, config diff, file dispatch, log ingest/query, artifact chunks, browser artifact download, plugin bridge execution, and mediated AI invocation while preserving real future-work boundaries.
+- [x] 2.2 Update AI provider, run artifact, frontend API, and plugin README documentation to match implemented behavior.
+- [x] 2.3 Update stale handler Swagger comments for artifact and log stream metadata.
+
+## 3. Verification
+
+- [x] 3.1 Run focused stale-marker scans for the corrected files.
+- [x] 3.2 Run `scripts/check-structure.sh`.
+- [x] 3.3 Run `openspec validate sync-implemented-docs-and-comments --strict` after implementation.