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
|
|
@ -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