replace v1 contracts with v2 boundaries

Author: fajarnugraha37

global-template/docgen/CONTRACTS.md

@@ -1,85 +1,89 @@
-# DocGen Contract Firewall
+# DocGen 2 contracts
 
-DocGen treats every LLM-produced artifact as untrusted, uncommitted output until it has passed canonicalization and invariant validation.
+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.
 
 ## Boundary matrix
 
-| Stage | Canonical artifact | Canonical arrays/fields |
+| Boundary | Canonical artifact | Owner |
 |---|---|---|
-| discover | `.docgen/evidence/index.json` | `artifacts` |
-| analyze | `.docgen/model/system.json` | `components`, `relationships`, `workflows`, `unknowns` |
-| semantics/business | `.docgen/model/business.json` | `actors`, `capabilities`, `concepts`, `businessRules`, `decisions`, `branchConditions`, `lifecycles`, `invariants`, `useCases`, `unknowns` |
-| semantics/flows | `.docgen/model/flows.json` | `businessFlows`, `controlFlows`, `requestFlows`, `trafficFlows`, `dataFlows`, `eventFlows` |
-| semantics/catalogs | `.docgen/model/catalogs.json` | `endpoints`, `messageHandlers`, `externalDependencies`, `dataStores`, `scheduledJobs` |
-| enterprise/security | `.docgen/model/security.json` | `trustBoundaries`, `principals`, `authenticationFlows`, `authorizationRules`, `permissions`, `serviceIdentities`, `secrets`, `sensitiveData`, `threats`, `controls`, `unknowns` |
-| enterprise/operations | `.docgen/model/operations.json` | runtime, health, observability, SLI/SLO, alerts, capacity, scaling, failures, recovery, backup, deployment, runbooks |
-| enterprise/testing | `.docgen/model/testing.json` | suites, test types, fixtures, test data, environments, commands, gaps, contract tests, failure injection, quality gates |
-| enterprise/data governance | `.docgen/model/data-governance.json` | entities, ownership, sources of truth, classification, retention, transactions, consistency, concurrency, idempotency, reconciliation, lineage, migration, auditability |
-| enterprise/decisions | `.docgen/model/decisions.json` | recorded/inferred decisions, alternatives, trade-offs, constraints, consequences, superseded decisions |
-| enterprise/configuration | `.docgen/model/configuration.json` | settings, environments, flags, secrets, tuning, validation, reload behavior, deprecations |
-| enterprise/change impact | `.docgen/model/change-impact.json` | change surfaces, impact edges, compatibility, extension points, risks, tests, operations and contracts |
-| enterprise/ownership | `.docgen/model/ownership.json` | teams, responsibilities, RACI, component/data/operational ownership, approvals and escalation |
-| plan | `.docgen/plan/manifest.json` | `navigation`, `pages`, canonical `docs/**/*.md` paths |
-| generate/enrich/fix | `docs/**/*.md` | exact manifest target, valid Markdown, Mermaid-only diagrams |
-| page traceability | `.docgen/traceability/pages/<page-id>.json` | typed claims, evidence refs, model/catalog/branch coverage, source snapshot |
-| cross-page consistency | `.docgen/traceability/{index,contradictions,duplicates,freshness}.json` | unique claim IDs, contradiction groups, duplicate groups, freshness |
-| audit | `.docgen/audit/pages/<page-id>.json` | `pageId`, `pagePath`, `pageHash`, `inputHash`, `findings` |
-| update-impact | `.docgen/plan/update-plan.json` | `changedPaths`, `affectedEvidenceScopes`, `affectedModels`, `affectedPageIds`, `rationale` |
-| publishing | `.docgen/publish/*.json`, `docs/llms*.txt`, page frontmatter | mode, aliases, lifecycle/version metadata, search/navigation/backlink/redirect/example indexes |
+| source eligibility | `.docgen/index/inventory.json` | deterministic inventory |
+| searchable knowledge | `.docgen/index/semantic.db` | deterministic indexer |
+| provider input | `.docgen/context/<stage>/*.json` | bounded context compiler |
+| core synthesis | `.docgen/model/{system,business,flows,catalogs}.json` | one bounded provider call + orchestrator validation |
+| enterprise synthesis | `.docgen/model/{security,operations,testing,data-governance,decisions,configuration,change-impact,ownership}.json` | one bounded provider call + orchestrator validation |
+| page plan | `.docgen/plan/manifest.json` | bounded planner + deterministic canonicalization |
+| reference pages | selected `docs/**/*.md` | deterministic renderer |
+| narrative pages | selected `docs/**/*.md` | bounded writer |
+| page claims | `.docgen/traceability/pages/<page-id>.json` | same generation call or deterministic item mapping |
+| structural/grounding audit | `.docgen/audit/deterministic.json` | deterministic auditor |
+| semantic risk audit | `.docgen/audit/llm-risk.json` | selective, hash-cached provider call |
+| quality summary | `.docgen/audit/quality-summary.json` | deterministic aggregator |
+| publishing | `.docgen/publish/*.json`, `docs/llms*.txt` | deterministic publisher |
+| provider usage | `.docgen/telemetry/provider-runs.jsonl`, `.docgen/budget/report.json` | orchestrator |
 
-## Invariants
+## Hard invariants
 
-1. **Single canonical representation** — aliases are removed from committed artifacts.
-2. **Idempotence** — normalizing canonical output again cannot change or duplicate it.
-3. **Losslessness for known split aliases** — producers, consumers and listeners are merged into the complete message-handler catalog.
-4. **Path safety** — evidence remains under `.docgen/evidence/**`; published pages remain under `docs/**/*.md`.
-5. **Identity consistency** — audit page ID/path/hash must match the current manifest/page.
-6. **Input consistency** — generated pages and audits are fingerprinted against their declared evidence/model inputs.
-7. **Transactional stages** — partial output is quarantined and the previous valid artifact restored.
-8. **Dependency invalidation** — rerunning an upstream stage invalidates dependent stage skips.
-9. **Typed semantic items** — each model item has stable ID, kind, epistemic classification, confidence, evidence, and source references.
-10. **Direct evidence for FACT** — FACT items and claims cannot commit without resolvable repository evidence.
-11. **Claim-level traceability** — material page claims map to source and normalized semantic/catalog items.
-12. **Cross-page consistency** — claim ID collisions and subject/predicate contradictions fail quality gates.
-13. **Freshness** — page, input, Git/source fingerprint changes make traceability stale.
-14. **Evidence-centric quality** — grounding and coverage are hard gates; word count is advisory.
-15. **Ignore-aware source boundary** — `.gitignore`, `.docgenignore`, hard exclusions, and project `config.exclude` produce one canonical source inventory used by every stage.
-16. **Ignored evidence rejection** — an ignored path cannot support a typed FACT or page claim.
-17. **Enterprise-depth coverage** — security, operations, testing, data governance, decisions, configuration, change impact, and ownership use typed, evidence-backed item contracts.
-18. **Binary/non-text budget boundary** — binary extensions, magic signatures, NUL bytes, invalid UTF-8, excessive control characters, and oversized text are excluded before reads, fingerprints, change detection, or evidence validation.
-19. **Mode-aware documentation** — every planned page has a canonical document mode and mode-specific structural contract.
-20. **Deterministic publishing** — frontmatter, navigation, search, backlinks, redirects, orphan reports, examples indexes, and `llms*.txt` are produced without a provider call.
-21. **Evidence-derived examples** — publishable examples must map to page claims and source/model references; generic unsupported examples do not satisfy the quality contract.
+1. **Source is indexed once** — provider sessions do not broadly scan repository source.
+2. **Canonical inventory** — `.gitignore`, nested non-Git fallback, `.docgenignore`, binary signatures, UTF-8 checks, and size limits are applied before indexing.
+3. **Context-only provider** — hooks restrict provider reads to declared `.docgen/context/**` packs and stage outputs.
+4. **Bounded context** — each pack has an explicit token budget and reports omitted facts/model items.
+5. **Content addressing** — contexts, stages, pages, and risk audits are reusable only while selected item hashes remain unchanged.
+6. **Hard provider budget** — a call is refused before execution when it would exceed configured call, input-token, output-token, or per-call limits.
+7. **Typed models** — semantic items preserve stable identity, kind, classification, confidence, evidence, and unknowns.
+8. **Direct evidence for FACT** — deterministic audit rejects FACT page claims without evidence or with evidence outside the canonical inventory.
+9. **Qualified model identity** — SQLite item IDs are model-qualified to prevent cross-model collisions.
+10. **Deterministic references** — exhaustive low-risk catalogs are rendered without provider calls.
+11. **Selective audit** — LLM audit runs only for risk-scored pages and only when page/context hashes change.
+12. **No repair loop** — there is no automatic enrich, fix, or full re-audit cycle.
+13. **No parent delegation** — provider prompts complete their bounded task directly and do not load agent/skill trees.
+14. **Mermaid only** — published diagrams may not use PlantUML, Graphviz, or image-only diagrams.
+15. **Breaking migration** — v1 workflow artifacts are archived, not interpreted as v2 checkpoints.
 
-Run the zero-token suite with:
+## Core model surfaces
 
-```bash
-docgen contract-test
-```
+- `system.json`: components, relationships, workflows, unknowns;
+- `business.json`: actors, capabilities, concepts, rules, decisions, branches, lifecycles, invariants, use cases, unknowns;
+- `flows.json`: business, control, request, traffic, data, and event flows;
+- `catalogs.json`: endpoints, message handlers, dependencies, data stores, scheduled jobs.
 
-The machine-readable report is written to `.docgen/state/contract-report.json`.
+## Enterprise model surfaces
 
-## Trustworthiness reports
+- `security.json`
+- `operations.json`
+- `testing.json`
+- `data-governance.json`
+- `decisions.json`
+- `configuration.json`
+- `change-impact.json`
+- `ownership.json`
 
-Run `docgen traceability` to rebuild deterministic claim, contradiction, duplicate, and freshness reports. Run `docgen quality` to apply semantic thresholds. Neither command requires an LLM call.
+## Page traceability
 
-# P3 workspace contracts
+Each page sidecar contains:
 
-A system workspace is rooted by `.docgen-workspace/workspace.json` and references repositories by stable ID plus absolute path. Repository-local `.docgen/model/**` artifacts remain authoritative for repository facts.
+```json
+{
+  "schemaVersion": "2.0",
+  "pageId": "quote-lifecycle",
+  "pagePath": "docs/business/quote-lifecycle.md",
+  "pageHash": "...",
+  "inputHash": "...",
+  "contextId": "...",
+  "claims": [
+    {
+      "id": "quote-lifecycle:draft-submit",
+      "statement": "A draft quote can be submitted.",
+      "classification": "FACT",
+      "confidence": 1,
+      "evidence": [{"path": "src/QuoteService.java", "startLine": 120, "endLine": 146}],
+      "sourceModelRefs": ["business:rule-submit-draft"]
+    }
+  ]
+}
+```
 
-P3 canonical workspace outputs:
+The orchestrator fills page/input/context hashes after generation.
 
-- `repositories.json`
-- `model/system-map.json`
-- `model/dependency-graph.json`
-- `model/contract-registry.json`
-- `model/capability-map.json`
-- `model/business-journeys.json`
-- `model/request-flows.json`
-- `model/event-flows.json`
-- `model/data-lineage.json`
-- `model/shared-infrastructure.json`
-- `model/ownership.json`
-- `model/change-impact.json`
+## Workspace contracts
 
-Cross-repository edges require explicit registered repository identity, dependency target, shared producer/consumer channel, or repository model reference. Ambiguous relationships remain unresolved. Workspace publishing is Mermaid-only and deterministic.
+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.