203 lines
7.8 KiB
Markdown
203 lines
7.8 KiB
Markdown
# Policy precedence
|
|
|
|
DocForge composes an immutable effective policy for each project-bound process. It resolves
|
|
restrictions in a fixed order:
|
|
|
|
```text
|
|
core safety
|
|
> explicit binding
|
|
> no-AST shorthand
|
|
> resource availability
|
|
```
|
|
|
|
A lower layer can make a requested operation unavailable; it cannot override a higher-layer
|
|
prohibition. Bootstrap and generated client evidence report the composed result and hashes so a
|
|
client does not need to infer policy from command-line arguments.
|
|
|
|
## 1. Core safety
|
|
|
|
Core safety is unconditional. No capability mode exposes:
|
|
|
|
- arbitrary file access or project switching;
|
|
- arbitrary renderer, module, command, shell, argument, working-directory, or environment
|
|
selection;
|
|
- Git mutation;
|
|
- project builds or compiler execution;
|
|
- deployment or publication.
|
|
|
|
Canonical application is limited to DocForge's validated serializer boundary. Adapter launch is
|
|
limited to the immutable launcher contract. Rendering is limited to declared views and fixed
|
|
built-in workers. An indexed instruction cannot alter any of these rules.
|
|
|
|
## 2. Explicit binding
|
|
|
|
A process is bound at startup to one project root, descriptor, adapter, capability mode, writer and
|
|
applier identities when present, no-AST selection, diagnostics selection, and projection modes.
|
|
The binding does not change during the process lifetime.
|
|
|
|
Capability modes are:
|
|
|
|
- `read`: register only the read surface;
|
|
- `proposal`: add proposal tools when a valid selected writer is available;
|
|
- `application`: require a startup-bound canonical applier and expose exact-hash application;
|
|
- `operator`: reserved; it currently adds no tools.
|
|
|
|
Mode describes the maximum registered surface. Actual authority can be narrower. A descriptor must
|
|
declare the selected writer, including allowed families and operation types. Application defaults
|
|
to a matching configured writer, changeset creator, and canonical-applier identity. A project-owned
|
|
server may explicitly authorize its applier to accept changesets from additional configured writers.
|
|
A mode name cannot create a missing descriptor grant or extend that accepted-writer allowlist.
|
|
|
|
Generic generated client fragments default to read mode. Other construction paths preserve their
|
|
documented compatible factory defaults. Treat `docforge_bootstrap.session_contract` and its actual
|
|
capabilities as authoritative for a running server.
|
|
|
|
## 3. No-AST shorthand
|
|
|
|
`--no-ast` is a restrictive compatibility shorthand. It composes:
|
|
|
|
- adapter evolution `preserve`;
|
|
- AST analysis `forbidden`;
|
|
- Logic indexing `off`;
|
|
- `docforge_get_logic` blocked;
|
|
- prohibitions on AST, Tree-sitter, compiler-AST, and function-Logic upgrades.
|
|
|
|
Non-AST source fingerprinting and incremental caching remain allowed. Existing one-method adapters
|
|
continue to use `load_projection()`.
|
|
|
|
The shorthand does not inspect how an existing adapter was implemented, sandbox its filesystem
|
|
reads, or transform an AST-based adapter into a no-AST adapter. Do not run the Python,
|
|
JavaScript/TypeScript, or C++ syntax reference integrations and then describe the binding as a
|
|
proved no-AST integration. See [Legacy and no-AST operation](LEGACY_AND_NO_AST.md).
|
|
|
|
## 4. Resource availability
|
|
|
|
Even an allowed policy cannot create a missing resource:
|
|
|
|
- application mode requires a startup-bound canonical applier;
|
|
- manual `explicit` or `auto` requires declared manual render configuration;
|
|
- manual `auto` also requires canonical application in the current operation or server;
|
|
- portable graph `explicit` requires declared portable graph configuration;
|
|
- live viewer `on-demand` requires the viewer runtime;
|
|
- an optional reference language requires its installed extra;
|
|
- a project-owned launcher module must be installed, isolated, project-owned, and unchanged.
|
|
|
|
Unavailable requested modes fail before hidden work. Missing optional language grammars return an
|
|
actionable install target such as `docforge[typescript]` or `docforge[cpp]`; DocForge does not
|
|
silently downgrade to a different frontend.
|
|
|
|
## Effective process policy
|
|
|
|
The version-1 effective policy reports:
|
|
|
|
- capability mode and whether it came from a factory default or explicit selection;
|
|
- adapter evolution, AST analysis, and Logic indexing;
|
|
- automatic synchronization and validated integrity;
|
|
- the compatible manual-render projection;
|
|
- profiling state;
|
|
- blocked tools and prohibitions;
|
|
- the exact precedence list.
|
|
|
|
This version-1 projection preserves compatibility. It is not the complete version-2 rendering
|
|
policy; portable graph and live-viewer choices are reported separately.
|
|
|
|
## Independent projection policy
|
|
|
|
Manual rendering, portable graph publication, and live visualization use a separate immutable
|
|
version-2 policy:
|
|
|
|
```text
|
|
manual: auto | explicit | disabled
|
|
portable_graph: explicit | disabled
|
|
live_viewer: on-demand | disabled
|
|
```
|
|
|
|
When a selector is omitted, composition uses availability-aware defaults:
|
|
|
|
- manual is `auto` only when manual configuration and canonical application are both available;
|
|
otherwise it is `explicit` when configured, or `disabled`;
|
|
- portable graph is `explicit` when configured, otherwise `disabled`;
|
|
- live viewer is `on-demand` when the runtime is available, otherwise `disabled`.
|
|
|
|
An explicit non-disabled selection for a missing resource returns
|
|
`projection_policy_unavailable`. An active operation prohibited by the selected policy returns
|
|
`projection_policy_forbids_operation` before planning, rendering, or viewer startup.
|
|
|
|
Status remains intentionally narrower than active work. Manual and portable receipt-only status
|
|
are available when their active operations are disabled. Viewer status and explicit stop remain
|
|
available when viewer start is disabled.
|
|
|
|
Ordinary standalone CLI rendering uses manual `explicit`. Manual `auto` belongs to a canonical
|
|
application operation that owns automatic regeneration.
|
|
|
|
## Diagnostics do not grant authority
|
|
|
|
`--diagnostics` enables bounded request-local stage timings and compiler-work counters. It does not
|
|
enable tools, broaden paths, retain project content, or displace a primary MCP result that already
|
|
needs the response budget.
|
|
|
|
## Descriptor policy and process policy
|
|
|
|
The project descriptor is canonical project configuration. The process policy is a runtime
|
|
restriction. They compose by intersection:
|
|
|
|
```text
|
|
operation is available
|
|
only if core permits it
|
|
and the startup binding registers it
|
|
and no-AST permits it
|
|
and required resources exist
|
|
and the descriptor grants the requested project authority
|
|
and current graph/hash preconditions validate
|
|
```
|
|
|
|
Changing a descriptor does not retarget a running project-owned process. Descriptor, adapter
|
|
implementation, or launcher drift requires a fresh process.
|
|
|
|
## Common decisions
|
|
|
|
For an agent that only reads documentation:
|
|
|
|
```bash
|
|
docforge-mcp \
|
|
--project-root /absolute/path/MyProject \
|
|
--capability-mode read
|
|
```
|
|
|
|
For an agent that may prepare reviewable proposals:
|
|
|
|
```bash
|
|
docforge-mcp \
|
|
--project-root /absolute/path/MyProject \
|
|
--capability-mode proposal \
|
|
--proposal-writer project-editor
|
|
```
|
|
|
|
For a tightly controlled application process:
|
|
|
|
```bash
|
|
docforge-mcp \
|
|
--project-root /absolute/path/MyProject \
|
|
--capability-mode application \
|
|
--proposal-writer project-editor \
|
|
--canonical-applier project-editor
|
|
```
|
|
|
|
For a read binding with every active output projection disabled:
|
|
|
|
```bash
|
|
docforge-mcp \
|
|
--project-root /absolute/path/MyProject \
|
|
--capability-mode read \
|
|
--manual-render-policy disabled \
|
|
--portable-graph-policy disabled \
|
|
--live-viewer-policy disabled
|
|
```
|
|
|
|
Prefer the narrowest binding that completes the workflow. Call `docforge_bootstrap` first and use
|
|
the returned effective policy, projection policy, actual capabilities, and prohibitions rather
|
|
than assumptions based on client configuration.
|
|
|
|
See the [MCP contract](MCP_CONTRACT.md), [Security](SECURITY.md), [Project
|
|
descriptor](PROJECT_DESCRIPTOR.md), and [Rendering and
|
|
visualization](RENDERING_AND_VISUALIZATION.md).
|