From fee2bb00805fd21f321c2bf49ca5cdbec448bd65 Mon Sep 17 00:00:00 2001 From: Andraxion Date: Wed, 29 Jul 2026 14:14:52 -0400 Subject: [PATCH] Activate Milestone 4 adapter SDK contract --- ACTIVE_SLICE.md | 73 ++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 66 insertions(+), 7 deletions(-) diff --git a/ACTIVE_SLICE.md b/ACTIVE_SLICE.md index 4d6b119..bd86996 100644 --- a/ACTIVE_SLICE.md +++ b/ACTIVE_SLICE.md @@ -2,12 +2,71 @@ ```text Last completed milestone: 3 — independent projections -Outcome: Manual output, portable graph artifacts, and the live viewer are independent generation-pinned consumers of the validated graph. -Evidence: Clean candidate f5dccb5e1c312121f1af63780162f593d9363b98; 281 tests and 272 subtests; 3 accessibility flows; clean 1,000-node ten-sample benchmark; isolated wheel proof; no secret-scan findings. -Active milestone: None. -Next directional milestone: 4 — adapter SDK and product documentation. -Status: Milestone 3 is closed. Milestone 4 has not started. +Evidence: d6d9f47672c513c4927c5c42ad97a175ed651a74 is merged and pushed on main and dev. +Active milestone: 4 — adapter SDK and product documentation. +Outcome: New projects can adopt DocForge incrementally, and users can understand the CLI, MCP server, policies, adapters, renderers, and agent integration without reading implementation code. +Status: Active. The first gate freezes and proves the adapter SDK before language references. +Next directional milestone: 5 — stabilization and first DocForge2 release. ``` -Milestones 4–5 remain directional context. Do not begin Milestone 4 without a new active-slice -contract. +## Milestone 4 contract + +Milestone 4 closes only when all of the following are true: + +1. A typed public adapter SDK and repository-native conformance kit make complete, incremental, + Logic, confinement, restart, cache-recovery, no-AST, and retrieval contracts usable without + reading core implementation. +2. Repository-owned runnable reference integrations exist for Python, JavaScript/TypeScript, and + C++. They declare their evidence authorities and unsupported facts. Syntax-only evidence never + claims compiler-resolved calls, inheritance, types, or ownership. +3. Heavy language frontends are optional. A base wheel and no-AST operation work without them. + Missing optional features fail with closed, actionable errors. +4. CLI and MCP reference tables are generated deterministically from implementation-owned + metadata and a repository gate rejects drift. +5. Custom adapters can declare one versioned, immutable, project-bound launcher. Codex, Claude, + and OpenClaw client configuration is generated from that launcher without arbitrary discovery + or execution. +6. Dedicated onboarding, authority, descriptor, policy, adapter, language, legacy/no-AST, + rendering, agent-integration, security, recovery/performance, and DocForge v1 migration + guidance passes a fresh-wheel adoption proof. +7. Existing package, import, CLI, MCP, legacy-adapter, generic-project, no-AST, projection, + application, and recovery behavior remains additively compatible. + +## Fixed decisions + +- Milestone 4 provides stable in-repository SDK APIs and reference integrations. It does not + promise separately published language-adapter distributions. +- Complete adapter evidence includes primary graph and function Logic. An incremental adapter that + publishes Logic must expose an independent complete Logic oracle before equivalence can pass. +- Python reference evidence may use the standard-library AST. JavaScript/TypeScript and C++ + reference evidence uses optional pinned parsing frontends for syntax plus declared build + inventory. It omits semantic facts that require a compiler, language server, or SCIP evidence. +- C++ inventory is bound to a project-confined compilation database. WorldForge is not used or + changed. +- JavaScript and TypeScript are both exercised. TypeScript support requires its own optional + pinned grammar; it is not silently parsed as JavaScript. +- Adapter extraction caches remain disposable and may become safely ahead of the last published + SQLite index. The index remains the active validated generation. Recovery must prove this + behavior instead of claiming one joint cache-and-index transaction. +- Generated references and templates are derived artifacts. Implementation metadata is their + authority. + +## Exclusions + +- No WorldForge, ScrapeStation, legacy-repository, or production-binding change. +- No remote adapter execution, arbitrary adapter commands, renderer ecosystem, render farm, + storage rewrite, or cross-project graph. +- No compiler or language-server installation by DocForge. +- No self-hosting requirement. +- No version, release tag, or Forgejo release before Milestone 5. + +## Slice order + +1. Freeze complete graph-plus-Logic equivalence, the SDK facade, conformance protocol, schemas, and + baseline measurements. +2. Add deterministic command metadata, generated CLI/MCP references, and a drift gate. +3. Add the Python reference integration and scaled complete/incremental benchmark. +4. Add optional JavaScript/TypeScript and C++ reference integrations with bounded evidence. +5. Add versioned adapter launcher metadata and generated agent configurations. +6. Freeze the candidate, perform one documentation closeout, and run focused, complete, + fresh-wheel, adoption, benchmark, accessibility, build, and secret-scan gates.