Immutability

Overview

This skill defines the immutability contract for every Datarim pipeline stage. An artefact produced by a stage MUST NOT be weakened to accommodate a constraint discovered in a downstream stage. When a genuine constraint makes an artefact unsatisfiable, the Return-to-Source Transition provides the formal revision path.

Foundation: Design by Contract (Meyer, 1986) — preconditions and postconditions are non-negotiable specifications. ADRs (Nygard, 2011) — accepted decisions are immutable; changes are made by superseding, not editing. Configuration Management (IEEE 828-2012) — a baseline changes only through formal change control.

Loading

Loaded by every pipeline command (/dr-prd, /dr-plan, /dr-design, /dr-do, /dr-qa, /dr-compliance) and by the architect and developer agents. The general section and common rules are always loaded; per-stage fragments are loaded conditionally by the consuming command. Frontend-UI tasks additionally load the Frontend-UI fragment.

Common Rules

Artefact Immutability Rule

An artefact is «weakened» when a requirement (V-AC, D-REQ) is relaxed, a design decision is silently reversed without a new creative doc, a test or verification command is relaxed to make a failing deliverable pass, a checklist item's completion criterion is narrowed, a QA criterion is re-scoped to avoid a failure, a compliance check is skipped or downgraded, or a visual baseline is replaced without operator diff review.

Only two responses are valid: fix the downstream work (the artefact is correct, the work is wrong), or recognise that the artefact specified the wrong contract — which triggers the Return-to-Source Transition.

V-AC Parity Rule

V-AC rows at every stage are subject to the same immutability. A V-AC that verifies a deliverable MUST NOT be changed to a weaker check so the deliverable passes without meeting the original criterion. Extends the TDD discipline's V-AC parity rule to all pipeline stages.

Non-Code Parity Rule

For non-code tasks, the to-do / checklist is the «test». A checklist item MUST NOT have its completion criterion weakened — «checklist scope reduction» is the non-code equivalent of weakening a V-AC assertion.

Anti-Tautological Rule

A verification criterion MUST be falsifiable. A criterion that always passes regardless of the state of the implementation is a tautology and MUST be removed or re-scoped. Examples: «check that the file exists» (always passes if the implementation creates it), «check that variable X is truthy» (always passes if the test runner initialises it).

Return-to-Source Transition

Trigger. A real blocker that genuinely requires changing an immutable artefact — not implementation difficulty (never a valid reason), but a discovered constraint: impossible preconditions, wrong level of specification, newly understood requirement, or an upstream API change that invalidates the original contract.

Who decides. The stage executor cannot decide alone. Escalate to the operator with (a) the original artefact text verbatim, (b) the concrete reason it must change, (c) the proposed new text.

Where it is recorded. In datarim/tasks/{TASK-ID}-task-description.md § Decisions, carrying the artefact id, verbatim original, reason, verbatim proposal, and the routing target. The record is written BEFORE the artefact is changed.

How the stage resumes. After the operator approves the revision and the upstream stage updates or re-issues its artefact, the executor resumes. The next-step recommendation MUST route to the stage that owns the immutable artefact, not continue the current stage.

Routing table

• PRD V-AC / D-REQ → owned by /dr-prd → routes to /dr-prd
• Plan V-AC / implementation step → owned by /dr-plan → routes to /dr-plan
• Design decision (creative doc) → owned by /dr-design → routes to /dr-design
• Test / V-AC verification command → owned by /dr-do (recorded in plan) → routes to /dr-plan
• QA criterion / layer structure → owned by /dr-qa → routes to /dr-qa
• Compliance checklist item → owned by /dr-compliance → routes to /dr-qa for re-verification
• Visual baseline (frontend) → owned by /dr-do with operator sign-off → routes to /dr-do

What this is NOT

• NOT an escape hatch for implementation difficulty.
• NOT a post-hoc rationalization without evidence.
• NOT a solo decision — operator review is required.

Per-Stage Fragments

Each fragment is loaded conditionally by the command that owns the stage, and defines that stage's immutable artefact, its supersede path, and its stage-specific immutability rules. Fragments exist for /dr-prd, /dr-plan, /dr-design, /dr-do, /dr-qa, /dr-compliance, and frontend-UI work.