Close Milestone 3 with measured projection evidence
This commit is contained in:
parent
f5dccb5e1c
commit
d6d9f47672
11 changed files with 1115 additions and 47 deletions
|
|
@ -71,6 +71,19 @@ Existing hand-written client configurations remain valid and are never rewritten
|
|||
Doctor is inspection-only and does not become a hidden bootstrap, synchronization, or migration
|
||||
path.
|
||||
|
||||
The following Milestone 3 CLI additions are also additive:
|
||||
|
||||
- `docforge graph-plan VIEW_ID`
|
||||
- `docforge graph-render VIEW_ID`
|
||||
- `docforge graph-render-status [VIEW_ID]`
|
||||
- `--manual-render-policy auto|explicit|disabled`
|
||||
- `--portable-graph-policy explicit|disabled`
|
||||
- `--live-viewer-policy on-demand|disabled`
|
||||
|
||||
MCP adds the read-only `docforge_graph_plan` and `docforge_graph_render_status` tools. Portable
|
||||
graph publication remains an explicit local CLI integration action. Existing manual render,
|
||||
preview, visualization, and status names remain supported.
|
||||
|
||||
## Versioned data contracts
|
||||
|
||||
Milestone 0 preserves:
|
||||
|
|
@ -96,6 +109,11 @@ Milestone 0 preserves:
|
|||
- Latest-generation-diff page schema version 1. Pages use one top-level pagination object and a
|
||||
nested `receipt_header`. `stored_receipt_hash` names the complete stored receipt. Opaque cursors
|
||||
may be restarted after a server or receipt change and are not durable public identifiers.
|
||||
- Manual render-plan schema version 1.
|
||||
- Graph view-plan schema version 1.
|
||||
- Projection-package schema version 1.
|
||||
- Projection-receipt schema version 1.
|
||||
- Independent projection-policy schema version 2. Effective policy version 1 remains frozen.
|
||||
|
||||
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
|
||||
|
|
@ -161,12 +179,24 @@ The following guarantees remain stable:
|
|||
|
||||
## 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 `generic_html` renderer remains the supported version-1 manual projection. Its public
|
||||
`GenericHtmlRenderer.prepare()` signature, renderer identity, frozen alpha bytes, confined paths,
|
||||
raw-HTML suppression, fixed template tokens, deterministic identities, atomic replacement, and
|
||||
side-effect-free status remain compatible. It now delegates through a versioned manual plan,
|
||||
immutable package, and independent renderer.
|
||||
|
||||
The `portable_graph_html` renderer and `graph_render` descriptor table are additive. Manual and
|
||||
portable graph declarations, plans, policies, publication receipts, and status remain separate.
|
||||
The portable renderer does not replace the existing live viewer or `docforge_visualize`.
|
||||
|
||||
Existing project descriptors may retain any positive `max_render_bytes` accepted by schema version
|
||||
1. A value above 20,000,000 bytes does not make the descriptor invalid, and a smaller actual
|
||||
artifact still renders. Actual detached worker transfer is a separate fixed 20,000,000-byte
|
||||
runtime boundary.
|
||||
|
||||
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.
|
||||
not become project authority or MCP retrieval authority. Source reads use the pinned index
|
||||
generation instead of reopening mutable canonical files behind that generation.
|
||||
|
||||
## Task-context compatibility
|
||||
|
||||
|
|
@ -199,8 +229,9 @@ The exact version-1 relation aliases are frozen by the MCP contract and reposito
|
|||
Changing an alias category requires a new planner version; it is not a silent implementation
|
||||
detail.
|
||||
|
||||
`ManualRenderPlan`, `GraphViewPlan`, a portable graph renderer, and independently packaged
|
||||
renderers are later-milestone direction. Milestone 0 does not claim that those contracts exist.
|
||||
Milestone 3 adds `ManualRenderPlanV1`, `GraphViewPlanV1`, projection package and receipt version 1,
|
||||
and projection policy version 2. These are additive submodule and schema contracts. They do not
|
||||
change the legacy task-context, adapter, changeset, or effective-policy contracts described above.
|
||||
|
||||
## Safety boundary
|
||||
|
||||
|
|
@ -221,6 +252,8 @@ Milestone 0 records rather than redesigns these areas:
|
|||
callers use targeted retrieval for that node.
|
||||
- One individually oversized changeset diff is transported as reconstructable canonical-JSON
|
||||
chunks. Cursors are corruption-detecting read tokens, not authenticated authorization tokens.
|
||||
- Manual planning is not separated from rendering.
|
||||
- There is no portable graph-planning or graph-rendering contract.
|
||||
- Production fragment validation is currently slower than forced-full rendering at the maintained
|
||||
1,000-page fixture. Full rendering remains the equivalence and recovery oracle.
|
||||
- Remote render services, render farms, third-party renderer ecosystems, and a separate render MCP
|
||||
remain deferred.
|
||||
- DocForge2 does not self-host its bootstrap documentation.
|
||||
|
|
|
|||
|
|
@ -24,6 +24,11 @@ commit when Git is available; it cannot change repository state.
|
|||
- Latest generation-diff page: `schemas/generation-diff-page.schema.json`, version 1.
|
||||
- Generated client configuration: `schemas/client-configuration.schema.json`, version 1.
|
||||
- Client doctor result: `schemas/doctor-result.schema.json`, version 1.
|
||||
- Manual render plan: `schemas/manual-render-plan.schema.json`, version 1.
|
||||
- Graph view plan: `schemas/graph-view-plan.schema.json`, version 1.
|
||||
- Projection package: `schemas/projection-package.schema.json`, version 1.
|
||||
- Projection receipt: `schemas/projection-receipt.schema.json`, version 1.
|
||||
- Independent projection policy: `schemas/projection-policy.schema.json`, version 2.
|
||||
- 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.
|
||||
|
|
@ -82,7 +87,9 @@ the header alone. One top-level pagination object carries the only continuation
|
|||
Generated Codex, Claude, and OpenClaw fragments are machine-local projections. They are not
|
||||
canonical project content. Version 1 binds the selected project, exact isolated Python
|
||||
interpreter, canonical argument layout, effective policy, no-AST projection, render policy,
|
||||
timeouts, artifact bytes, and configuration hash.
|
||||
timeouts, artifact bytes, and configuration hash. Milestone 3 adds the version-2 projection policy,
|
||||
its hash, projection availability, and the exact descriptor hash to that attested configuration
|
||||
evidence. Omitted default selectors are recomposed against the bound descriptor.
|
||||
|
||||
Preview is side-effect free. Explicit publication creates only one new private standalone
|
||||
fragment in an existing real directory. It never merges or replaces different content. Descriptor,
|
||||
|
|
@ -135,10 +142,12 @@ preview root, and one or more stable view IDs. Each view names a built-in render
|
|||
derived output file, title, and optional family filter. Paths are resolved under the project root
|
||||
and may not overlap canonical content, authority files, changesets, templates, or previews.
|
||||
|
||||
The initial `generic_html` renderer uses pinned CommonMark parsing with raw HTML disabled. Templates
|
||||
are UTF-8 files with a fixed token vocabulary; they cannot name commands, modules, or executable
|
||||
The `generic_html` renderer uses pinned CommonMark parsing with raw HTML disabled. Templates are
|
||||
UTF-8 files with a fixed token vocabulary; they cannot name commands, modules, or executable
|
||||
renderers. Render identity covers the canonical source hash, optional changeset hash, selected node
|
||||
and edge identities, view configuration, template hash, renderer contract, and exact parser version.
|
||||
and edge identities, view configuration, template hash, renderer contract, and exact parser
|
||||
version. The frozen version-1 API and alpha bytes are preserved by a compatibility wrapper over the
|
||||
manual plan/package/renderer path.
|
||||
|
||||
An explicit CLI render atomically replaces one declared derived output. MCP can render a validated
|
||||
changeset only to its isolated preview path. Normal status verifies bounded source, configuration,
|
||||
|
|
@ -146,6 +155,56 @@ template, output, renderer, and publication-receipt identities without reconstru
|
|||
Explicit deep status remains the side-effect-free full-render oracle. Input changes detected before
|
||||
atomic replacement fail without publishing a current receipt for stale output.
|
||||
|
||||
## Independent projection boundary
|
||||
|
||||
Manual and portable graph plans are separate version-1 contracts over one immutable validated
|
||||
generation. They use canonical JSON, deterministic ordering, fixed structural and serialized-size
|
||||
bounds, and content-derived identities. Plans contain selected graph facts and bounded content.
|
||||
They contain no live project object, database handle, absolute project or index path, arbitrary
|
||||
query, command, executable path, or caller-selected module.
|
||||
|
||||
Projection packages bind one plan to inert assets, a closed built-in renderer identity, declared
|
||||
component versions, and an artifact inventory with a byte allowance. Receipts bind the exact
|
||||
package, plan, renderer, artifact hashes and sizes, diagnostics, timing, and detached peak memory.
|
||||
Manual and graph renderer modules accept only validated packages. They cannot select nodes, invent
|
||||
relationships, read project state, choose publication paths, or write canonical files.
|
||||
|
||||
Detached execution uses one fixed private Python module, isolated mode, a trusted working
|
||||
directory, a sanitized environment, exactly one canonical newline-terminated JSON request and
|
||||
response, a closed renderer allowlist, a 30-second timeout, disk-spooled stdout, and bounded reads. The package
|
||||
contract is capped at 24,000,000 bytes and actual detached artifact transfer at 20,000,000 bytes.
|
||||
Project descriptors may retain a larger `max_render_bytes` compatibility allowance, but an actual
|
||||
detached transfer above the fixed worker boundary fails closed.
|
||||
|
||||
Portable graph configuration is independent of manual render configuration. One view selects
|
||||
either an exact root or a bounded metadata-only lexical query plus closed filters and node, edge,
|
||||
depth, and work limits. Logic is excluded. The renderer emits a complete static Nodes, Flow, or Web
|
||||
artifact and uses JavaScript only as progressive enhancement.
|
||||
|
||||
Portable publication commits a content-addressed artifact, renderer receipt, and one bounded
|
||||
generation/view manifest in that order. The manifest is the publication commit. Status reads only
|
||||
bounded manifest and receipt evidence and never plans or renders. Repair restores declared output
|
||||
only from validated content-addressed evidence. A failure after a replacement that cannot be
|
||||
proven rolled back returns explicit degraded committed evidence.
|
||||
|
||||
Manual fragment records are disposable semantic cache entries. Their keys bind the renderer,
|
||||
component version, and complete page semantics. The detached renderer recomputes the expected page
|
||||
fragment before accepting cached bytes. Cold creation is compared with a full detached render
|
||||
before cache publication. Invalid, corrupt, forged, stale, individually oversized, or
|
||||
aggregate-oversized records fall back to the full oracle. The dedicated cache retains only current
|
||||
keys and is capped at 10,000 entries and 64,000,000 bytes.
|
||||
|
||||
Projection policy version 2 composes manual `auto|explicit|disabled`, portable graph
|
||||
`explicit|disabled`, and live viewer `on-demand|disabled` independently. Active plan, render,
|
||||
application, onboarding, and viewer-start operations enforce the relevant policy before hidden
|
||||
work. Receipt-only status and explicit viewer stop remain available. Effective policy version 1
|
||||
and its legacy projections remain unchanged.
|
||||
|
||||
The live viewer remains separate from portable graph publication. It consumes one
|
||||
generation-pinned validated index through the viewer manager. Source reads come from that pinned
|
||||
generation and do not reopen mutable canonical files behind an older snapshot. Neither live nor
|
||||
portable visualization is retrieval or canonical authority.
|
||||
|
||||
Normal MCP access does not expose canonical application. An explicitly configured canonical
|
||||
applier registers one hash-bound application tool. No MCP mode exposes arbitrary renderer
|
||||
execution, arbitrary file writes, shell commands, Git mutation, build commands, deployment, or
|
||||
|
|
|
|||
90
docs/MILESTONE_3_BASELINE.md
Normal file
90
docs/MILESTONE_3_BASELINE.md
Normal file
|
|
@ -0,0 +1,90 @@
|
|||
# Milestone 3 baseline
|
||||
|
||||
## Scope and method
|
||||
|
||||
This baseline records the independent-projection behavior completed in Milestone 3. It was
|
||||
captured on 2026-07-29 from clean candidate commit
|
||||
`f5dccb5e1c312121f1af63780162f593d9363b98`.
|
||||
|
||||
The maintained command was:
|
||||
|
||||
```bash
|
||||
.venv/bin/python tools/milestone3_benchmark.py \
|
||||
--mode full \
|
||||
--nodes 1000 \
|
||||
--samples 10 \
|
||||
--output benchmarks/milestone3-2026-07-29.json
|
||||
```
|
||||
|
||||
The synthetic generic fixture contains 1,000 manual pages, 1,000 portable-graph nodes, and 999
|
||||
edges. Durations use `time.perf_counter_ns()` and nearest-rank p95. In-process peak memory uses
|
||||
`tracemalloc`; detached worker peak memory comes from the worker receipt and `RUSAGE_SELF`.
|
||||
Every measured result is checked for deterministic semantic identity and bounded response size.
|
||||
|
||||
Environment:
|
||||
|
||||
- Linux 7.1.3-200.nobara.fc44.x86_64.
|
||||
- CPython 3.14.6.
|
||||
- x86_64.
|
||||
- Ten samples except the one-time production cold render and fragment-cache population.
|
||||
- In-process and detached-worker memory ceiling: 268,435,456 bytes.
|
||||
- Detached artifact-transfer ceiling: 20,000,000 bytes.
|
||||
|
||||
The complete machine-readable result is
|
||||
[`benchmarks/milestone3-2026-07-29.json`](../benchmarks/milestone3-2026-07-29.json).
|
||||
|
||||
## Results
|
||||
|
||||
| Operation | Median | p95 | Limit | Maximum response |
|
||||
|---|---:|---:|---:|---:|
|
||||
| Manual full plan/package/render | 801.948 ms | 810.490 ms | 15,000 ms | 664 B |
|
||||
| Manual detached worker | 591.317 ms | 599.394 ms | 20,000 ms | 667 B |
|
||||
| Fragment-assisted equivalence | 638.999 ms | 666.119 ms | 15,000 ms | 664 B |
|
||||
| Production incremental cold | 2,827.152 ms | 2,827.152 ms | 20,000 ms | 668 B |
|
||||
| Production incremental warm | 2,143.388 ms | 2,206.540 ms | 20,000 ms | 669 B |
|
||||
| Production forced full | 944.135 ms | 978.870 ms | 20,000 ms | 668 B |
|
||||
| Fragment cache miss sweep | 106.203 ms | 106.888 ms | 5,000 ms | 145 B |
|
||||
| Fragment cache hit sweep | 498.911 ms | 514.324 ms | 5,000 ms | 145 B |
|
||||
| Portable graph full plan/package/render | 303.736 ms | 323.690 ms | 10,000 ms | 657 B |
|
||||
| Portable graph detached worker | 265.448 ms | 268.428 ms | 20,000 ms | 660 B |
|
||||
| Manual receipt-only status | 62.881 ms | 111.381 ms | 500 ms | 1,542 B |
|
||||
| Portable graph receipt-only status | 58.467 ms | 59.331 ms | 500 ms | 879 B |
|
||||
|
||||
The largest traced in-process peak was 35,160,716 bytes. The direct manual worker track peaked at
|
||||
88,580,096 bytes and the portable graph worker at 89,583,616 bytes. The production manual paths,
|
||||
including cold, warm, forced-full, and mutation variants, peaked at 104,771,584 bytes. Every child
|
||||
peak was validated from its projection receipt against the 268,435,456-byte gate.
|
||||
|
||||
The manual artifact was 583,149 bytes. The portable graph artifact was 718,383 bytes. The manual
|
||||
plan was 1,006,393 bytes and its ordinary package was 1,007,297 bytes. The graph plan was 398,158
|
||||
bytes and its package was 398,715 bytes.
|
||||
|
||||
## Equivalence and no-work gates
|
||||
|
||||
The benchmark proved exact output equivalence for:
|
||||
|
||||
- Manual in-process and detached rendering.
|
||||
- Manual full and fragment-assisted rendering.
|
||||
- Production cold, warm, and forced-full rendering.
|
||||
- Production add, change, delete, and reorder variants.
|
||||
- Portable graph in-process and detached rendering.
|
||||
|
||||
Manual and portable-graph status each performed zero project loads, source parses, adapter
|
||||
projection loads, adapter extraction, index checks, synchronization, index builds, render
|
||||
preparation, output construction, output hashing, and viewer-manager requests. Each status path
|
||||
performed only two cheap source-generation checks and verified committed receipt or manifest
|
||||
evidence.
|
||||
|
||||
## Measured limits and future notes
|
||||
|
||||
- Fragment reuse is a correctness, isolation, and recovery boundary in this milestone. At 1,000
|
||||
pages, production warm fragment validation is slower than the forced-full path. Later
|
||||
optimization must start from this measurement and preserve byte equivalence.
|
||||
- Full rendering remains the oracle and recovery path. Invalid, corrupt, oversized, stale, or
|
||||
mismatched fragment records fall back without changing canonical facts.
|
||||
- The benchmark main-process `ru_maxrss` value was 102,692 KiB. It is cumulative across all
|
||||
main-process operations and is recorded only as diagnostic context. Detached child peaks are
|
||||
measured separately. Per-operation traced peaks and every detached receipt peak own the memory
|
||||
gates.
|
||||
- The results do not justify a storage rewrite, render farm, remote renderer, or separate render
|
||||
MCP.
|
||||
89
docs/MILESTONE_3_CLOSEOUT.md
Normal file
89
docs/MILESTONE_3_CLOSEOUT.md
Normal file
|
|
@ -0,0 +1,89 @@
|
|||
# Milestone 3 closeout
|
||||
|
||||
## Outcome
|
||||
|
||||
Milestone 3 is complete. Manual compilation, portable graph rendering, and the live viewer are
|
||||
separate generation-pinned consumers of the validated graph. They cannot become canonical or
|
||||
retrieval authority.
|
||||
|
||||
Implemented contracts:
|
||||
|
||||
- Version-1 `ManualRenderPlan`, `GraphViewPlan`, projection package, and projection receipt.
|
||||
- Strict canonical JSON identities and packaged Draft 2020-12 schemas.
|
||||
- Independent manual and portable-graph renderer import boundaries.
|
||||
- One isolated, fixed, one-request detached worker protocol with bounded request, response,
|
||||
artifact, timeout, environment, and renderer inventory.
|
||||
- Content-addressed portable graph artifacts, renderer receipts, generation/view manifests,
|
||||
receipt-only status, repair, and degraded committed-publication evidence.
|
||||
- Disposable semantic fragment records with bounded cache inventory, corruption recovery, and
|
||||
full-render equivalence.
|
||||
- Version-2 independent projection policy while preserving version-1 effective-policy behavior.
|
||||
- Generation-pinned live source reads and a separate read-only viewer-manager lifecycle.
|
||||
- Automated axe-tag and keyboard gates for the manual, portable graph, and live viewer.
|
||||
- Repository-native contract, smoke, scale, response-size, memory, and equivalence gates.
|
||||
|
||||
## Candidate evidence
|
||||
|
||||
The frozen implementation candidate is
|
||||
`f5dccb5e1c312121f1af63780162f593d9363b98`.
|
||||
|
||||
The complete repository gate passed:
|
||||
|
||||
- Ruff formatting and lint.
|
||||
- HTML, rendered-manual HTML, portable-graph HTML, CSS, and JavaScript checks.
|
||||
- Pyright with zero diagnostics.
|
||||
- Warning-strict compilation and tests.
|
||||
- 281 tests and 272 subtests.
|
||||
- Three Playwright and axe accessibility flows. The alpha manual is checked with WCAG 2.0/2.1
|
||||
A/AA axe tags; portable and live graph flows add WCAG 2.2 A/AA tags and keyboard interaction.
|
||||
- Lock and npm dependency-tree checks.
|
||||
- Wheel and source-distribution builds.
|
||||
- Milestone 0, 1, 2, and 3 smoke benchmarks.
|
||||
|
||||
The maintained projection contract subset passed 142 tests and 236 subtests. A 10,000-node deep
|
||||
chain and one 10,000-node strongly connected component prove that manual cycle planning has no
|
||||
recursion-depth failure.
|
||||
|
||||
An isolated wheel installation passed CLI and MCP startup, a real detached manual render, and the
|
||||
closed malformed-worker-request contract. Six Milestone 3 commits and the complete candidate tree
|
||||
passed Gitleaks 8.30.1 with no findings.
|
||||
|
||||
Three independent adversarial review tracks covered manual isolation and fragment integrity,
|
||||
portable publication and policy binding, and worker/accessibility/benchmark gates. Reproduced
|
||||
project import, hostile environment, unbounded stdout, fragment forgery, cache growth, aggregate
|
||||
overflow, coordinated policy drift, render-limit compatibility, deep-graph, and module-startup
|
||||
defects were fixed and regression-tested before closeout.
|
||||
|
||||
The clean ten-sample 1,000-node benchmark passed every threshold. Exact measurements, equivalence
|
||||
results, memory peaks, and response sizes are recorded in
|
||||
[`MILESTONE_3_BASELINE.md`](MILESTONE_3_BASELINE.md) and
|
||||
[`benchmarks/milestone3-2026-07-29.json`](../benchmarks/milestone3-2026-07-29.json).
|
||||
|
||||
## Preserved boundaries
|
||||
|
||||
- The `docforge` distribution, package, CLI, MCP executable, and existing tool names remain.
|
||||
- The frozen alpha manual remains exactly 2,043 bytes with its legacy output hash and render
|
||||
identity.
|
||||
- Legacy one-method `load_projection()` adapters remain supported.
|
||||
- Effective policy version 1, no-AST behavior, and existing client bindings remain compatible.
|
||||
- Project descriptor schema version 1 and SQLite index schema version 3 remain unchanged.
|
||||
- Configured `max_render_bytes` values above the detached transfer ceiling still load; a small
|
||||
actual artifact renders normally. Actual detached transfer remains capped at 20,000,000 bytes.
|
||||
- No storage replacement or self-hosting dependency was introduced.
|
||||
- WorldForge and ScrapeStation were not touched.
|
||||
- No production MCP integration was repointed.
|
||||
- The legacy Forgejo repository and `legacy` remote were not changed.
|
||||
- No tag, release, release announcement, or visibility change was created.
|
||||
|
||||
## Known follow-up work
|
||||
|
||||
Milestone 4 remains directional and is not active. Its adapter SDK and product-documentation work
|
||||
must not silently absorb these separate future ideas:
|
||||
|
||||
- Optimize production fragment reuse only from measured profiles while preserving the forced-full
|
||||
oracle.
|
||||
- Add authenticated cursors only if a stronger threat model requires them.
|
||||
- Verify Claude's native timeout representation.
|
||||
- Add versioned adapter-owned launcher metadata before generating custom-adapter configurations.
|
||||
- Keep remote render services, shared render farms, third-party renderers, storage replacement,
|
||||
and self-hosting deferred until their own evidence justifies them.
|
||||
|
|
@ -27,6 +27,10 @@ incremental methods while retaining the full loader as a fallback.
|
|||
- Opt-in incremental adapter extraction with reverse-dependency invalidation.
|
||||
- Lazy function-scoped logic projections that do not densify the primary graph.
|
||||
- Declared HTML render views. Arbitrary templates, render commands, and output paths are rejected.
|
||||
- Separate versioned manual and portable graph plans, immutable packages, detached built-in
|
||||
renderers, and validated receipts.
|
||||
- Content-addressed portable Nodes/Flow/Web artifacts with receipt-only status and repair.
|
||||
- Independent manual, portable-graph, and live-viewer policy.
|
||||
- A loopback-only graph browser with Nodes, semantic Flow, and convergence Web views,
|
||||
relationship keys, source inspection, branch-aware node hiding, panel resizing, zooming, and
|
||||
managed idle shutdown.
|
||||
|
|
@ -47,7 +51,11 @@ Canonical files own facts:
|
|||
canonical Markdown/TOML or adapter sources
|
||||
↓ validate
|
||||
disposable SQLite graph
|
||||
↓ query / visualize / compile context
|
||||
├── query / compile context
|
||||
├── ManualRenderPlanV1 → detached manual renderer → declared manual
|
||||
├── GraphViewPlanV1 → detached graph renderer → portable Nodes/Flow/Web artifact
|
||||
└── pinned index → managed live Nodes/Flow/Web/Logic viewer
|
||||
↓
|
||||
people and agents
|
||||
↓ propose
|
||||
isolated changeset + preview
|
||||
|
|
@ -77,8 +85,8 @@ source format.
|
|||
Clone and verify DocForge:
|
||||
|
||||
```bash
|
||||
git clone forgejo@repo.andraxion.net:administrator/DocForge.git /absolute/path/DocForge
|
||||
cd /absolute/path/DocForge
|
||||
git clone forgejo@repo.andraxion.net:administrator/DocForge2.git /absolute/path/DocForge2
|
||||
cd /absolute/path/DocForge2
|
||||
uv sync --group dev
|
||||
npm ci
|
||||
|
||||
|
|
@ -159,6 +167,27 @@ output = "Docs/Rendered/Manual.html"
|
|||
title = "My Project Manual"
|
||||
families = ["architecture", "system", "operations", "roadmap"]
|
||||
|
||||
[graph_render]
|
||||
output_root = ".docforge/portable-graph"
|
||||
|
||||
[[graph_render.views]]
|
||||
id = "architecture"
|
||||
renderer = "portable_graph_html"
|
||||
output = "architecture.html"
|
||||
title = "Architecture"
|
||||
root = "architecture.overview"
|
||||
initial_mode = "web"
|
||||
depth = 3
|
||||
max_nodes = 250
|
||||
max_edges = 1000
|
||||
max_work = 100000
|
||||
families = ["architecture", "system"]
|
||||
relations = ["depends_on", "owns", "calls", "reads", "writes", "tested_by", "relates_to"]
|
||||
authorities = []
|
||||
statuses = ["current", "active", "verified"]
|
||||
tags = []
|
||||
include_logic = false
|
||||
|
||||
[graph]
|
||||
allowed_relations = ["depends_on", "owns", "calls", "reads", "writes", "tested_by", "relates_to"]
|
||||
|
||||
|
|
@ -492,13 +521,25 @@ builds or repairs the index.
|
|||
```text
|
||||
render-status [VIEW_ID] [--deep]
|
||||
render VIEW_ID
|
||||
graph-plan VIEW_ID
|
||||
graph-render VIEW_ID
|
||||
graph-render-status [VIEW_ID]
|
||||
preview CHANGESET_ID VIEW_ID
|
||||
apply CHANGESET_ID --changeset-hash SHA256 --applier WRITER_ID
|
||||
```
|
||||
|
||||
`graph-plan` validates and returns one declared `GraphViewPlanV1` without publishing. A portable
|
||||
view must select exactly one stable `root` or metadata-only lexical `query`. It may use only Nodes,
|
||||
Flow, or Web as `initial_mode`; portable version 1 excludes function-scoped Logic.
|
||||
|
||||
`graph-render` explicitly publishes the declared static artifact, content-addressed renderer
|
||||
evidence, and generation/view manifest. `graph-render-status` verifies only bounded committed
|
||||
evidence and never plans or renders. Portable publication is a local CLI action.
|
||||
|
||||
The CLI apply command supports the generic adapter. It verifies that the configured writer owns the
|
||||
changeset, applies the exact reviewed hash, rebuilds the index, checks it, and regenerates every
|
||||
declared render. It does not commit or push the result.
|
||||
declared manual render when manual policy is `auto`. It does not publish portable graphs, commit,
|
||||
or push the result.
|
||||
|
||||
### Viewer commands
|
||||
|
||||
|
|
@ -549,6 +590,20 @@ declares the named writer, and application requires the same writer/applier iden
|
|||
`--no-ast` to preserve the no-AST binding. Generic CLI generation refuses project-owned adapters
|
||||
because it cannot safely reconstruct their composition.
|
||||
|
||||
Select projection behavior independently:
|
||||
|
||||
```bash
|
||||
docforge configure codex \
|
||||
--project /absolute/path/MyProject \
|
||||
--manual-render-policy explicit \
|
||||
--portable-graph-policy disabled \
|
||||
--live-viewer-policy on-demand
|
||||
```
|
||||
|
||||
The generated version-1 configuration result carries an additive version-2 `projection_policy`,
|
||||
its hash, projection availability, and the exact descriptor hash. Omitted default selectors are
|
||||
validated against that descriptor rather than trusted as self-reported output.
|
||||
|
||||
Inspect one configured client binding:
|
||||
|
||||
```bash
|
||||
|
|
@ -569,6 +624,54 @@ starts MCP, executes the configured command, synchronizes, builds, renders, star
|
|||
writes configuration. Claude timeout representation and client filtering that cannot be proved
|
||||
locally remain explicit warnings.
|
||||
|
||||
## Independent projection behavior
|
||||
|
||||
Manual and portable graph renderers consume immutable, path-free packages. A package binds one
|
||||
generation-pinned plan, inert assets, fixed component versions, a built-in renderer identity, and
|
||||
an exact artifact inventory. The detached child cannot select nodes, open the project or index,
|
||||
choose a publication path, execute project code, or mutate canonical facts.
|
||||
|
||||
Child startup is fixed to isolated Python, a private module entrypoint, a trusted working
|
||||
directory, and a sanitized environment. One request and response use canonical newline-terminated
|
||||
JSON. The request, response, receipt, execution time, and disk-spooled stdout are bounded. Actual
|
||||
artifact transfer is capped at 20,000,000 bytes even when the descriptor retains a larger
|
||||
`max_render_bytes` compatibility value.
|
||||
|
||||
Manual fragment records are disposable semantic cache entries. On a cold miss, DocForge performs a
|
||||
trusted full detached render, extracts candidate page fragments, and compares fragment-assisted
|
||||
output byte-for-byte before publishing records. On a warm hit, the worker recomputes each expected
|
||||
page fragment before accepting cached bytes. Corrupt, forged, stale, individually oversized, or
|
||||
aggregate-oversized records fall back to the full oracle. Fragment reuse is currently a correctness
|
||||
and recovery boundary, not a promised speedup.
|
||||
|
||||
Projection policy version 2 is:
|
||||
|
||||
```text
|
||||
manual: auto | explicit | disabled
|
||||
portable_graph: explicit | disabled
|
||||
live_viewer: on-demand | disabled
|
||||
```
|
||||
|
||||
For ordinary CLI commands, place the corresponding global flag before the subcommand:
|
||||
|
||||
```bash
|
||||
docforge --project-root "$PROJECT" --manual-render-policy disabled render manual
|
||||
docforge --project-root "$PROJECT" --portable-graph-policy disabled graph-plan architecture
|
||||
docforge --project-root "$PROJECT" --live-viewer-policy disabled visualize
|
||||
```
|
||||
|
||||
An active operation blocked by policy returns `projection_policy_forbids_operation` before hidden
|
||||
work. Manual and portable receipt-only status remain available. Viewer status and explicit stop
|
||||
remain available when viewer start is disabled.
|
||||
|
||||
A non-disabled projection also requires its declared configuration or runtime. Manual `explicit`
|
||||
requires manual render configuration. Manual `auto` additionally requires canonical application in
|
||||
the current operation or server capability. Portable graph `explicit` requires portable graph
|
||||
render configuration, and live viewer `on-demand` requires its runtime. An unavailable selection
|
||||
returns `projection_policy_unavailable` before work begins. In particular, ordinary CLI `render`
|
||||
operations cannot select manual `auto`; use `explicit`, or let a configured canonical `apply`
|
||||
operation own automatic regeneration.
|
||||
|
||||
## MCP usage
|
||||
|
||||
Run one MCP server per project with absolute paths:
|
||||
|
|
@ -586,7 +689,10 @@ Select the session's declared surface explicitly when useful:
|
|||
```bash
|
||||
docforge-mcp \
|
||||
--project-root /absolute/path/MyProject \
|
||||
--capability-mode read
|
||||
--capability-mode read \
|
||||
--manual-render-policy explicit \
|
||||
--portable-graph-policy explicit \
|
||||
--live-viewer-policy on-demand
|
||||
```
|
||||
|
||||
Supported modes are `read`, `proposal`, `application`, and `operator`. Existing startup defaults
|
||||
|
|
@ -613,8 +719,9 @@ identity, not a command. The changeset creator, configured writer, and canonical
|
|||
|
||||
Call `docforge_bootstrap` first. Its version-1 `session_contract` contains the fixed binding,
|
||||
current graph generation, effective policy, actual capabilities, render policies, prohibitions,
|
||||
and a recommended first operation. Workflow guidance does not recommend registration or
|
||||
application when those startup capabilities are unavailable.
|
||||
and a recommended first operation. The result also carries the independently composed version-2
|
||||
`projection_policy` and hash. Workflow guidance does not recommend registration or application
|
||||
when those startup capabilities are unavailable.
|
||||
|
||||
Example MCP client configuration:
|
||||
|
||||
|
|
@ -653,11 +760,16 @@ Example MCP client configuration:
|
|||
- `docforge_get_task_context`
|
||||
- `docforge_validate_project`
|
||||
- `docforge_render_status`
|
||||
- `docforge_graph_plan`
|
||||
- `docforge_graph_render_status`
|
||||
- `docforge_visualize`
|
||||
- `docforge_visualization_status`
|
||||
- `docforge_stop_visualization`
|
||||
- `docforge_get_generation_diff`
|
||||
|
||||
MCP graph plan and status are read-only. MCP does not expose portable graph publication; use the
|
||||
explicit local `graph-render` CLI command.
|
||||
|
||||
### Proposal tools
|
||||
|
||||
- `docforge_create_changeset`
|
||||
|
|
@ -976,8 +1088,29 @@ docforge --project-root "$PROJECT" render-status
|
|||
docforge --project-root "$PROJECT" render VIEW_ID
|
||||
```
|
||||
|
||||
Successful canonical apply regenerates all declared views automatically. A manual canonical edit
|
||||
requires reindexing and rendering.
|
||||
Successful canonical apply regenerates declared manual views only when manual policy is `auto`.
|
||||
A manual canonical edit requires reindexing and explicit rendering. Portable graph publication
|
||||
always remains a separate explicit CLI action.
|
||||
|
||||
Portable graph publication has separate status and policy:
|
||||
|
||||
```bash
|
||||
docforge --project-root "$PROJECT" graph-render-status
|
||||
docforge --project-root "$PROJECT" graph-render architecture
|
||||
```
|
||||
|
||||
### `projection_policy_forbids_operation`
|
||||
|
||||
The process was deliberately started with the relevant manual, portable-graph, or live-viewer
|
||||
operation disabled. Restart with an allowed selector after confirming that the integration should
|
||||
receive that capability. Status and explicit stop operations remain available as described above.
|
||||
|
||||
### `projection_policy_unavailable`
|
||||
|
||||
The selected non-disabled projection has no matching project configuration or runtime. Add the
|
||||
declared manual or portable graph render configuration, or make the live viewer runtime available,
|
||||
before selecting that mode. Manual `auto` also requires an operation or MCP server with canonical
|
||||
application enabled. Use manual `explicit` for a standalone CLI render.
|
||||
|
||||
### Descriptor changed after startup
|
||||
|
||||
|
|
@ -992,8 +1125,11 @@ Run the complete release gate from the DocForge repository:
|
|||
make gate
|
||||
```
|
||||
|
||||
Use `make benchmark` for the historical Milestone 0 baseline and `make benchmark-m1` for the
|
||||
counter-gated 1,000-node warm-operation benchmark.
|
||||
Use `make benchmark` for the historical Milestone 0 baseline, `make benchmark-m1` for the
|
||||
counter-gated warm-operation benchmark, `make benchmark-m2` for agent workflow gates, and
|
||||
`make benchmark-m3-full` for the ten-sample 1,000-node projection, worker, fragment, status,
|
||||
equivalence, response-size, and memory gates. `make accessibility` runs the generated manual,
|
||||
portable graph, and live viewer axe and keyboard flows.
|
||||
|
||||
Project-specific vocabulary, extraction rules, and serialization belong in the project adapter.
|
||||
Generic core behavior must remain deterministic, project-bound, and recoverable.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue