216 lines
12 KiB
Markdown
216 lines
12 KiB
Markdown
# 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.
|