DocForge2/SLICE_HISTORY.md

Completed slices

DFG-15 strict static typing gate

Changed

• Made the existing strict Pyright configuration resolve DocForge's .venv automatically.
• Converted validated TOML, JSON, subprocess, socket, MCP, render, and visualization boundaries from unknown dynamic values into explicit checked types.
• Kept runtime validation and fail-closed behavior at every untrusted input boundary.
• Made strict pyright an explicit repository development gate.

Verification

• Pyright reports zero errors, warnings, or informational diagnostics across all source modules.
• Ruff lint and formatting, Python compilation, all 52 warning-strict tests, and diff checks pass.

DFG-14.1 detached viewer lifecycle correction

Changed

• Released DocForge 0.8.1 with the existing graph-browser@5 interface.
• Moved the loopback listener into a detached worker so MCP transport teardown cannot kill an active viewer.
• Bound the worker to the longer-lived MCP client host plus the existing browser lease and startup grace.

Verification

• Added a process-boundary regression test that exits the launching transport process, verifies the viewer still responds, and then verifies lease expiry.
• Retained the in-process listener tests for token confinement, read-only behavior, stale-index rejection, and lease renewal.

DFG-14 durable graph navigation

Changed

• Released the fixed graph-browser@5 template and DocForge 0.8.0.
• Kept the loopback listener alive across short-lived MCP standard-input transactions with a browser-renewed lease, while preserving explicit process termination and bounded abandoned-page cleanup.
• Added a visible disconnected state instead of leaving stale controls to fail silently.
• Added pointer and keyboard resizing for both side panels.
• Made the unblurred modal natively resizable and draggable by its constrained title bar.
• Added generic topology-derived Primary focus, Children, and Edge & context navigation sections.
• Arranged neighborhoods by shortest-hop rings and applied distinct role palettes that darken progressively by hop distance, capped at fifty percent.
• Kept all category and color decisions client-side without changing project graph facts.

Verification

• Focused HTTP tests cover heartbeat renewal, bounded lease expiry, non-daemon listener ownership, and the unchanged token/read-only boundary.
• A deterministic JavaScript harness proves topology roles, hop rings, and distance shading.
• Embedded JavaScript syntax and interaction-contract checks cover panel resizing, modal movement and resizing, unblurred backdrop behavior, grouped navigation, and lease renewal.
• Ruff, formatting, compilation, the complete warning-strict suite, and live project-bound viewer checks pass.

Limits

• Panel widths, modal geometry, viewport position, and open dialog state are not persisted.
• Topology roles are presentation aids. They do not replace project-authored relationship meaning.
• Background-browser timer throttling is tolerated by the three-minute lease but may delay cleanup.

Next gate

No further gate is planned. Measure use before adding saved layouts, minimaps, or export.

DFG-13 graph activation reliability

Changed

• Released the fixed graph-browser@4 template.
• Delayed SVG pointer capture until movement crosses the four-pixel drag threshold so an ordinary click remains targeted at the graph node and reaches the modal inspection handler.
• Preserved pointer capture and click suppression for actual canvas drags.
• Added an explicit hidden-state rule so rendered neighborhoods remove the empty-canvas instruction.
• Kept the token-bound HTTP surface, graph data, and listener lifetime unchanged.
• Released the compatible fix as DocForge 0.7.3.

Verification

• Focused interaction-contract checks distinguish click setup from drag pointer capture and cover empty-state hiding.
• Embedded JavaScript syntax validation, Ruff, formatting, compilation, and the complete warning-strict 49-test DocForge suite pass.

Limits

• The listener remains owned by the MCP process and closes when that process exits.
• Browser state remains client-local and is not persisted.

Next gate

No further gate is planned. Measure graph-browser use before adding history, comparison, or editing surfaces.

DFG-12 modal node inspection

Changed

• Released the fixed graph-browser@3 template with a native modal node inspector.
• Made graph-node activation inspect full validated node metadata and content without replacing the current neighborhood or viewport.
• Added mouse and keyboard activation plus Escape, explicit close controls, and backdrop dismissal.
• Added a separate Explore neighborhood action for intentional graph recentering.
• Kept the existing token-bound, read-only HTTP surface and exact-node endpoint unchanged.
• Released the compatible change as DocForge 0.7.2.

Verification

• Focused HTTP interaction-contract checks cover the dialog, inspection handler, and explicit neighborhood action.
• Embedded JavaScript syntax validation and the complete warning-strict DocForge suite pass.

Limits

• Dialog state is session-local and is not persisted in the URL.
• Node content remains plain text and is not rendered as trusted HTML.
• The right sidebar continues to describe the current root neighborhood.

Next gate

No further gate is planned. Measure graph-browser use before adding history, comparison, or editing surfaces.

DFG-11 graph viewport navigation

Changed

• Released the fixed graph-browser@2 template with pointer-centered mouse-wheel zoom.
• Added left-button drag pan with pointer capture and a four-pixel movement threshold.
• Preserved normal node activation by suppressing click navigation only after an actual drag.
• Added keyboard-operable zoom-in, zoom-out, and reset buttons plus a live zoom percentage.
• Reset the viewport whenever a new root neighborhood loads.
• Kept all viewport behavior client-side without adding HTTP endpoints or project authority.
• Released the compatible change as DocForge 0.7.1.

Verification

• Focused HTTP tests and embedded JavaScript syntax validation cover button zoom, reset, pointer-centered wheel zoom, left-drag pan, and preserved node-click handling. The current agent runtime did not expose its rendered browser automation connection, so no rendered interaction claim is made for this gate.
• The complete warning-strict DocForge suite passes.

Limits

• Viewport position is session-local and is not persisted.
• The radial layout itself remains deterministic and fixed.
• A minimap, saved node positions, and alternate layouts remain outside the current contract.

Next gate

No further gate is planned. Measure dense-graph use before adding more navigation or layout features.

DFG-10 project-bound graph visualization

Changed

• Added the fixed docforge_visualize MCP read tool to generic, read-only adapter, and proposal-enabled adapter servers.
• Added the built-in graph-browser@1 HTML/CSS/JavaScript template with project overview, family filtering, lexical search, exact node content, and bounded neighborhood traversal.
• Bound the ephemeral HTTP listener to 127.0.0.1 on an operating-system-selected port.
• Added an unguessable per-process URL token and rejected every non-token path.
• Exposed only fixed GET and HEAD endpoints. Rejected POST, PUT, PATCH, and DELETE.
• Validated the complete project and index once per MCP invocation, then served fast queries from the exact validated SQLite snapshot.
• Rejected index replacement or alteration after launch and required reinvocation to refresh.
• Accepted no project root, database path, SQL, template path, bind address, command, or renderer.
• Released the capability as DocForge 0.7.0 without changing canonical-write policy.

Verification

• Protocol tests exercised the new tool through the official in-memory MCP transport.
• HTTP tests proved token confinement, loopback binding, security headers, read-only methods, deterministic results, exact node retrieval, and snapshot invalidation.
• Cross-project tests ran two simultaneous visualization servers and proved separate project data, ports, tokens, and indexes.
• The complete warning-strict DocForge suite passed.
• Ani-web proof loaded 3,289 nodes and 6,292 edges. After one full validation, the graph overview returned in approximately 0.30 seconds and a node neighborhood in approximately 0.03 seconds.

Limits

• The browser is a validated index snapshot, not a live canonical-file watcher.
• It is reachable only from the machine running the MCP process.
• It does not persist, publish, or externally host a visualization.
• It does not infer relationships beyond the configured project's graph.

Next gate

No further gate is planned. Measure actual graph-browser use before adding layout modes, exports, remote access, or project-declared visualization templates.

DFG-9 controlled application decision

Decision

• Retained manual canonical integration as the permanent DocForge 0.x policy.
• Added no application command to the library, CLI, or MCP server.
• Kept project builders, tests, Git, deployment, and publication under developer or project-owner control.
• Required a new approved gate with measured multi-project evidence before canonical application can be reconsidered.

Evidence

• DFG-8 produced one real content-only AssetForge proposal and one manual chapter replacement.
• Validation, conflicts, diffs, previews, and stale-source handling were already automated.
• Manual integration completed without an error, lost work, or meaningful repeated cost.
• Automating the remaining step would require canonical writers, developer authorization, atomic rollback, failure recovery, and project-format ownership that the current evidence does not justify.
• Existing exact-surface MCP tests prohibit application tools, and proposal tests preserve canonical source bytes.

Limits

• DocForge does not apply, commit, push, build, deploy, or publish canonical changes.
• Reopening the decision requires a separately approved, versioned contract and cannot add MCP canonical application.

Next gate

No further DFG gate is planned. Continue measured adoption through project-owned integrations.

DFG-0 contract freeze and DFG-1 standalone read-only core

Changed

• Created the standalone DocForge repository and versioned the project, node, edge, result, and reserved changeset contracts.
• Added one-root project descriptors with confined canonical, authority, cache, and index paths.
• Added generic Markdown front matter and TOML node loading, stable IDs, typed relationships, authority classes, limits, deterministic ordering, dependency-cycle validation, and hashes.
• Added atomic SQLite FTS5 indexes with project-root fingerprints, source revisions, logical row validation, stale rejection, and preservation of the previous index when rebuilds fail.
• Added exact lookup, bounded search and filtering, backlinks, dependencies, impact traversal, and cited token-budgeted context compilation with explicit omissions.
• Added deterministic JSON CLI commands for project information, validation, index operations, retrieval, traversal, and context compilation.
• Added two unrelated generic fixtures. No Worldforge or AssetForge vocabulary entered the core.

Verification

• Ruff lint and format checks passed.
• Python compilation passed.
• All 13 unit and integration tests passed.
• Tests covered root and symbolic-link escapes, unknown configuration, cache overlap, duplicate and broken graph state, dependency cycles, source-set changes, stale indexes, tampered rows, cross-project cache reuse, query-time source changes, deterministic retrieval, and bounded context.
• Installed CLI proof built and checked a temporary project index, returned the expected search result, selected the required node and dependency, used 153 of 180 estimated tokens, and reported the omitted proof node.

Limits

• No MCP server exists yet.
• No changeset or write operation exists.
• No project adapter or renderer exists.
• The token estimator is deliberately conservative and lexical; measured project adoption remains a later gate.

Next gate

DFG-2: expose only the proven read operations through a project-bound local stdio MCP server.

DFG-2 project-bound read-only MCP server

Changed

• Pinned the official stable MCP Python SDK to the compatible mcp>=1.28,<2 release line.
• Added a local standard input/output server bound to one immutable project root at startup.
• Exposed eleven read tools for project health, contract boundaries, exact lookup, search, metadata filtering, backlinks, dependencies, impact, bounded context, source validation, and render status.
• Added project identity, root fingerprint, revision, source hash, adapter version, staleness, server version, and an untrusted-content warning to tool results.
• Added structured domain failures for missing nodes, stale indexes, and oversized results without returning partial content.
• Exposed no write, proposal, arbitrary file, shell, Git, build, deployment, publication, or project-switching operation.
• Kept cache rebuilding as an explicit CLI integration action. MCP queries fail closed when the derived index is missing or stale.

Verification

• Ruff lint and format checks passed.
• Python compilation passed.
• All 19 core, CLI, and MCP tests passed with ResourceWarning treated as an error.
• Protocol tests called all eleven tools through the official in-memory MCP transport.
• A separate subprocess test initialized the server through real stdio transport and retrieved only its configured fixture project.
• Tests proved the exact read-only tool surface, fixed project identity, structured missing and stale failures, output limits, explicit omissions, safe fallback when passive Git revision detection is unavailable, and the absence of canonical write tools.

Limits

• The server cannot create changesets or proposals yet.
• The server cannot rebuild its own index.
• Render status reports not_configured until DFG-4 defines renderer orchestration.
• Worldforge and AssetForge adapters remain unopened.

Next gate

DFG-3: add isolated, hash-bound proposal changesets without canonical write authority.

DFG-3 isolated changesets

Changed

• Added a confined changeset root and project-declared proposal writers with explicit family and operation permissions.
• Bound proposal identity once at MCP server startup. Tools cannot select or impersonate a writer.
• Added ordered, project-bound JSON changesets with canonical base revision and source hash, root fingerprint, creator, optimistic changeset hash, expected node hashes, rationales, and structured relationship changes.
• Added create, update, same-format move, and delete proposals. Deletes require exact removal of every incident relationship; required profile nodes cannot be deleted.
• Added deterministic projected graph validation and structured metadata, content, source, and relationship diffs without changing canonical files.
• Added exact stale-base, stale-node, stale-changeset, ownership, family, operation, path, graph, source, size, and cross-proposal conflict failures.
• Added process-safe file locking, atomic replacement, symbolic-link rejection, source confinement, configured limits, and rollback if canonical inputs change during proposal storage.
• Added nine MCP proposal tools, including stale-safe proposal inspection and bounded listing. Canonical application, previews, arbitrary commands, Git mutation, builds, deployment, and publication remain absent.

Verification

• Focused core tests cover all four operation types, deterministic diffs, canonical immutability, simultaneous append serialization, overlapping changesets, stale identities, atomic failures, family permissions, ownership, target confinement, symbolic links, and configuration validation.
• Protocol tests call all four mutation tools through the official in-memory MCP transport and prove fixed writer identity, isolated output, validation, deterministic diff retrieval, and the disabled mutation behavior of a server without a writer.
• Ruff formatting and lint checks, Python compilation, all five JSON schema parses, and the locked dependency check passed.
• All 29 core, CLI, changeset, concurrency, in-memory MCP, and real stdio tests passed with ResourceWarning treated as an error.

Limits

• Changesets are proposals only. DocForge does not apply them to canonical project files.
• A changeset may operate on a node once; a later operation on the same node requires another changeset after external integration.
• Moves preserve the canonical source format. Cross-format conversion belongs to a future adapter or explicit migration contract.
• Preview generation and renderer orchestration remain unopened.

Next gate

DFG-4: add deterministic previews and confined renderer orchestration without canonical application.

DFG-4 deterministic previews and renderer orchestration

Changed

• Added optional project-declared template, preview, view, and derived-output configuration with strict root confinement, overlap rejection, stable view IDs, and configured size limits.
• Added an explicit renderer protocol backed by a closed built-in registry. Configuration cannot name commands, modules, executable paths, or undeclared renderers.
• Added the generic_html renderer with pinned markdown-it-py CommonMark parsing, disabled raw HTML, fixed safe template tokens, deterministic node ordering, navigation, metadata, content, and relationship output.
• Added render identities covering canonical and proposal inputs, node and edge identities, view configuration, template hash, renderer contract, and exact Markdown parser version.
• Added atomic per-view CLI rendering, non-writing render status, and isolated changeset previews. Input changes detected before replacement preserve prior output.
• Added docforge_preview_changeset to MCP and made docforge_render_status report configured view hashes and state. MCP cannot render declared project output or select a renderer or command.
• Split shared configuration validation, render configuration, renderer contract, and orchestration into focused modules instead of expanding the project loader or MCP translation layer.

Verification

• Renderer tests prove repeatable identities and bytes, current and stale status, isolated previews, escaped raw HTML, CommonMark conversion, unchanged canonical and declared output, configured limits, symbolic-link rejection, and preservation of prior output after invalid or changing input.
• Configuration tests reject command-like fields, unsupported renderer IDs, protected output paths, undeclared views, oversized templates and output, and unsafe symbolic links.
• CLI tests cover declared render, render status, isolated preview, and structured unknown-view failure. Protocol tests exercise preview through the official in-memory MCP transport and prove declared output remains absent.
• Ruff formatting and lint checks, Python compilation, all five JSON schema parses, and the locked dependency check passed.
• All 35 core, CLI, changeset, concurrency, renderer, in-memory MCP, and real stdio tests passed with ResourceWarning treated as an error.

Limits

• The first built-in renderer emits one self-contained HTML file per view. Multi-file asset bundles and project-specific view models remain future adapter work.
• Preview generation validates proposals but does not apply them to canonical documentation.
• Declared project-output rendering is an explicit local CLI integration action, not an MCP tool.
• Worldforge and unrelated-project adapters remain unopened.

Next gate

DFG-5: reproduce Worldforge semantics and generated output through a shadow-only adapter without changing the live workflow.

DFG-5A Worldforge non-AssetForge shadow proof

Changed

• Added a reusable adapter contract with ordered project projections, adapter metadata, root and identity validation, a standard read-index bridge, and byte-exact artifact comparison.
• Generalized the derived index boundary to accept any immutable project service without changing generic project loading, proposals, rendering, or MCP behavior.
• Added a Worldforge-local shadow adapter that translates the existing normalized manual index into core nodes and edges while retaining acceptance and relationship provenance as adapter metadata.
• Kept Worldforge-specific weighted search, backlink ordering, context profiles, and render-model composition in the Worldforge adapter.
• Excluded the independently managed AssetForge family and combined manual output from this subgate.

Verification

• The shadow graph matched 522 nodes and 805 edges exactly and built through DocForge's standard disposable index.
• Exact lookup, three weighted searches, active-development filtering, Phase 5 backlinks, and Phase 5 dependency traversal matched the current Worldforge index.
• Active, Phase 3, and Phase 5 context packs were byte-repeatable. Active also matched the current derived context cache.
• All 31 generated outputs that do not require AssetForge matched committed bytes. The proof wrote only temporary derived files and removed them afterward.
• DocForge adapter-contract tests cover standard index use, graph and metadata rejection, identity changes, cache confinement, and complete byte-exact artifact comparison.

Limits

• The remaining 10 AssetForge nodes, 25 incident edges, AssetForge context profile, and combined manual/manual.html output are not read or rebuilt by this proof.
• The shadow adapter is an explicit local command. It is not discoverable or executable through the normal MCP server.

Next gate

DFG-5B: complete the full-family shadow proof when AssetForge is explicitly authorized.

DFG-5B Worldforge full-family shadow completion

Changed

• Expanded the Worldforge-local adapter from the partial proof to all source families, including the ten AssetForge nodes and their 25 incident edges.
• Added a Worldforge-owned AssetForge context profile with deterministic source ordering, stable node and source citations, a hard token budget, and explicit omission records.
• Routed the shadow render comparison through the complete Worldforge builder output inventory, including the combined manual/manual.html output.
• Released the adapter boundary as DocForge 0.4.0. Worldforge-specific context, query, and render policy remains outside the generic core.

Verification

• The shadow graph matched all 532 nodes and 830 edges exactly through DocForge's standard disposable index.
• Exact lookup, five weighted searches, development and AssetForge filters, backlinks, and phase and AssetForge dependency traversal matched the current Worldforge index.
• Active, Phase 3, Phase 5, and AssetForge contexts were byte-repeatable. Active matched the current cache; AssetForge included all ten nodes under the normal budget.
• A reduced AssetForge budget retained the required root, stayed within budget, and recorded omissions. An invalid budget failed before producing a context.
• All 32 generated outputs matched committed bytes. The proof wrote only temporary derived files and removed them afterward.

Limits

• The adapter remains an explicit local shadow command and is not loaded by the normal MCP server.
• Canonical application and public deployment remain outside DocForge.
• Reuse outside Worldforge is not yet proven.

Next gate

DFG-6: prove the generic core with an unrelated project and simultaneous project-isolated servers.

DFG-6 unrelated-project proof

Changed

• Added an Awesome Ski Game fixture using the generic project descriptor, five unrelated node families, six relationships, a bounded ride-day context, one proposal writer, and one declared field-guide view.
• Added an end-to-end proof covering generic loading, indexing, exact graph counts, search, filters, dependency traversal, deterministic bounded context, isolated updates, validation, diffs, and escaped preview rendering.
• Added a source guard that rejects Worldforge, AssetForge, phase, or villager vocabulary in the generic core.
• Added a live isolation proof with two simultaneous MCP server subprocesses bound to Awesome Ski Game and Alpha Documentation.

Verification

• Awesome Ski Game loaded through adapter = "generic" with five nodes, six edges, and trail, riding, safety, session, and proof families.
• The 300-token context retained its required session node, stayed within budget, recorded omissions, and reproduced exactly.
• The proposal changed only its isolated changeset and preview. Canonical sources and declared output remained unchanged, and raw HTML was escaped.
• Both live servers returned their own project identity and nodes, rejected the other project's stable IDs, and wrote same-named changesets and previews only under their bound roots.
• The complete DocForge suite passes with warnings treated as errors.

Limits

• This proof does not adopt DocForge inside Worldforge or enable any canonical write path.
• The Worldforge adapter and generic Awesome Ski Game fixture remain separate ownership paths.
• HTTP transport, accounts, and web administration remain unopened.

Next gate

DFG-7: adopt project-bound DocForge retrieval for real Worldforge read-only tasks with measured quality and a documented rollback path.

DFG-7 Worldforge read-only adoption

Changed

• Added an explicit adapter-backed read-only MCP constructor that accepts one validated project service and an optional project-owned context provider.
• Kept adapter discovery, session selection, family partitioning, and project context policy outside the generic core.
• Added Worldforge-owned descriptors and separate Worldforge and AssetForge sessions with disjoint derived indexes and the exact fixed read tool surface.
• Added durable retrieval, context-size, omission, latency, stale-state, and rollback evidence.
• Released the adapter-backed read-only boundary as DocForge 0.5.0.

Verification

• Eight real Worldforge and AssetForge retrieval tasks retained every required node in the first five results; seven matched the current manual index result set exactly.
• Active and Phase 5 contexts reduced the full structured Worldforge session by 97.3% and 98.2%. Tight budgets reported every omitted candidate.
• Two simultaneous MCP processes retained separate identities, exposed only read tools, rejected cross-family node access, and kept Worldforge stale-state failure isolated from AssetForge.
• Checked DocForge search measured 84.4 ms median in the adoption run versus 18.8 ms for the current manual index. The additional validation cost remained below 0.1 seconds.
• The DocForge suite, Worldforge manual suite, integration tests, shadow proof, format, lint, and generated-output checks passed.

Limits

• DocForge read-only operations do not write canonical Worldforge files or replace its builder.
• Adapter-backed read-only service construction is explicit; the generic server does not discover project adapters or sessions.
• AssetForge proposal access, canonical application, publication, and deployment remain closed.

Next gate

DFG-8: adopt isolated AssetForge-only proposals with explicit review and the canonical Worldforge build and verification workflow.

DFG-8 AssetForge proposal adoption

Changed

• Added confined adapter proposal settings for canonical sources, writer permissions, changesets, templates, previews, and declared review output.
• Added a project-owned proposal-validation hook while retaining generic hash, permission, graph, conflict, atomic-storage, diff, and preview enforcement in the core.
• Moved generic Markdown and TOML source-layout validation behind the generic project owner so an adapter can enforce its own canonical format without weakening graph validation.
• Added an explicit full-surface server constructor for one configured project service and one startup-bound writer.
• Marked base, content, source, adapter-source, and index conflicts as stale tool results.
• Released the proposal-enabled adapter boundary as DocForge 0.6.0.

Verification

• OpenClaw was bound to the AssetForge-only session and update-only permission.
• One real proposal updated an existing AssetForge chapter, validated, produced a structured diff, and rendered an isolated escaped preview before manual integration.
• The Worldforge canonical builder and manual index rebuilt after review. The original changeset then failed with base_conflict against the new canonical source hash.
• Live tests rejected create, metadata, root-manifest, relationship, and cross-family access; rejected an overlapping changeset; escaped raw HTML; preserved canonical bytes; and rejected stale canonical sources.
• The complete DocForge and Worldforge manual suites, shadow proof, generated-output check, format, and lint passed.

Limits

• DFG-8 permits content-only updates to existing AssetForge chapters. Create, move, delete, metadata, relationship, and manifest changes remain closed.
• DocForge does not apply canonical changes, run the Worldforge builder, use Git, deploy, or publish.
• A developer must review and manually integrate accepted prose.

Next gate

DFG-9: decide from evidence whether a narrowly scoped developer-only application command is justified or manual integration should remain permanent.