From 49e1a87c138cdc63fb5abb85fc6eb2cf9f4a9d73 Mon Sep 17 00:00:00 2001 From: Andraxion Date: Wed, 29 Jul 2026 16:50:39 -0400 Subject: [PATCH] Document the 1.4.0 release candidate --- ACTIVE_SLICE.md | 30 +++++ CHANGELOG.md | 57 ++++++++++ DEVELOPMENT_NOTES.md | 45 ++++++++ README.md | 28 ++++- SLICE_HISTORY.md | 44 +++++++- docs/COMPATIBILITY.md | 34 +++++- docs/CONTRACT.md | 41 ++++++- docs/MIGRATING_FROM_V1.md | 30 +++++ docs/MILESTONE_5_BASELINE.md | 187 +++++++++++++++++++++++++++++++ docs/MILESTONE_5_CLOSEOUT.md | 101 +++++++++++++++++ docs/RECOVERY_AND_PERFORMANCE.md | 45 +++++++- docs/SECURITY.md | 35 +++++- docs/USER_MANUAL.md | 88 +++++++++++++-- 13 files changed, 739 insertions(+), 26 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 docs/MILESTONE_5_BASELINE.md create mode 100644 docs/MILESTONE_5_CLOSEOUT.md diff --git a/ACTIVE_SLICE.md b/ACTIVE_SLICE.md index 2d5667c..d656659 100644 --- a/ACTIVE_SLICE.md +++ b/ACTIVE_SLICE.md @@ -96,3 +96,33 @@ The release candidate must prove all of the following from maintained, reproduci 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. + +Milestone 5 remains active. Documentation closeout, final branch synchronization, a fresh +anonymous clone at the exact documentation-bearing remote commit, final artifact checksums, the +annotated `v1.4.0` tag, and the Forgejo release are still pending. No PyPI publication is planned. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..a2628c6 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,57 @@ +# Changelog + +Notable changes in the DocForge product line are recorded here. Historical milestone evidence +remains in `docs/MILESTONE_*_BASELINE.md` and `docs/MILESTONE_*_CLOSEOUT.md`. + +## Unreleased + +### DocForge 1.4.0 release candidate + +Version `1.4.0` is frozen as an additive successor release. The annotated tag and Forgejo release +do not exist yet; Milestone 5 remains active until the final documentation-bearing commit passes +the fresh-clone gate and publication is verified. + +Added: + +- One authoritative version shared by package metadata, Python, CLI, generic MCP, reference MCP, + viewer manager, generated client bindings, and release checks. +- Public adapter SDK and complete graph-plus-Logic conformance checks. +- Base Python and optional JavaScript, TypeScript, and C++ reference adapters. +- Task-shaped retrieval, generation diffs, generated client configuration, doctor checks, and + bounded response continuation. +- Independent manual, portable-graph, and live-viewer projections with immutable packages, + receipts, policy enforcement, and accessibility gates. +- Maintained compatibility, migration, concurrency, recovery, representative-task, + fresh-wheel, artifact-reproducibility, secret-scan, and benchmark gates. +- MIT licensing and Forgejo repository metadata. + +Changed: + +- Warm graph reads use generation-bound SQLite state without reparsing canonical project sources. +- Incremental adapters use bounded extraction caches while retaining a complete-build equivalence + oracle. +- Generated client configuration is bound to the exact DocForge version. +- Derived publication uses durable atomic replacement and fails closed on malformed, foreign, + stale, oversized, or incompatible state. +- Generic canonical application uses project-owned locking, compare-and-swap publication, and + exact-hash proposal checks while preserving raced source data. + +Compatibility: + +- The `docforge` distribution and Python package, `docforge` CLI, `docforge-mcp`, MCP tool names, + legacy one-method adapters, generic projects, and descriptor schema version 1 remain supported. +- Version `1.4.0` rebuilds disposable version-1 indexes as version 3 without rewriting canonical + source or active proposal bytes. +- The base wheel has no Tree-sitter dependency. Optional language extras remain explicit. + +Release channels: + +- The intended release channel is the public Forgejo repository and its release artifacts. +- PyPI publication is not planned because the `docforge` name is occupied by an unrelated + project. + +## 1.0.0 - 2026-07-25 + +The first stable release established the project-scoped graph, generic Markdown/TOML adapter, +SQLite index, project-bound CLI and MCP server, reviewable exact-hash changesets, declared manual +rendering, visualization, and the original versioned compatibility surface. diff --git a/DEVELOPMENT_NOTES.md b/DEVELOPMENT_NOTES.md index 2cca502..df19e94 100644 --- a/DEVELOPMENT_NOTES.md +++ b/DEVELOPMENT_NOTES.md @@ -31,6 +31,51 @@ policy, projection, task-comparison, package, clone, browser, benchmark, and sec pass before documentation closeout, tag creation, or publication. `main` remains the Milestone 4 baseline while implementation proceeds on `dev`. +### Release-candidate freeze — 2026-07-29 + +The executable implementation froze at +`d2bb95fe6190e659cf66ba57c78be53b63b53240`. It centralizes version `1.4.0`, binds generated +clients to that version, adds MIT license and package metadata, proves reproducible artifacts, +migrates a real archived `v1.0.0` project, maintains comparative real-task evidence, and hardens +derived and canonical publication against measured race and durability failures. + +The clean executable release gate passed: + +- Ruff formatting and lint, web lint, strict Pyright, compilation, lock, dependency, build, + generated-reference, and documentation checks. +- 142 contract tests plus 272 subtests and 371 complete tests plus 419 subtests. +- Three manual, portable-graph, and live-viewer accessibility flows. +- 116 compatibility tests plus 263 subtests. +- 29 concurrency tests plus 2 subtests. +- Offline fresh-wheel adoption, reproducible artifacts, version checks, and secret scans. +- Every maintained full Milestone 0 through Milestone 4 benchmark. + +Commit `97f3b6b` made the fresh-clone rehearsal require and verify the exact annotated legacy tag. +Commit `2b98059b44f4d46b4d4cce776f163e893c647c76` added four maintained recovery proofs without +changing product code. The recovery aggregate now passes 72 tests plus 62 subtests. Those tests +record exact canonical bytes, canonical collection hash, complete snapshot hash, and index +graph-plus-Logic identity before corrupting and repairing the index attestation, manual render +receipt, generation-diff receipt, and portable-graph manifest through normal public work paths. + +The real migration evidence uses tag object +`2d7d306a37da89f1c860c7f0be161c45386acf61`, peeled commit +`593c173b453236a6872d0a4e88e7a51a67a21cde`, and a real schema-1 index plus active proposal. +Canonical bytes, the graph snapshot, proposal hash, and proposal file bytes remain exact after the +schema-3 rebuild. The proof retains the inherited version-1 metadata/runtime mismatch: package +metadata is `1.0.0`, while the module and server report `0.15.0`. + +The representative real-task track pins `markdown-it-py 4.2.0` at 66 Python files and 225,945 +bytes. Both workflows answer all three reviewed questions exactly. Graph-assisted work inspects +349 versus 10,628 bytes, 419 versus 225,945 bytes, and 212 versus 225,945 bytes, with medians of +0.008 versus 1.341 ms, 0.009 versus 32.108 ms, and 0.013 versus 32.142 ms. Source-only final +responses are smaller, so the evidence claims reduced inspected source and faster maintained task +latency rather than a universal response-size advantage. + +Documentation closeout is now being prepared against this frozen lineage. Milestone 5 remains +active until the final documentation-bearing commit is pushed, passes the exact fresh-clone +rehearsal, and is published through one annotated `v1.4.0` tag and Forgejo release. PyPI remains +excluded. + ## Milestone 0 — complete Milestone 0 established the public successor, preserved the complete lineage and v1 tag, integrated diff --git a/README.md b/README.md index 6e14013..a84bb3f 100644 --- a/README.md +++ b/README.md @@ -9,10 +9,10 @@ DocForge never treats indexed text as instructions. It does not run project buil compilers, Git operations, deployments, or arbitrary renderers, and it does not select projects globally. -DocForge 1.0.0 remains the first stable release in this product line. This checkout is the -post-1.0 development line (`1.3.0.dev0`) and contains the Milestone 4 adapter-platform work. -Milestone 4 is not a new product release, and Milestone 5 release and publication work remains -separate. +DocForge 1.0.0 remains the latest published stable release in this product line. This checkout is +the `1.4.0` release candidate and contains the complete Milestone 4 adapter platform plus +Milestone 5 stabilization evidence. The `v1.4.0` tag and Forgejo release are still pending; this +candidate is not published yet. ## Start here @@ -23,6 +23,8 @@ separate. - Agent and client setup: [Agent integration](docs/AGENT_INTEGRATION.md) - Exact live command and tool inventory: [Generated command reference](docs/COMMAND_REFERENCE.md) - Task-oriented operating guide: [User manual](docs/USER_MANUAL.md) +- Release-candidate changes and evidence: [Changelog](CHANGELOG.md) and [Milestone 5 + baseline](docs/MILESTONE_5_BASELINE.md) ## Current capabilities @@ -210,6 +212,8 @@ paths. ### Milestone evidence +- [Milestone 5 baseline](docs/MILESTONE_5_BASELINE.md) +- [Milestone 5 release-candidate closeout](docs/MILESTONE_5_CLOSEOUT.md) - [Milestone 4 baseline](docs/MILESTONE_4_BASELINE.md) - [Milestone 4 closeout](docs/MILESTONE_4_CLOSEOUT.md) - [Milestone 3 baseline](docs/MILESTONE_3_BASELINE.md) and [closeout](docs/MILESTONE_3_CLOSEOUT.md) @@ -244,6 +248,22 @@ Python reference plus a real isolated read-only MCP retrieval. The optional-lang have their own focused tests and extras. `benchmark-m4` runs the maintained full adapter workload; the smoke target is for routine gate coverage, not final performance evidence. +Milestone 5 adds focused and aggregate release-candidate 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` includes the complete repository, accessibility, adoption, artifact-reproducibility, +secret-scan, and full maintained benchmark sequence. `fresh-clone-m5` is the final remote-commit +rehearsal and must pass before the annotated tag and Forgejo release are created. + Pass `--diagnostics` to `docforge` or `docforge-mcp` for bounded request-local timings and compiler work counters. Diagnostics are disabled by default and do not displace a primary result when the configured output budget is tight. diff --git a/SLICE_HISTORY.md b/SLICE_HISTORY.md index 0caab02..06958d5 100644 --- a/SLICE_HISTORY.md +++ b/SLICE_HISTORY.md @@ -1,4 +1,46 @@ -# Completed slices +# Release candidates and completed slices + +## DocForge2 Milestone 5 release candidate — active + +### Changed + +- Centralized version `1.4.0` across package metadata, Python, executable surfaces, generated + clients, and release validation. +- Added MIT licensing, public Forgejo metadata, reproducible artifact checks, a real archived-v1 + migration proof, focused compatibility/concurrency/recovery gates, and representative + graph-assisted versus source-only task evidence. +- Hardened durable derived publication and generic exact-hash canonical application against + measured race windows. +- Added a fresh-clone rehearsal that requires the exact annotated legacy tag. + +### Verification + +- The clean executable candidate passed 371 tests and 419 subtests, 142 contract tests and 272 + subtests, three accessibility flows, lint, strict types, compilation, dependencies, builds, + adoption, reproducible artifacts, secret scans, and every maintained full benchmark. +- Focused compatibility passed 116 tests plus 263 subtests. Concurrency passed 29 tests plus 2 + subtests. +- Four later proof-only tests brought the recovery gate to 72 tests plus 62 subtests without + changing executable product code. +- Real `v1.0.0` migration preserved canonical, graph, and proposal evidence while rebuilding the + disposable index from schema 1 to schema 3. +- The lock-pinned real-package comparison returned exact answers from both workflows and measured + substantially less inspected source for graph-assisted work. + +### Limits + +- This is release-candidate evidence, not a completed milestone or published release. +- Multi-file canonical application does not claim process-death atomicity. +- Source-only task responses were smaller even where graph-assisted work inspected fewer bytes and + ran faster. +- No WorldForge, ScrapeStation, legacy repository, production binding, self-hosting, PyPI, tag, or + Forgejo release was changed. + +### Final gate + +Commit the documentation closeout, synchronize the final branches, pass the exact fresh anonymous +clone, build final checksummed artifacts, and then create and verify the annotated `v1.4.0` tag and +Forgejo release. Milestone 5 remains active until that sequence succeeds. ## DocForge2 Milestone 4 adapter SDK and product documentation diff --git a/docs/COMPATIBILITY.md b/docs/COMPATIBILITY.md index 8eca1c9..4907d41 100644 --- a/docs/COMPATIBILITY.md +++ b/docs/COMPATIBILITY.md @@ -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 diff --git a/docs/CONTRACT.md b/docs/CONTRACT.md index 177a62d..780f15d 100644 --- a/docs/CONTRACT.md +++ b/docs/CONTRACT.md @@ -1,4 +1,4 @@ -# DocForge post-1.0 development contract +# DocForge 1.4 contract ## Authority boundary @@ -34,13 +34,19 @@ commit when Git is available; it cannot change repository state. - Reference adapter configuration: `schemas/reference-adapter.schema.json`, version 1. - Index schema: version 3, disposable and reproducible. - Index attestation: schema version 1, disposable and reproducible. -- Core, CLI, and MCP server: version 1.3.0.dev0. +- Distribution, Python package, CLI, generic MCP, reference MCP, and viewer manager: version 1.4.0. - Incremental extraction cache: version 1, disposable and reproducible. Schema files describe the generic interchange contract. Runtime validation remains responsible for path confinement, source hashing, relationship resolution, dependency cycles, project limits, stale state, and adapter-specific rules that JSON Schema cannot prove by itself. +`src/docforge/_version.py` is the sole package-version authority. The maintained executable +surfaces report exactly `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 bind `docforge_version` into their validated +hashes. + ## Generic node storage Markdown nodes begin with a TOML metadata block delimited by `+++`. The remaining Markdown is the @@ -73,6 +79,13 @@ Index replacement is the derived publication commit point. Attestation, cheap so and latest-generation-diff receipts are independent post-commit evidence. Their failure produces bounded degraded success and never falsely reports that a committed index mutation failed. +Derived publication stages and flushes one complete bounded artifact before atomic replacement or +no-clobber publication, then flushes the containing directory. An interruption therefore leaves +the preceding complete artifact, the new complete artifact, or explicit degraded post-commit +evidence. Index attestations, manual render receipts, generation-diff baselines, and portable-graph +manifests have maintained exact-oracle corruption-and-repair proofs. Canonical project files remain +unchanged throughout those recoveries. + Before replacement, a build accepts a predecessor only when its exact main-file inode has a matching whole-file attestation, has no WAL, journal, or shared-memory sidecar, and passes the published SQLite identity, row, hash, FTS, integrity, and policy checks. It uses an immutable @@ -174,6 +187,30 @@ default active listing contains only draft and ready work. Stale, applied, and a remain queryable by explicit status or history request. Terminal proposals do not block new proposals. +## Canonical application durability + +Generic canonical application stages replacements and backups in a mode-0700 +`.docforge/application/transaction-*` directory. Before each canonical create, update, or delete, +it compares exact file identity at the publication boundary. Creates use no-clobber publication. +Updates and deletes use atomic exchange and no-replace detachment. A concurrent canonical-target +mutation fails closed, is rolled back only when exact displaced state remains provable, or is +retained without overwriting foreign data. + +This is per-file compare-and-swap publication, not multi-file crash atomicity. In-process failures +run rollback across already published files, but there is no process-death journal. Process or host +death between publications may leave a partial canonical application and requires operator +inspection before a new proposal or restoration. + +The private transaction namespace is integrity-confined against ordinary path access. It is not a +filesystem sandbox, and deliberate arbitrary tampering by another process with the same operating- +system UID is outside the contract. DocForge identity-checks private files before consuming or +removing them. + +After the serializer reproduces the approved graph, canonical success is final. If private cleanup +then degrades, application still returns `applied`, closes the proposal, and persists bounded +`application_recovery` lifecycle metadata with status `cleanup_required`, retained paths, and +remediation. The reviewed changeset must not be applied twice. + ## Declared rendering and previews Render configuration is optional. A configured project declares one template root, one isolated diff --git a/docs/MIGRATING_FROM_V1.md b/docs/MIGRATING_FROM_V1.md index dab9669..eb24fbe 100644 --- a/docs/MIGRATING_FROM_V1.md +++ b/docs/MIGRATING_FROM_V1.md @@ -19,6 +19,36 @@ Read [compatibility](COMPATIBILITY.md), [legacy and no-AST operation](LEGACY_AND Disposable index and cache schemas may change. Rebuild them rather than copying them as authority. +## Maintained v1.0.0 migration evidence + +`make migration-m5` archives and executes the actual annotated `v1.0.0` release, then opens its +fixture, index, and active proposal through DocForge 1.4.0. The frozen tag object is +`2d7d306a37da89f1c860c7f0be161c45386acf61`; it identifies commit +`593c173b453236a6872d0a4e88e7a51a67a21cde`. + +The tagged release contains an inherited identity mismatch that the migration proof records +rather than hiding: distribution metadata says `1.0.0`, while `docforge.__version__` and the MCP +server report `0.15.0`. DocForge 1.4.0 replaces that duplicated state with one authoritative +version and requires its package and server values to agree. + +The maintained fixture evidence is exact: + +- Canonical collection hash: + `9fde91b6b08669177d690cdf9f91b162120baee1f7e24b05fec67f56617f286a`. +- Graph snapshot hash: + `45bef8b0e1a4dac976e096dcf8f9048e1268211cd7f7638cdf99951428ec0500`. +- Source hash: `0aa6ad13a95355102300a69b2f9d06883c301d63e2624b083e45f15102dab504`. +- Active proposal hash: + `2c055dfae45443b4a4d9d4087ef70959e7293beae8d27acb14ffffe52eca7111`. +- Proposal-file hash: + `4658d494b43bd7c6cc3e3f5933a2c878c817b52bc4566e9e8429e7b8e43ca007`. + +Current loading preserves all five identities and every canonical byte. It rebuilds the disposable +index from schema 1 to schema 3 without changing the graph or active proposal. All 20 tagged CLI +commands remain in the current 28-command surface, and all 25 tagged MCP tools remain in the +current 36-tool application-enabled surface. These counts describe the maintained rehearsal, not +a promise that every additive current command belongs in a legacy binding. + ## Recommended migration 1. Record the v1 package version, adapter identity, project descriptor, canonical source hash, diff --git a/docs/MILESTONE_5_BASELINE.md b/docs/MILESTONE_5_BASELINE.md new file mode 100644 index 0000000..f883a47 --- /dev/null +++ b/docs/MILESTONE_5_BASELINE.md @@ -0,0 +1,187 @@ +# Milestone 5 baseline + +## Status and method + +This baseline records the frozen DocForge `1.4.0` release candidate. It is release-candidate +evidence, not a claim that the tag or Forgejo release already exists. + +The executable implementation freeze is +`d2bb95fe6190e659cf66ba57c78be53b63b53240`. Fresh-clone legacy-tag verification was added in +`97f3b6b1ae303c972387508557a3d54ea621a702`, and the maintained aggregate recovery proofs were +completed in +`2b98059b44f4d46b4d4cce776f163e893c647c76`. The final tag must point to the later +documentation-bearing commit after its clean fresh-clone gate. + +The clean executable candidate used: + +- Linux 7.1.3-200.nobara.fc44.x86_64 with glibc 2.43. +- CPython 3.14.6 on x86_64. +- The repository lockfile and offline wheel inputs. +- Maintained repository-native gates rather than a self-hosted DocForge development loop. + +No WorldForge, ScrapeStation, legacy repository, production binding, or production MCP +configuration was changed. + +## Quality and compatibility gates + +The clean executable candidate passed: + +- Ruff formatting and lint, web lint, strict Pyright with zero diagnostics, and compilation. +- 142 contract tests plus 272 subtests. +- 371 complete tests plus 419 subtests. +- Three Playwright and axe accessibility flows covering the manual, portable graph, and live + viewer. +- Lockfile, dependency-tree, wheel, source-distribution, generated-reference, and documentation + checks. +- 116 compatibility tests plus 263 subtests. +- 29 concurrency tests plus 2 subtests. +- Offline fresh-wheel adoption, exact version identity, reproducible artifact, and secret-scan + gates. +- The complete maintained Milestone 0 through Milestone 4 benchmark sequence. + +The later maintained recovery proof adds four tests without changing executable product code. Its +aggregate recovery gate passes 72 tests plus 62 subtests. A final clean clone must rerun the +complete totals from the documentation-bearing commit before tagging. + +Compatibility remains additive: + +- The `docforge` distribution and imports, CLI, generic MCP executable, MCP tool names, generic + project descriptor, result envelopes, legacy one-method adapter, and no-AST behavior remain. +- Effective policy version 1, projection policy version 2, descriptor schema version 1, and index + schema version 3 remain the current authorities. +- Complete and incremental maintained adapters produce exact primary-graph and Logic equivalence. + +## Version and artifact identity + +One source file owns version `1.4.0`. The following executable surfaces reported that exact +version: + +- `docforge` +- `docforge-mcp` +- `docforge-viewer-manager` +- `python -m docforge.reference_mcp` + +The package metadata also reported `docforge 1.4.0`, Python 3.12 or newer, the MIT license +expression, the public Forgejo repository, and its issues URL. Generated client bindings include +the version in their validated, hash-bound identity. + +Two independent builds from the executable candidate and the same source-date epoch produced +identical artifacts: + +| Artifact | Bytes | Executable-candidate SHA-256 | +|---|---:|---| +| Wheel | 315,811 | `c3b9bfa320d00d827154e0f858a6b970459ae0eba6ab14e1cd4f6ba470e33b6a` | +| Source distribution | 685,891 | `bb5f9333e5fa2365cf0f8ac12d7920122315b4835c9f81b7aa457eb05f1702f5` | + +Both contained the license and version authority. These identify the executable freeze only. +Documentation changes alter the final release artifacts, so final checksums must be generated from +the exact tagged documentation-bearing commit. + +The release channel is Forgejo only. PyPI is excluded because the `docforge` name is occupied by an +unrelated project. + +## Exact migration evidence + +The migration gate archives and executes the real annotated `v1.0.0` lineage: + +- Tag object: `2d7d306a37da89f1c860c7f0be161c45386acf61`. +- Peeled commit: `593c173b453236a6872d0a4e88e7a51a67a21cde`. +- Canonical byte hash before and after: + `9fde91b6b08669177d690cdf9f91b162120baee1f7e24b05fec67f56617f286a`. +- Snapshot hash before and after: + `45bef8b0e1a4dac976e096dcf8f9048e1268211cd7f7638cdf99951428ec0500`. +- Active proposal hash: + `2c055dfae45443b4a4d9d4087ef70959e7293beae8d27acb14ffffe52eca7111`. +- Active proposal file hash: + `4658d494b43bd7c6cc3e3f5933a2c878c817b52bc4566e9e8429e7b8e43ca007`. + +The version-1 disposable index rebuilt from schema 1 to schema 3. Canonical bytes, graph meaning, +and the active proposal remained exact. The current CLI is a 28-command superset of the version-1 +20-command surface. The current generic MCP surface is a 36-tool superset of the version-1 +25-tool surface. + +The proof also preserves a real inherited version-1 inconsistency: package metadata reports +`1.0.0`, while its Python module and server report `0.15.0`. Migration evidence records that fact; +it does not rewrite history to make the old identities agree. + +## Recovery and concurrency evidence + +The maintained gates prove: + +- Concurrent canonical-source changes fail closed without publishing or serving mixed + generations. +- Exact-hash canonical application uses project-owned serialization and compare-and-swap + publication, rejects stale proposals, and preserves raced source data. +- Extraction caches and SQLite indexes rebuild from canonical sources or complete adapter + projections. +- Corrupt index attestations, manual render receipts, generation-diff receipts, and portable-graph + manifests recover through their normal synchronize, rebuild, or render entry points. +- Recovery preserves exact canonical bytes, the canonical collection hash, the complete snapshot + hash, and primary-graph-plus-Logic index identity. +- Derived publication uses durable atomic replacement and directory synchronization. + +The release does not claim that a multi-file canonical application is process-death atomic. A +malicious same-UID process deliberately modifying the private mode-0700 transaction directory is +also outside the application race contract. Those limits do not weaken the maintained +concurrent-canonical-source compare-and-swap proof. + +## Representative real-task evidence + +The real-package track uses installed, lock-pinned `markdown-it-py 4.2.0`: + +- 66 Python files. +- 225,945 source bytes. +- Source-tree SHA-256: + `bd57c9f332fcf6507282ec2023e6804fce0cf844631696336ee17cbe46e63aad`. +- No network, production binding, installed-source mutation, or self-hosting. +- Python reference-adapter local-import projection for graph-assisted work. +- Independent standard-library AST import inspection for source-only work. + +Both workflows returned the exact reviewed answer for all three tasks: + +| Task | Graph inspected | Source inspected | Graph median | Source median | +|---|---:|---:|---:|---:| +| Renderer direct dependencies | 349 B | 10,628 B | 0.008 ms | 1.341 ms | +| Three-level HTML-block impact | 419 B | 225,945 B | 0.009 ms | 32.108 ms | +| CLI-to-core-state path | 212 B | 225,945 B | 0.013 ms | 32.142 ms | + +Per-task latency excludes the separately reported one-time graph preparation. Graph-assisted +answers inspected substantially fewer agent-visible bytes and carried generation-bound +provenance. The source-only answers were smaller on the final response-size metric. The comparison +therefore records the measured tradeoff rather than claiming that every metric favors the graph. + +The real-package semantic evidence SHA-256 is +`c8c19b2900fa47abdaff94f5b13fd9ca537241089edc97b30d32d9db8809a2c1`. +The combined real and generated-track evidence SHA-256 is +`45952883b47449eb4fd862b51854aa2001749928e0d37c5a6e58c2d3292fbee4`. + +## Machine-readable evidence + +The maintained evidence generators emit canonical compact JSON and can write it atomically with +their `--output` option: + +```bash +.venv/bin/python tools/milestone5_migration.py --output /tmp/docforge-m5-migration.json +.venv/bin/python tools/milestone5_task_evidence.py \ + --mode full --output /tmp/docforge-m5-task-evidence.json +.venv/bin/python tools/check_release_identity.py \ + --mode full --require-clean --tag-state absent \ + --output /tmp/docforge-m5-release-identity.json +.venv/bin/python tools/milestone5_fresh_clone.py \ + --commit "$(git rev-parse HEAD)" \ + --output /tmp/docforge-m5-fresh-clone.json +``` + +Migration, task, release identity, artifact hashes, and the final anonymous-clone result therefore +remain reproducible machine evidence rather than prose-only claims. The final Forgejo release +attaches the release-identity JSON beside the wheel and source distribution. + +## Remaining release gate + +The baseline is complete for the release candidate. Milestone 5 remains active until: + +1. The documentation closeout is committed. +2. `main` and `dev` are synchronized and pushed. +3. The exact final commit passes the maintained fresh anonymous clone gate. +4. Final artifacts and checksums are generated from that commit. +5. The annotated `v1.4.0` tag and Forgejo release are created and verified. diff --git a/docs/MILESTONE_5_CLOSEOUT.md b/docs/MILESTONE_5_CLOSEOUT.md new file mode 100644 index 0000000..8c271f2 --- /dev/null +++ b/docs/MILESTONE_5_CLOSEOUT.md @@ -0,0 +1,101 @@ +# Milestone 5 release-candidate closeout + +## Outcome + +DocForge `1.4.0` has reached its documentation closeout candidate. Compatibility, migration, +determinism, concurrency, recovery, policy, projection isolation, accessibility, performance, +adoption, artifact reproducibility, and representative real-task evidence are maintained and +passing. + +This is not the final publication record. Milestone 5 remains active, and DocForge `1.0.0` remains +the latest published stable release, until the documentation-bearing commit passes its final +fresh-clone gate and the annotated `v1.4.0` tag and Forgejo release are verified. + +## Candidate lineage + +- Merged Milestone 4 baseline: + `6d06195950d33bcd2d712f8819bbfb3d6652ad03`. +- Frozen executable implementation: + `d2bb95fe6190e659cf66ba57c78be53b63b53240`. +- Fresh-clone legacy-tag verification: + `97f3b6b1ae303c972387508557a3d54ea621a702`. +- Maintained aggregate recovery proof: + `2b98059b44f4d46b4d4cce776f163e893c647c76`. +- Intended release version and tag: `1.4.0` and `v1.4.0`. +- Publication channel: public Forgejo release only. + +The tag does not exist yet. It must resolve to the final documentation-bearing descendant of this +lineage, never to the earlier executable-only commit. + +## Closed release evidence + +The clean executable release gate passed: + +- Formatting, Python and web lint, strict types, compilation, lock, dependency, package-build, + generated-reference, and documentation checks. +- 142 contract tests plus 272 subtests. +- 371 complete tests plus 419 subtests. +- Three interactive accessibility flows. +- 116 compatibility tests plus 263 subtests. +- 29 concurrency tests plus 2 subtests. +- Offline fresh-wheel adoption. +- Reproducible wheel and source-distribution builds with exact version and MIT license identity. +- Gitleaks scans of reachable history and the candidate directory with no findings. +- Full maintained Milestone 0, 1, 2, 3, and 4 benchmarks. + +The later proof-only recovery commit adds four maintained tests. The aggregate recovery gate now +passes 72 tests plus 62 subtests. The final fresh clone owns the final complete-suite total. + +Detailed migration identities, artifact evidence, recovery boundaries, and task measurements are +in the [Milestone 5 baseline](MILESTONE_5_BASELINE.md). + +## Compatibility and migration result + +Version `1.4.0` preserves the established distribution, imports, CLI, MCP, schema-1 descriptor, +generic-project, one-method adapter, exact-hash changeset, rendering, result-envelope, and no-AST +surfaces. New adapter, retrieval, projection, and release capabilities are additive. + +The real annotated `v1.0.0` archive migrates without canonical or proposal changes. Its schema-1 +index rebuilds as schema 3, and its graph identity remains exact. The current CLI and MCP +registrations are supersets of the version-1 surfaces. The proof reports the inherited version-1 +metadata/runtime mismatch instead of hiding it. + +## Representative task result + +The pinned real-package comparison uses `markdown-it-py 4.2.0`, 66 Python files, and 225,945 bytes. +Graph-assisted and source-only workflows both return exact reviewed answers for direct +dependencies, bounded reverse impact, and a dependency path. + +Graph-assisted medians were 0.008, 0.009, and 0.013 ms after one-time preparation, versus 1.341, +32.108, and 32.142 ms for source-only inspection. Graph-assisted work also reduced inspected bytes +from 10,628 to 349, from 225,945 to 419, and from 225,945 to 212. Source-only final responses were +smaller, so no universal response-size advantage is claimed. + +## Preserved boundaries + +- Canonical project files remain authoritative. Indexes, caches, receipts, render output, graph + output, client fragments, and viewer state remain disposable. +- Full rebuild remains the recovery and equivalence oracle. +- Derived publication is durable and atomic. Multi-file canonical application does not claim + process-death atomicity. +- `--no-ast` remains a restrictive binding policy, not a parser detector or filesystem sandbox. +- Reference adapters publish narrow static evidence and do not claim resolved calls, types, + inheritance, runtime behavior, compiler semantics, or semantic ownership. +- Reference MCP remains read-only. +- No WorldForge, ScrapeStation, legacy repository, production binding, storage, or self-hosting + change belongs to this release. +- No PyPI publication belongs to this release. + +## Publication still pending + +The remaining sequence is exact: + +1. Commit this coherent documentation closeout on the verified candidate lineage. +2. Run documentation-only checks and confirm the final worktree contains no unrelated changes. +3. Merge and push the final candidate so `main`, `dev`, `origin/main`, and `origin/dev` agree. +4. Run the complete fresh-clone release rehearsal at that exact remote commit. +5. Build the final artifacts and checksum manifest from the verified commit. +6. Create and push one annotated `v1.4.0` tag at that commit. +7. Publish and verify the Forgejo release and attached artifacts. + +Until all seven steps succeed, the milestone status is release candidate rather than complete. diff --git a/docs/RECOVERY_AND_PERFORMANCE.md b/docs/RECOVERY_AND_PERFORMANCE.md index 62f6499..14836bb 100644 --- a/docs/RECOVERY_AND_PERFORMANCE.md +++ b/docs/RECOVERY_AND_PERFORMANCE.md @@ -41,14 +41,42 @@ reported as degraded committed success, not as permission to repeat a mutation. The live viewer pins one validated index identity. Index replacement makes the running snapshot stale and causes a later visualize request to start a fresh worker. +Milestone 5 maintains exact-oracle recovery proofs for four independently disposable artifacts: + +- A corrupt index attestation is rejected, then `synchronize()` recreates the exact attestation + after complete verification while preserving canonical bytes, snapshot hash, and index identity. +- A corrupt manual-render receipt reports `unverified/receipt_corrupt`; explicit rendering restores + the exact output bytes and semantic receipt, and normal and deep status return `current`. +- A corrupt generation-diff receipt reports `unverified/corrupt_receipt`; a complete index build + recreates the exact current-graph baseline with `baseline/no_meaningful_transition`. +- A corrupt portable-graph manifest reports missing publication evidence; explicit rendering + restores the exact artifact bytes and semantic manifest, and status returns `current`. + +These proofs are maintained by `tests/test_milestone5_recovery.py`. They do not promote receipts, +attestations, or manifests to canonical authority. + ## Proposal and application recovery Hash or base conflicts are not cache failures. Retrieve the current changeset and diff, then review the new exact hash. Rebase is allowed only when every touched node, relationship, source, permission, and graph invariant still matches. A content conflict requires a new proposal. -If a canonical serializer fails its round-trip check, use its reported rollback state. Do not -reapply a changeset whose application may already have committed. See +Generic canonical create, update, and delete publication compares exact target identity at the +commit boundary. Concurrent target mutation fails closed. In-process failures roll back only when +the exact displaced state remains provable; otherwise DocForge preserves foreign data and returns +`application_recovery_required` with retained evidence. + +Canonical application is not journaled across several files. Each file publication is atomic, but +process or host death between publications can leave a partial canonical application. Inspect the +named canonical targets, the active proposal, and `.docforge/application/transaction-*` before +deciding whether to restore or create a new proposal. Do not retry the old approved hash merely +because a process ended. + +If semantic application committed but private transaction cleanup degraded, the result remains +`applied`. The proposal is closed and its compact lifecycle receipt records +`application_recovery.status = "cleanup_required"`, retained paths, and remediation. Preserve and +inspect those files. Remove only artifacts proven to be DocForge-owned. If a canonical serializer +fails its round-trip check before success, use its reported rollback state. See [migrating from v1](MIGRATING_FROM_V1.md) for rollback planning. ## Milestone 4 scale evidence @@ -80,7 +108,18 @@ make gate make adoption-m4 make benchmark-m4-full make docs-check +make compatibility-m5 +make migration-m5 +make concurrency-m5 +make recovery-m5 +make task-evidence-m5 +make release-gate +make fresh-clone-m5 ``` The main gate includes smoke benchmarks. Full milestone evidence is recorded separately from a -clean candidate so smoke or dirty-tree results cannot become release claims. +clean candidate so smoke or dirty-tree results cannot become release claims. `release-gate` +aggregates the complete quality, compatibility, migration, concurrency, recovery, task-evidence, +fresh-wheel, identity, reproducible-artifact, secret-scan, and full benchmark proofs. +`fresh-clone-m5` repeats that aggregate gate from anonymous HTTPS at one exact published commit +after verifying the frozen annotated `v1.0.0` migration tag. diff --git a/docs/SECURITY.md b/docs/SECURITY.md index 4c8569e..6e81c91 100644 --- a/docs/SECURITY.md +++ b/docs/SECURITY.md @@ -1,7 +1,8 @@ # Security model DocForge is a project-bound knowledge compiler. Its security boundary is an explicit project root, -closed configuration, bounded data, and exact identities. It is not a general process sandbox. +closed configuration, bounded data, and exact identities. It is not a general process or +filesystem sandbox. Start with [core authority](CORE_CONCEPTS_AND_AUTHORITY.md), then use [policy precedence](POLICY_PRECEDENCE.md) to decide which capabilities a server should expose. @@ -18,6 +19,13 @@ Confinement protects DocForge operations. It does not stop another process with from changing files. Long-running bindings revalidate descriptor and adapter implementation identity and require a restart after drift. +Generic canonical application stages backups and replacements below +`.docforge/application/transaction-*` in mode-0700 directories. That private namespace confines +ordinary path access and prevents access by other users. Deliberate arbitrary tampering by another +process running as the same operating-system user is outside this boundary. DocForge still +identity-checks private files before using or removing them, but mode `0700` is not isolation from +the same UID. + ## Untrusted project content Documentation, source text, templates, adapter metadata, compiler-database entries, and changeset @@ -56,16 +64,33 @@ the exact changeset hash that was reviewed. Source identity, content hashes, per conflicts, graph validity, and serializer round trips are checked before success. DocForge never turns prose approval into a fuzzy merge. +The generic applier compares exact canonical file identity immediately before each publication. +Create uses no-clobber publication. Update and delete use atomic exchange and no-replace moves. +Concurrent canonical-target mutation therefore fails closed, rolls back when the exact displaced +state is still provable, or retains recovery evidence without overwriting foreign data. + +This compare-and-swap protection is not a process-death journal. One file publication is atomic, +and an in-process failure runs exact rollback, but an application spanning several canonical files +does not promise crash atomicity if the process or host dies between publications. Operators must +inspect canonical state and retained transaction evidence before retrying after such an +interruption. + ## Derived state and publication SQLite indexes, source-generation receipts, extraction caches, render fragments, previews, and portable artifacts are disposable. Corrupt, stale, foreign, oversized, or mismatched derived state is rejected or rebuilt from current project evidence. -Generated command-reference publication serializes cooperating writers and uses no-clobber or -compare-and-swap publication. A raced target is restored or retained for recovery instead of being -silently discarded. Projection publication records when an artifact was committed but later -receipt verification degraded, so a completed mutation is never reported as an ordinary failure. +Derived publication stages complete bounded output, flushes file and directory state, and commits +with atomic replacement or no-clobber compare-and-swap. It is crash-safe: an interruption leaves +the prior verified artifact, the complete new artifact, or explicit degraded post-commit evidence, +not a mixed publication. Generated command-reference publication also serializes cooperating +writers. A raced target is restored or retained for recovery instead of being silently discarded. + +Projection and canonical-application lifecycles record when semantic content committed but later +private cleanup or receipt verification degraded. Canonical success closes the applied proposal +and persists compact `application_recovery` metadata with retained paths and remediation. A +completed mutation is never reported as an ordinary retryable failure. ## Limits and denial-of-service resistance diff --git a/docs/USER_MANUAL.md b/docs/USER_MANUAL.md index 21f3007..cca7833 100644 --- a/docs/USER_MANUAL.md +++ b/docs/USER_MANUAL.md @@ -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.