DocForge2/SLICE_HISTORY.md

# Completed slices

## 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.