DocForge2/docs/POLICY_PRECEDENCE.md

Policy precedence

DocForge composes an immutable effective policy for each project-bound process. It resolves restrictions in a fixed order:

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 requires the matching configured writer, changeset creator, and canonical-applier identity. A mode name cannot create a missing descriptor grant.

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.

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:

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:

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:

docforge-mcp \
  --project-root /absolute/path/MyProject \
  --capability-mode read

For an agent that may prepare reviewable proposals:

docforge-mcp \
  --project-root /absolute/path/MyProject \
  --capability-mode proposal \
  --proposal-writer project-editor

For a tightly controlled application process:

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:

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, Security, Project descriptor, and Rendering and visualization.