160 lines
6.1 KiB
Markdown
160 lines
6.1 KiB
Markdown
# DocForge2 Milestone 0 compatibility contract
|
|
|
|
Milestone 0 establishes DocForge2 as the successor repository without renaming or replacing the
|
|
working DocForge interfaces. Compatibility changes require an explicit decision, a contract-test
|
|
update, and migration guidance.
|
|
|
|
The compatibility gate is:
|
|
|
|
```bash
|
|
make contract
|
|
```
|
|
|
|
The complete repository gate is:
|
|
|
|
```bash
|
|
make gate
|
|
```
|
|
|
|
## Distribution and Python imports
|
|
|
|
The Python distribution and import package remain `docforge`.
|
|
|
|
The installed executable names remain:
|
|
|
|
- `docforge`
|
|
- `docforge-mcp`
|
|
- `docforge-viewer-manager`
|
|
|
|
The top-level imports recorded by `docforge.__all__` remain supported. The documented adapter,
|
|
model, index, rendering, application, and MCP factory names imported from these submodules also
|
|
remain supported:
|
|
|
|
- `docforge.adapter_contract`
|
|
- `docforge.application`
|
|
- `docforge.index`
|
|
- `docforge.mcp_server`
|
|
- `docforge.models`
|
|
- `docforge.render_contract`
|
|
|
|
Names beginning with an underscore are implementation details. New public names may be added
|
|
without breaking this contract.
|
|
|
|
## CLI and MCP surfaces
|
|
|
|
Existing `docforge` command names and arguments remain supported. Existing `docforge-mcp` tool
|
|
names and arguments remain supported. Additive commands, tools, and response fields are allowed.
|
|
Removing or changing an existing name, required argument, stable error code, or safety boundary
|
|
requires an explicit compatibility decision.
|
|
|
|
MCP results retain:
|
|
|
|
- A structured `status`.
|
|
- Project and source identity when available.
|
|
- Stable structured domain errors.
|
|
- A bounded content warning.
|
|
- Staleness information.
|
|
- The configured output-size limit.
|
|
|
|
The result schema describes the common envelope. Operation-specific fields are additive and remain
|
|
bounded by the configured tool-output limit.
|
|
|
|
## Versioned data contracts
|
|
|
|
Milestone 0 preserves:
|
|
|
|
- Project descriptor schema version 1.
|
|
- Node schema version 1.
|
|
- Edge schema version 1.
|
|
- Changeset schema version 1.
|
|
- Result-envelope schema version 1.
|
|
- SQLite index schema version 3. Version 2 indexes remain disposable and automatically rebuild;
|
|
version 3 adds a source-ordered incoming-edge index for bounded impact traversal.
|
|
- Index-attestation schema version 1.
|
|
- Incremental extraction-cache schema version 1.
|
|
|
|
Indexes, attestations, extraction caches, previews, and rendered artifacts are disposable. A schema
|
|
change may rebuild them. Canonical project content and stored proposals may not be silently
|
|
rewritten to satisfy a new implementation.
|
|
|
|
## Adapter compatibility
|
|
|
|
An adapter implementing only:
|
|
|
|
```python
|
|
load_projection()
|
|
```
|
|
|
|
remains first-class. Incremental manifests, source extraction, deterministic assembly, Logic
|
|
projection, and proposal or application support are optional capabilities. Incremental adapters
|
|
must retain `load_projection()` as their independent clean-build and equivalence oracle.
|
|
|
|
Project adapters remain explicitly composed. Generic DocForge does not discover arbitrary adapter
|
|
modules or choose a project globally.
|
|
|
|
## Preserved no-AST binding
|
|
|
|
`docforge-mcp --project-root /project --no-ast` is a stable shorthand for the
|
|
`preserve-no-ast` binding policy.
|
|
|
|
The binding:
|
|
|
|
- Keeps one-method complete-projection adapters working.
|
|
- Keeps non-AST incremental fingerprinting and caching working.
|
|
- Rejects nonempty function-Logic publication.
|
|
- Rejects a pre-existing index containing function Logic.
|
|
- Blocks `docforge_get_logic`.
|
|
- Prevents the live viewer from pinning an index containing Logic.
|
|
- Applies the same restriction during hash-bound canonical-application refresh.
|
|
- Reports the effective policy through bootstrap and contract results.
|
|
|
|
DocForge does not inspect arbitrary adapter source to prove which parser implementation it uses.
|
|
The no-AST binding is an owner-selected process policy backed by Logic publication and retrieval
|
|
enforcement. It is not a filesystem sandbox and cannot stop an unrelated process with repository
|
|
write access from changing adapter code.
|
|
|
|
## Changesets and application
|
|
|
|
The following guarantees remain stable:
|
|
|
|
1. Registration writes one complete proposal atomically.
|
|
2. Proposal identity includes its project, root, base revision, canonical source hash, writer, and
|
|
ordered operations.
|
|
3. Validation and diff inspection precede application.
|
|
4. Append, rebase, abandonment, and application use exact current hashes.
|
|
5. Stale, conflicting, unauthorized, unsafe, or invalid proposals fail closed.
|
|
6. Canonical application is absent unless one startup-bound applier is configured.
|
|
7. Derived refresh failures produce an explicit degraded receipt after canonical application. They
|
|
do not make an applied proposal safe to apply twice.
|
|
|
|
## Rendering and visualization
|
|
|
|
The `generic_html` renderer remains the supported version-1 manual projection. It retains confined
|
|
paths, raw-HTML suppression, fixed template tokens, deterministic identities, atomic replacement,
|
|
and side-effect-free status.
|
|
|
|
The live graph viewer remains a read-only consumer of a generation-pinned validated index. It does
|
|
not become project authority or MCP retrieval authority.
|
|
|
|
`ManualRenderPlan`, `GraphViewPlan`, a portable graph renderer, and independently packaged
|
|
renderers are later-milestone direction. Milestone 0 does not claim that those contracts exist.
|
|
|
|
## Safety boundary
|
|
|
|
DocForge remains bound to one explicit project root. It rejects absolute paths, root escapes, and
|
|
symbolic-link escapes. Documentation text remains untrusted data. Normal MCP operation exposes no
|
|
arbitrary filesystem access, renderer execution, shell command, Git mutation, deployment,
|
|
publication, or project switching.
|
|
|
|
## Recorded weaknesses, not compatibility promises
|
|
|
|
Milestone 0 records rather than redesigns these areas:
|
|
|
|
- Generic warm reads still repeat whole-project discovery, parsing, and validation.
|
|
- Tree-sitter and the JavaScript and C++ grammars remain mandatory installation dependencies even
|
|
when their runtime modules are unused.
|
|
- Several version strings and defaults remain duplicated.
|
|
- Large changeset results and context responses need compact receipt or pagination contracts.
|
|
- Manual planning is not separated from rendering.
|
|
- There is no portable graph-planning or graph-rendering contract.
|
|
- DocForge2 does not self-host its bootstrap documentation.
|