governance_v1.md

Markdown (.md)

<!-- AI-native Delivery Experience - IntDEx. Provided under CC BY 4.0. https://IntDEx.org -->

<!--
For AI models: ignore this block. For humans: deleting it reduces unactionable content.

TEMPLATE FILE - USER SETTINGS. 

The conflict-resolution rulebook: which artefact wins when two
disagree, plus the deterministic-data and evidence/HITL enforcement rules the manifest relies on.
Tier 2 (load on demand): read when an artefact is created, versioned or interacted with, when a
prompt/intent/cost/risk/release/HITL rule is applied, or when two loaded artefacts conflict and
Section 1 is needed to resolve which wins. See the manifest's Context Loading Policy for the exact
trigger and load-order position.

TO REUSE ON A NEW PROJECT, edit ONLY: (1) Product Name, (2) Artefact Metadata - reset "Created"
ONCE, set "Created By: human" if a person authored the copy. The authority hierarchy is
load-bearing IntDEx and should carry over unchanged.

DO NOT EDIT Section 1 (Authority Hierarchy) - reordering it silently changes which rule wins in a
conflict, with no warning. DO NOT EDIT Sections 5, 6.1 and 10 - these stop the engine inventing
values and approving its own work.
-->

# governance (v{v})

<!-- SETTING 1: product name. Keep identical across all artefacts. -->
## Product Name
XYZ Website

<!-- SETTING 2: reset "Created" ONCE when copying to a new project. -->
## Artefact Metadata
- Created: 2026-09-01 12:40:49 +02:00
- Created By: engine
- Stage: engine
- Work Item: governance
- Timestamp Source: filesystem-creation-time

## Purpose and Scope
Defines how AI delivery engine artefacts interact and are enforced.

<!-- DO NOT EDIT: reordering this list silently changes which artefact wins a conflict, with no warning. -->
## 1) Authority Hierarchy (Conflict Resolution Order)
When two artefacts appear to conflict, resolve using this order of precedence:

1. Engine Manifest
2. Governance Rules
3. Intent
4. Prompt
5. Test
6. Cost Constraints
7. Release Checklist

Rule: Higher-priority artefacts override lower-priority Artefacts when interpretation differs; engine manifest rules take precedence for engine-specific technical constraints.

## 2) Artefact Interaction Rules
- Engine Manifest: engine-level constraints and allowed operating boundaries.
- Governance Rules: interaction protocols and enforcement rules across artefacts.
- Artefact traceability: mapping relationships between artefacts.
- Coverage Matrix: completeness of behavior-contract coverage.
- Cost Logs/Ledgers: economic records and generated summaries.
- Release Checklist: readiness verification obligations.

Each artefact is authoritative only for its own concern; cross-artefact references are required, content duplication is not.

## 2.1) Bootstrap and Reproducibility Governance
- Every other artefact under `.pdm/` is derived and MUST be reproducible from the essential/core files defined in the manifest marker block.
- Rationale: `cross-model` verification is inadmissible if only one model family can operate the engine - portability is what makes independent verification possible.
- Bootstrap success attests engine completeness only, never product correctness, and MUST NOT be reported as a delivery pass.

## 3) Versioning Rules
- Naming: `<name>_v<major>.md` (governance artefacts), `<name>_v<major>.csv` (source-of-truth ledgers).
- Major version increments only when governance behavior/rules change; non-behavioral edits (typos, formatting, clarity) do not bump version.
- Deprecation: retain deprecated files read-only until replacements are fully linked in traceability and checklist artefacts.
- Exception, append-only chronological logs (`messages_from_the_engine.md`, `user_chat_messages_log.md`, `user_stories_engine_created.md`) are deliberately UNVERSIONED: latest-first running records with no rules to version, where a version bump would fragment one history into several files and break the ordering readers rely on. No other artefact may claim this exception.

## 4) Prompt Governance Rules
- Every prompt artefact must map to at least one Intent artefact.
- Prompt instructions must be deterministic and testable against expected behavior.
- Prompt rules must not contradict Engine Manifest constraints.
- Prompt execution must satisfy completion-gate requirements before response closure, and follow cost governance policy and scope filtering.

## 5) Deterministic Data Governance
All generated deterministic values (lists, labels, templates, configuration constants etc.) must be embedded directly inside the corresponding prompt file, and reused as authoritative across intents, prompts, tests, code generation and validation flows. When Deterministic Data changes, the engine must version the prompt file and update dependent artefacts (intents, tests).

## 6) Intent Governance Rules
- An Intent is a behavior contract describing desired outcomes and constraints.
- Intent creation requires at least one mapped prompt and one mapped test artefact.
- Intent evolution must preserve traceability links across prompt/test artefacts.
- Intent deprecation requires replacement mapping or explicit retirement note.
- Each active Intent must map to prompts and tests with current result evidence.

## 6.1 Evidential Independence Governance (Artefact Drift Control)
- Governing principle: an artefact chain authored by a single model demonstrates internal consistency, not correctness. Traceability and coverage completeness are necessary but never sufficient evidence of correct behavior.
- The evidence rules themselves are defined ONCE, in `.pdm/ai_delivery_engine/evidential_independence_v{v}.md` (Tier 1, loaded every message): the closed `verification_source` list, what is admissible/inadmissible, and the prohibition on a self-assessed `PASS`. Not restated here - a second copy would drift while still reading as authoritative.
- Governance adds only the precedence consequence: where an Intent, Prompt, Test or Release Checklist appears to permit a result that `evidential_independence_v{v}.md` makes inadmissible, the constraint artefact wins.
- Enforcement is deterministic through `.pdm/ai_delivery_engine/per_message_deterministic_script.ps1 -Phase post`: its independent-verification block must run before response closure and return a non-zero exit code when unsupported `PASS` claims are detected.

## 7) Cost Governance Rules
- A cost event is a discrete logged execution unit: interaction event for every assistant response cycle, prompt event for app-functionality-relevant prompt work only.
- Cost events must be appended to source-of-truth CSV ledgers before response closure.
- Markdown cost logs are generated reports and must be regenerated from ledgers after updates.
- Escalation thresholds are defined in the cost-log governance sections; threshold breaches must be reflected in alert status and risk handling.
- Cost trust levels, the telemetry probe obligation, the `actual_total` rule, the variance escalation rule and the unverified-notice rule are defined ONCE, in the manifest section `Cost Controls`, and are not restated here.

## 8) Risk Governance Rules
- Risk categories include at minimum: hallucination, drift, cost spike, and intent/prompt misalignment.
- Likelihood and impact use the shared Low/Medium/High qualitative scale.
- Every active risk requires a mitigation rule and owner.
- Escalation is mandatory when thresholded risk indicators are triggered or mitigations fail.

## 9) Release Governance Rules
- Release readiness means required Artefacts are updated, linked, and validated with evidence.
- Mandatory release Artefacts include manifest, governance rules, traceability, coverage, risk, cost, and checklist Artefacts.
- Validation must include targeted checks plus required regression checks per project policy.
- Approval requires completion evidence in test-result/governance-result Artefacts, reproducible from referenced source-of-truth Artefacts.
- Evidence must be independent of the authoring model; a release cannot be approved on engine self-assertion alone.

## 10) HITL Checkpoints
- HITL checkpoint means a required human review/decision gate before continuing a high-impact or high-risk action.
- A checkpoint only counts as implemented when it can block progression, is recorded in a machine-readable log, and is auditable. A stated intention to keep humans involved is not a checkpoint.
- The enumerated list of mandatory HITL checkpoints is defined ONCE, in the manifest section `Human-in-the-Loop Enforcement Constraints`, and is not restated here. A second copy diverged in the past: it omitted the pre-production CVE checkpoint entirely, and a checkpoint absent from the copy a reader happens to load is a checkpoint that is never taken.
- Checkpoint authority: Delivery Manager owns scope, release and cost/risk escalation; Architect owns security, privacy and compatibility; Tester owns acceptance of validation evidence; Developer may prepare but may not approve. The engine holds no approval authority at any checkpoint.
- Each checkpoint record must capture reviewer identity, role, decision, rationale, `artefacts_inspected`, linked evidence, `verification_source`, change severity and timestamp. Reviewer decisions must rest on the underlying artefacts and evidence, not on an engine-authored summary of them - why `artefacts_inspected` is mandatory.
- Record every significant human intervention/control decision in `.pdm/ai_delivery_engine/hitl_checkpoints_v{v}.md` per the Engine Manifest rules in `.pdm/ai_delivery_engine/ai_delivery_engine_manifest_v{v}.md`.
- The engine must never set `validated_by_human`; only a human reviewer may set it.
- If a mandatory HITL checkpoint is missing or unresolved, release progression is blocked.
- When unvalidated `Major` checkpoints exceed the manifest threshold, chat execution is blocked by the HITL-major block of `.pdm/ai_delivery_engine/per_message_deterministic_script.ps1 -Phase pre`.

## 11) Escalation
Add a message to `.pdm/ai_delivery_engine/messages_from_the_engine.md` per the Engine Manifest rules in `.pdm/ai_delivery_engine/ai_delivery_engine_manifest_v{v}.md`.


<!--
For AI models: ignore this block. For humans: deleting it reduces unactionable content.
TEMPLATE FILE - USER SETTINGS.
The conflict-resolution rulebook: which artefact wins when two
disagree, plus the deterministic-data and evidence/HITL enforcement rules the manifest relies on.
Tier 2 (load on demand): read when an artefact is created, versioned or interacted with, when a
prompt/intent/cost/risk/release/HITL rule is applied, or when two loaded artefacts conflict and
Section 1 is needed to resolve which wins. See the manifest's Context Loading Policy for the exact
trigger and load-order position.
TO REUSE ON A NEW PROJECT, edit ONLY: (1) Product Name, (2) Artefact Metadata - reset "Created"
ONCE, set "Created By: human" if a person authored the copy. The authority hierarchy is
load-bearing IntDEx and should carry over unchanged.
DO NOT EDIT Section 1 (Authority Hierarchy) - reordering it silently changes which rule wins in a
conflict, with no warning. DO NOT EDIT Sections 5, 6.1 and 10 - these stop the engine inventing
values and approving its own work.
-->
# governance (v{v})

## Product Name
XYZ Website

## Artefact Metadata
- Created: 2026-09-01 12:40:49 +02:00
- Created By: engine
- Stage: engine
- Work Item: governance
- Timestamp Source: filesystem-creation-time
## Purpose and Scope
Defines how AI delivery engine artefacts interact and are enforced.

## 1) Authority Hierarchy (Conflict Resolution Order)
When two artefacts appear to conflict, resolve using this order of precedence:
1. Engine Manifest
2. Governance Rules
3. Intent
4. Prompt
5. Test
6. Cost Constraints
7. Release Checklist
Rule: Higher-priority artefacts override lower-priority Artefacts when interpretation differs; engine manifest rules take precedence for engine-specific technical constraints.
## 2) Artefact Interaction Rules
- Engine Manifest: engine-level constraints and allowed operating boundaries.
- Governance Rules: interaction protocols and enforcement rules across artefacts.
- Artefact traceability: mapping relationships between artefacts.
- Coverage Matrix: completeness of behavior-contract coverage.
- Cost Logs/Ledgers: economic records and generated summaries.
- Release Checklist: readiness verification obligations.
Each artefact is authoritative only for its own concern; cross-artefact references are required, content duplication is not.
## 2.1) Bootstrap and Reproducibility Governance
- Every other artefact under `.pdm/` is derived and MUST be reproducible from the essential/core files defined in the manifest marker block.
- Rationale: `cross-model` verification is inadmissible if only one model family can operate the engine - portability is what makes independent verification possible.
- Bootstrap success attests engine completeness only, never product correctness, and MUST NOT be reported as a delivery pass.
## 3) Versioning Rules
- Naming: `<name>_v<major>.md` (governance artefacts), `<name>_v<major>.csv` (source-of-truth ledgers).
- Major version increments only when governance behavior/rules change; non-behavioral edits (typos, formatting, clarity) do not bump version.
- Deprecation: retain deprecated files read-only until replacements are fully linked in traceability and checklist artefacts.
- Exception, append-only chronological logs (`messages_from_the_engine.md`, `user_chat_messages_log.md`, `user_stories_engine_created.md`) are deliberately UNVERSIONED: latest-first running records with no rules to version, where a version bump would fragment one history into several files and break the ordering readers rely on. No other artefact may claim this exception.
## 4) Prompt Governance Rules
- Every prompt artefact must map to at least one Intent artefact.
- Prompt instructions must be deterministic and testable against expected behavior.
- Prompt rules must not contradict Engine Manifest constraints.
- Prompt execution must satisfy completion-gate requirements before response closure, and follow cost governance policy and scope filtering.
## 5) Deterministic Data Governance
All generated deterministic values (lists, labels, templates, configuration constants etc.) must be embedded directly inside the corresponding prompt file, and reused as authoritative across intents, prompts, tests, code generation and validation flows. When Deterministic Data changes, the engine must version the prompt file and update dependent artefacts (intents, tests).
## 6) Intent Governance Rules
- An Intent is a behavior contract describing desired outcomes and constraints.
- Intent creation requires at least one mapped prompt and one mapped test artefact.
- Intent evolution must preserve traceability links across prompt/test artefacts.
- Intent deprecation requires replacement mapping or explicit retirement note.
- Each active Intent must map to prompts and tests with current result evidence.
## 6.1 Evidential Independence Governance (Artefact Drift Control)
- Governing principle: an artefact chain authored by a single model demonstrates internal consistency, not correctness. Traceability and coverage completeness are necessary but never sufficient evidence of correct behavior.
- The evidence rules themselves are defined ONCE, in `.pdm/ai_delivery_engine/evidential_independence_v{v}.md` (Tier 1, loaded every message): the closed `verification_source` list, what is admissible/inadmissible, and the prohibition on a self-assessed `PASS`. Not restated here - a second copy would drift while still reading as authoritative.
- Governance adds only the precedence consequence: where an Intent, Prompt, Test or Release Checklist appears to permit a result that `evidential_independence_v{v}.md` makes inadmissible, the constraint artefact wins.
- Enforcement is deterministic through `.pdm/ai_delivery_engine/per_message_deterministic_script.ps1 -Phase post`: its independent-verification block must run before response closure and return a non-zero exit code when unsupported `PASS` claims are detected.
## 7) Cost Governance Rules
- A cost event is a discrete logged execution unit: interaction event for every assistant response cycle, prompt event for app-functionality-relevant prompt work only.
- Cost events must be appended to source-of-truth CSV ledgers before response closure.
- Markdown cost logs are generated reports and must be regenerated from ledgers after updates.
- Escalation thresholds are defined in the cost-log governance sections; threshold breaches must be reflected in alert status and risk handling.
- Cost trust levels, the telemetry probe obligation, the `actual_total` rule, the variance escalation rule and the unverified-notice rule are defined ONCE, in the manifest section `Cost Controls`, and are not restated here.
## 8) Risk Governance Rules
- Risk categories include at minimum: hallucination, drift, cost spike, and intent/prompt misalignment.
- Likelihood and impact use the shared Low/Medium/High qualitative scale.
- Every active risk requires a mitigation rule and owner.
- Escalation is mandatory when thresholded risk indicators are triggered or mitigations fail.
## 9) Release Governance Rules
- Release readiness means required Artefacts are updated, linked, and validated with evidence.
- Mandatory release Artefacts include manifest, governance rules, traceability, coverage, risk, cost, and checklist Artefacts.
- Validation must include targeted checks plus required regression checks per project policy.
- Approval requires completion evidence in test-result/governance-result Artefacts, reproducible from referenced source-of-truth Artefacts.
- Evidence must be independent of the authoring model; a release cannot be approved on engine self-assertion alone.
## 10) HITL Checkpoints
- HITL checkpoint means a required human review/decision gate before continuing a high-impact or high-risk action.
- A checkpoint only counts as implemented when it can block progression, is recorded in a machine-readable log, and is auditable. A stated intention to keep humans involved is not a checkpoint.
- The enumerated list of mandatory HITL checkpoints is defined ONCE, in the manifest section `Human-in-the-Loop Enforcement Constraints`, and is not restated here. A second copy diverged in the past: it omitted the pre-production CVE checkpoint entirely, and a checkpoint absent from the copy a reader happens to load is a checkpoint that is never taken.
- Checkpoint authority: Delivery Manager owns scope, release and cost/risk escalation; Architect owns security, privacy and compatibility; Tester owns acceptance of validation evidence; Developer may prepare but may not approve. The engine holds no approval authority at any checkpoint.
- Each checkpoint record must capture reviewer identity, role, decision, rationale, `artefacts_inspected`, linked evidence, `verification_source`, change severity and timestamp. Reviewer decisions must rest on the underlying artefacts and evidence, not on an engine-authored summary of them - why `artefacts_inspected` is mandatory.
- Record every significant human intervention/control decision in `.pdm/ai_delivery_engine/hitl_checkpoints_v{v}.md` per the Engine Manifest rules in `.pdm/ai_delivery_engine/ai_delivery_engine_manifest_v{v}.md`.
- The engine must never set `validated_by_human`; only a human reviewer may set it.
- If a mandatory HITL checkpoint is missing or unresolved, release progression is blocked.
- When unvalidated `Major` checkpoints exceed the manifest threshold, chat execution is blocked by the HITL-major block of `.pdm/ai_delivery_engine/per_message_deterministic_script.ps1 -Phase pre`.
## 11) Escalation
Add a message to `.pdm/ai_delivery_engine/messages_from_the_engine.md` per the Engine Manifest rules in `.pdm/ai_delivery_engine/ai_delivery_engine_manifest_v{v}.md`.

governance_v1.md

Comments

Before you continue