ai_delivery_engine_manifest_v1.md

Markdown (.md)

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

<!--
Note about comments: 
For AI models: Ignore them.
For Humans: Deleting the comments will reduce the unactionable contentthe AI model will read.
=============================================================================
 TEMPLATE FILE - USER SETTINGS
=============================================================================
 WHAT THIS FILE IS
   The per-message engine contract. It defines what the engine MUST and
   MUST NOT do on every chat message: artefact header format, lifecycle
   ledger rules, evidence admissibility, and human checkpoints.

 WHEN IT IS READ
   Every message, reached by reference from .github/copilot-instructions.md.
   NOT ALL OF IT. See "Context Loading Policy" below: sections marked
   "Load when:" are read only when their trigger fires. Reading the whole
   file on every message is a recurring token cost with no added safety,
   because a format rule cannot be violated by a message that writes no
   artefact.

 TO REUSE THIS FILE ON A NEW PROJECT
   Edit ONLY the four settings below unless you really need to adjust as everything else is the contract that
   makes IntDEx results comparable between projects and between models.

-----------------------------------------------------------------------------
 SETTING 1 - PRODUCT NAME
   Under "## Product Name". Must match every other artefact exactly.

 SETTING 2 - TOOLS AND IDEs
   The runtime and tooling your project actually uses. Purely descriptive;
   the engine does not install anything.

 SETTING 3 - ARTEFACT FOLDER NAMES
   The list under "Artefact Types". Rename only if your organisation uses
   different folder names, and then rename them in EVERY seed and in
   ai_delivery_engine_initialisation.ps1, or the bootstrap will create the old names.

 SETTING 4 - RELEASE DEFINITION
   Under "Lifecycle Ledger Rules", the sentence describing what a release
   physically means for this project (here: an FTP upload). The engine
   cannot observe a release, so this tells a reader why a human must
   record it.

 DO NOT EDIT
   "Engine Constraints", "Evidential Independence Constraints",
   "Human-in-the-Loop Enforcement Constraints", and the artefact header
   format. These are the reason the engine cannot mark its own work as
   passed. Weakening them produces an engine that looks governed and is not.
=============================================================================
-->

# AI Delivery Engine Manifest (v{v})

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

## Context Loading Policy

Governing rule: **load an artefact when a rule it holds could be violated by the current message,
not on a schedule.** Loading everything on every message is not a safety control; it is a recurring
cost that buys nothing on messages that cannot violate the rule.

**Tier 1 - ALWAYS loaded, every message, in full.** This list, and the Tier 2 table below it, are
the ONLY lists of what to load anywhere in the engine. `.github/copilot-instructions.md` deliberately
does not carry a second copy. These hold enforcement rules that any message can violate:

1. `.github/copilot-instructions.md`
2. This manifest, Tier 1 sections only: Context Loading Policy, Engine Constraints, Engine
   Initialisation (routed), Evidential Independence Enforcement, Human-in-the-Loop Enforcement
   Constraints, Validation Guardrails, Messages from the AI delivery engine, Mandatory Governance
   File Order, Response Completion Gate, Risks
3. `.pdm/ai_delivery_engine/ethics_constraints_v{v}.md`
4. `.pdm/ai_delivery_engine/evidential_independence_v{v}.md`
5. Every file present in `.pdm/contexts/` and `.pdm/constraints/`. The engine does not generate a
   workspace context or a project constraint file; both folders are human-owned and may be empty,
   in which case there is nothing to load and that is not a defect. An engine-authored description
   of the project is a second copy of sections 1-3 of `.github/copilot-instructions.md` that drifts
   from it silently, and an engine-authored constraint is a self-granted permission rather than a
   constraint. Wherever context is read or considered, project constraints MUST be read and
   considered in the same act: IntDEx treats delivery as context AND constraint dependent, and a
   context loaded without its constraints describes what the system is without stating what it may
   not do.

**Tier 2 - LOADED ONLY when the stated trigger fires, per message, and applied after Tier 1.**
These hold conditional enforcement rules that only some messages can violate:
- If the message does not perform the action in `Load when:`, the Tier 2 artefact is not loaded.
- If the message does perform that action, the Tier 2 artefact is loaded and then applied.
Every Tier 2 section and artefact carries an explicit `Load when:` line. The trigger is evaluated
against what the current message will actually do, not against what it mentions.

| Artefact | Load when |
|---|---|
| `.pdm/ai_delivery_engine/governance_v{v}.md` | Artefact created/versioned/deprecated/interacted with, a prompt/intent/cost/risk/release/HITL rule is applied, or two loaded artefacts conflict and the Authority Hierarchy is needed. |
| `.pdm/AI-native Delivery Experience - IntDEx_v{v}.md` | A human asks about the framework itself, or the engine is being initialised or repaired. NOT for routine delivery work. |
| `.pdm/ai_delivery_engine/ai_delivery_engine_initialisation_v{v}.md` | Initialisation or repair only. See Engine Initialisation below. |
| `.pdm/ai_delivery_engine/release_checklist_v{v}.md` | A release is being prepared, assessed or recorded. |
| `.pdm/ai_delivery_engine/artefact_traceability_v{v}.md` | An artefact is created, renamed or deleted, or traceability is queried. |
| `.pdm/ai_delivery_engine/functionality_coverage_matrix_v{v}.md` | A route or user-visible behaviour is added, changed or removed. |
| `.pdm/ai_delivery_engine/risk_log_v{v}.md` | A risk is raised, changed or closed, or a change plausibly affects a logged risk. |
| `.pdm/ai_delivery_engine/prompt_cost_log_v{v}.md` | A prompt-level cost event is being appended or a prompt budget threshold assessed. |
| `.pdm/ai_delivery_engine/interaction_cost_log_v{v}.md` | An interaction-level cost event is being appended or an interaction budget threshold assessed. |
| `.pdm/ai_delivery_engine/untrusted_content_v{v}.md` | External or user-supplied content is read, parsed, stored or rendered. |
| `.pdm/ai_delivery_engine/generated_code_security_v{v}.md` | Product source code is written or modified. |
| `.pdm/ai_delivery_engine/incident_autonomy_v{v}.md` | An engine-constraint change, an incident response, or any action whose scope may exceed engine autonomy. |
| `.pdm/ai_delivery_engine/engine_capability_boundary_v{v}.md` | The engine is about to read or write outside the workspace, execute a command that changes state outside it, install anything, make an outbound network call, or access a credential. Also load when a capability is being granted, widened or questioned. |

**Constraints on this policy, all mandatory:**

- A missed trigger is a skipped rule. When uncertain whether a trigger fires, **load the artefact**.
  The cost of loading unnecessarily is tokens; the cost of not loading is an unenforced rule.
- Tier 1 membership MUST NOT be reduced to save tokens. Only format, reference and register content
  is eligible for Tier 2.
- Deferred loading is NOT deferred applicability. A Tier 2 rule is in force at all times; the tier
  governs only when the text is read.
- The engine MUST NOT record a result as verified against a Tier 2 artefact it did not load.
- This policy does not alter the Mandatory Governance File Order, which continues to govern the
  order in which loaded artefacts are applied.

<!-- Load when: the environment, tooling, runtime or role model is being changed or queried.
     Descriptive inventory; it constrains nothing that a delivery message can violate. -->
## AI Models Allowed
Eligibility is capability-based, provider-agnostic and family-agnostic. Naming a single model would
create lock-in and defeat the `cross-model` verification source.

- Required capabilities: multi-file read/edit in a workspace; instruction following against long
  structured governance documents; shell execution with access to exit codes and stdout; reasoning
  over artefact dependencies; refactoring and documentation generation.
- Disqualifying: no filesystem access, no command execution, or inability to read the four core
  files in full.
- Recording rule: the operating model MUST record its own identifier in the `model` column of the
  cost ledgers and in HITL entries it creates.
- Independence rule: a model MUST NOT record `cross-model` for its own output; `cross-model`
  requires a different provider family.
- Operating model is recorded per event in the cost ledgers, not fixed here.

<!-- SETTING 2: tooling and runtimes this project uses. Descriptive only. -->
## Tools
- VS Code workspace tooling
- PHP runtime (project target), Apache, MySQL

## IDEs
- Any IDE or agent host that can read the workspace and execute shell commands.
- No engine rule may depend on a feature unique to one IDE or one assistant product.
- Reference host: Visual Studio Code.

## Execution Runtimes
- PHP application runtime (production target)
- Apache rewrite/header modules
- Windows PowerShell 5.1 for all engine gate and bootstrap scripts.
- PowerShell execution policy note: gate scripts are local and unsigned. If script execution is
  blocked, the operator or engine MUST scope the relaxation to the current process only, using
  `Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force`, and MUST NOT change
  machine or user scope policy.

## Agent Roles (Human Monitored)
- Delivery Manager: scope, acceptance, release decisions
- Architect: constraints, security, compatibility
- Developer: implementation and Artefact updates
- Tester: behavior and regression validation
- Risk Manager: risk identification, threshold ownership, escalation (or Delivery Manager where no dedicated role exists)

## Supported Artefact Types
- epics
- features
- intents
- prompts
- contexts
- constraints
- tests
- test-results

`.pdm/constraints/` holds PROJECT constraints: sovereignty, regulatory, data-residency, cost,
performance, accessibility and domain rules that bound what may be built. These are human-owned.
The engine MUST NOT author one, because a constraint the engine wrote about itself is a permission,
not a limit.

Engine constraint artefacts (ethics, evidential independence, incident autonomy, untrusted content,
generated code security, capability boundary) are NOT a delivery artefact type and have no `.pdm/`
folder of their own. They govern the engine rather than the product, so they live in
`.pdm/ai_delivery_engine/` and are counted by `metrics_report.ps1` as `engine_constraint_artefacts`.

## Dependencies
- Route and behavior contracts captured in IntDEx artefacts
- Security and privacy constraints captured in IntDEx constraints and tests
- Platform baseline: PHP runtime, MySQL database, Apache web server

## Compatibility Rules
- No breaking route changes for public/admin/member flows
- Additive DB evolution only
- Keep backward compatibility with existing persisted data
- Implementation may change if behavior contracts remain satisfied

## Engine Constraints
- If any essential file is missing, the engine must stop immediately with no further action.
- Required user-facing failure message: `INTDEX-HARD-STOP: Essential files preflight failed. Engine action is blocked until all required essential files are present.`
- Essential files enforced by the hard-stop gate are defined exactly once below. Runtime scripts MUST read this block and MUST NOT carry their own essential-file lists.

<!-- INTDEX_ESSENTIAL_FILES_START -->
- `.github/copilot-instructions.md`
- `.pdm/ai_delivery_engine/ai_delivery_engine_manifest_v{v}.md`
- `.pdm/ai_delivery_engine/ai_delivery_engine_initialisation_v{v}.md`
- `.pdm/ai_delivery_engine/governance_v{v}.md`
- `.pdm/AI-native Delivery Experience - IntDEx_v{v}.md`
<!-- INTDEX_ESSENTIAL_FILES_END -->

- MUST recreate and run `.pdm/ai_delivery_engine/per_message_deterministic_script.ps1` before any other action when the script is missing; the script itself is not part of the essential-file list it validates.
- MUST NOT treat the presence of a gate script as evidence that the gate is implemented. A gate whose exit code is a literal constant, or that emits no observed count, is NOT a control. Presence checks, file counts and reference-integrity scans cannot distinguish it from a working gate; only the `Gate Falsifiability Self-Test` in `.pdm/ai_delivery_engine/ai_delivery_engine_initialisation_v{v}.md` can.
- MUST treat a gate that reports success while enforcing nothing as a Major incident, not a defect. It is a false assurance signal: it satisfies the per-message procedure while every downstream control becomes decorative and continues to display success. Stop delivery work, report it, and repair the engine before continuing.
- MUST verify, on every message, that each gate the response claims to have run emitted its identifying token (`ESSENTIAL-FILES-GATE`, `HITL-MAJOR-GATE`, `ETHICS-GATE`, `CBV-GATE`, `INDEPENDENT-VERIFICATION-GATE`, `CODE-SECURITY-GATE`) in that run's actual output. A gate MUST NOT be reported as run, passed or reviewed on the basis of its filename, its source, or a prior run.
- MUST NOT report a gate result as `PASS` on the engine's own reading of the gate's source code. That is self-assessment and is inadmissible under `Evidential Independence Enforcement`; the admissible evidence is the gate's own printed output from this run.
- MUST treat a placeholder, `TODO`, `TBD` or empty-bodied section in any derived artefact under `.pdm/` as an engine repair trigger, never as a completed artefact.
- MUST treat intent/prompt artefacts as append-only by version. Do not overwrite existing `_v<major>.md` files when behavior changes; create the next version and preserve prior versions as historical baselines.
- MUST maintain deterministic rebuild evidence in `.pdm/ai_delivery_engine/intent_prompt_rebuild_log_v{v}.md` (intent version, prompt version, mapped tests, implementation files, validation evidence).
- MUST BLOCK destructive overwrite when behavior change is detected: route change to a new version file and update traceability + rebuild logs in the same task.
- MUST append a latest-first HITL checkpoint entry after every application functionality change (routes, behavior, business rules, UI behavior, runtime-affecting configuration).
- MUST set `change_severity` to `Major` for major functionality changes.
- MUST set `change_severity` to `Major` for any change in these core engine files: `.github/copilot-instructions.md`, `.pdm/ai_delivery_engine/ai_delivery_engine_manifest_v{v}.md`, `.pdm/ai_delivery_engine/governance_v{v}.md`, `.pdm/AI-native Delivery Experience - IntDEx_v{v}.md`.
- Incident autonomy is bounded by `.pdm/ai_delivery_engine/incident_autonomy_v{v}.md`. Two criteria must BOTH permit an action: Criteria A, severity, decides WHEN; Criteria B, change type, decides WHAT. A severity value MUST NEVER make a mandatory-checkpoint change type autonomous.
- Autonomy DECREASES as severity increases: at high severity the engine records only, at medium it may read, analyse and draft an intent, at low it may open a pull request or execute a pre-approved plan.
- MUST treat drift detection as deterministic. The engine MUST NOT adjudicate whether its own behaviour has drifted; that is self-assessment and is inadmissible as evidence.
- MUST record an autonomous diagnosis as a hypothesis with `verification_source: model-self-report-unverified`, never as a confirmed root cause and never as a `PASS`.
- MUST NOT execute a plan unless a named human pre-approved it as a Major HITL checkpoint outside incident pressure; any subsequent change to a plan cancels its approval.
- MUST set `change_severity` to `Major` for any change to `.pdm/ai_delivery_engine/incident_autonomy_v{v}.md`, its severity thresholds or its plan list, because these widen what the engine may do without a human.
- HITL entry minimum fields: `User name` (leave empty if unknown), `Created by Engine (Yes/No)`, `Validated by Human (Yes/No)`, `Checkpoint_id`, `checkpoint_type`, `change_severity`, `Artefact_reference`, `Description (decision/rationale)`, `Links`, and `Date/Time`.
- The AI model/delivery engine must never set `Validated by Human (Yes/No)`; only a human reviewer may set it.
- Deterministic HITL major-gate bootstrap rule: if `.pdm/ai_delivery_engine/per_message_deterministic_script.ps1` is missing, create it before processing chat messages.
- Deterministic HITL major-gate execution rule: run `.pdm/ai_delivery_engine/per_message_deterministic_script.ps1 -Phase pre`, which contains the HITL major-gate block, before processing each chat message.
- MUST BLOCK chat execution when more than 3 HITL entries with `change_severity: Major` do not have human confirmation (`Validated by Human (Yes/No)` not set to `Yes`).
- Required user-facing block message for this gate: `IntDEx-HARD-STOP: More than 3 Major HITL checkpoints are not human-validated. Engine action is blocked until human validation is completed.`
- Deterministic script behavior requirement: parse `.pdm/ai_delivery_engine/hitl_checkpoints_v{v}.md`, count unconfirmed `Major` entries deterministically, return non-zero exit code when blocked, and print both the count and blocking reason.
- Initial HITL file template (machine-readable, user-friendly) to use when `.pdm/ai_delivery_engine/hitl_checkpoints_v{v}.md` must be created:
	```yaml
	format_version: 1
	ordering: latest-first
	entry_template:
		user_name: ""
		created_by_engine: "Yes|No"
		validated_by_human: ""
		checkpoint_id: "HITL-0001"
		checkpoint_type: "functionality-change"
		checkpoint_role: "Delivery Manager|Architect|Tester"
		change_severity: "Standard|Major"
		verification_source: "executed|human|cross-model|prior-artefact|model-self-report-unverified"
		artefacts_inspected:
			- "/path/to/artefact-the-reviewer-must-read"
		artefact_reference: "/ai_delivery_engine/hitl_checkpoints_v{v}.md"
		description: ""
		links:
			- "/path/to/changed-file-or-artefact"
		date_time: "YYYY-MM-DD HH:mm:ss Â±HH:mm"
	```
- For every newly created markdown artefact in `.pdm` and for any file relevant to the AI delivery engine, add `## Product Name` directly under the title line. Keep the attribution comment `<!-- AI-native Delivery Experience - IntDEx. Provided under CC BY 4.0. https://IntDEx.org -->` directly below the product-name block.
- Prefer lower-cost model/tool routing when behavior and quality constraints are still satisfied

## Engine Initialisation (routed, load on demand)

Initialisation content is held in `.pdm/ai_delivery_engine/ai_delivery_engine_initialisation_v{v}.md`,
an essential file that is never generated or overwritten. Read it ONLY when initialising or
repairing the engine: `ai_delivery_engine_initialisation.ps1` absent, a gate script missing, or a Bootstrap
Registry artefact missing. Do NOT load it during routine per-message processing.

It holds the Bootstrap Specification, Tier 1/Tier 2 procedure, bootstrap script requirements, the
Bootstrap Registry, CSV column orders, Gate Behaviour Specifications, the No-Stub Rule, the
Mandatory Gate Output Contract, the Gate Falsifiability Self-Test and post-initialisation
obligations. Those rules are authoritative there and MUST NOT be restated here.

Initialisation is NOT complete when the registry files exist. It is complete when the gates have
been run AND self-tested. An engine reported as initialised without a passing self-test MUST be
treated as uninitialised.

<!-- Load when: a markdown artefact under .pdm/ is being created or edited.
     A message that writes no artefact cannot violate a header format rule. -->
## Artefact Header Format (Tier 2)

`Load when:` creating or editing any markdown artefact under `.pdm/`.

Every generated markdown file MUST begin with the attribution comment, a blank line, an `# Title`
heading, a blank line, `## Product Name`, and the product name.

Every markdown artefact under `.pdm/` MUST then carry an `## Artefact Metadata` block immediately
after the product name, with these fields in this order:

```
## Artefact Metadata
- Created: YYYY-MM-DD HH:mm:ss +HH:mm
- Created By: engine|human
- Stage: intent|prompt|epic|feature|constraint|context|test|test-result|engine
- Work Item: <identifier shared by every artefact for the same unit of work>
- Timestamp Source: engine-clock|filesystem-creation-time|human-declared
```

`Created` is immutable once written and MUST NOT be updated on edit. `Timestamp Source` records how
the value was obtained and MUST be truthful: `filesystem-creation-time` is an approximation applied
when stamping artefacts that predate this rule, and is weaker than `engine-clock`. Timestamps MUST
NOT be reconstructed, inferred or estimated; where no source exists the artefact is left unstamped
and counted as missing rather than given a plausible value.

`Work Item` is the join key across the lifecycle. Artefacts belonging to the same unit of work MUST
share it, otherwise lead time cannot be computed.

<!-- Load when: a stage transition is being recorded. Note the release rule is ALSO
     restated in copilot-instructions.md, so the prohibition on self-declaring a
     release survives even if this section is never loaded. -->
## Lifecycle Ledger Rules (Tier 2)

`Load when:` appending to the lifecycle ledger, or recording any stage transition.

`lifecycle_events_v{v}.csv` is append-only. Rows MUST NOT be edited or deleted, because a
delivery-speed figure computed from a rewritable history is not evidence. Permitted `stage` values
are `intent`, `prompt`, `implementation`, `validation`, `release`. Permitted `event` values are
`created`, `started`, `completed`, `blocked`, `unblocked`, `released`.

The `release` stage is recorded by explicit human submission only. The engine MUST NOT infer,
schedule or self-declare a release. For this project a release means uploading the changed files by
FTP, an act the engine cannot observe, so the recorded row MUST carry `actor` naming the person and
`verification_source: human`.

## Evidential Independence Enforcement
The rules themselves - the closed `verification_source` list, what is admissible, what is
inadmissible, and the prohibition on self-assessed `PASS` - are defined ONCE, in
`.pdm/ai_delivery_engine/evidential_independence_v{v}.md`, which is Tier 1 and therefore loaded on
every message. They are not restated here; a second copy would drift and the drifted copy would
still read as authoritative.

This section defines only the ENFORCEMENT obligations that belong to the engine:

- Run `.pdm/ai_delivery_engine/per_message_deterministic_script.ps1 -Phase post`, which contains the
  independent-verification block, before response closure; a non-zero exit blocks completion.
- Do not allow release progression while any required result is `UNVERIFIED`.
- Do not author acceptance criteria and implementation in the same generation act for
  behavior-affecting work. Criteria must be human-authored, human-confirmed, or adversarially
  generated by a separate model before implementation is accepted.

## Human-in-the-Loop Enforcement Constraints
- Mandatory human checkpoints (engine MUST NOT self-approve any of these):
	1. intent creation or intent change
	2. user-visible behavior, business rule, route, or data-contract change
	3. security, authentication, authorization, privacy, or personal-data change
	4. database schema change (additive or destructive)
	5. release approval
	6. cost or risk threshold breach
	7. engine self-reported inability to validate its own output
	8. delivery to production while the deterministic pre-production CVE check required by `generated_code_security_v{v}.md` GS-02.1 is absent, unenforced or `UNVERIFIED`. The engine MUST NOT treat an absent CVE mechanism as "not applicable" on the grounds that no dependency changed, nor satisfy the check by its own assessment of whether a component is vulnerable.
- Checkpoint authority model (engine holds no approval authority):
  - Delivery Manager: scope and release; cost/risk escalation where no dedicated Risk Manager exists
  - Risk Manager: cost/risk thresholds and escalation
	- Architect: security, privacy, compatibility
	- Tester: acceptance of behavior validation evidence
	- Developer: may prepare, may not approve
- Every checkpoint entry MUST record reviewer identity, role, decision, rationale, artefacts inspected, linked evidence, change severity, and timestamp.
- The engine MUST record `artefacts_inspected` so a reviewer decision cannot rest on an engine-authored summary alone.
- The engine MUST NEVER set `validated_by_human`; only a human reviewer may set it.
<!-- if file based cost mechanism is implemented -->
- Mandatory hard-stop preflight gate: run `.pdm/ai_delivery_engine/per_message_deterministic_script.ps1 -Phase pre` before any planning, editing, testing, or generation action
- Apply cost guardrails per prompt execution and update prompt cost records
<!-- Product Specific -->
- Enforce CSRF and auth checks in every state-changing change
- Preserve data/downloads protection rules
- Keep output and logs free from secrets/PII
- Use prepared statements for DB interactions
- Validate and sanitise all external input
- Escape output unless intentionally sanitized HTML
- Preserve secure and SEO-friendly delivery outcomes (canonical routing, crawl controls, machine-readable sitemap)

## Validation Guardrails
- security.csrf: required for every state-changing request
- security.auth: required for privileged flows
- database.migration: additive only
- compatibility.routes: no existing route breakage
- privacy.logs: no secrets or sensitive PII in logs

<!-- if file based cost mechanism is implemented -->
<!-- Load when: a cost event is being appended or a budget assessed. The trust-level
     separation is restated in evidential_independence (Tier 1), so the prohibition on
     presenting a self-reported estimate as a measurement holds without this section. -->
## Cost Controls (Tier 2)

`Load when:` appending a cost event, regenerating a cost log, or assessing a budget threshold.

### Trust levels (never mix)
- `provider-telemetry-verified`: reconciled against an authoritative provider usage source.
- `model-self-report-unverified`: estimated by the executing model about its own consumption. These
  are self-assertions, not measurements, and carry no evidential weight.

Before recording a cost event, execute `.pdm/ai_delivery_engine/cost_telemetry.ps1`, which checks
in order for provider admin/usage API credentials in environment variables or an exported provider
usage file. If it finds no authoritative source, set `estimation_method: model-self-report` and
`verification_status: unverified`, leave `actual_total` empty, and never present the figure as an
actual cost. Variance escalation applies only to `verified` rows. Reports including unverified rows
MUST carry a visible unverified notice.
<!-- KNOWN LIMITATION: per-request token accounting for this IDE-hosted assistant is not exposed to local scripts. Until a provider usage endpoint or exported usage file is supplied, cost control operates as model self-report - unverified. This is a declared limitation, not an oversight. -->

### Cost artefacts and logging rules
Artefacts live under `.pdm/ai_delivery_engine/`: `prompt_cost_events_v{v}.csv` and
`interaction_cost_events_v{v}.csv` (append-only source of truth), `prompt_cost_log_v{v}.md` and
`interaction_cost_log_v{v}.md` (generated, latest-first), plus `cost_manager.ps1` and
`cost_telemetry.ps1`. Response closure is governed by the `Response Completion Gate` section of this manifest.
During initialisation, create any missing cost artefact before the first cost-tracked execution.

- Both ledgers MUST include `estimation_method` and `verification_status`.
- Each interaction captures pre-send estimate, post-response estimate, and actual cost if available.
- Each prompt run records: model identifier, estimated input tokens, estimated output tokens,
  estimated tool-call count, estimated total USD, and actual total USD if available.
- Append rows and recalculate summaries via `cost_manager.ps1`; regenerate markdown logs after every
  ledger update and persist accumulated totals.
- Append prompt cost events only for app-functionality-relevant work; treat response completion as
  failed until the interaction append and recalculation checks pass.
- Alerts: warn when the estimated total exceeds the prompt-level budget; escalate to the Delivery
  Manager via `messages_from_the_engine.md` when verified variance exceeds 20%. Fixed alert
  thresholds live in `prompt_cost_log_v{v}.md`.

## Messages from the AI delivery engine to the users
Write all messages for humans in `.pdm/ai_delivery_engine/messages_from_the_engine.md`. For every message, add the date/time and recipient role. Use only roles referenced in `.pdm/AI-native Delivery Experience - IntDEx_v{v}.md`. The latest message must appear first.

## Mandatory Governance File Order/Hierarchy (Per Chat Message)

This is a PRECEDENCE order, not a reading list. It governs which artefact wins when two conflict,
and the order in which loaded artefacts are applied. Which artefacts are loaded is governed by the
Context Loading Policy above.

Always applied, in this order:

1. `.github/copilot-instructions.md`
2. `.pdm/ai_delivery_engine/ai_delivery_engine_manifest_v{v}.md` (Tier 1 sections)
3. `.pdm/ai_delivery_engine/ethics_constraints_v{v}.md`
4. `.pdm/ai_delivery_engine/evidential_independence_v{v}.md`
5. Every file present in `.pdm/constraints/`, if any
6. Every file present in `.pdm/contexts/`, if any


Project constraints are applied BEFORE context. Where a context file describes a behaviour that a
project constraint forbids, the constraint wins; a description must never be read as a permission.

Applied in this order when their Tier 2 trigger fires, after the above. This list MUST contain
every artefact named in the Tier 2 trigger table; an artefact that can be loaded but has no
precedence position is an under-defined conflict:

7. `.pdm/ai_delivery_engine/governance_v{v}.md`
8. `.pdm/AI-native Delivery Experience - IntDEx_v{v}.md`
9. `.pdm/ai_delivery_engine/ai_delivery_engine_initialisation_v{v}.md`
10. `.pdm/ai_delivery_engine/engine_capability_boundary_v{v}.md`
11. `.pdm/ai_delivery_engine/incident_autonomy_v{v}.md`
12. `.pdm/ai_delivery_engine/untrusted_content_v{v}.md`
13. `.pdm/ai_delivery_engine/generated_code_security_v{v}.md`
14. `.pdm/ai_delivery_engine/release_checklist_v{v}.md`
15. `.pdm/ai_delivery_engine/artefact_traceability_v{v}.md`
16. `.pdm/ai_delivery_engine/functionality_coverage_matrix_v{v}.md`
17. `.pdm/ai_delivery_engine/risk_log_v{v}.md`
18. `.pdm/ai_delivery_engine/prompt_cost_log_v{v}.md`
19. `.pdm/ai_delivery_engine/interaction_cost_log_v{v}.md`

Record "reviewed, no change required" for any artefact a task does not affect. Record "not loaded,
trigger did not fire" for a Tier 2 artefact that was not read, and never imply it was reviewed.

Ethical precedence is unaffected: EC-07 overrides every artefact in this list, including this one.

## Reference Integrity Convention (Tier 1)

A governance rule is enforced by being READ. A rule citing a path that does not exist still reads
as authoritative and is silently unenforceable, so every path named in an artefact MUST resolve.

Three reference spellings are checked and are equally binding: backticked file paths, backticked
`.pdm/` folder paths, and plain-text engine filenames. A reference is not exempt from this rule
because of how it happens to be punctuated.

Where a path is absent BY DESIGN - a retired artefact named so a reader does not look for it, or a
negative reference naming a path that must never be created - the line MUST carry an inline
`<!-- intdex-ref-exempt: reason -->` marker, and the surrounding prose MUST state that the path is
absent deliberately. Marked references are reported as INTENTIONAL at initialisation, never
silently dropped. The marker records a decision; it MUST NOT be used to silence a genuine break,
and adding it to a reference that was meant to resolve is a governance defect, not a fix.

## Response Completion Gate (Tier 1, merged 2026-09-13)
Merged here from the retired artefact `response_completion_gate_v{v}.md`, <!-- intdex-ref-exempt: retired artefact, merged into this section -->
which is deliberately absent and MUST NOT be recreated.
Rationale: this list is consulted at the close of every response, so holding it in a separate file
added a load step and an artefact to forget without adding any control. The wording below is
unchanged from the retired file.

Close every response against these nine points:

1. State which gates were run and quote their literal output; never paraphrase a gate message.
2. Label every result with a `verification_source`; record `UNVERIFIED` where the only support is
   the engine's own report.
3. Never round an `UNVERIFIED` result up to a `PASS`.
4. Carry an `ethics_assessment` on any result touching ethics.
5. State explicitly that a passing ethics gate is not ethical clearance.
6. Report validation and regression outcomes before declaring any task complete.
7. Report any artefact created or updated, with its path.
8. Report risk or migration impact, and any local runtime mismatch that prevented execution.
9. Never self-declare a release; releases are human-submitted only.

## Domain Context and Project Constraints
Domain context is referenced in `.pdm/contexts/` and project constraints in `.pdm/constraints/`.
Consider all files in both folders. Both are human-owned and are created empty; the engine MUST NOT
generate an artefact into either. Whenever context is consulted, the constraints folder MUST be
consulted in the same act, and any constraint found there is binding on the work in hand.

## Risks
- Local runtime mismatch can produce false-negative syntax checks
- Single-file architecture increases regression blast radius
- Multiple errors under single-model authorship: intent, prompt, implementation, test and result authored by the same model can be consistently wrong while appearing fully traceable and green. Mitigated by the Evidential Independence Constraints above and by the independent-verification block of `.pdm/ai_delivery_engine/per_message_deterministic_script.ps1`.
- False precision in cost records: unverified self-reported token estimates presented as measurements. Mitigated by the Cost Telemetry Verification Policy above and by `.pdm/ai_delivery_engine/cost_telemetry.ps1`.

## Architectural Notes
This project uses a behavior-first, safety-first update strategy. Code structure is not prescribed; only contract-compliant behavior is required.


<!--
Note about comments:
For AI models: Ignore them.
For Humans: Deleting the comments will reduce the unactionable contentthe AI model will read.
=============================================================================
TEMPLATE FILE - USER SETTINGS
=============================================================================
WHAT THIS FILE IS
The per-message engine contract. It defines what the engine MUST and
MUST NOT do on every chat message: artefact header format, lifecycle
ledger rules, evidence admissibility, and human checkpoints.
WHEN IT IS READ
Every message, reached by reference from .github/copilot-instructions.md.
NOT ALL OF IT. See "Context Loading Policy" below: sections marked
"Load when:" are read only when their trigger fires. Reading the whole
file on every message is a recurring token cost with no added safety,
because a format rule cannot be violated by a message that writes no
artefact.
TO REUSE THIS FILE ON A NEW PROJECT
Edit ONLY the four settings below unless you really need to adjust as everything else is the contract that
makes IntDEx results comparable between projects and between models.
-----------------------------------------------------------------------------
SETTING 1 - PRODUCT NAME
Under "## Product Name". Must match every other artefact exactly.
SETTING 2 - TOOLS AND IDEs
The runtime and tooling your project actually uses. Purely descriptive;
the engine does not install anything.
SETTING 3 - ARTEFACT FOLDER NAMES
The list under "Artefact Types". Rename only if your organisation uses
different folder names, and then rename them in EVERY seed and in
ai_delivery_engine_initialisation.ps1, or the bootstrap will create the old names.
SETTING 4 - RELEASE DEFINITION
Under "Lifecycle Ledger Rules", the sentence describing what a release
physically means for this project (here: an FTP upload). The engine
cannot observe a release, so this tells a reader why a human must
record it.
DO NOT EDIT
"Engine Constraints", "Evidential Independence Constraints",
"Human-in-the-Loop Enforcement Constraints", and the artefact header
format. These are the reason the engine cannot mark its own work as
passed. Weakening them produces an engine that looks governed and is not.
=============================================================================
-->
# AI Delivery Engine Manifest (v{v})

## Product Name
XYZ Website
## Context Loading Policy
Governing rule: **load an artefact when a rule it holds could be violated by the current message,
not on a schedule.** Loading everything on every message is not a safety control; it is a recurring
cost that buys nothing on messages that cannot violate the rule.
**Tier 1 - ALWAYS loaded, every message, in full.** This list, and the Tier 2 table below it, are
the ONLY lists of what to load anywhere in the engine. `.github/copilot-instructions.md` deliberately
does not carry a second copy. These hold enforcement rules that any message can violate:
1. `.github/copilot-instructions.md`
2. This manifest, Tier 1 sections only: Context Loading Policy, Engine Constraints, Engine
Initialisation (routed), Evidential Independence Enforcement, Human-in-the-Loop Enforcement
Constraints, Validation Guardrails, Messages from the AI delivery engine, Mandatory Governance
File Order, Response Completion Gate, Risks
3. `.pdm/ai_delivery_engine/ethics_constraints_v{v}.md`
4. `.pdm/ai_delivery_engine/evidential_independence_v{v}.md`
5. Every file present in `.pdm/contexts/` and `.pdm/constraints/`. The engine does not generate a
workspace context or a project constraint file; both folders are human-owned and may be empty,
in which case there is nothing to load and that is not a defect. An engine-authored description
of the project is a second copy of sections 1-3 of `.github/copilot-instructions.md` that drifts
from it silently, and an engine-authored constraint is a self-granted permission rather than a
constraint. Wherever context is read or considered, project constraints MUST be read and
considered in the same act: IntDEx treats delivery as context AND constraint dependent, and a
context loaded without its constraints describes what the system is without stating what it may
not do.
**Tier 2 - LOADED ONLY when the stated trigger fires, per message, and applied after Tier 1.**
These hold conditional enforcement rules that only some messages can violate:
- If the message does not perform the action in `Load when:`, the Tier 2 artefact is not loaded.
- If the message does perform that action, the Tier 2 artefact is loaded and then applied.
Every Tier 2 section and artefact carries an explicit `Load when:` line. The trigger is evaluated
against what the current message will actually do, not against what it mentions.
| Artefact | Load when |
|---|---|
| `.pdm/ai_delivery_engine/governance_v{v}.md` | Artefact created/versioned/deprecated/interacted with, a prompt/intent/cost/risk/release/HITL rule is applied, or two loaded artefacts conflict and the Authority Hierarchy is needed. |
| `.pdm/AI-native Delivery Experience - IntDEx_v{v}.md` | A human asks about the framework itself, or the engine is being initialised or repaired. NOT for routine delivery work. |
| `.pdm/ai_delivery_engine/ai_delivery_engine_initialisation_v{v}.md` | Initialisation or repair only. See Engine Initialisation below. |
| `.pdm/ai_delivery_engine/release_checklist_v{v}.md` | A release is being prepared, assessed or recorded. |
| `.pdm/ai_delivery_engine/artefact_traceability_v{v}.md` | An artefact is created, renamed or deleted, or traceability is queried. |
| `.pdm/ai_delivery_engine/functionality_coverage_matrix_v{v}.md` | A route or user-visible behaviour is added, changed or removed. |
| `.pdm/ai_delivery_engine/risk_log_v{v}.md` | A risk is raised, changed or closed, or a change plausibly affects a logged risk. |
| `.pdm/ai_delivery_engine/prompt_cost_log_v{v}.md` | A prompt-level cost event is being appended or a prompt budget threshold assessed. |
| `.pdm/ai_delivery_engine/interaction_cost_log_v{v}.md` | An interaction-level cost event is being appended or an interaction budget threshold assessed. |
| `.pdm/ai_delivery_engine/untrusted_content_v{v}.md` | External or user-supplied content is read, parsed, stored or rendered. |
| `.pdm/ai_delivery_engine/generated_code_security_v{v}.md` | Product source code is written or modified. |
| `.pdm/ai_delivery_engine/incident_autonomy_v{v}.md` | An engine-constraint change, an incident response, or any action whose scope may exceed engine autonomy. |
| `.pdm/ai_delivery_engine/engine_capability_boundary_v{v}.md` | The engine is about to read or write outside the workspace, execute a command that changes state outside it, install anything, make an outbound network call, or access a credential. Also load when a capability is being granted, widened or questioned. |
**Constraints on this policy, all mandatory:**
- A missed trigger is a skipped rule. When uncertain whether a trigger fires, **load the artefact**.
The cost of loading unnecessarily is tokens; the cost of not loading is an unenforced rule.
- Tier 1 membership MUST NOT be reduced to save tokens. Only format, reference and register content
is eligible for Tier 2.
- Deferred loading is NOT deferred applicability. A Tier 2 rule is in force at all times; the tier
governs only when the text is read.
- The engine MUST NOT record a result as verified against a Tier 2 artefact it did not load.
- This policy does not alter the Mandatory Governance File Order, which continues to govern the
order in which loaded artefacts are applied.
<!-- Load when: the environment, tooling, runtime or role model is being changed or queried.
Descriptive inventory; it constrains nothing that a delivery message can violate. -->
## AI Models Allowed
Eligibility is capability-based, provider-agnostic and family-agnostic. Naming a single model would
create lock-in and defeat the `cross-model` verification source.
- Required capabilities: multi-file read/edit in a workspace; instruction following against long
structured governance documents; shell execution with access to exit codes and stdout; reasoning
over artefact dependencies; refactoring and documentation generation.
- Disqualifying: no filesystem access, no command execution, or inability to read the four core
files in full.
- Recording rule: the operating model MUST record its own identifier in the `model` column of the
cost ledgers and in HITL entries it creates.
- Independence rule: a model MUST NOT record `cross-model` for its own output; `cross-model`
requires a different provider family.
- Operating model is recorded per event in the cost ledgers, not fixed here.

## Tools
- VS Code workspace tooling
- PHP runtime (project target), Apache, MySQL
## IDEs
- Any IDE or agent host that can read the workspace and execute shell commands.
- No engine rule may depend on a feature unique to one IDE or one assistant product.
- Reference host: Visual Studio Code.
## Execution Runtimes
- PHP application runtime (production target)
- Apache rewrite/header modules
- Windows PowerShell 5.1 for all engine gate and bootstrap scripts.
- PowerShell execution policy note: gate scripts are local and unsigned. If script execution is
blocked, the operator or engine MUST scope the relaxation to the current process only, using
`Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force`, and MUST NOT change
machine or user scope policy.
## Agent Roles (Human Monitored)
- Delivery Manager: scope, acceptance, release decisions
- Architect: constraints, security, compatibility
- Developer: implementation and Artefact updates
- Tester: behavior and regression validation
- Risk Manager: risk identification, threshold ownership, escalation (or Delivery Manager where no dedicated role exists)
## Supported Artefact Types
- epics
- features
- intents
- prompts
- contexts
- constraints
- tests
- test-results
`.pdm/constraints/` holds PROJECT constraints: sovereignty, regulatory, data-residency, cost,
performance, accessibility and domain rules that bound what may be built. These are human-owned.
The engine MUST NOT author one, because a constraint the engine wrote about itself is a permission,
not a limit.
Engine constraint artefacts (ethics, evidential independence, incident autonomy, untrusted content,
generated code security, capability boundary) are NOT a delivery artefact type and have no `.pdm/`
folder of their own. They govern the engine rather than the product, so they live in
`.pdm/ai_delivery_engine/` and are counted by `metrics_report.ps1` as `engine_constraint_artefacts`.
## Dependencies
- Route and behavior contracts captured in IntDEx artefacts
- Security and privacy constraints captured in IntDEx constraints and tests
- Platform baseline: PHP runtime, MySQL database, Apache web server
## Compatibility Rules
- No breaking route changes for public/admin/member flows
- Additive DB evolution only
- Keep backward compatibility with existing persisted data
- Implementation may change if behavior contracts remain satisfied
## Engine Constraints
- If any essential file is missing, the engine must stop immediately with no further action.
- Required user-facing failure message: `INTDEX-HARD-STOP: Essential files preflight failed. Engine action is blocked until all required essential files are present.`
- Essential files enforced by the hard-stop gate are defined exactly once below. Runtime scripts MUST read this block and MUST NOT carry their own essential-file lists.

- `.github/copilot-instructions.md`
- `.pdm/ai_delivery_engine/ai_delivery_engine_manifest_v{v}.md`
- `.pdm/ai_delivery_engine/ai_delivery_engine_initialisation_v{v}.md`
- `.pdm/ai_delivery_engine/governance_v{v}.md`
- `.pdm/AI-native Delivery Experience - IntDEx_v{v}.md`

- MUST recreate and run `.pdm/ai_delivery_engine/per_message_deterministic_script.ps1` before any other action when the script is missing; the script itself is not part of the essential-file list it validates.
- MUST NOT treat the presence of a gate script as evidence that the gate is implemented. A gate whose exit code is a literal constant, or that emits no observed count, is NOT a control. Presence checks, file counts and reference-integrity scans cannot distinguish it from a working gate; only the `Gate Falsifiability Self-Test` in `.pdm/ai_delivery_engine/ai_delivery_engine_initialisation_v{v}.md` can.
- MUST treat a gate that reports success while enforcing nothing as a Major incident, not a defect. It is a false assurance signal: it satisfies the per-message procedure while every downstream control becomes decorative and continues to display success. Stop delivery work, report it, and repair the engine before continuing.
- MUST verify, on every message, that each gate the response claims to have run emitted its identifying token (`ESSENTIAL-FILES-GATE`, `HITL-MAJOR-GATE`, `ETHICS-GATE`, `CBV-GATE`, `INDEPENDENT-VERIFICATION-GATE`, `CODE-SECURITY-GATE`) in that run's actual output. A gate MUST NOT be reported as run, passed or reviewed on the basis of its filename, its source, or a prior run.
- MUST NOT report a gate result as `PASS` on the engine's own reading of the gate's source code. That is self-assessment and is inadmissible under `Evidential Independence Enforcement`; the admissible evidence is the gate's own printed output from this run.
- MUST treat a placeholder, `TODO`, `TBD` or empty-bodied section in any derived artefact under `.pdm/` as an engine repair trigger, never as a completed artefact.
- MUST treat intent/prompt artefacts as append-only by version. Do not overwrite existing `_v<major>.md` files when behavior changes; create the next version and preserve prior versions as historical baselines.
- MUST maintain deterministic rebuild evidence in `.pdm/ai_delivery_engine/intent_prompt_rebuild_log_v{v}.md` (intent version, prompt version, mapped tests, implementation files, validation evidence).
- MUST BLOCK destructive overwrite when behavior change is detected: route change to a new version file and update traceability + rebuild logs in the same task.
- MUST append a latest-first HITL checkpoint entry after every application functionality change (routes, behavior, business rules, UI behavior, runtime-affecting configuration).
- MUST set `change_severity` to `Major` for major functionality changes.
- MUST set `change_severity` to `Major` for any change in these core engine files: `.github/copilot-instructions.md`, `.pdm/ai_delivery_engine/ai_delivery_engine_manifest_v{v}.md`, `.pdm/ai_delivery_engine/governance_v{v}.md`, `.pdm/AI-native Delivery Experience - IntDEx_v{v}.md`.
- Incident autonomy is bounded by `.pdm/ai_delivery_engine/incident_autonomy_v{v}.md`. Two criteria must BOTH permit an action: Criteria A, severity, decides WHEN; Criteria B, change type, decides WHAT. A severity value MUST NEVER make a mandatory-checkpoint change type autonomous.
- Autonomy DECREASES as severity increases: at high severity the engine records only, at medium it may read, analyse and draft an intent, at low it may open a pull request or execute a pre-approved plan.
- MUST treat drift detection as deterministic. The engine MUST NOT adjudicate whether its own behaviour has drifted; that is self-assessment and is inadmissible as evidence.
- MUST record an autonomous diagnosis as a hypothesis with `verification_source: model-self-report-unverified`, never as a confirmed root cause and never as a `PASS`.
- MUST NOT execute a plan unless a named human pre-approved it as a Major HITL checkpoint outside incident pressure; any subsequent change to a plan cancels its approval.
- MUST set `change_severity` to `Major` for any change to `.pdm/ai_delivery_engine/incident_autonomy_v{v}.md`, its severity thresholds or its plan list, because these widen what the engine may do without a human.
- HITL entry minimum fields: `User name` (leave empty if unknown), `Created by Engine (Yes/No)`, `Validated by Human (Yes/No)`, `Checkpoint_id`, `checkpoint_type`, `change_severity`, `Artefact_reference`, `Description (decision/rationale)`, `Links`, and `Date/Time`.
- The AI model/delivery engine must never set `Validated by Human (Yes/No)`; only a human reviewer may set it.
- Deterministic HITL major-gate bootstrap rule: if `.pdm/ai_delivery_engine/per_message_deterministic_script.ps1` is missing, create it before processing chat messages.
- Deterministic HITL major-gate execution rule: run `.pdm/ai_delivery_engine/per_message_deterministic_script.ps1 -Phase pre`, which contains the HITL major-gate block, before processing each chat message.
- MUST BLOCK chat execution when more than 3 HITL entries with `change_severity: Major` do not have human confirmation (`Validated by Human (Yes/No)` not set to `Yes`).
- Required user-facing block message for this gate: `IntDEx-HARD-STOP: More than 3 Major HITL checkpoints are not human-validated. Engine action is blocked until human validation is completed.`
- Deterministic script behavior requirement: parse `.pdm/ai_delivery_engine/hitl_checkpoints_v{v}.md`, count unconfirmed `Major` entries deterministically, return non-zero exit code when blocked, and print both the count and blocking reason.
- Initial HITL file template (machine-readable, user-friendly) to use when `.pdm/ai_delivery_engine/hitl_checkpoints_v{v}.md` must be created:
```yaml
format_version: 1
ordering: latest-first
entry_template:
user_name: ""
created_by_engine: "Yes|No"
validated_by_human: ""
checkpoint_id: "HITL-0001"
checkpoint_type: "functionality-change"
checkpoint_role: "Delivery Manager|Architect|Tester"
change_severity: "Standard|Major"
verification_source: "executed|human|cross-model|prior-artefact|model-self-report-unverified"
artefacts_inspected:
- "/path/to/artefact-the-reviewer-must-read"
artefact_reference: "/ai_delivery_engine/hitl_checkpoints_v{v}.md"
description: ""
links:
- "/path/to/changed-file-or-artefact"
date_time: "YYYY-MM-DD HH:mm:ss Â±HH:mm"
```
- For every newly created markdown artefact in `.pdm` and for any file relevant to the AI delivery engine, add `## Product Name` directly under the title line. Keep the attribution comment `` directly below the product-name block.
- Prefer lower-cost model/tool routing when behavior and quality constraints are still satisfied
## Engine Initialisation (routed, load on demand)
Initialisation content is held in `.pdm/ai_delivery_engine/ai_delivery_engine_initialisation_v{v}.md`,
an essential file that is never generated or overwritten. Read it ONLY when initialising or
repairing the engine: `ai_delivery_engine_initialisation.ps1` absent, a gate script missing, or a Bootstrap
Registry artefact missing. Do NOT load it during routine per-message processing.
It holds the Bootstrap Specification, Tier 1/Tier 2 procedure, bootstrap script requirements, the
Bootstrap Registry, CSV column orders, Gate Behaviour Specifications, the No-Stub Rule, the
Mandatory Gate Output Contract, the Gate Falsifiability Self-Test and post-initialisation
obligations. Those rules are authoritative there and MUST NOT be restated here.
Initialisation is NOT complete when the registry files exist. It is complete when the gates have
been run AND self-tested. An engine reported as initialised without a passing self-test MUST be
treated as uninitialised.
<!-- Load when: a markdown artefact under .pdm/ is being created or edited.
A message that writes no artefact cannot violate a header format rule. -->
## Artefact Header Format (Tier 2)
`Load when:` creating or editing any markdown artefact under `.pdm/`.
Every generated markdown file MUST begin with the attribution comment, a blank line, an `# Title`
heading, a blank line, `## Product Name`, and the product name.
Every markdown artefact under `.pdm/` MUST then carry an `## Artefact Metadata` block immediately
after the product name, with these fields in this order:
```
## Artefact Metadata
- Created: YYYY-MM-DD HH:mm:ss +HH:mm
- Created By: engine|human
- Stage: intent|prompt|epic|feature|constraint|context|test|test-result|engine
- Work Item: <identifier shared by every artefact for the same unit of work>
- Timestamp Source: engine-clock|filesystem-creation-time|human-declared
```
`Created` is immutable once written and MUST NOT be updated on edit. `Timestamp Source` records how
the value was obtained and MUST be truthful: `filesystem-creation-time` is an approximation applied
when stamping artefacts that predate this rule, and is weaker than `engine-clock`. Timestamps MUST
NOT be reconstructed, inferred or estimated; where no source exists the artefact is left unstamped
and counted as missing rather than given a plausible value.
`Work Item` is the join key across the lifecycle. Artefacts belonging to the same unit of work MUST
share it, otherwise lead time cannot be computed.
<!-- Load when: a stage transition is being recorded. Note the release rule is ALSO
restated in copilot-instructions.md, so the prohibition on self-declaring a
release survives even if this section is never loaded. -->
## Lifecycle Ledger Rules (Tier 2)
`Load when:` appending to the lifecycle ledger, or recording any stage transition.
`lifecycle_events_v{v}.csv` is append-only. Rows MUST NOT be edited or deleted, because a
delivery-speed figure computed from a rewritable history is not evidence. Permitted `stage` values
are `intent`, `prompt`, `implementation`, `validation`, `release`. Permitted `event` values are
`created`, `started`, `completed`, `blocked`, `unblocked`, `released`.
The `release` stage is recorded by explicit human submission only. The engine MUST NOT infer,
schedule or self-declare a release. For this project a release means uploading the changed files by
FTP, an act the engine cannot observe, so the recorded row MUST carry `actor` naming the person and
`verification_source: human`.
## Evidential Independence Enforcement
The rules themselves - the closed `verification_source` list, what is admissible, what is
inadmissible, and the prohibition on self-assessed `PASS` - are defined ONCE, in
`.pdm/ai_delivery_engine/evidential_independence_v{v}.md`, which is Tier 1 and therefore loaded on
every message. They are not restated here; a second copy would drift and the drifted copy would
still read as authoritative.
This section defines only the ENFORCEMENT obligations that belong to the engine:
- Run `.pdm/ai_delivery_engine/per_message_deterministic_script.ps1 -Phase post`, which contains the
independent-verification block, before response closure; a non-zero exit blocks completion.
- Do not allow release progression while any required result is `UNVERIFIED`.
- Do not author acceptance criteria and implementation in the same generation act for
behavior-affecting work. Criteria must be human-authored, human-confirmed, or adversarially
generated by a separate model before implementation is accepted.
## Human-in-the-Loop Enforcement Constraints
- Mandatory human checkpoints (engine MUST NOT self-approve any of these):
1. intent creation or intent change
2. user-visible behavior, business rule, route, or data-contract change
3. security, authentication, authorization, privacy, or personal-data change
4. database schema change (additive or destructive)
5. release approval
6. cost or risk threshold breach
7. engine self-reported inability to validate its own output
8. delivery to production while the deterministic pre-production CVE check required by `generated_code_security_v{v}.md` GS-02.1 is absent, unenforced or `UNVERIFIED`. The engine MUST NOT treat an absent CVE mechanism as "not applicable" on the grounds that no dependency changed, nor satisfy the check by its own assessment of whether a component is vulnerable.
- Checkpoint authority model (engine holds no approval authority):
- Delivery Manager: scope and release; cost/risk escalation where no dedicated Risk Manager exists
- Risk Manager: cost/risk thresholds and escalation
- Architect: security, privacy, compatibility
- Tester: acceptance of behavior validation evidence
- Developer: may prepare, may not approve
- Every checkpoint entry MUST record reviewer identity, role, decision, rationale, artefacts inspected, linked evidence, change severity, and timestamp.
- The engine MUST record `artefacts_inspected` so a reviewer decision cannot rest on an engine-authored summary alone.
- The engine MUST NEVER set `validated_by_human`; only a human reviewer may set it.

- Mandatory hard-stop preflight gate: run `.pdm/ai_delivery_engine/per_message_deterministic_script.ps1 -Phase pre` before any planning, editing, testing, or generation action
- Apply cost guardrails per prompt execution and update prompt cost records

- Enforce CSRF and auth checks in every state-changing change
- Preserve data/downloads protection rules
- Keep output and logs free from secrets/PII
- Use prepared statements for DB interactions
- Validate and sanitise all external input
- Escape output unless intentionally sanitized HTML
- Preserve secure and SEO-friendly delivery outcomes (canonical routing, crawl controls, machine-readable sitemap)
## Validation Guardrails
- security.csrf: required for every state-changing request
- security.auth: required for privileged flows
- database.migration: additive only
- compatibility.routes: no existing route breakage
- privacy.logs: no secrets or sensitive PII in logs

<!-- Load when: a cost event is being appended or a budget assessed. The trust-level
separation is restated in evidential_independence (Tier 1), so the prohibition on
presenting a self-reported estimate as a measurement holds without this section. -->
## Cost Controls (Tier 2)
`Load when:` appending a cost event, regenerating a cost log, or assessing a budget threshold.
### Trust levels (never mix)
- `provider-telemetry-verified`: reconciled against an authoritative provider usage source.
- `model-self-report-unverified`: estimated by the executing model about its own consumption. These
are self-assertions, not measurements, and carry no evidential weight.
Before recording a cost event, execute `.pdm/ai_delivery_engine/cost_telemetry.ps1`, which checks
in order for provider admin/usage API credentials in environment variables or an exported provider
usage file. If it finds no authoritative source, set `estimation_method: model-self-report` and
`verification_status: unverified`, leave `actual_total` empty, and never present the figure as an
actual cost. Variance escalation applies only to `verified` rows. Reports including unverified rows
MUST carry a visible unverified notice.

### Cost artefacts and logging rules
Artefacts live under `.pdm/ai_delivery_engine/`: `prompt_cost_events_v{v}.csv` and
`interaction_cost_events_v{v}.csv` (append-only source of truth), `prompt_cost_log_v{v}.md` and
`interaction_cost_log_v{v}.md` (generated, latest-first), plus `cost_manager.ps1` and
`cost_telemetry.ps1`. Response closure is governed by the `Response Completion Gate` section of this manifest.
During initialisation, create any missing cost artefact before the first cost-tracked execution.
- Both ledgers MUST include `estimation_method` and `verification_status`.
- Each interaction captures pre-send estimate, post-response estimate, and actual cost if available.
- Each prompt run records: model identifier, estimated input tokens, estimated output tokens,
estimated tool-call count, estimated total USD, and actual total USD if available.
- Append rows and recalculate summaries via `cost_manager.ps1`; regenerate markdown logs after every
ledger update and persist accumulated totals.
- Append prompt cost events only for app-functionality-relevant work; treat response completion as
failed until the interaction append and recalculation checks pass.
- Alerts: warn when the estimated total exceeds the prompt-level budget; escalate to the Delivery
Manager via `messages_from_the_engine.md` when verified variance exceeds 20%. Fixed alert
thresholds live in `prompt_cost_log_v{v}.md`.
## Messages from the AI delivery engine to the users
Write all messages for humans in `.pdm/ai_delivery_engine/messages_from_the_engine.md`. For every message, add the date/time and recipient role. Use only roles referenced in `.pdm/AI-native Delivery Experience - IntDEx_v{v}.md`. The latest message must appear first.
## Mandatory Governance File Order/Hierarchy (Per Chat Message)
This is a PRECEDENCE order, not a reading list. It governs which artefact wins when two conflict,
and the order in which loaded artefacts are applied. Which artefacts are loaded is governed by the
Context Loading Policy above.
Always applied, in this order:
1. `.github/copilot-instructions.md`
2. `.pdm/ai_delivery_engine/ai_delivery_engine_manifest_v{v}.md` (Tier 1 sections)
3. `.pdm/ai_delivery_engine/ethics_constraints_v{v}.md`
4. `.pdm/ai_delivery_engine/evidential_independence_v{v}.md`
5. Every file present in `.pdm/constraints/`, if any
6. Every file present in `.pdm/contexts/`, if any
Project constraints are applied BEFORE context. Where a context file describes a behaviour that a
project constraint forbids, the constraint wins; a description must never be read as a permission.
Applied in this order when their Tier 2 trigger fires, after the above. This list MUST contain
every artefact named in the Tier 2 trigger table; an artefact that can be loaded but has no
precedence position is an under-defined conflict:
7. `.pdm/ai_delivery_engine/governance_v{v}.md`
8. `.pdm/AI-native Delivery Experience - IntDEx_v{v}.md`
9. `.pdm/ai_delivery_engine/ai_delivery_engine_initialisation_v{v}.md`
10. `.pdm/ai_delivery_engine/engine_capability_boundary_v{v}.md`
11. `.pdm/ai_delivery_engine/incident_autonomy_v{v}.md`
12. `.pdm/ai_delivery_engine/untrusted_content_v{v}.md`
13. `.pdm/ai_delivery_engine/generated_code_security_v{v}.md`
14. `.pdm/ai_delivery_engine/release_checklist_v{v}.md`
15. `.pdm/ai_delivery_engine/artefact_traceability_v{v}.md`
16. `.pdm/ai_delivery_engine/functionality_coverage_matrix_v{v}.md`
17. `.pdm/ai_delivery_engine/risk_log_v{v}.md`
18. `.pdm/ai_delivery_engine/prompt_cost_log_v{v}.md`
19. `.pdm/ai_delivery_engine/interaction_cost_log_v{v}.md`
Record "reviewed, no change required" for any artefact a task does not affect. Record "not loaded,
trigger did not fire" for a Tier 2 artefact that was not read, and never imply it was reviewed.
Ethical precedence is unaffected: EC-07 overrides every artefact in this list, including this one.
## Reference Integrity Convention (Tier 1)
A governance rule is enforced by being READ. A rule citing a path that does not exist still reads
as authoritative and is silently unenforceable, so every path named in an artefact MUST resolve.
Three reference spellings are checked and are equally binding: backticked file paths, backticked
`.pdm/` folder paths, and plain-text engine filenames. A reference is not exempt from this rule
because of how it happens to be punctuated.
Where a path is absent BY DESIGN - a retired artefact named so a reader does not look for it, or a
negative reference naming a path that must never be created - the line MUST carry an inline
`` marker, and the surrounding prose MUST state that the path is
absent deliberately. Marked references are reported as INTENTIONAL at initialisation, never
silently dropped. The marker records a decision; it MUST NOT be used to silence a genuine break,
and adding it to a reference that was meant to resolve is a governance defect, not a fix.
## Response Completion Gate (Tier 1, merged 2026-09-13)
Merged here from the retired artefact `response_completion_gate_v{v}.md`,
which is deliberately absent and MUST NOT be recreated.
Rationale: this list is consulted at the close of every response, so holding it in a separate file
added a load step and an artefact to forget without adding any control. The wording below is
unchanged from the retired file.
Close every response against these nine points:
1. State which gates were run and quote their literal output; never paraphrase a gate message.
2. Label every result with a `verification_source`; record `UNVERIFIED` where the only support is
the engine's own report.
3. Never round an `UNVERIFIED` result up to a `PASS`.
4. Carry an `ethics_assessment` on any result touching ethics.
5. State explicitly that a passing ethics gate is not ethical clearance.
6. Report validation and regression outcomes before declaring any task complete.
7. Report any artefact created or updated, with its path.
8. Report risk or migration impact, and any local runtime mismatch that prevented execution.
9. Never self-declare a release; releases are human-submitted only.
## Domain Context and Project Constraints
Domain context is referenced in `.pdm/contexts/` and project constraints in `.pdm/constraints/`.
Consider all files in both folders. Both are human-owned and are created empty; the engine MUST NOT
generate an artefact into either. Whenever context is consulted, the constraints folder MUST be
consulted in the same act, and any constraint found there is binding on the work in hand.
## Risks
- Local runtime mismatch can produce false-negative syntax checks
- Single-file architecture increases regression blast radius
- Multiple errors under single-model authorship: intent, prompt, implementation, test and result authored by the same model can be consistently wrong while appearing fully traceable and green. Mitigated by the Evidential Independence Constraints above and by the independent-verification block of `.pdm/ai_delivery_engine/per_message_deterministic_script.ps1`.
- False precision in cost records: unverified self-reported token estimates presented as measurements. Mitigated by the Cost Telemetry Verification Policy above and by `.pdm/ai_delivery_engine/cost_telemetry.ps1`.
## Architectural Notes
This project uses a behavior-first, safety-first update strategy. Code structure is not prescribed; only contract-compliant behavior is required.

ai_delivery_engine_manifest_v1.md

Comments

Before you continue