ai_delivery_engine_initialisation_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

The engine BUILD SPECIFICATION. ai_delivery_engine_initialisation.ps1 (if exists) is an implementation of it;
this file is the contract that a deterministic script/buidl mechanism must satisfy. Lose the script and a competent model rebuilds
it from this file alone. That is why this is a seed and the script is not.

READ ONLY when initialising or repairing. NEVER during routine per-message work: the split exists
to keep this cost off every message. The essential-files gate prints a SCOPE line telling you which
situation you are in.

TO REUSE ON A NEW PROJECT edit only: (1) Product Name, (2) the Created timestamp, ONCE, and
(3) the Bootstrap Registry, if your organisation needs an extra register - and then you MUST add
the code that emits it to the script in the same work item.

DO NOT EDIT the Gate Behaviour Specifications, Output Contract, Self-Test or No-Stub Rule. They are
observable-behaviour contracts that make independently authored gates interchangeable. Loosening a
pass condition here loosens it everywhere, permanently, and the loosened gate still reports PASS.
-->

# AI Delivery Engine Initialisation (v{v})

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

<!-- SETTING 2: reset "Created" ONCE when copying to a new project. -->
## Artefact Metadata
- Created: 2026-09-03 13:40:00 +02:00
- Created By: human
- Stage: engine
- Work Item: manifest_split
- Timestamp Source: engine-clock

## Governing Principles
Four principles generate most of the rules below. They are stated once here and referenced by name
rather than restated.

- **P1 Seeds vs derived.** The essential files are listed in ONE place: the marker block in
  `.pdm/ai_delivery_engine/ai_delivery_engine_manifest_v{v}.md` between `INTDEX_ESSENTIAL_FILES_START`
  and `INTDEX_ESSENTIAL_FILES_END`. They are human-owned and MUST NEVER be generated or overwritten.
  Everything else under `.pdm/` is derived and MUST be reproducible from the seeds alone. Bootstrap
  never overwrites an existing file, so re-running is always safe and idempotent.
- **P2 False assurance is worse than absence.** A control that reports success while enforcing
  nothing satisfies the per-message procedure and makes every downstream control decorative, while
  continuing to display success. Wherever this file offers a choice between failing loudly and
  passing quietly, fail loudly. A known gap is recoverable; a false pass is not.
- **P3 Presence is not function.** Creating a filename is not creating an artefact. Counts, file
  presence and reference-integrity scans are all satisfied by an empty shell. Only content
  comparison and the self-test distinguish a working engine from a plausible-looking one.
- **P4 The engine holds no authority over itself.** It MUST NOT author its own ethical constraints,
  autonomy scope or capability boundary. A limit the engine wrote about itself is a self-granted
  permission and will be obeyed exactly as far as it is convenient.

## Status and Loading Rule
This is an **essential file** (P1), enforced by the essential-files block of
`per_message_deterministic_script.ps1`.
Load it ONLY when initialising or repairing: the bootstrap script is absent, a gate script is
missing, or a Bootstrap Registry artefact is found missing. Loading it during routine work while
the gate reports the engine COMPLETE is a context-scope error and MUST be reported as one.
It is authoritative for initialisation and defines the process so that any model, provider family
or agent host produces the same end state. No specific command phrasing triggers it.

**Why one file sits outside `.pdm/`.** `.github/copilot-instructions.md` is the only file the agent
host injects automatically, so it is the sole entry point through which anything else is reached and
cannot be relocated or merged. Its size is a recurring per-message cost; initialisation content is
needed rarely, so it lives here and loads on demand. This does not weaken reproducibility, because
this file is a seed, not a derived artefact. Were it derived, a workspace missing the bootstrap
script would also be missing the instructions for recreating it, and self-heal would be impossible.

## Initialisation Procedure

### Tier 1 (preferred, deterministic)
Relax the PowerShell execution policy for the current process only, then run
`.pdm/ai_delivery_engine/ai_delivery_engine_initialisation.ps1` with `-WorkspaceRoot` and
`-OperatingModel`. That is the whole procedure. It creates the gate scripts AND runs them, and
records the Continuous Behaviour Validation baseline. Two models running it produce byte-identical
artefacts.

`-WorkspaceRoot` is the authoritative scope setting. If omitted the script may auto-discover the
root by walking up to the first folder containing `.pdm`, but generated artefacts MUST treat the
resolved value as current scope and never hardcode historical paths.

Gate script names, their order and their exit-code meanings are internal to the engine and MUST NOT
appear in any initialisation instruction. Requiring a human to remember five script names moves
engine knowledge into human memory, where it decays, and a gate nobody remembers to run is not a
control. After initialisation, state explicitly that the workspace is governed but unvalidated.

If a gate script or any derived artefact is missing during routine operation, re-run the bootstrap;
it regenerates whatever is absent without touching what exists (P1). Never hand-author a derived
engine file. Any model from any provider family MUST be able to do this: depend on no feature
specific to one assistant product or IDE.

### Tier 2 (fallback, bootstrap script missing)
Author the script from this specification, then run Tier 1. MUST NOT hand-create derived artefacts
one by one while leaving the script absent; that reintroduces per-model variation and leaves the
workspace unable to self-heal.

Tier 2 is a REBUILD of the generator, not a sketch. Its output MUST be shippable as the canonical
bootstrap for every future workspace. A file that merely has the right name, or prints progress
without writing engine logic, is a Tier 2 FAILURE and MUST be reported as one.

Build in this order; each step depends on the one before:

1. **`engine_paths.ps1` first.** Every gate dot-sources it. Implement `Get-IntdexRoot`,
   `Resolve-IntdexPath` (including `{v}` highest-version resolution) and `Get-IntdexEssentialFiles`
   (parsing the manifest marker block). A gate written before this exists will hardcode paths.
2. **Each gate body in full**, to `Gate Behaviour Specifications` and the `Mandatory Gate Output
   Contract`. Write the real parsing, scanning and counting logic; a gate MUST derive its exit code
   from what it observed on disk in this run.
3. **Embed every body** in the generator as a single-quoted here-string, per `Engine Script Bodies`.
4. **Every registry artefact**, to the substance floor in `No-Stub Rule`.
5. **Run the generator**, then run the `Gate Falsifiability Self-Test`. A generator that has not
   been executed has not been written: a here-string is opaque to the parser, so its contents are
   unverified until they run.

If a gate's logic cannot be implemented, write it to exit `3` with an explicit `NOT-IMPLEMENTED`
message naming the gate, report the gap in the summary and in `engine_capability_boundary_v{v}.md`
with `Enforced by: Nothing`. MUST NOT write a gate that exits `0` (P2).

### Bootstrap script requirements
`ai_delivery_engine_initialisation.ps1` MUST:
- accept `-WorkspaceRoot`, optional `-WhatIfReport` (report-only), optional `-OperatingModel` and
  optional `-SkipGates` (diagnostic);
- verify the essential files FIRST and exit `1` with the hard-stop message if any is missing;
- be SELF-CONTAINED: carry the body of every executable engine script it creates, depending on
  nothing outside the seeds (see `Engine Script Bodies`);
- never overwrite an existing file (P1);
- create every folder and file in the Bootstrap Registry;
- regenerate the markdown cost reports from the CSV ledgers, and the metrics report from the engine
  artefacts;
- stamp any markdown artefact under `.pdm/` lacking an `## Artefact Metadata` block;
- verify governance reference integrity and report dangling references;
- RUN every gate it created, in per-message order, print each gate's own output verbatim, and
  summarise every exit code;
- COMPARE CONTENT, not only presence (P3). Re-materialise every embedded script body and compare it
  byte-for-byte by hash against the live `.ps1`; compare the `## ` section structure of every
  embedded markdown seed against the live artefact. Report any mismatch as `DRIFT` naming the file.
  This is the only mechanical detection of a double-edit violation that exists; without it a
  bootstrap reports `Created: 32 / Failed: 0` while reproducing a degraded engine. Structural, not
  byte, comparison is used for markdown because a live register legitimately diverges once
  customised: a MISSING SECTION is drift, differing prose is not;
- record the initial CBV baseline AFTER the gates have run, so it reflects the state they ran
  against;
- SELF-TEST every gate per `Gate Falsifiability Self-Test`, and fail initialisation if any gate
  cannot be made to return non-zero. Running a gate proves it executes; only the self-test proves it
  decides;
- VERIFY the `No-Stub Rule` substance floor for every artefact written, reporting shortfalls by name;
- print that EC-01 to EC-08 are active and unauthored, and name authoring them as the first required
  human action;
- exit `0` on success; `1` if a blocking gate did not pass, any gate failed the self-test, or any
  artefact fell below its substance floor; `3` on write failure. Self-test and substance-floor
  failures are exit `1`, never a warning (P2);
- depend only on Windows PowerShell 5.1 built-ins: no network, no LLM call.

A non-zero exit from `cost_telemetry.ps1` is NOT blocking; `2` is its normal unverified result and
MUST be reported as such rather than as an error.

## No-Stub Rule (normative)
The Bootstrap Registry lists files that must EXIST AND FUNCTION (P3). A registry of filenames is
trivially satisfiable by writing thirty headings, and the result passes every presence check, file
count and reference scan while containing no engine.

These are FAILURES, not partial successes, and MUST be reported as such with a non-zero exit:

- A `.ps1` that prints a message and exits without the observable behaviour specified for it.
  `Write-Host 'gate: ready'; exit 0` is not a gate.
- A `.ps1` whose exit code is a literal constant rather than derived from what it observed this run.
  Every gate MUST have at least one reachable input state producing a non-zero exit.
- A markdown register consisting only of a title, `## Product Name` and `## Artefact Metadata`
  where the registry requires seeded rows, a template or defined sections.
- Any `TODO`, `TBD`, `placeholder`, `stub`, `to be implemented`, `coming soon`, or empty section
  body in any derived artefact.
- A generator that writes artefacts but does not carry every engine script body, and so cannot
  rebuild from the seeds alone.

**Substance floor.** Floors, not targets, stated numerically only so failure is mechanically
detectable rather than a matter of judgement. Meeting a floor does not make a file correct; falling
below one makes it certainly incomplete.

| Artefact class | Minimum | Must contain |
|---|---|---|
| `engine_paths.ps1` | 30 non-comment lines | All three exported functions, `{v}` highest-version resolution, manifest marker parsing |
| `per_message_deterministic_script.ps1` | 200 non-comment lines | Five distinct, separately callable blocks; `pre`, `post`, `all`, `baseline` phases; per-block output and exit aggregation |
| `code_security_gate.ps1` | 40 non-comment lines | At least 4 GS-03 and 4 GS-04 patterns, a real file walk, a skip list, the GS-01/GS-02 unenforced disclosure |
| `cost_manager.ps1`, `metrics_report.ps1`, `lifecycle_manager.ps1`, `cost_telemetry.ps1` | 40 non-comment lines each | Their `-Mode`/`-Phase` parameters, real file I/O, the specified exit-code range |
| `ai_delivery_engine_initialisation.ps1` | All engine script bodies, plus every registry seed | Self-containment: seeds plus this file build a complete engine |
| Seeded register (`risk_log`, `ethics_constraints`, `incident_autonomy`, `engine_capability_boundary`) | Every row the registry names | R-001 to R-009, EC-01 to EC-08, CB-01 to CB-07, both incident criteria, as applicable |
| Template register (`hitl_checkpoints`) | Full `entry_template` | Every field in the manifest's HITL minimum-field list |
| Ledger CSV | Header row | Exactly the normative column order, unreordered |
| Generated report (`metrics_report`, cost logs, `artefact_traceability`, `functionality_coverage_matrix`) | Written by its generator, not by hand | Values computed from artefacts on disk, `NOT-COMPUTABLE` where input is absent |

A model that cannot meet a floor MUST say so explicitly, naming the artefact and shortfall. It MUST
NOT pad to reach a line count, and MUST NOT silently emit less.

## Engine Script Bodies
Every executable engine script is carried inside the bootstrap as a single-quoted here-string. That
file plus the seeds is a complete engine.

An external source folder was tried and reverted: it removed the double-edit rule but made the
generator depend on twelve files instead of one, and its copy was byte-identical, so it bought no
transformation, only distribution fragility.

**DOUBLE-EDIT RULE (normative).** Each engine script exists twice: the live `.ps1` and the embedded
copy. A change to one MUST be applied to the other in the same work item. A fix applied only to the
live copy works today and disappears at the next bootstrap.

This has already failed in practice: six of eleven embedded bodies were once found drifted, and the
embedded lifecycle manager still referenced a methodology filename that no longer existed. Every
clean-room rebuild in that period reported success while reproducing a degraded engine, because
verification counted files and compared references but never compared CONTENT. Two consequences:

- Verification MUST compare content, not counts (P3). Hash comparison of each generated `.ps1`
  against the live one is what detects a double-edit violation, and MUST run whenever a script
  changes.
- A here-string is opaque to the parser, so a syntax error inside one is undetectable until the
  generated script runs. An edit to an embedded body MUST be validated by executing the generated
  script, never by inspection alone.

## Bootstrap Registry

**Folders:** `.pdm/ai_delivery_engine`, `.pdm/epics`, `.pdm/features`, `.pdm/intents`,
`.pdm/prompts`, `.pdm/contexts`, `.pdm/constraints`, `.pdm/tests/prompts`,
`.pdm/tests/prompts/results`. No other folder may be created.

No subfolder of the results tree is created at initialisation: filing subfolders are a readability
measure only, created by a human if wanted, never assumed. Every scanner reading result artefacts,
in particular the independent-verification block and `metrics_report.ps1`, MUST nevertheless recurse
into that tree. A subfolder that escaped the gate would let a workspace clear an inadmissible `PASS`
by moving the file, converting a governance control into a filing convention.

`.pdm/contexts` and `.pdm/constraints` are created EMPTY and are human-owned; the engine MUST NOT
generate an artefact into either (P4). An engine-authored description of product and stack
duplicates sections 1-3 of `.github/copilot-instructions.md` and drifts from it with nothing to flag
the contradiction. `.pdm/constraints` holds PROJECT constraints per IntDEx section 6.5 `Context and
Constraint Dependent`: sovereignty, regulatory, data-residency, cost, performance, accessibility and
domain rules. It exists from initialisation so the place to put them precedes the first intent, and
is loaded in Tier 1 alongside `.pdm/contexts` so constraints are never read later than the context
they bound. An empty folder is not a defect and MUST NOT be reported as one.

No scratch or temporary folder may be created anywhere under `.pdm/`. Transient output belongs in
the operating system temporary directory; under `.pdm/` the stamping pass and reference scan would
both treat it as a governed artefact.

The reference-integrity scan checks backticked file paths, backticked `.pdm/` folder paths AND
plain-text engine filenames, because a reference naming a missing path misleads regardless of its
punctuation. Prefer describing an absent path to naming it; where naming is unavoidable, mark it per
the manifest section `Reference Integrity Convention`.

**Files**, with the content each must contain (all under `ai_delivery_engine/` unless shown):

| File | Required content |
|---|---|
| `ai_delivery_engine_initialisation.ps1` | This specification, implemented. Carries every engine script body. |
| `engine_paths.ps1` | Shared versioned-path resolver, dot-sourced by the gates. Written first; the gates depend on it. |
| `per_message_deterministic_script.ps1` | Block 1 core-file hard stop, Block 2 unvalidated Major checkpoint gate, Block 3 mechanically decidable ethics gate, Block 4 configuration-drift demand (warn-only), Block 5 evidence admissibility. Phases `pre`, `post`, `all`, `baseline`. |
| `code_security_gate.ps1` | GS-03 secret shapes and GS-04 insecure defaults, by pattern matching only. |
| `cost_telemetry.ps1` | Deterministic verified/unverified probe. |
| `cost_manager.ps1` | Ledger append, schema migration, report rebuild. |
| `metrics_v{v}.md` | Metric definitions, each with data source and verification tier. |
| `metrics_report.ps1` | Deterministic metric computation over engine artefacts. |
| `metrics_report_v{v}.md` | Generated; never hand-edited. |
| `lifecycle_events_v{v}.csv` | Header row only. Append-only stage-transition ledger. |
| `lifecycle_manager.ps1` | Metadata stamping, stage-event append, manual release flag. |
| `prompt_cost_events_v{v}.csv`, `interaction_cost_events_v{v}.csv` | Header row only. |
| `prompt_cost_log_v{v}.md`, `interaction_cost_log_v{v}.md` | Generated from their ledgers. |
| `hitl_checkpoints_v{v}.md` | YAML block, `entries: []`, full `entry_template`. |
| `artefact_traceability_v{v}.md` | GENERATED by `metrics_report.ps1` every run from the `Work Item` field of every artefact under `.pdm/`. Never hand-edited, never seeded empty: an empty register nobody populates is documentation, not a control. |
| `functionality_coverage_matrix_v{v}.md` | GENERATED every run from the same work-item grouping, joined to result artefacts and their declared `verification_source`. Never hand-edited. |
| `cbv_baseline_v{v}.md` | CBV baseline. Written by `-Phase baseline`, not by the bootstrap directly, so it records the state the gates actually ran against. |
| `risk_log_v{v}.md` | Seven-column table seeded R-001 to R-009. |
| `ethics_constraints_v{v}.md` | EC-01 to EC-08, EC-07 operating rules, limits-of-mechanical-enforcement statement, tiering rule, empty determination ledger. |
| `release_checklist_v{v}.md` | Checklist plus a not-releasable release status. |
| `intent_prompt_rebuild_log_v{v}.md` | Empty rebuild-evidence table. |
| `messages_from_the_engine.md` | Table plus the initialisation message. |
| `user_chat_messages_log.md` | Empty latest-first table. |
| `user_stories_engine_created.md` | Latest-first heading. |
| `evidential_independence_v{v}.md` | Admissible and inadmissible evidence rules. |
| `untrusted_content_v{v}.md` | UC-01 to UC-08, unenforced rules recorded as open gaps, never as satisfied. |
| `generated_code_security_v{v}.md` | GS-01 to GS-07 and RR-01 to RR-05, unenforced rules as open gaps. |
| `incident_autonomy_v{v}.md` | Criteria A severity (WHEN), Criteria B change-type matrix (WHAT), plan pre-approval rule, autonomy-scope drift rule, empty adoption ledger. Seeded closed, per `Seeded-Closed Artefacts`. |
| `engine_capability_boundary_v{v}.md` | CB-01 to CB-07: read, write, execute, egress, installation and credential scope, each as `Observed today` / `Proposed boundary` / `Enforced by` / `Open question`. Seeded closed. Where no script enforces a row, `Enforced by` MUST read `Nothing` rather than being left implied. |

**CSV column order is normative and MUST NOT be reordered:**
- prompt: `timestamp,event_type,model,estimated_input_tokens,estimated_output_tokens,estimated_tool_calls,estimated_total_usd,actual_total_usd,estimation_method,verification_status,notes`
- interaction: `timestamp,interaction_id,event_phase,model,estimated_input_tokens,estimated_output_tokens,estimated_tool_calls,estimated_total_usd,actual_total_usd,estimation_method,verification_status,notes`
- lifecycle: `timestamp,work_item,stage,event,actor,verification_source,notes`

Markdown header format and the `## Artefact Metadata` block are specified in the per-message
manifest and are not restated here.

### Licence attribution (normative)
Every derived artefact MUST carry the IntDEx CC BY 4.0 attribution as its FIRST content, not only
markdown ones. An engine that attributes its prose but not its code distributes the part most likely
to be copied with no licence attached. Syntax MUST be correct for the language: an attribution that
breaks the parser is worse than a missing one.

| File type | Required first line | Placement |
|---|---|---|
| Markdown | `<!-- AI-native Delivery Experience - IntDEx. Provided under CC BY 4.0. https://IntDEx.org -->` | Line 1 |
| PowerShell | `# AI-native Delivery Experience - IntDEx. Provided under CC BY 4.0. https://IntDEx.org` | After `#requires`, before comment-based help |
| CSV | None | A comment line would corrupt the header row and every parser reading it |

HTML comment syntax MUST NOT appear in a `.ps1`: it is a syntax error and would make the script
unloadable. `#requires` MUST remain line 1, since PowerShell honours it only there. This rule
applies to embedded bodies too, and is therefore subject to the DOUBLE-EDIT RULE.

## Gate Behaviour Specifications
Observable behaviour, not implementation, so independently authored scripts are interchangeable.
`per_message_deterministic_script.ps1` is abbreviated `PMDS` below.

| Gate | Input | Pass condition | Exit codes |
|---|---|---|---|
| PMDS Block 1 essential files, `pre` | Essential-file list from manifest markers | Every listed file present | `0` pass, `1` block with hard-stop message and missing list. MUST also print an advisory `SCOPE` line stating whether the engine is COMPLETE or INCOMPLETE, determined solely from derived marker artefacts and never from essential files, which are always present whenever this gate can pass. When COMPLETE it names the initialisation-scope artefacts as out of scope for routine work; when INCOMPLETE it lists absent markers and routes repair to the bootstrap. The advisory MUST NEVER block |
| PMDS Block 2 HITL major, `pre` | `hitl_checkpoints_v{v}.md` | Unvalidated `Major` entries `<= 3` | `0` pass, `1` block; always prints the unvalidated count |
| PMDS Block 3 ethics, `pre` | `ethics_constraints_v{v}.md`, `.pdm/` and product source, test results | Artefact present and no mechanically decidable violation of EC-01, EC-03, EC-05 or EC-08. An `AWAITING-HUMAN-AUTHORING` definition WARNS while the workspace holds no delivery artefact and BLOCKS as soon as one exists. MUST always print EC-02, EC-04, EC-06, EC-07 as not adjudicated and MUST NEVER report them passed | `0` no mechanical violation, `1` block or artefact missing, `3` scan failure |
| PMDS Block 4 CBV drift, `post` and `baseline` | The essential files, resolved via `engine_paths.ps1`, against `cbv_baseline_v{v}.md` | Watched-surface hashes match the baseline and the operating model is unchanged | `0` always in check; drift WARNS and never blocks; `3` scan failure. MUST warn, not fail, when no baseline exists, and MUST warn when re-baselining on `model-self-report-unverified` evidence |
| PMDS Block 5 independent verification, `post` | `.pdm/tests/prompts/results/*.md` | Every file asserting `PASS` declares a `verification_source` of `executed`, `human`, `cross-model` or `prior-artefact` | `0` pass, `1` block listing each violation |
| `code_security_gate.ps1` | Product source and `.pdm/` artefacts | No match among implemented GS-03 / GS-04 patterns | `0` no finding, `1` finding requiring human triage. MUST print that GS-01 (SAST) and GS-02 (dependency/CVE) remain unenforced, and that absence of findings does not mean secure |
| `cost_telemetry.ps1` | Usage file, provider API credentials, or metrics config | An authoritative source is found | `0` verified, `2` unverified (normal, not an error), `1` probe failure |
| `metrics_report.ps1` | Registry artefacts, HITL register, risk log, test results, cost ledgers, core files | All metrics computed and the report written | `0` success, `1` a required input is missing, `3` write failure |
| `lifecycle_manager.ps1` | `-Mode stamp` markdown under `.pdm/`; `-Mode append`/`-Mode release` the lifecycle ledger | Stamping adds metadata only where absent and never alters an existing `Created`; appends are additive and preserve column order | `0` success, `1` invalid stage/event/arguments or a release without an actor, `3` write failure |
| Bootstrap embedded-body drift check | Every embedded script body and markdown seed, against the live artefact | Every `.ps1` body matches after line-ending normalisation, and every required `## ` section of a seed is present in the live register | Advisory. Reports `DRIFT` per file and carries the count into the summary. MUST NOT block, because a drifted engine still needs to be buildable to be repaired, but the count MUST appear where it cannot be missed |

`lifecycle_manager.ps1` MUST be idempotent in `-Mode stamp`, never rewrite an existing `Created`,
and refuse a `release` event without an actor, since an unattributed release claim is
indistinguishable from a self-declared one.

`metrics_report.ps1` MUST compute every metric from artefacts on disk only, MUST NOT infer, estimate
or narrate, and MUST mark any metric whose input is absent as `NOT-COMPUTABLE` rather than omitting
it. Metrics are indicators, never evidence: a metric value MUST NOT justify a `PASS`.

`cost_telemetry.ps1` MUST log credential environment variable **names** only, never values.
`cost_manager.ps1` MUST clear `actual_total_usd` whenever `verification_status` is not `verified`.

### Mandatory Gate Output Contract
A pass condition producing no distinguishing output cannot be audited from outside the script, and a
gate printing only its own name is indistinguishable from one that does nothing. Each gate MUST emit
at least one line carrying its identifying token AND the count it observed. The count is the
cheapest available proof that the gate inspected something: a stub can print a label, but not a
number it never computed.

| Gate / block | Token | Must also print |
|---|---|---|
| Block 1 essential files | `ESSENTIAL-FILES-GATE` | Number of essential files resolved, and the `SCOPE` advisory |
| Block 2 HITL major | `HITL-MAJOR-GATE` | Unvalidated `Major` count and the threshold |
| Block 3 ethics | `ETHICS-GATE` | Per-constraint state for EC-01/03/05/08, and EC-02/04/06/07 explicitly as `UNVERIFIED` |
| Block 4 CBV drift | `CBV-GATE` | Baseline id and number of watched surfaces compared |
| Block 5 independent verification | `INDEPENDENT-VERIFICATION-GATE` | Result files scanned and violations found |
| `code_security_gate.ps1` | `CODE-SECURITY-GATE` | Files scanned, findings count, GS-01/GS-02 unenforced disclosure |

The engine MUST NOT report a gate as run unless that gate's token appeared in THIS run's output.
Paraphrasing a gate's output, or summarising it as "gates passed", is prohibited.

### Gate Falsifiability Self-Test
Every pass condition above is satisfied by a script whose only statement is `exit 0`. Presence
checks, file counts and reference scans do not distinguish such a script from a working gate. This
self-test is the only mechanical check that does, and it MUST be implemented.

After the gates run and before the summary, the bootstrap MUST, for each gate, construct a condition
the gate is specified to reject, invoke the gate, and confirm a non-zero exit, then restore the
workspace exactly. All fixtures MUST be built under the OS temporary directory or reverted in a
`finally` block, never left under `.pdm/`.

| Gate | Injected condition | Required result |
|---|---|---|
| Block 1 essential files | `-WorkspaceRoot` pointed at an empty temporary folder | Exit `1` and the hard-stop message |
| Block 2 HITL major | Temporary HITL register holding 4 unvalidated `Major` entries | Exit `1` and the block message |
| Block 3 ethics | Temporary delivery artefact under `.pdm/intents` while definitions are unauthored | Exit `1` |
| Block 4 CBV drift | Baseline recording a different operating model | Exit `0` with a drift WARNING present |
| Block 5 independent verification | Temporary result file asserting `PASS` with no `verification_source` | Exit `1` naming the file |
| `code_security_gate.ps1` | Temporary file containing `AKIA` plus 16 upper-case alphanumerics | Exit `1` with a `GS-03` finding |

A gate returning `0` for its injected condition is NOT implemented, regardless of line count or how
plausible its source reads. The bootstrap MUST print `SELF-TEST: <gate> FAILED - gate cannot reject
its own reject condition`, name every such gate in the summary, and exit `1`. This MUST NOT be
softened (P2): an engine whose gates cannot fail is not partially working, it is a reporting surface
that returns PASS unconditionally.

## Seeded-Closed Artefacts
`ethics_constraints_v{v}.md`, `incident_autonomy_v{v}.md` and `engine_capability_boundary_v{v}.md`
MUST be created in the SAME run as every other registry artefact, never later and never on request.
An engine that can act before its constraints exist has an unconstrained window at exactly the point
it is least observed. Existing copies MUST NOT be overwritten (P1). If one is found missing during
routine operation, treat it as a repair trigger and restore it before continuing delivery work.

All three are seeded CLOSED, granting no authority, because the engine holds none over itself (P4):
- **Ethics.** EC-01 to EC-08 seeded `AWAITING-HUMAN-AUTHORING`. An unauthored definition cannot be
  adjudicated, so it MUST NOT be reported as passed.
- **Incident autonomy.** `metrics` and `plans` both EMPTY lists; status `DRAFT-ENGINE-AUTHORED`,
  under which every severity level is treated as its most restrictive neighbour and no plan may
  execute. Detection declared `deterministic-script-only`: a model MUST NOT adjudicate whether its
  own behaviour has drifted. Severity ordering seeded so autonomy DECREASES as severity increases —
  an engine acting most freely during the most severe incidents has the safety property backwards.
- **Capability boundary.** EMPTY Adoption Ledger. The engine MUST NOT seed an adopted boundary.

The Criteria B change-type matrix is not tunable by severity. A change in a mandatory human
checkpoint type — security, authentication, authorisation, privacy, schema, data contract,
user-visible behaviour, release, or engine constraints — is NEVER made autonomous by a severity
value.

**Three authoring states**, which the seed MUST define so a workspace later obtaining draft wording
has somewhere truthful to record it:

| State | Meaning | Gate effect |
|---|---|---|
| `AWAITING-HUMAN-AUTHORING` | No wording exists; cannot be adjudicated at all | WARNS pre-delivery, BLOCKS once any delivery artefact exists |
| `DRAFT-ENGINE-AUTHORED` | Drafted by the engine at explicit operator request, recorded as a Major HITL checkpoint. Not canonical, no ethical authority | WARNS; reported `UNVERIFIED` |
| `HUMAN-AUTHORED` | Authored or explicitly adopted by a named human, recorded in the Authorship Ledger | May be adjudicated per its Detection column |

The engine MUST NEVER write `HUMAN-AUTHORED` or add a row to the Authorship Ledger. A mechanical
check against `DRAFT-ENGINE-AUTHORED` wording verifies conformance to text the engine wrote about
itself, and is `script-detected` against draft wording, never `human-reviewed`.

**Pre-delivery ethics posture.** The gate MUST NOT block unconditionally either: a workspace holding
no delivery artefact has nothing to adjudicate, and blocking there deadlocks initialisation, since
the engine cannot act yet authoring the constraints is itself an action. A gate that blocks where
nothing can be harmed protects nothing and trains operators to bypass it. Therefore:
- No artefact under `.pdm/intents`, `.pdm/prompts`, `.pdm/epics`, `.pdm/features` or
  `.pdm/tests/prompts/results`: unauthored definitions WARN and the gate reports `PRE-DELIVERY
  PASS`, which is explicitly neither ethical clearance nor a pass for any delivery work.
- Any such artefact present: unauthored definitions BLOCK.

Delivery-work detection MUST be a deterministic file count; a model MUST NOT decide whether delivery
work has begun. Authoring EC-01 to EC-08 is the FIRST required human action after initialisation.

The initialisation output MUST state that EC-01 to EC-08 are active from the first message, that
EC-07 prohibits unlawful or foreseeably seriously harmful use, cannot be waived by any operator
instruction, prompt or artefact, and is assessed on assembled intent rather than the wording of a
single message, and that constraints whose `detection` is `human` are `UNVERIFIED` until a named
human reviews them, so initialisation confers no ethical clearance whatsoever.

## Post-initialisation Obligations
Initialisation produces an empty, governed workspace, not a validated one. The engine MUST report
that no delivery work has been validated, that cost control runs `model-self-report` / `unverified`
until a provider usage source is configured, that the release checklist is unticked, and that no
ethics constraint has been human-reviewed. Bootstrap success evidences engine completeness only,
never product correctness and never ethical acceptability.

It MUST report the `Gate Falsifiability Self-Test` result gate by gate, and MUST NOT describe the
engine as initialised, ready, complete or operational if any gate failed it or the self-test was not
run. "The files were created" reports file creation, not engine completeness, and the difference
between the two is the entire control surface (P3).

It MUST also report that EC-01 to EC-08 are unauthored, that the ethics gate is in its pre-delivery
warning posture, and that creating any delivery artefact before a named human authors those
definitions will block the gate. This is the obligation most likely to be deferred, because an
initialised workspace looks ready.


<!--
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
The engine BUILD SPECIFICATION. ai_delivery_engine_initialisation.ps1 (if exists) is an implementation of it;
this file is the contract that a deterministic script/buidl mechanism must satisfy. Lose the script and a competent model rebuilds
it from this file alone. That is why this is a seed and the script is not.
READ ONLY when initialising or repairing. NEVER during routine per-message work: the split exists
to keep this cost off every message. The essential-files gate prints a SCOPE line telling you which
situation you are in.
TO REUSE ON A NEW PROJECT edit only: (1) Product Name, (2) the Created timestamp, ONCE, and
(3) the Bootstrap Registry, if your organisation needs an extra register - and then you MUST add
the code that emits it to the script in the same work item.
DO NOT EDIT the Gate Behaviour Specifications, Output Contract, Self-Test or No-Stub Rule. They are
observable-behaviour contracts that make independently authored gates interchangeable. Loosening a
pass condition here loosens it everywhere, permanently, and the loosened gate still reports PASS.
-->
# AI Delivery Engine Initialisation (v{v})

## Product Name
XYZ

## Artefact Metadata
- Created: 2026-09-03 13:40:00 +02:00
- Created By: human
- Stage: engine
- Work Item: manifest_split
- Timestamp Source: engine-clock
## Governing Principles
Four principles generate most of the rules below. They are stated once here and referenced by name
rather than restated.
- **P1 Seeds vs derived.** The essential files are listed in ONE place: the marker block in
`.pdm/ai_delivery_engine/ai_delivery_engine_manifest_v{v}.md` between `INTDEX_ESSENTIAL_FILES_START`
and `INTDEX_ESSENTIAL_FILES_END`. They are human-owned and MUST NEVER be generated or overwritten.
Everything else under `.pdm/` is derived and MUST be reproducible from the seeds alone. Bootstrap
never overwrites an existing file, so re-running is always safe and idempotent.
- **P2 False assurance is worse than absence.** A control that reports success while enforcing
nothing satisfies the per-message procedure and makes every downstream control decorative, while
continuing to display success. Wherever this file offers a choice between failing loudly and
passing quietly, fail loudly. A known gap is recoverable; a false pass is not.
- **P3 Presence is not function.** Creating a filename is not creating an artefact. Counts, file
presence and reference-integrity scans are all satisfied by an empty shell. Only content
comparison and the self-test distinguish a working engine from a plausible-looking one.
- **P4 The engine holds no authority over itself.** It MUST NOT author its own ethical constraints,
autonomy scope or capability boundary. A limit the engine wrote about itself is a self-granted
permission and will be obeyed exactly as far as it is convenient.
## Status and Loading Rule
This is an **essential file** (P1), enforced by the essential-files block of
`per_message_deterministic_script.ps1`.
Load it ONLY when initialising or repairing: the bootstrap script is absent, a gate script is
missing, or a Bootstrap Registry artefact is found missing. Loading it during routine work while
the gate reports the engine COMPLETE is a context-scope error and MUST be reported as one.
It is authoritative for initialisation and defines the process so that any model, provider family
or agent host produces the same end state. No specific command phrasing triggers it.
**Why one file sits outside `.pdm/`.** `.github/copilot-instructions.md` is the only file the agent
host injects automatically, so it is the sole entry point through which anything else is reached and
cannot be relocated or merged. Its size is a recurring per-message cost; initialisation content is
needed rarely, so it lives here and loads on demand. This does not weaken reproducibility, because
this file is a seed, not a derived artefact. Were it derived, a workspace missing the bootstrap
script would also be missing the instructions for recreating it, and self-heal would be impossible.
## Initialisation Procedure
### Tier 1 (preferred, deterministic)
Relax the PowerShell execution policy for the current process only, then run
`.pdm/ai_delivery_engine/ai_delivery_engine_initialisation.ps1` with `-WorkspaceRoot` and
`-OperatingModel`. That is the whole procedure. It creates the gate scripts AND runs them, and
records the Continuous Behaviour Validation baseline. Two models running it produce byte-identical
artefacts.
`-WorkspaceRoot` is the authoritative scope setting. If omitted the script may auto-discover the
root by walking up to the first folder containing `.pdm`, but generated artefacts MUST treat the
resolved value as current scope and never hardcode historical paths.
Gate script names, their order and their exit-code meanings are internal to the engine and MUST NOT
appear in any initialisation instruction. Requiring a human to remember five script names moves
engine knowledge into human memory, where it decays, and a gate nobody remembers to run is not a
control. After initialisation, state explicitly that the workspace is governed but unvalidated.
If a gate script or any derived artefact is missing during routine operation, re-run the bootstrap;
it regenerates whatever is absent without touching what exists (P1). Never hand-author a derived
engine file. Any model from any provider family MUST be able to do this: depend on no feature
specific to one assistant product or IDE.
### Tier 2 (fallback, bootstrap script missing)
Author the script from this specification, then run Tier 1. MUST NOT hand-create derived artefacts
one by one while leaving the script absent; that reintroduces per-model variation and leaves the
workspace unable to self-heal.
Tier 2 is a REBUILD of the generator, not a sketch. Its output MUST be shippable as the canonical
bootstrap for every future workspace. A file that merely has the right name, or prints progress
without writing engine logic, is a Tier 2 FAILURE and MUST be reported as one.
Build in this order; each step depends on the one before:
1. **`engine_paths.ps1` first.** Every gate dot-sources it. Implement `Get-IntdexRoot`,
`Resolve-IntdexPath` (including `{v}` highest-version resolution) and `Get-IntdexEssentialFiles`
(parsing the manifest marker block). A gate written before this exists will hardcode paths.
2. **Each gate body in full**, to `Gate Behaviour Specifications` and the `Mandatory Gate Output
Contract`. Write the real parsing, scanning and counting logic; a gate MUST derive its exit code
from what it observed on disk in this run.
3. **Embed every body** in the generator as a single-quoted here-string, per `Engine Script Bodies`.
4. **Every registry artefact**, to the substance floor in `No-Stub Rule`.
5. **Run the generator**, then run the `Gate Falsifiability Self-Test`. A generator that has not
been executed has not been written: a here-string is opaque to the parser, so its contents are
unverified until they run.
If a gate's logic cannot be implemented, write it to exit `3` with an explicit `NOT-IMPLEMENTED`
message naming the gate, report the gap in the summary and in `engine_capability_boundary_v{v}.md`
with `Enforced by: Nothing`. MUST NOT write a gate that exits `0` (P2).
### Bootstrap script requirements
`ai_delivery_engine_initialisation.ps1` MUST:
- accept `-WorkspaceRoot`, optional `-WhatIfReport` (report-only), optional `-OperatingModel` and
optional `-SkipGates` (diagnostic);
- verify the essential files FIRST and exit `1` with the hard-stop message if any is missing;
- be SELF-CONTAINED: carry the body of every executable engine script it creates, depending on
nothing outside the seeds (see `Engine Script Bodies`);
- never overwrite an existing file (P1);
- create every folder and file in the Bootstrap Registry;
- regenerate the markdown cost reports from the CSV ledgers, and the metrics report from the engine
artefacts;
- stamp any markdown artefact under `.pdm/` lacking an `## Artefact Metadata` block;
- verify governance reference integrity and report dangling references;
- RUN every gate it created, in per-message order, print each gate's own output verbatim, and
summarise every exit code;
- COMPARE CONTENT, not only presence (P3). Re-materialise every embedded script body and compare it
byte-for-byte by hash against the live `.ps1`; compare the `## ` section structure of every
embedded markdown seed against the live artefact. Report any mismatch as `DRIFT` naming the file.
This is the only mechanical detection of a double-edit violation that exists; without it a
bootstrap reports `Created: 32 / Failed: 0` while reproducing a degraded engine. Structural, not
byte, comparison is used for markdown because a live register legitimately diverges once
customised: a MISSING SECTION is drift, differing prose is not;
- record the initial CBV baseline AFTER the gates have run, so it reflects the state they ran
against;
- SELF-TEST every gate per `Gate Falsifiability Self-Test`, and fail initialisation if any gate
cannot be made to return non-zero. Running a gate proves it executes; only the self-test proves it
decides;
- VERIFY the `No-Stub Rule` substance floor for every artefact written, reporting shortfalls by name;
- print that EC-01 to EC-08 are active and unauthored, and name authoring them as the first required
human action;
- exit `0` on success; `1` if a blocking gate did not pass, any gate failed the self-test, or any
artefact fell below its substance floor; `3` on write failure. Self-test and substance-floor
failures are exit `1`, never a warning (P2);
- depend only on Windows PowerShell 5.1 built-ins: no network, no LLM call.
A non-zero exit from `cost_telemetry.ps1` is NOT blocking; `2` is its normal unverified result and
MUST be reported as such rather than as an error.
## No-Stub Rule (normative)
The Bootstrap Registry lists files that must EXIST AND FUNCTION (P3). A registry of filenames is
trivially satisfiable by writing thirty headings, and the result passes every presence check, file
count and reference scan while containing no engine.
These are FAILURES, not partial successes, and MUST be reported as such with a non-zero exit:
- A `.ps1` that prints a message and exits without the observable behaviour specified for it.
`Write-Host 'gate: ready'; exit 0` is not a gate.
- A `.ps1` whose exit code is a literal constant rather than derived from what it observed this run.
Every gate MUST have at least one reachable input state producing a non-zero exit.
- A markdown register consisting only of a title, `## Product Name` and `## Artefact Metadata`
where the registry requires seeded rows, a template or defined sections.
- Any `TODO`, `TBD`, `placeholder`, `stub`, `to be implemented`, `coming soon`, or empty section
body in any derived artefact.
- A generator that writes artefacts but does not carry every engine script body, and so cannot
rebuild from the seeds alone.
**Substance floor.** Floors, not targets, stated numerically only so failure is mechanically
detectable rather than a matter of judgement. Meeting a floor does not make a file correct; falling
below one makes it certainly incomplete.
| Artefact class | Minimum | Must contain |
|---|---|---|
| `engine_paths.ps1` | 30 non-comment lines | All three exported functions, `{v}` highest-version resolution, manifest marker parsing |
| `per_message_deterministic_script.ps1` | 200 non-comment lines | Five distinct, separately callable blocks; `pre`, `post`, `all`, `baseline` phases; per-block output and exit aggregation |
| `code_security_gate.ps1` | 40 non-comment lines | At least 4 GS-03 and 4 GS-04 patterns, a real file walk, a skip list, the GS-01/GS-02 unenforced disclosure |
| `cost_manager.ps1`, `metrics_report.ps1`, `lifecycle_manager.ps1`, `cost_telemetry.ps1` | 40 non-comment lines each | Their `-Mode`/`-Phase` parameters, real file I/O, the specified exit-code range |
| `ai_delivery_engine_initialisation.ps1` | All engine script bodies, plus every registry seed | Self-containment: seeds plus this file build a complete engine |
| Seeded register (`risk_log`, `ethics_constraints`, `incident_autonomy`, `engine_capability_boundary`) | Every row the registry names | R-001 to R-009, EC-01 to EC-08, CB-01 to CB-07, both incident criteria, as applicable |
| Template register (`hitl_checkpoints`) | Full `entry_template` | Every field in the manifest's HITL minimum-field list |
| Ledger CSV | Header row | Exactly the normative column order, unreordered |
| Generated report (`metrics_report`, cost logs, `artefact_traceability`, `functionality_coverage_matrix`) | Written by its generator, not by hand | Values computed from artefacts on disk, `NOT-COMPUTABLE` where input is absent |
A model that cannot meet a floor MUST say so explicitly, naming the artefact and shortfall. It MUST
NOT pad to reach a line count, and MUST NOT silently emit less.
## Engine Script Bodies
Every executable engine script is carried inside the bootstrap as a single-quoted here-string. That
file plus the seeds is a complete engine.
An external source folder was tried and reverted: it removed the double-edit rule but made the
generator depend on twelve files instead of one, and its copy was byte-identical, so it bought no
transformation, only distribution fragility.
**DOUBLE-EDIT RULE (normative).** Each engine script exists twice: the live `.ps1` and the embedded
copy. A change to one MUST be applied to the other in the same work item. A fix applied only to the
live copy works today and disappears at the next bootstrap.
This has already failed in practice: six of eleven embedded bodies were once found drifted, and the
embedded lifecycle manager still referenced a methodology filename that no longer existed. Every
clean-room rebuild in that period reported success while reproducing a degraded engine, because
verification counted files and compared references but never compared CONTENT. Two consequences:
- Verification MUST compare content, not counts (P3). Hash comparison of each generated `.ps1`
against the live one is what detects a double-edit violation, and MUST run whenever a script
changes.
- A here-string is opaque to the parser, so a syntax error inside one is undetectable until the
generated script runs. An edit to an embedded body MUST be validated by executing the generated
script, never by inspection alone.
## Bootstrap Registry
**Folders:** `.pdm/ai_delivery_engine`, `.pdm/epics`, `.pdm/features`, `.pdm/intents`,
`.pdm/prompts`, `.pdm/contexts`, `.pdm/constraints`, `.pdm/tests/prompts`,
`.pdm/tests/prompts/results`. No other folder may be created.
No subfolder of the results tree is created at initialisation: filing subfolders are a readability
measure only, created by a human if wanted, never assumed. Every scanner reading result artefacts,
in particular the independent-verification block and `metrics_report.ps1`, MUST nevertheless recurse
into that tree. A subfolder that escaped the gate would let a workspace clear an inadmissible `PASS`
by moving the file, converting a governance control into a filing convention.
`.pdm/contexts` and `.pdm/constraints` are created EMPTY and are human-owned; the engine MUST NOT
generate an artefact into either (P4). An engine-authored description of product and stack
duplicates sections 1-3 of `.github/copilot-instructions.md` and drifts from it with nothing to flag
the contradiction. `.pdm/constraints` holds PROJECT constraints per IntDEx section 6.5 `Context and
Constraint Dependent`: sovereignty, regulatory, data-residency, cost, performance, accessibility and
domain rules. It exists from initialisation so the place to put them precedes the first intent, and
is loaded in Tier 1 alongside `.pdm/contexts` so constraints are never read later than the context
they bound. An empty folder is not a defect and MUST NOT be reported as one.
No scratch or temporary folder may be created anywhere under `.pdm/`. Transient output belongs in
the operating system temporary directory; under `.pdm/` the stamping pass and reference scan would
both treat it as a governed artefact.
The reference-integrity scan checks backticked file paths, backticked `.pdm/` folder paths AND
plain-text engine filenames, because a reference naming a missing path misleads regardless of its
punctuation. Prefer describing an absent path to naming it; where naming is unavoidable, mark it per
the manifest section `Reference Integrity Convention`.
**Files**, with the content each must contain (all under `ai_delivery_engine/` unless shown):
| File | Required content |
|---|---|
| `ai_delivery_engine_initialisation.ps1` | This specification, implemented. Carries every engine script body. |
| `engine_paths.ps1` | Shared versioned-path resolver, dot-sourced by the gates. Written first; the gates depend on it. |
| `per_message_deterministic_script.ps1` | Block 1 core-file hard stop, Block 2 unvalidated Major checkpoint gate, Block 3 mechanically decidable ethics gate, Block 4 configuration-drift demand (warn-only), Block 5 evidence admissibility. Phases `pre`, `post`, `all`, `baseline`. |
| `code_security_gate.ps1` | GS-03 secret shapes and GS-04 insecure defaults, by pattern matching only. |
| `cost_telemetry.ps1` | Deterministic verified/unverified probe. |
| `cost_manager.ps1` | Ledger append, schema migration, report rebuild. |
| `metrics_v{v}.md` | Metric definitions, each with data source and verification tier. |
| `metrics_report.ps1` | Deterministic metric computation over engine artefacts. |
| `metrics_report_v{v}.md` | Generated; never hand-edited. |
| `lifecycle_events_v{v}.csv` | Header row only. Append-only stage-transition ledger. |
| `lifecycle_manager.ps1` | Metadata stamping, stage-event append, manual release flag. |
| `prompt_cost_events_v{v}.csv`, `interaction_cost_events_v{v}.csv` | Header row only. |
| `prompt_cost_log_v{v}.md`, `interaction_cost_log_v{v}.md` | Generated from their ledgers. |
| `hitl_checkpoints_v{v}.md` | YAML block, `entries: []`, full `entry_template`. |
| `artefact_traceability_v{v}.md` | GENERATED by `metrics_report.ps1` every run from the `Work Item` field of every artefact under `.pdm/`. Never hand-edited, never seeded empty: an empty register nobody populates is documentation, not a control. |
| `functionality_coverage_matrix_v{v}.md` | GENERATED every run from the same work-item grouping, joined to result artefacts and their declared `verification_source`. Never hand-edited. |
| `cbv_baseline_v{v}.md` | CBV baseline. Written by `-Phase baseline`, not by the bootstrap directly, so it records the state the gates actually ran against. |
| `risk_log_v{v}.md` | Seven-column table seeded R-001 to R-009. |
| `ethics_constraints_v{v}.md` | EC-01 to EC-08, EC-07 operating rules, limits-of-mechanical-enforcement statement, tiering rule, empty determination ledger. |
| `release_checklist_v{v}.md` | Checklist plus a not-releasable release status. |
| `intent_prompt_rebuild_log_v{v}.md` | Empty rebuild-evidence table. |
| `messages_from_the_engine.md` | Table plus the initialisation message. |
| `user_chat_messages_log.md` | Empty latest-first table. |
| `user_stories_engine_created.md` | Latest-first heading. |
| `evidential_independence_v{v}.md` | Admissible and inadmissible evidence rules. |
| `untrusted_content_v{v}.md` | UC-01 to UC-08, unenforced rules recorded as open gaps, never as satisfied. |
| `generated_code_security_v{v}.md` | GS-01 to GS-07 and RR-01 to RR-05, unenforced rules as open gaps. |
| `incident_autonomy_v{v}.md` | Criteria A severity (WHEN), Criteria B change-type matrix (WHAT), plan pre-approval rule, autonomy-scope drift rule, empty adoption ledger. Seeded closed, per `Seeded-Closed Artefacts`. |
| `engine_capability_boundary_v{v}.md` | CB-01 to CB-07: read, write, execute, egress, installation and credential scope, each as `Observed today` / `Proposed boundary` / `Enforced by` / `Open question`. Seeded closed. Where no script enforces a row, `Enforced by` MUST read `Nothing` rather than being left implied. |
**CSV column order is normative and MUST NOT be reordered:**
- prompt: `timestamp,event_type,model,estimated_input_tokens,estimated_output_tokens,estimated_tool_calls,estimated_total_usd,actual_total_usd,estimation_method,verification_status,notes`
- interaction: `timestamp,interaction_id,event_phase,model,estimated_input_tokens,estimated_output_tokens,estimated_tool_calls,estimated_total_usd,actual_total_usd,estimation_method,verification_status,notes`
- lifecycle: `timestamp,work_item,stage,event,actor,verification_source,notes`
Markdown header format and the `## Artefact Metadata` block are specified in the per-message
manifest and are not restated here.
### Licence attribution (normative)
Every derived artefact MUST carry the IntDEx CC BY 4.0 attribution as its FIRST content, not only
markdown ones. An engine that attributes its prose but not its code distributes the part most likely
to be copied with no licence attached. Syntax MUST be correct for the language: an attribution that
breaks the parser is worse than a missing one.
| File type | Required first line | Placement |
|---|---|---|
| Markdown | `` | Line 1 |
| PowerShell | `# AI-native Delivery Experience - IntDEx. Provided under CC BY 4.0. https://IntDEx.org` | After `#requires`, before comment-based help |
| CSV | None | A comment line would corrupt the header row and every parser reading it |
HTML comment syntax MUST NOT appear in a `.ps1`: it is a syntax error and would make the script
unloadable. `#requires` MUST remain line 1, since PowerShell honours it only there. This rule
applies to embedded bodies too, and is therefore subject to the DOUBLE-EDIT RULE.
## Gate Behaviour Specifications
Observable behaviour, not implementation, so independently authored scripts are interchangeable.
`per_message_deterministic_script.ps1` is abbreviated `PMDS` below.
| Gate | Input | Pass condition | Exit codes |
|---|---|---|---|
| PMDS Block 1 essential files, `pre` | Essential-file list from manifest markers | Every listed file present | `0` pass, `1` block with hard-stop message and missing list. MUST also print an advisory `SCOPE` line stating whether the engine is COMPLETE or INCOMPLETE, determined solely from derived marker artefacts and never from essential files, which are always present whenever this gate can pass. When COMPLETE it names the initialisation-scope artefacts as out of scope for routine work; when INCOMPLETE it lists absent markers and routes repair to the bootstrap. The advisory MUST NEVER block |
| PMDS Block 2 HITL major, `pre` | `hitl_checkpoints_v{v}.md` | Unvalidated `Major` entries `<= 3` | `0` pass, `1` block; always prints the unvalidated count |
| PMDS Block 3 ethics, `pre` | `ethics_constraints_v{v}.md`, `.pdm/` and product source, test results | Artefact present and no mechanically decidable violation of EC-01, EC-03, EC-05 or EC-08. An `AWAITING-HUMAN-AUTHORING` definition WARNS while the workspace holds no delivery artefact and BLOCKS as soon as one exists. MUST always print EC-02, EC-04, EC-06, EC-07 as not adjudicated and MUST NEVER report them passed | `0` no mechanical violation, `1` block or artefact missing, `3` scan failure |
| PMDS Block 4 CBV drift, `post` and `baseline` | The essential files, resolved via `engine_paths.ps1`, against `cbv_baseline_v{v}.md` | Watched-surface hashes match the baseline and the operating model is unchanged | `0` always in check; drift WARNS and never blocks; `3` scan failure. MUST warn, not fail, when no baseline exists, and MUST warn when re-baselining on `model-self-report-unverified` evidence |
| PMDS Block 5 independent verification, `post` | `.pdm/tests/prompts/results/*.md` | Every file asserting `PASS` declares a `verification_source` of `executed`, `human`, `cross-model` or `prior-artefact` | `0` pass, `1` block listing each violation |
| `code_security_gate.ps1` | Product source and `.pdm/` artefacts | No match among implemented GS-03 / GS-04 patterns | `0` no finding, `1` finding requiring human triage. MUST print that GS-01 (SAST) and GS-02 (dependency/CVE) remain unenforced, and that absence of findings does not mean secure |
| `cost_telemetry.ps1` | Usage file, provider API credentials, or metrics config | An authoritative source is found | `0` verified, `2` unverified (normal, not an error), `1` probe failure |
| `metrics_report.ps1` | Registry artefacts, HITL register, risk log, test results, cost ledgers, core files | All metrics computed and the report written | `0` success, `1` a required input is missing, `3` write failure |
| `lifecycle_manager.ps1` | `-Mode stamp` markdown under `.pdm/`; `-Mode append`/`-Mode release` the lifecycle ledger | Stamping adds metadata only where absent and never alters an existing `Created`; appends are additive and preserve column order | `0` success, `1` invalid stage/event/arguments or a release without an actor, `3` write failure |
| Bootstrap embedded-body drift check | Every embedded script body and markdown seed, against the live artefact | Every `.ps1` body matches after line-ending normalisation, and every required `## ` section of a seed is present in the live register | Advisory. Reports `DRIFT` per file and carries the count into the summary. MUST NOT block, because a drifted engine still needs to be buildable to be repaired, but the count MUST appear where it cannot be missed |
`lifecycle_manager.ps1` MUST be idempotent in `-Mode stamp`, never rewrite an existing `Created`,
and refuse a `release` event without an actor, since an unattributed release claim is
indistinguishable from a self-declared one.
`metrics_report.ps1` MUST compute every metric from artefacts on disk only, MUST NOT infer, estimate
or narrate, and MUST mark any metric whose input is absent as `NOT-COMPUTABLE` rather than omitting
it. Metrics are indicators, never evidence: a metric value MUST NOT justify a `PASS`.
`cost_telemetry.ps1` MUST log credential environment variable **names** only, never values.
`cost_manager.ps1` MUST clear `actual_total_usd` whenever `verification_status` is not `verified`.
### Mandatory Gate Output Contract
A pass condition producing no distinguishing output cannot be audited from outside the script, and a
gate printing only its own name is indistinguishable from one that does nothing. Each gate MUST emit
at least one line carrying its identifying token AND the count it observed. The count is the
cheapest available proof that the gate inspected something: a stub can print a label, but not a
number it never computed.
| Gate / block | Token | Must also print |
|---|---|---|
| Block 1 essential files | `ESSENTIAL-FILES-GATE` | Number of essential files resolved, and the `SCOPE` advisory |
| Block 2 HITL major | `HITL-MAJOR-GATE` | Unvalidated `Major` count and the threshold |
| Block 3 ethics | `ETHICS-GATE` | Per-constraint state for EC-01/03/05/08, and EC-02/04/06/07 explicitly as `UNVERIFIED` |
| Block 4 CBV drift | `CBV-GATE` | Baseline id and number of watched surfaces compared |
| Block 5 independent verification | `INDEPENDENT-VERIFICATION-GATE` | Result files scanned and violations found |
| `code_security_gate.ps1` | `CODE-SECURITY-GATE` | Files scanned, findings count, GS-01/GS-02 unenforced disclosure |
The engine MUST NOT report a gate as run unless that gate's token appeared in THIS run's output.
Paraphrasing a gate's output, or summarising it as "gates passed", is prohibited.
### Gate Falsifiability Self-Test
Every pass condition above is satisfied by a script whose only statement is `exit 0`. Presence
checks, file counts and reference scans do not distinguish such a script from a working gate. This
self-test is the only mechanical check that does, and it MUST be implemented.
After the gates run and before the summary, the bootstrap MUST, for each gate, construct a condition
the gate is specified to reject, invoke the gate, and confirm a non-zero exit, then restore the
workspace exactly. All fixtures MUST be built under the OS temporary directory or reverted in a
`finally` block, never left under `.pdm/`.
| Gate | Injected condition | Required result |
|---|---|---|
| Block 1 essential files | `-WorkspaceRoot` pointed at an empty temporary folder | Exit `1` and the hard-stop message |
| Block 2 HITL major | Temporary HITL register holding 4 unvalidated `Major` entries | Exit `1` and the block message |
| Block 3 ethics | Temporary delivery artefact under `.pdm/intents` while definitions are unauthored | Exit `1` |
| Block 4 CBV drift | Baseline recording a different operating model | Exit `0` with a drift WARNING present |
| Block 5 independent verification | Temporary result file asserting `PASS` with no `verification_source` | Exit `1` naming the file |
| `code_security_gate.ps1` | Temporary file containing `AKIA` plus 16 upper-case alphanumerics | Exit `1` with a `GS-03` finding |
A gate returning `0` for its injected condition is NOT implemented, regardless of line count or how
plausible its source reads. The bootstrap MUST print `SELF-TEST: <gate> FAILED - gate cannot reject
its own reject condition`, name every such gate in the summary, and exit `1`. This MUST NOT be
softened (P2): an engine whose gates cannot fail is not partially working, it is a reporting surface
that returns PASS unconditionally.
## Seeded-Closed Artefacts
`ethics_constraints_v{v}.md`, `incident_autonomy_v{v}.md` and `engine_capability_boundary_v{v}.md`
MUST be created in the SAME run as every other registry artefact, never later and never on request.
An engine that can act before its constraints exist has an unconstrained window at exactly the point
it is least observed. Existing copies MUST NOT be overwritten (P1). If one is found missing during
routine operation, treat it as a repair trigger and restore it before continuing delivery work.
All three are seeded CLOSED, granting no authority, because the engine holds none over itself (P4):
- **Ethics.** EC-01 to EC-08 seeded `AWAITING-HUMAN-AUTHORING`. An unauthored definition cannot be
adjudicated, so it MUST NOT be reported as passed.
- **Incident autonomy.** `metrics` and `plans` both EMPTY lists; status `DRAFT-ENGINE-AUTHORED`,
under which every severity level is treated as its most restrictive neighbour and no plan may
execute. Detection declared `deterministic-script-only`: a model MUST NOT adjudicate whether its
own behaviour has drifted. Severity ordering seeded so autonomy DECREASES as severity increases —
an engine acting most freely during the most severe incidents has the safety property backwards.
- **Capability boundary.** EMPTY Adoption Ledger. The engine MUST NOT seed an adopted boundary.
The Criteria B change-type matrix is not tunable by severity. A change in a mandatory human
checkpoint type — security, authentication, authorisation, privacy, schema, data contract,
user-visible behaviour, release, or engine constraints — is NEVER made autonomous by a severity
value.
**Three authoring states**, which the seed MUST define so a workspace later obtaining draft wording
has somewhere truthful to record it:
| State | Meaning | Gate effect |
|---|---|---|
| `AWAITING-HUMAN-AUTHORING` | No wording exists; cannot be adjudicated at all | WARNS pre-delivery, BLOCKS once any delivery artefact exists |
| `DRAFT-ENGINE-AUTHORED` | Drafted by the engine at explicit operator request, recorded as a Major HITL checkpoint. Not canonical, no ethical authority | WARNS; reported `UNVERIFIED` |
| `HUMAN-AUTHORED` | Authored or explicitly adopted by a named human, recorded in the Authorship Ledger | May be adjudicated per its Detection column |
The engine MUST NEVER write `HUMAN-AUTHORED` or add a row to the Authorship Ledger. A mechanical
check against `DRAFT-ENGINE-AUTHORED` wording verifies conformance to text the engine wrote about
itself, and is `script-detected` against draft wording, never `human-reviewed`.
**Pre-delivery ethics posture.** The gate MUST NOT block unconditionally either: a workspace holding
no delivery artefact has nothing to adjudicate, and blocking there deadlocks initialisation, since
the engine cannot act yet authoring the constraints is itself an action. A gate that blocks where
nothing can be harmed protects nothing and trains operators to bypass it. Therefore:
- No artefact under `.pdm/intents`, `.pdm/prompts`, `.pdm/epics`, `.pdm/features` or
`.pdm/tests/prompts/results`: unauthored definitions WARN and the gate reports `PRE-DELIVERY
PASS`, which is explicitly neither ethical clearance nor a pass for any delivery work.
- Any such artefact present: unauthored definitions BLOCK.
Delivery-work detection MUST be a deterministic file count; a model MUST NOT decide whether delivery
work has begun. Authoring EC-01 to EC-08 is the FIRST required human action after initialisation.
The initialisation output MUST state that EC-01 to EC-08 are active from the first message, that
EC-07 prohibits unlawful or foreseeably seriously harmful use, cannot be waived by any operator
instruction, prompt or artefact, and is assessed on assembled intent rather than the wording of a
single message, and that constraints whose `detection` is `human` are `UNVERIFIED` until a named
human reviews them, so initialisation confers no ethical clearance whatsoever.
## Post-initialisation Obligations
Initialisation produces an empty, governed workspace, not a validated one. The engine MUST report
that no delivery work has been validated, that cost control runs `model-self-report` / `unverified`
until a provider usage source is configured, that the release checklist is unticked, and that no
ethics constraint has been human-reviewed. Bootstrap success evidences engine completeness only,
never product correctness and never ethical acceptability.
It MUST report the `Gate Falsifiability Self-Test` result gate by gate, and MUST NOT describe the
engine as initialised, ready, complete or operational if any gate failed it or the self-test was not
run. "The files were created" reports file creation, not engine completeness, and the difference
between the two is the entire control surface (P3).
It MUST also report that EC-01 to EC-08 are unauthored, that the ethics gate is in its pre-delivery
warning posture, and that creating any delivery artefact before a named human authors those
definitions will block the gate. This is the obligation most likely to be deferred, because an
initialised workspace looks ready.

ai_delivery_engine_initialisation_v1.md

Comments

Before you continue