administrator/DocForge2
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Packages Wiki Activity Actions Pages
DocForge2/docs/MILESTONE_3_CLOSEOUT.md

4.7 KiB
Raw Blame History

Milestone 3 closeout

Outcome

Milestone 3 is complete. Manual compilation, portable graph rendering, and the live viewer are separate generation-pinned consumers of the validated graph. They cannot become canonical or retrieval authority.

Implemented contracts:

  • Version-1 ManualRenderPlan, GraphViewPlan, projection package, and projection receipt.
  • Strict canonical JSON identities and packaged Draft 2020-12 schemas.
  • Independent manual and portable-graph renderer import boundaries.
  • One isolated, fixed, one-request detached worker protocol with bounded request, response, artifact, timeout, environment, and renderer inventory.
  • Content-addressed portable graph artifacts, renderer receipts, generation/view manifests, receipt-only status, repair, and degraded committed-publication evidence.
  • Disposable semantic fragment records with bounded cache inventory, corruption recovery, and full-render equivalence.
  • Version-2 independent projection policy while preserving version-1 effective-policy behavior.
  • Generation-pinned live source reads and a separate read-only viewer-manager lifecycle.
  • Automated axe-tag and keyboard gates for the manual, portable graph, and live viewer.
  • Repository-native contract, smoke, scale, response-size, memory, and equivalence gates.

Candidate evidence

The frozen implementation candidate is f5dccb5e1c312121f1af63780162f593d9363b98.

The complete repository gate passed:

  • Ruff formatting and lint.
  • HTML, rendered-manual HTML, portable-graph HTML, CSS, and JavaScript checks.
  • Pyright with zero diagnostics.
  • Warning-strict compilation and tests.
  • 281 tests and 272 subtests.
  • Three Playwright and axe accessibility flows. The alpha manual is checked with WCAG 2.0/2.1 A/AA axe tags; portable and live graph flows add WCAG 2.2 A/AA tags and keyboard interaction.
  • Lock and npm dependency-tree checks.
  • Wheel and source-distribution builds.
  • Milestone 0, 1, 2, and 3 smoke benchmarks.

The maintained projection contract subset passed 142 tests and 236 subtests. A 10,000-node deep chain and one 10,000-node strongly connected component prove that manual cycle planning has no recursion-depth failure.

An isolated wheel installation passed CLI and MCP startup, a real detached manual render, and the closed malformed-worker-request contract. Six Milestone 3 commits and the complete candidate tree passed Gitleaks 8.30.1 with no findings.

Three independent adversarial review tracks covered manual isolation and fragment integrity, portable publication and policy binding, and worker/accessibility/benchmark gates. Reproduced project import, hostile environment, unbounded stdout, fragment forgery, cache growth, aggregate overflow, coordinated policy drift, render-limit compatibility, deep-graph, and module-startup defects were fixed and regression-tested before closeout.

The clean ten-sample 1,000-node benchmark passed every threshold. Exact measurements, equivalence results, memory peaks, and response sizes are recorded in MILESTONE_3_BASELINE.md and benchmarks/milestone3-2026-07-29.json.

Preserved boundaries

  • The docforge distribution, package, CLI, MCP executable, and existing tool names remain.
  • The frozen alpha manual remains exactly 2,043 bytes with its legacy output hash and render identity.
  • Legacy one-method load_projection() adapters remain supported.
  • Effective policy version 1, no-AST behavior, and existing client bindings remain compatible.
  • Project descriptor schema version 1 and SQLite index schema version 3 remain unchanged.
  • Configured max_render_bytes values above the detached transfer ceiling still load; a small actual artifact renders normally. Actual detached transfer remains capped at 20,000,000 bytes.
  • No storage replacement or self-hosting dependency was introduced.
  • WorldForge and ScrapeStation were not touched.
  • No production MCP integration was repointed.
  • The legacy Forgejo repository and legacy remote were not changed.
  • No tag, release, release announcement, or visibility change was created.

Known follow-up work

Milestone 4 remains directional and is not active. Its adapter SDK and product-documentation work must not silently absorb these separate future ideas:

  • Optimize production fragment reuse only from measured profiles while preserving the forced-full oracle.
  • Add authenticated cursors only if a stronger threat model requires them.
  • Verify Claude's native timeout representation.
  • Add versioned adapter-owned launcher metadata before generating custom-adapter configurations.
  • Keep remote render services, shared render farms, third-party renderers, storage replacement, and self-hosting deferred until their own evidence justifies them.