You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
DocGen 2 treats provider output as untrusted and prevents providers from becoming repository scanners. Deterministic code owns source access, indexing, retrieval, validation, budgets, rendering of low-risk references, and most auditing.
3
+
DocGen 2 is a language-, framework-, and architecture-neutral documentation pipeline. It treats provider output as untrusted. Deterministic code owns source eligibility, indexing, retrieval, budgets, checkpoints, artifact validation, low-risk rendering, quality gates, and publishing. Providers receive bounded context packs rather than unrestricted repository access.
4
4
5
5
## Boundary matrix
6
6
@@ -9,53 +9,84 @@ DocGen 2 treats provider output as untrusted and prevents providers from becomin
-`flows.json`: business, control, request, traffic, data, and event flows;
47
-
-`catalogs.json`: endpoints, message handlers, dependencies, data stores, scheduled jobs.
48
-
49
-
## Enterprise model surfaces
50
-
51
-
-`security.json`
52
-
-`operations.json`
53
-
-`testing.json`
54
-
-`data-governance.json`
55
-
-`decisions.json`
56
-
-`configuration.json`
57
-
-`change-impact.json`
58
-
-`ownership.json`
27
+
1.**Technology neutrality** — no language, framework, protocol, datastore, messaging system, deployment model, or repository shape is assumed. Applications, libraries, CLIs, jobs, plugins, infrastructure, data pipelines, embedded systems, monoliths, services, and mixed workspaces are all valid inputs.
28
+
2.**Canonical source boundary** — Git-aware discovery or filesystem fallback, `.gitignore`, `.docgenignore`, binary signatures, UTF-8 checks, and size limits are applied before indexing.
29
+
3.**One index phase per full run** — `docgen all` indexes once, then all later phases consume that inventory and semantic database.
30
+
4.**Context-only provider** — provider work is bounded by declared context packs and explicit output contracts; prompts must not perform broad repository scans.
31
+
5.**Bounded context** — every pack has a token budget and records omitted facts and model items.
32
+
6.**Content addressing** — contexts, stages, pages, traces, audits, and publishing are reusable only while their source, model, input, and artifact hashes remain current.
33
+
7.**Crash-safe page checkpoints** — page state records running, completed, and failed work. A failed generation batch preserves valid pages and retries only missing or invalid pages.
34
+
8.**Fresh-artifact recovery** — a provider non-zero exit may be recovered only when the current invocation produced artifacts that pass the complete output contract. Pre-existing stale artifacts are never accepted as recovery proof.
35
+
9.**Effective provider configuration** — every call records and prints the executable, model, effective `maxTurns`, timeout, context size, and log files. The supported minimum conversation-turn budget is 30.
36
+
10.**Hard provider budget** — a call is refused before execution when configured call, token, or per-call limits would be exceeded.
37
+
11.**Typed semantic claims** — model items and page claims use `FACT`, `INFERENCE`, `ASSUMPTION`, or `UNKNOWN`, with confidence, evidence, and stable qualified identity.
38
+
12.**Grounded facts** — a `FACT` requires repository-relative evidence inside the canonical inventory. By default it also requires valid line evidence whose source hash still matches the index.
39
+
13.**Context-bound generation** — generated claim evidence and model references must come from the page's supplied context unless explicitly disabled.
40
+
14.**Qualified model identity** — references use `<model>:<semantic-id>` to prevent collisions and permit deterministic validation.
41
+
15.**Deterministic references where possible** — generic components, interfaces, dependencies, data assets, automation, configuration, ownership, and change-impact catalogs can be rendered without provider calls.
42
+
16.**Quality before publishing** — publishing requires a current passing audit and revalidates source, model, page, trace, links, evidence, and audit hashes to reject stale output.
43
+
17.**Selective semantic-risk audit** — provider audit is limited to risk-scored pages after deterministic validation and is reused only while its inputs remain unchanged.
44
+
18.**No hidden repair loop** — there is no unbounded enrich/fix/re-audit cycle. Recovery is bounded and checkpointed.
45
+
19.**Mermaid only** — generated diagrams may not depend on PlantUML, Graphviz, or image-only formats.
46
+
20.**Breaking migration boundary** — legacy workflow artifacts are archived rather than interpreted as current checkpoints.
47
+
48
+
## Framework-neutral semantic surfaces
49
+
50
+
The shape is extensible. Technology-specific arrays are optional signals, not requirements.
-`business.json`: actors, capabilities, concepts, rules, decisions, branches, lifecycles, invariants, use cases, and unknowns.
54
+
-`flows.json`: execution, control, request, traffic, data, event, batch, and other evidenced flows.
55
+
-`catalogs.json`: interfaces, contracts, dependencies, data assets, automations, build artifacts, configuration surfaces, plus optional protocol-specific catalogs when present.
56
+
- enterprise models: security, operations, testing, data governance, decisions, configuration, change impact, and ownership.
57
+
58
+
The deterministic index always provides generic file artifacts and source chunks. It may additionally recognize common symbols, functions, imports/modules, manifests, configuration keys, runtime declarations, infrastructure resources, interfaces, data entities, scheduled automation, or security boundaries. Absence of a recognizer never makes a technology unsupported because bounded source chunks remain the fallback evidence surface.
59
+
60
+
## Runtime and resume contract
61
+
62
+
A full run is:
63
+
64
+
```text
65
+
index -> modelCore -> modelEnterprise -> plan -> generate -> audit -> publish
66
+
```
67
+
68
+
`docgen resume` runs the same state-aware pipeline. Completed stages and pages are reused only when their input hashes and required outputs remain valid. During generation:
69
+
70
+
1. each page is marked `running` with batch, context, and input identity;
71
+
2. provider output is validated page-by-page;
72
+
3. valid pages are checkpointed immediately;
73
+
4. failed or missing pages are marked with their error;
74
+
5. bounded recovery retries only the unresolved subset;
75
+
6. a page becomes `completed` only after Markdown and traceability validation succeeds.
76
+
77
+
## Correctness gate
78
+
79
+
The deterministic audit validates, at minimum:
80
+
81
+
- source inventory membership, live-source hash, and evidence line ranges;
82
+
- model JSON validity, qualified identities, classifications, confidence, and FACT evidence;
83
+
- page frontmatter, H1, required sections, Mermaid policy, and local links;
- claim classification, confidence, evidence, context-bound grounding, and model references;
86
+
- missing, duplicate, conflicting, stale, orphaned, or substantially duplicated artifacts;
87
+
- model-reference coverage and configurable warning/failure policy.
88
+
89
+
The detailed report is `.docgen/audit/deterministic.json`. `.docgen/audit/quality-summary.json` is the publish gate and contains aggregate claim, evidence, model-reference, failure, warning, and selective-risk metrics.
The orchestrator fills page/input/context hashes after generation.
116
+
The orchestrator normalizes and verifies page, input, and context hashes after generation.
86
117
87
-
## Workspace contracts
118
+
## Workspace boundary
88
119
89
-
P3 remains deterministic and consumes current repository models plus commit/source/model hashes. Cross-repository edges require explicit repository identity, dependency targets, shared evidenced producer/consumer channels, or model references. Ambiguous relationships remain unresolved.
120
+
Cross-repository synthesis remains deterministic and requires explicit repository identity plus evidenced relationships, declared dependencies, shared producer/consumer contracts, or qualified model references. Ambiguous relationships remain unresolved instead of being inferred from a preferred stack.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments