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

Document the 1.4.0 release candidate

Browse source
This commit is contained in:
Andraxion 2026-07-29 16:50:39 -04:00
parent 2b98059b44
commit 49e1a87c13
13 changed files with 739 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

34
docs/COMPATIBILITY.md
View file

@ -1,8 +1,9 @@
# DocForge2 Milestone 0 compatibility contract
# DocForge 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.
update, and migration guidance. DocForge 1.4.0 preserves that baseline and adds the adapter,
rendering, recovery, and release surfaces recorded below.
The compatibility gate is:
@ -16,6 +17,11 @@ The complete repository gate is:
make gate
```
Milestone 5 also maintains `make compatibility-m5` for the frozen public, adapter, policy,
projection, rendering, and retrieval matrix. `make release-gate` aggregates that matrix with
migration, concurrency, recovery, task-evidence, adoption, version, artifact, secret-scan, browser,
and benchmark proofs.
## Distribution and Python imports
The Python distribution and import package remain `docforge`.
@ -63,6 +69,12 @@ names and arguments remain supported. Additive commands, tools, and response fie
Removing or changing an existing name, required argument, stable error code, or safety boundary
requires an explicit compatibility decision.
Version `1.4.0` comes from one `docforge._version` authority. The four maintained executable
surfaces report `docforge 1.4.0`, `docforge-mcp 1.4.0`,
`python -m docforge.reference_mcp 1.4.0`, and `docforge-viewer-manager 1.4.0` for `--version`.
Generated generic and adapter client configurations include and hash-bind the same
`docforge_version`.
MCP results retain:
- A structured `status`.
@ -191,6 +203,14 @@ The following guarantees remain stable:
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.
8. Generic canonical publication compares exact target identity at the commit boundary. Concurrent
create, update, and delete mutations fail closed, roll back when exact state remains provable, or
retain recovery evidence without overwriting foreign data.
9. Per-file publication is atomic and in-process rollback covers earlier publications, but
canonical application has no process-death journal and does not promise multi-file crash
atomicity.
10. Cleanup degradation after semantic commit closes the proposal as `applied` and persists bounded
`application_recovery` lifecycle metadata instead of returning a retryable ordinary failure.
## Rendering and visualization
@ -260,6 +280,15 @@ symbolic-link escapes. Documentation text remains untrusted data. Normal MCP ope
arbitrary filesystem access, renderer execution, shell command, Git mutation, deployment,
publication, or project switching.
DocForge is not a filesystem sandbox. Mode-0700 canonical transaction directories protect against
other users and ordinary path access; deliberate arbitrary tampering by another process with the
same operating-system UID is outside the compatibility boundary.
The historical `v1.0.0` release carried distribution metadata `1.0.0` while its module and MCP
runtime reported `0.15.0`. Version 1.4.0 records that inherited mismatch in its maintained
migration proof and resolves current identity through one authority. See
[migrating from v1](MIGRATING_FROM_V1.md).
## Recorded weaknesses, not compatibility promises
Milestone 0 records rather than redesigns these areas:
@ -268,7 +297,6 @@ Milestone 0 records rather than redesigns these areas:
- The base wheel intentionally omits Tree-sitter. JavaScript, TypeScript, and C++ syntax evidence
requires the matching `docforge[javascript]`, `docforge[typescript]`, or `docforge[cpp]` extra.
Python reference evidence uses the standard library and remains available in the base wheel.
- Several version strings and defaults remain duplicated.
- One individually oversized context entry is represented as explicit bounded omission evidence;
callers use targeted retrieval for that node.
- One individually oversized changeset diff is transported as reconstructable canonical-JSON