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

88
docs/USER_MANUAL.md
View file

@ -5,9 +5,11 @@ people and AI agents can search, inspect, visualize, and change through reviewab
Canonical project files remain authoritative. The SQLite graph, previews, rendered manuals, and
viewer processes are derived and can be rebuilt.
DocForge 1.0.0 is the first stable product release. It includes the project-scoped graph,
CLI and MCP query surfaces, hash-approved proposal application, generic and project-owned adapters,
declared rendering, and the Nodes/Flow/Web visualization model documented below.
This manual describes the DocForge 1.4.0 release candidate. The tagged `v1.0.0` baseline was the
first stable product release. Version 1.4.0 preserves its project-scoped graph, CLI and MCP query
surfaces, hash-approved proposal application, generic and project-owned adapters, declared
rendering, and Nodes/Flow/Web model while adding the maintained incremental, projection, adapter
SDK, recovery, and release proofs documented below.
Later incremental-compiler capabilities are additive. A Release 1 adapter with only
`load_projection()` remains valid and follows the same complete-rebuild path. No existing project
@ -76,6 +78,12 @@ The generic adapter can serialize its Markdown and TOML nodes directly. A custom
provide its own canonical applier because only that project knows how a graph node maps back to its
source format.
Generic canonical application compare-and-swaps each target against its exact expected identity.
A concurrent create, update, or delete fails closed, rolls back when the exact displaced state is
still provable, or preserves recovery evidence without overwriting foreign data. Per-file
publication is atomic, but an application spanning several canonical files has no process-death
journal and does not claim crash atomicity across the group.
## Setup
### Requirements
@ -115,6 +123,20 @@ The base wheel contains the Python reference adapter and no Tree-sitter distribu
TypeScript, and C++ require their matching optional extras. `docforge[languages]` installs all
three optional frontend groups.
Verify the four executable surfaces from the exact installed environment:
```bash
python -m docforge.cli --version
python -m docforge.mcp_server --version
python -m docforge.reference_mcp --version
python -m docforge.viewer_manager --version
```
For version 1.4.0 these 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`. Package metadata,
Python imports, generated generic and adapter configurations, and these commands share the same
version authority.
### Configure a reference source project
Reference adapters are a narrow alternative to the generic documentation descriptor. Create
@ -996,6 +1018,10 @@ effective policy. A replacement receipt returns `stale_cursor`; restart from its
Canonical application records its terminal receipt immediately after the project-owned serializer
verifies the new canonical state. A later index or render refresh failure is reported as degraded
derived state with remediation, not as permission to apply the same canonical change again.
Likewise, failure to remove a private transaction artifact after semantic commit returns
`applied`, closes the proposal, and persists compact `application_recovery` lifecycle metadata
with `cleanup_required`, retained paths, and remediation. Inspect and remove only files proven to
be DocForge-owned.
Every successful declared render publishes a bounded version-1 receipt below the disposable cache.
Normal `render-status` compares cheap source-generation, view-configuration, template-file, and
@ -1115,6 +1141,13 @@ process verifies the unchanged database against that receipt instead of reconstr
row. Missing or mismatched receipts fall back to complete verification and are recreated only after
the full check succeeds.
Milestone 5 maintains exact recovery for four corrupt derived artifacts. Synchronization restores
a corrupt index attestation after complete verification. Explicit `render` restores a corrupt
manual receipt to the exact output and receipt semantics. A complete `reindex` recreates a corrupt
generation-diff baseline against the exact current graph. Explicit `graph-render` recreates a
corrupt portable-graph manifest and exact artifact. Status operations diagnose these conditions
without hidden repair.
### `visualization_manager_unavailable`
The per-user manager is not installed, is stopped, or points to an old virtual environment.
@ -1159,9 +1192,28 @@ content or relationship conflict remains fail-closed and requires a newly review
### `application_mismatch`
The written sources did not reproduce the validated projection. DocForge rolls the generic
canonical files back. For a custom adapter, fix its serializer or node-to-source mapping before
retrying.
The written sources did not reproduce the validated projection. During an ordinary in-process
failure, DocForge rolls generic canonical files back when their exact publication identities are
still provable. If another process raced a target, DocForge preserves foreign and displaced data
and returns `application_recovery_required` rather than overwriting either. For a custom adapter,
fix its serializer or node-to-source mapping before retrying.
### `application_recovery_required` or `cleanup_required`
`application_recovery_required` means canonical publication or rollback encountered concurrent or
unprovable state. Preserve every retained file named in the error. Compare it with the canonical
target and resolve the project before creating a newly reviewed proposal. Do not retry the old
approved hash.
`cleanup_required` means semantic application already committed. The proposal is closed as
`applied`, and its lifecycle receipt names private transaction artifacts that could not be removed.
Inspect those files and remove only confirmed DocForge-owned artifacts. The canonical change must
not be applied again.
Generic application uses mode-0700 transaction directories, but DocForge is not a filesystem
sandbox. Deliberate arbitrary tampering by another process running as the same operating-system
user is outside that integrity boundary. A process or host death can also interrupt a multi-file
application because canonical application has no process-death journal.
### `path_escape`, `unsafe_template`, or missing source
@ -1178,7 +1230,7 @@ ambiguous adapter evidence.
### Full inspector content does not fit
DocForge 1.0 uses a fixed header and footer with a scrollable inspector body. If an older page is
DocForge 1.4 uses a fixed header and footer with a scrollable inspector body. If an older page is
still open, stop and reopen the visualization so it loads the current `graph-browser@17` template.
### Render output is stale
@ -1219,7 +1271,7 @@ the process so it binds the new descriptor deliberately.
## Development and verification
Run the complete release gate from the DocForge repository:
Run the ordinary repository gate:
```bash
make gate
@ -1234,5 +1286,25 @@ and recovery benchmark. `make adoption-m4` performs the offline fresh-wheel proo
the maintained documentation graph. `make accessibility` runs the generated manual, portable
graph, and live viewer axe and keyboard flows.
Milestone 5 adds maintained compatibility, migration, concurrency, recovery, comparative-task,
release-identity, reproducible-artifact, secret-scan, and fresh-clone gates:
```bash
make compatibility-m5
make migration-m5
make concurrency-m5
make recovery-m5
make task-evidence-m5
make release-gate
make fresh-clone-m5
```
`release-gate` aggregates the full quality, browser, compatibility, migration, concurrency,
recovery, task-evidence, fresh-wheel, version, artifact, secret-scan, and benchmark suite.
`fresh-clone-m5` anonymously clones the exact published candidate over HTTPS, fetches and verifies
the frozen annotated `v1.0.0` migration tag, and repeats `release-gate`. Release operators use
`make release-pretag` before creating `v1.4.0` and `make release-posttag` after the annotated tag
points to the exact release commit.
Project-specific vocabulary, extraction rules, and serialization belong in the project adapter.
Generic core behavior must remain deterministic, project-bound, and recoverable.