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

docs: isolate current DocForge2 documentation

Browse source
This commit is contained in:
Andraxion 2026-07-31 10:07:30 -04:00
parent f9a05f868e
commit 377cca0531
7 changed files with 98 additions and 1274 deletions
Download patch file Download diff file Expand all files Collapse all files

146
ACTIVE_SLICE.md
View file

@ -1,134 +1,34 @@
# Milestone state
# Active slice
```text
Last completed milestone: 5 — stabilization and first DocForge2 release.
Baseline: annotated v1.4.0 release commit on main, dev, origin/main, and origin/dev.
Active milestone: none.
Outcome: Compatibility, determinism, recovery, security, performance, and representative task advantage are proven for the first successor release.
Status: Complete.
Last completed milestone: 5 - stabilization and first DocForge2 release.
Release: 1.4.0.
Active milestone: none.
Maintenance: Current product documentation boundary cleanup complete.
Status: Complete.
```
## Authority
## Current state
This contract activated Milestone 5 from the clean, merged, and pushed Milestone 4 closeout. The
roadmap in `/home/andraxion/.openclaw/workspace/DocForgeOutline.md` supplies direction; this file
freezes the executable scope and acceptance criteria.
DocForge2 `1.4.0` is the released product baseline. Current behavior is defined by the contracts and
guides under `docs/`. `SLICE_HISTORY.md` contains DocForge2 milestone summaries only.
The completed release synchronizes `main` and `dev` at the documentation-bearing commit identified
by annotated tag `v1.4.0`.
The live documentation set contains current product contracts, current operating guidance, and
current successor milestone evidence. Superseded product plans and policy notes remain available
only through repository history and are not part of normal documentation validation or retrieval.
## Required release evidence
## Maintenance proof - 2026-07-31
The release candidate must prove all of the following from maintained, reproducible gates:
- Replaced the historical application-decision memo with the current canonical-application
contract.
- Removed the predecessor chronology from the live slice history and removed the transition-only
repository closeout page.
- Updated the README and documentation validator to reference only current product documentation.
- Formatting, Python lint, web lint, command-reference validation, and the 33-page documentation
graph passed.
- Focused adapter and changeset verification passed 45 tests plus 2 subtests.
1. Legacy one-method adapter compatibility and the frozen package, CLI, MCP, schema, rendering,
descriptor, result-envelope, and no-AST surfaces.
2. Exact complete/incremental primary-graph and Logic equivalence for maintained incremental
adapters.
3. Deterministic adapter, worker, renderer, command-reference, configuration, and publication
output.
4. Detection of concurrent source mutation without publishing or serving a mixed or stale
generation.
5. Atomic, crash-safe derived publication and exact recovery from interrupted publication.
6. Corrupt extraction-cache, index, attestation, receipt, fragment, and projection recovery using
canonical sources as the authority.
7. No stale reads after source or policy change, including generation-pinned retrieval and viewer
behavior.
8. Exact-hash canonical application with project-owned serialization, stale-proposal rejection,
and post-application resynchronization.
9. Closed policy precedence across process capability, descriptor policy, `--no-ast`, projection
policy, worker enforcement, and viewer enforcement.
10. Manual and portable-graph isolation, immutable package verification, bounded detached workers,
rendering-policy enforcement, viewer-policy enforcement, and accessibility.
11. Comparative representative task evidence with fixed questions, answer keys, provenance,
latency, and response-size accounting for both graph-assisted and source-only workflows.
12. A fresh-wheel and fresh-clone release rehearsal, full quality and browser gates, maintained
benchmarks, secret scans, exact version identity, signed-off release notes, and reproducible
release artifacts.
## Next gate
## Deliverables
- A maintained Milestone 5 compatibility matrix and aggregate release gate.
- Reproducible migration, recovery, concurrency, and comparative-task evidence.
- One authoritative package version shared by package metadata, Python, CLI, MCP, viewer manager,
reference MCP, generated configuration, and release documentation.
- A standard project license file, changelog or release notes, release baseline, closeout record,
and machine-readable evidence.
- A clean `main` merge, synchronized `main` and `dev`, annotated `v1.4.0` tag, and Forgejo release
only after the final documentation-bearing commit passes a fresh-clone gate.
## Fixed boundaries
- Preserve the `docforge` package, `docforge` CLI, `docforge-mcp`, MCP tool names, schema version 1
surfaces, effective policy version 1, projection policy version 2, and legacy adapter entry point.
- Preserve canonical project sources. Migration may rebuild disposable state but may not rewrite
canonical content merely to satisfy the release.
- Full rebuild remains the recovery and equivalence oracle.
- Derived artifacts must fail closed on malformed, foreign, stale, oversized, or incompatible
state.
- Version `1.4.0` is additive relative to `1.0.0`; breaking a frozen contract requires a separately
justified major-version decision.
## Exclusions
- No WorldForge change or benchmark.
- No ScrapeStation change, production binding change, or production migration.
- No legacy-repository mutation.
- No production MCP repointing.
- No remote render service, render farm, third-party renderer ecosystem, graph federation, or
dedicated graph database.
- No arbitrary adapter command execution, compiler execution, remote execution, or expanded
launcher authority.
- No PyPI publication unless it is separately verified as an intended existing release channel.
## Release sequence
1. Freeze and implement the compatibility, migration, recovery, concurrency, and task-evidence
gates.
2. Stabilize version identity, packaging, license, security, and release automation.
3. Freeze one clean executable candidate and run the full repository, browser, benchmark,
fresh-wheel, fresh-clone, and secret-scan gates.
4. Close documentation atomically against that candidate and rerun documentation-only validation.
5. Merge and push the final candidate.
6. Rehearse from a fresh anonymous clone at the exact commit.
7. Create and push the annotated `v1.4.0` tag and publish the Forgejo release from the verified
artifacts.
The completed Milestone 4 contract and exclusions remain preserved in `SLICE_HISTORY.md`.
## Release-candidate evidence — 2026-07-29
The executable implementation is frozen at
`d2bb95fe6190e659cf66ba57c78be53b63b53240`. The proof-bearing candidate base is
`2b98059b44f4d46b4d4cce776f163e893c647c76`; it includes exact legacy-tag verification for the
fresh-clone gate and four maintained aggregate derived-recovery tests.
The clean executable release gate passed formatting, Python and web lint, strict Pyright,
compilation, lock and dependency checks, builds, generated documentation, three accessibility
flows, fresh-wheel adoption, artifact reproducibility, secret scans, and the full Milestone 0
through Milestone 4 benchmark sequence. Its exact test evidence was:
- 142 contract tests plus 272 subtests.
- 371 complete tests plus 419 subtests.
- 116 compatibility tests plus 263 subtests.
- 29 concurrency tests plus 2 subtests.
- 68 recovery tests plus 62 subtests.
The real migration gate preserves exact canonical and proposal bytes from the annotated `v1.0.0`
lineage while rebuilding the disposable index from schema 1 to schema 3. The real-package task
gate uses the lock-pinned `markdown-it-py 4.2.0` tree and proves exact graph-assisted and
source-only answers for all reviewed tasks.
The later proof-only recovery commit adds four maintained tests without changing executable
product code. The current recovery aggregate passes 72 tests plus 62 subtests.
The documentation-bearing candidate `49e1a87c138cdc63fb5abb85fc6eb2cf9f4a9d73` passed the complete
local release gate with 378 tests plus 422 subtests, all three accessibility flows, and every
focused and full gate above. Its final documentation-only descendant is the commit identified by
annotated tag `v1.4.0`; that exact remote commit passes the anonymous fresh-clone rehearsal before
tagging.
The public Forgejo release publishes the reproducible wheel, source distribution, and
machine-readable release-identity evidence from the tagged commit. `main`, `dev`, `origin/main`,
and `origin/dev` resolve to that same commit. No PyPI publication was performed.
No implementation milestone is active. Create one explicit bounded contract before changing
product behavior, version identity, release state, or public integration.

4
README.md
View file

@ -204,7 +204,7 @@ paths.
- [Compatibility contract](docs/COMPATIBILITY.md)
- [Adapter authoring guide](docs/ADAPTER_AUTHORING_GUIDE.md)
- [Incremental indexing](docs/INCREMENTAL_INDEXING.md)
- [Adapter application decision](docs/APPLICATION_DECISION.md)
- [Canonical application](docs/CANONICAL_APPLICATION.md)
- [Legacy and no-AST operation](docs/LEGACY_AND_NO_AST.md)
- [Migrating from version 1](docs/MIGRATING_FROM_V1.md)
- [Viewer manager](docs/VIEWER_MANAGER.md)
@ -218,7 +218,7 @@ paths.
- [Milestone 3 baseline](docs/MILESTONE_3_BASELINE.md) and [closeout](docs/MILESTONE_3_CLOSEOUT.md)
- [Milestone 2 baseline](docs/MILESTONE_2_BASELINE.md) and [closeout](docs/MILESTONE_2_CLOSEOUT.md)
- [Milestone 1 baseline](docs/MILESTONE_1_BASELINE.md) and [closeout](docs/MILESTONE_1_CLOSEOUT.md)
- [Milestone 0 baseline](docs/MILESTONE_0_BASELINE.md) and [closeout](docs/MILESTONE_0_CLOSEOUT.md)
- [Milestone 0 baseline](docs/MILESTONE_0_BASELINE.md)
Historical milestone records preserve the facts and dependency observations of their frozen
candidates. Use the current guides and contracts for present behavior.

1068
SLICE_HISTORY.md
View file

File diff suppressed because it is too large Load diff

15
docs/APPLICATION_DECISION.md → docs/CANONICAL_APPLICATION.md
View file

@ -1,8 +1,4 @@
# Canonical application decision
**Status:** Superseded by the DocForge 0.13 hash-bound application contract.
## Decision
# Canonical application
DocForge may apply one isolated changeset to canonical project sources through an explicit,
project-bound canonical applier. Application is available through both CLI and MCP. It is never an
@ -31,17 +27,14 @@ checks the derived index and regenerates declared render views.
Application does not run project commands, tests, shell operations, Git, deployment, publication,
or arbitrary renderers. Those remain with the owning project workflow.
## Why the earlier decision changed
## Safety contract
The earlier DFG-9 decision preserved manual integration because there was not yet repeated evidence
for canonical application. Later multi-project use produced recurring proposal application work,
stale-index round trips, and an explicit user requirement for faster approved integration. The new
contract addresses the original safety concerns with:
The application boundary requires:
- exact changeset-hash approval;
- startup-bound applier identity;
- project-owned serializers for custom adapters;
- canonical path and symlink confinement;
- canonical path and symbolic-link confinement;
- rollback and semantic round-trip verification;
- deterministic derived-state refresh; and
- complete separation from Git, builds, deployment, and publication.

133
docs/MILESTONE_0_CLOSEOUT.md
View file

@ -1,133 +0,0 @@
# DocForge2 Milestone 0 closeout
Milestone 0 establishes the public DocForge2 successor without changing the supported `docforge`
product identity or the legacy DocForge repository.
## Repository state
- Public successor: <https://repo.andraxion.net/administrator/DocForge2>
- Successor default branch: `main`
- Successor development branches: `main` and `dev`
- Local `origin`: `forgejo@repo.andraxion.net:administrator/DocForge2.git`
- Local `legacy`: `forgejo@repo.andraxion.net:administrator/DocForge.git`
- Legacy repository: private, nonempty, unarchived, and defaulted to `main`
- Existing annotated tag: `v1.0.0`
`main` is the last completely verified milestone. `dev` is the integration branch for the next
explicitly activated milestone and begins at the same commit. Historical development branch names
remain in the legacy repository as v1 evidence; they are not replicated as active DocForge2
branches.
No tag, release, release announcement, or production integration change was made.
## Preserved lineage
The migration began from the advanced
`codex/language-agnostic-onboarding` tip
`bb13258861175aafd0e6c03c1a5235cbaddf6db2`, nine linear commits beyond the legacy `main`.
The original seven-file no-AST working patch had SHA-256:
```text
8cd10759c232cd4cf8c5eb024e31bbfed355e0be31fc3e732e1567c1a19a887e
```
It was preserved in commit `6c05607` before other integration. The independent local-only adapter
lifecycle commit `1ef76f0271bb339bc0d7eeb62f996d6d680548cb` was retained unchanged and merged by
`15a9130`. The resulting successor `main` contains every commit that was reachable from any local
ref before migration. No rebase, reset, squash, shallow seed, or older-remote seed was used.
A verified pre-migration bundle was written outside the repository:
```text
/tmp/DocForge2-milestone0-candidate-20260729.bundle
SHA-256 6cccd4ae2a65fa2d81e324e4592bee488b111942a496fb85f7ac6b8bd319ea2d
```
## Legacy integrity
Before and after the successor push, the legacy repository advertised these exact heads:
```text
Dev-Rewrite 73165c9f511485ea397aaa00c5e0047bd3e635e2
DocForge-Dev 82b3b905212e7949c0a440879f3bf866197c3927
codex/adapter-authoring-docs 7bc2ac1e3f7f9cf23ec4dcad108f9bb59978ca73
codex/language-agnostic-onboarding bb13258861175aafd0e6c03c1a5235cbaddf6db2
main 9fcafc290c5b5ee9cb83c4c3b2ff600f75210c8e
```
The annotated `v1.0.0` tag object remained
`2d7d306a37da89f1c860c7f0be161c45386acf61`, pointing to
`593c173b453236a6872d0a4e88e7a51a67a21cde`.
No push, deletion, visibility change, archive operation, or default-branch change was performed
against `legacy`.
## Compatibility and correctness
The stable guarantees are recorded in
[`COMPATIBILITY.md`](COMPATIBILITY.md). The dedicated contract gate verifies:
- Distribution, package, imports, and three executable names.
- CLI command and MCP tool names.
- Published JSON schemas and representative runtime envelopes.
- One-method `load_projection()` adapters.
- Optional incremental behavior and full-projection equivalence.
- Canonical JSON changeset hashing.
- Complete no-AST behavior, including pre-existing Logic, viewer, and application-refresh paths.
The no-AST policy does not claim to inspect arbitrary adapter internals. It enforces the owner-bound
policy at Logic publication and retrieval surfaces while preserving complete-projection and
genuinely non-AST incremental adapters.
## Security and publication checks
Gitleaks 8.30.1 scanned reachable Git history and an exact archive of the candidate tree with full
redaction. Both scans reported zero findings. `git fsck --full` passed. A broader filename and
credential-pattern audit also found no high-confidence matches.
Forgejo repository creation used one timestamped short-lived administrator token. Forgejo accepted
it for repository creation but returned HTTP 401 when it attempted self-deletion. The exact
task-created token row was then validated by ID, owner, and unique name, deleted in one SQLite
transaction, and rechecked. Zero matching temporary token rows remain.
The package metadata declares MIT, but the repository has no tracked standalone `LICENSE`,
`COPYING`, or `NOTICE` file. Milestone 0 records that publication weakness without inventing or
changing legal terms.
## Validation and fresh-clone proof
The repository-native aggregate gate is:
```bash
make gate
```
It passed in the working tree and in an anonymous HTTPS clone of the public successor. The
fresh-clone proof:
- Selected the expected `main` commit through the public default branch.
- Passed `git fsck --full`.
- Recreated the Python virtual environment from `uv.lock`.
- Recreated JavaScript dependencies with `npm ci`, with zero reported vulnerabilities.
- Passed Ruff formatting and lint.
- Passed HTML, rendered-manual HTML, CSS, and JavaScript lint.
- Passed Pyright with zero diagnostics.
- Passed Python compilation.
- Passed 8 public-contract tests and 42 schema subtests.
- Passed the complete 95-test and 44-subtest warning-strict suite.
- Passed lock and dependency-tree checks.
- Built the wheel and source distribution.
- Passed the disposable benchmark smoke run.
- Remained clean after validation.
The maintained performance evidence and known gaps are recorded in
[`MILESTONE_0_BASELINE.md`](MILESTONE_0_BASELINE.md) and
[`benchmarks/milestone0-2026-07-29.json`](../benchmarks/milestone0-2026-07-29.json).
## Scope confirmation
Milestone 0 made no speculative storage rewrite and introduced no self-hosting dependency.
WorldForge and ScrapeStation were not read as benchmark fixtures or changed. No production MCP
integration was repointed. `ManualRenderPlan`, `GraphViewPlan`, and a portable graph renderer remain
later-milestone direction, not claimed implementation.

4
src/docforge/project.py
View file

@ -397,7 +397,9 @@ def _load_descriptor(root: Path) -> ProjectDescriptor:
title = require_string(document, "title", descriptor_path)
adapter = require_string(document, "adapter", descriptor_path)
if adapter != "generic":
raise DocForgeError("unsupported_adapter", "DFG-1 supports only the generic adapter")
raise DocForgeError(
"unsupported_adapter", "This project loader supports only the generic adapter"
)
sources = document.get("sources")
derived = document.get("derived")

2
tools/check_documentation.py
View file

@ -39,7 +39,7 @@ REQUIRED_MILESTONE_4_PAGES = (
Path("README.md"),
Path("docs/ADAPTER_AUTHORING_GUIDE.md"),
Path("docs/AGENT_INTEGRATION.md"),
Path("docs/APPLICATION_DECISION.md"),
Path("docs/CANONICAL_APPLICATION.md"),
Path("docs/COMMAND_REFERENCE.md"),
Path("docs/COMPATIBILITY.md"),
Path("docs/CONTRACT.md"),