@rasensio/aidlc 1.18.0 → 1.20.0

package/dist/change/parser.js

@@ -0,0 +1,339 @@
+/**
+ * Amendment parser: closed grammar over the `## Amendment <n>` sections of
+ * requirements.md (FR1).
+ *
+ * The grammar was derived from the corpus, not invented. Measured over 39
+ * `requirements.md` and 29 `tasks.md` on 2026-09-07, two conventions exist:
+ *
+ *   ## Amendment 1 — 2026-09-05, after the design review     (5 real, accepted)
+ *   ### Amendments from the design review (2026-09-05)       (4 real, warned)
+ *
+ * The second is unnumbered and undated and cannot be applied, so it warns
+ * rather than vanishing — a near-miss that reads as absence is this project's
+ * single most repeated defect class (AC-53).
+ *
+ * Two rules exist because a prototype got them wrong on real input:
+ *
+ * - **Three emphasis variants, copied from `ACTIVE_RE`** (`traceability/parser.ts:23-24`).
+ *   The first draft accepted `Retires:` and `**Retires**:` but not
+ *   `**Retires:**` — which is the form this instance's own Amendment 1 was
+ *   written with, so its 23 retirements parsed as zero (AC-78).
+ * - **A wrapped bullet is one bullet.** Ending the field block at "the first
+ *   non-bullet non-blank line" truncates any field that wraps: measured, a
+ *   wrapped `Retires:` yielded 12 of 23 ids and dropped `Issues`, `Reason`
+ *   and `Reopens` outright, and the impact report would then have said "no
+ *   retired ids" for an amendment that retired 23 criteria (AC-78, AC-94).
+ *
+ * Requirements: change-management/AC-3, AC-5, AC-7, AC-8, AC-51, AC-53,
+ * AC-54, AC-78, AC-79
+ */
+// Heading: `##` or `###`, `Amendment <n>`, em dash or hyphen, ISO date,
+// optional `, <context>` tail (AC-51).
+//
+// Up to three spaces of indentation are allowed, which is CommonMark's rule for
+// an ATX heading. Anchoring at column 0 instead would silently drop an indented
+// heading — and a near-miss that reads as absence is this project's most
+// repeated defect class, so the permissive form is the safe one here.
+const HEADING_RE = /^ {0,3}(#{2,3})\s+Amendment\s+([1-9][0-9]*)\s+[—-]\s+(\d{4}-\d{2}-\d{2})\s*(?:,\s*(\S.*?))?\s*$/;
+// Any heading whose text begins with Amendment/Amendments — the near-miss
+// lint (AC-53). Deliberately wider than HEADING_RE at every axis: any level,
+// singular or plural, no date required, same indent allowance.
+const AMENDMENT_SHAPED_RE = /^ {0,3}(#{1,6})\s+Amendments?\b/i;
+/** Any ATX heading — bounds a section (AC-51). */
+const ANY_HEADING_RE = /^ {0,3}(#{1,6})\s/;
+/**
+ * A dash bullet and its indentation.
+ *
+ * Field bullets sit at the section's own indentation; a line indented MORE than
+ * the bullet it follows is a continuation of it, not a new item. That
+ * distinction is the whole of AC-78 — the rule it replaced ended the field block
+ * at the first non-bullet line, so a wrapped `Retires:` list lost half its ids
+ * and three whole fields without a diagnostic.
+ */
+const BULLET_RE = /^(\s*)-\s+(.*)$/;
+const FIELD_NAMES = 'Retires|Issues|Reopens|Reason';
+// The same three emphasis variants `ACTIVE_RE` accepts, for the same reason:
+// authors write all three and two of them are invisible to a narrower rule.
+const FIELD_RE = new RegExp(String.raw `^(?:` +
+    String.raw `(${FIELD_NAMES}):|` +
+    String.raw `\*\*(${FIELD_NAMES})\*\*:|` +
+    String.raw `\*\*(${FIELD_NAMES}):\*\*` +
+    String.raw `)\s*(.*)$`);
+// A co-located AC definition bullet is not an unrecognised field — it is a
+// legitimate definition living inside the amendment section, which is what
+// `agent-portability` AM-2 and AM-3 do. Skipped silently rather than warned.
+const AC_DEF_BULLET_RE = /^(?:AC-[1-9][0-9]*|\*\*AC-[1-9][0-9]*)/;
+// A bold-prefixed bullet that is not a known field: kept and warned, mirroring
+// the unrecognized-token handling in `tasks/parser.ts:124-126`.
+const BOLD_PREFIX_RE = /^\*\*([^*]+?):?\*\*:?\s/;
+/** A whole `AC-<n>` token and nothing else (AC-3). */
+const AC_TOKEN_RE = /^AC-([1-9][0-9]*)$/;
+/** A phase name as written — shape only; validation belongs to reopen.ts. */
+const PHASE_TOKEN_RE = /^\S+$/;
+function excerpt(text, max = 60) {
+    const trimmed = text.trim();
+    return trimmed.length > max ? `${trimmed.slice(0, max - 3)}...` : trimmed;
+}
+/**
+ * Walk lines outside fenced code blocks (AC-79).
+ *
+ * CommonMark rules: a fence opens with 3+ backticks or tildes and closes only
+ * on the same character at the same length or longer. Written correctly rather
+ * than as a naive toggle because it is cheap to do so — the corpus currently
+ * cannot tell the two apart (1047 AC-shaped lines, zero inside fences), which
+ * is a reason to write the correct one, not evidence that it does not matter.
+ *
+ * Indentation is deliberately permissive (`\s*`, not ` {0,3}`): AIDLC markdown
+ * nests fenced examples inside list items routinely — see the `ac-coverage`
+ * example at `packages/content/skills/50-testing.md:43-45`, indented five
+ * spaces — and an absolute three-space rule is blind to every one of them.
+ */
+export function scanOutsideFences(lines, visit) {
+    let fence = null;
+    for (let i = 0; i < lines.length; i++) {
+        const opener = /^\s*(`{3,}|~{3,})/.exec(lines[i]);
+        if (opener) {
+            const marker = opener[1];
+            if (fence === null) {
+                fence = marker;
+            }
+            else if (marker[0] === fence[0] && marker.length >= fence.length) {
+                fence = null;
+            }
+            continue;
+        }
+        if (fence !== null)
+            continue;
+        visit(lines[i], i);
+    }
+}
+/** Split a `Retires:`/`Issues:` value into ids, reporting non-tokens (AC-3). */
+function parseAcList(value) {
+    const ids = [];
+    const rejected = [];
+    for (const raw of value.split(',')) {
+        const token = raw.trim();
+        if (token === '')
+            continue;
+        const match = AC_TOKEN_RE.exec(token);
+        if (match)
+            ids.push(Number(match[1]));
+        else
+            rejected.push(token);
+    }
+    return { ids, rejected };
+}
+/** Split a `Reopens:` value into phase-name tokens as written. */
+function parsePhaseList(value) {
+    return value
+        .split(',')
+        .map((part) => part.trim())
+        .filter((part) => part !== '' && PHASE_TOKEN_RE.test(part));
+}
+/**
+ * Collect an amendment section's field bullets.
+ *
+ * The block starts at the section's first `-` bullet, and that bullet's
+ * indentation becomes the block's. Subsequent bullets at that indentation or
+ * shallower are new fields; a blank line, or any non-blank line indented more
+ * deeply than the current bullet, **continues that bullet** — the AC-78 rule,
+ * and the whole reason a wrapped `Retires:` list no longer truncates. The block
+ * ends at the first line at or inside the block indentation that is not a bullet.
+ */
+function collectFields(body) {
+    const fields = [];
+    const warnings = [];
+    let current = null;
+    let started = false;
+    // The field block's own indentation, taken from its first bullet.
+    let blockIndent = null;
+    const flush = () => {
+        if (!current)
+            return;
+        const field = FIELD_RE.exec(current.text);
+        if (field) {
+            const name = (field[1] ?? field[2] ?? field[3]).toLowerCase();
+            fields.push({ name, value: field[4].trim(), line: current.line });
+        }
+        else if (!AC_DEF_BULLET_RE.test(current.text)) {
+            const bold = BOLD_PREFIX_RE.exec(current.text);
+            warnings.push({
+                line: current.line,
+                text: bold ? bold[1] : excerpt(current.text, 44),
+            });
+        }
+        current = null;
+    };
+    for (const { line, index } of body) {
+        const bullet = BULLET_RE.exec(line);
+        const indent = bullet ? bullet[1].length : 0;
+        if (bullet && (blockIndent === null || indent <= blockIndent)) {
+            flush();
+            if (blockIndent === null)
+                blockIndent = indent;
+            current = { text: bullet[2], line: index + 1, indent };
+            started = true;
+            continue;
+        }
+        if (line.trim() === '')
+            continue;
+        // Indented more deeply than the bullet it follows: a continuation of it.
+        // A nested bullet lands here too, which is correct — it belongs to the
+        // bullet above rather than starting a new field.
+        if (current !== null && /^\s/.test(line) && line.search(/\S/) > current.indent) {
+            current.text += ` ${line.trim()}`;
+            continue;
+        }
+        if (started)
+            break;
+    }
+    flush();
+    return { fields, warnings };
+}
+/**
+ * Parse every amendment section in one requirements.md.
+ *
+ * @param content - File content (UTF-8). Never throws.
+ */
+export function parseAmendments(content) {
+    const lines = content.split('\n');
+    const warnings = [];
+    const byNumber = new Map();
+    const order = [];
+    // Heading positions, gathered outside fences so a fenced example of an
+    // amendment heading is documentation rather than a record.
+    const headings = [];
+    const liveLines = new Set();
+    scanOutsideFences(lines, (line, index) => {
+        liveLines.add(index);
+        const heading = HEADING_RE.exec(line);
+        if (heading) {
+            headings.push({
+                index,
+                level: heading[1].length,
+                n: Number(heading[2]),
+                date: heading[3],
+                ...(heading[4] !== undefined && { context: heading[4] }),
+            });
+            return;
+        }
+        if (AMENDMENT_SHAPED_RE.test(line)) {
+            warnings.push({
+                line: index + 1,
+                text: `"${excerpt(line)}" resembles an amendment heading but does not match ` +
+                    `the grammar (expected "## Amendment <n> — YYYY-MM-DD[, context]")`,
+            });
+        }
+    });
+    for (const heading of headings) {
+        // Section: heading to the next heading at the same or shallower level, or
+        // end of file (AC-51). Only lines outside fences participate.
+        let end = lines.length;
+        for (let j = heading.index + 1; j < lines.length; j++) {
+            if (!liveLines.has(j))
+                continue;
+            const other = ANY_HEADING_RE.exec(lines[j]);
+            if (other && other[1].length <= heading.level) {
+                end = j;
+                break;
+            }
+        }
+        const body = [];
+        for (let j = heading.index + 1; j < end; j++) {
+            if (liveLines.has(j))
+                body.push({ line: lines[j], index: j });
+        }
+        const { fields, warnings: fieldWarnings } = collectFields(body);
+        for (const warning of fieldWarnings) {
+            warnings.push({
+                line: warning.line,
+                text: `Amendment ${heading.n}: unrecognised field bullet "${warning.text}" — kept`,
+            });
+        }
+        const seen = new Set();
+        let retires = [];
+        let issues = [];
+        let reopens = [];
+        let retiresPresent = false;
+        let reason;
+        for (const field of fields) {
+            if (seen.has(field.name)) {
+                warnings.push({
+                    line: field.line,
+                    text: `Amendment ${heading.n}: duplicate "${field.name}" field — first wins`,
+                });
+                continue;
+            }
+            seen.add(field.name);
+            if (field.name === 'retires' || field.name === 'issues') {
+                const { ids, rejected } = parseAcList(field.value);
+                for (const token of rejected) {
+                    warnings.push({
+                        line: field.line,
+                        text: `Amendment ${heading.n}: "${token}" in ${field.name} is not a whole AC-<n> ` +
+                            `token and contributes no id (ranges such as AC-4..AC-6 are not accepted)`,
+                    });
+                }
+                if (field.name === 'retires') {
+                    retires = ids;
+                    retiresPresent = true;
+                }
+                else {
+                    issues = ids;
+                }
+                continue;
+            }
+            if (field.name === 'reopens') {
+                reopens = parsePhaseList(field.value);
+                continue;
+            }
+            if (field.value !== '')
+                reason = field.value;
+        }
+        if (reason === undefined) {
+            warnings.push({
+                line: heading.index + 1,
+                text: `Amendment ${heading.n} has no Reason: field`,
+            });
+        }
+        const amendment = {
+            n: heading.n,
+            date: heading.date,
+            ...(heading.context !== undefined && { context: heading.context }),
+            line: heading.index + 1,
+            level: heading.level,
+            retires,
+            issues,
+            reopens,
+            retiresPresent,
+            ...(reason !== undefined && { reason }),
+        };
+        const existing = byNumber.get(amendment.n);
+        if (existing) {
+            warnings.push({
+                line: amendment.line,
+                text: `duplicate Amendment ${amendment.n}: lines ${existing.line} and ` +
+                    `${amendment.line} (first occurrence wins)`,
+            });
+            continue;
+        }
+        byNumber.set(amendment.n, amendment);
+        order.push(amendment);
+    }
+    // Numbering gaps (AC-7), over parsed numbers.
+    if (byNumber.size > 0) {
+        const max = Math.max(...byNumber.keys());
+        for (let n = 1; n <= max; n++) {
+            if (!byNumber.has(n)) {
+                warnings.push({ line: 0, text: `Amendment ${n} is never defined (numbering gap)` });
+            }
+        }
+    }
+    return {
+        amendments: order.sort((a, b) => a.n - b.n),
+        // Ordered by source line; the synthetic line 0 of a gap warning sorts first
+        // deliberately — it is a statement about the file, not about a place in it.
+        warnings: warnings.sort((a, b) => a.line - b.line).map((w) => w.text),
+    };
+}
+//# sourceMappingURL=parser.js.map

package/dist/change/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../src/change/parser.ts"],"names":[],"mappings":"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"}

package/dist/change/reopen.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Reopen planning and application (FR4).
+ *
+ * `planReopen` is pure — no I/O — so every refusal branch is testable without a
+ * filesystem. `applyReopen` is the single writing function in the module.
+ *
+ * **Why the range is contiguous.** Reopening only the phases an author named
+ * would leave a `complete` phase sitting behind an `in-progress` one, and two
+ * shipped behaviours then misfire: `findNextPendingPhase`
+ * (`core/lifecycle.ts:244-269`) jumps forward over the intermediates writing a
+ * `type: 'normal'` record with no skip recorded, and `checkDeploymentEntry`
+ * (`:491-505`) keys on template adjacency rather than the actual target, so a
+ * reopened `design` whose next pending phase is `deployment` would enter
+ * deployment with that gate never evaluated. A contiguous range fixes both
+ * without touching `evaluateTransition`, which is what lets this feature add no
+ * gate at all.
+ *
+ * **Why validation is an allowlist AND a character check.** Membership in
+ * `phasesForScope` serves three jobs — traversal guard, Gate-1 correctness guard
+ * (`lifecycle.ts:310-318` skips the required-artifacts gate entirely when
+ * `current_phase` is not in the list, so a typo silently switches the gate
+ * *off*), and scope guard. But membership alone is not enough:
+ * `validateTemplate` (`core/template-resolver.ts:323-326`) accepts any non-empty
+ * string as a phase name, so a project-local template declaring
+ * `- name: ../../evil` puts a traversal token *inside* the allowlist, and
+ * `saveSnapshot`'s `join` has no containment (`state/snapshot-store.ts:129-133`).
+ * This repo already treats `.aidlc/templates/` as hostile for exactly this
+ * reason (`traceability/gate-criterion.ts:64-71`).
+ *
+ * Requirements: change-management/AC-27, AC-50, AC-82, AC-83, AC-84, AC-85,
+ * AC-87, AC-89, AC-92
+ */
+import type { InstanceState, PhaseState, WorkflowTemplate } from '../core/types.js';
+import type { Amendment, ReopenPlan } from './types.js';
+export interface PlanInput {
+    amendment: Amendment;
+    instanceState: InstanceState;
+    phaseStates: Map<string, PhaseState>;
+    resolvedTemplate: WorkflowTemplate;
+    /** Actor identity for the record's `by` (AC-83). */
+    actor: string;
+    /** Injected so tests are deterministic. */
+    now: Date;
+}
+/**
+ * Plan a reopen. Pure: one of five variants out, no writes, no reads.
+ */
+export declare function planReopen(input: PlanInput): ReopenPlan;
+export interface ApplyInput {
+    projectRoot: string;
+    instance: string;
+    plan: Extract<ReopenPlan, {
+        kind: 'reopen';
+    }>;
+    instanceState: InstanceState;
+    phaseStates: Map<string, PhaseState>;
+    resolvedTemplate: WorkflowTemplate;
+    amendment: Amendment;
+    now: Date;
+}
+/**
+ * Apply a reopen plan.
+ *
+ * **Write order is deliberate** (AC-89): every phase state file first, then
+ * `instance.yaml` (`current_phase` and `applied_amendments` in one write), then
+ * the appended record last. A failure part-way therefore leaves phases reopened
+ * with the amendment unrecorded, which a re-run completes; the reverse order
+ * would leave the amendment recorded with phases untouched, which a re-run would
+ * refuse to fix.
+ */
+export declare function applyReopen(input: ApplyInput): void;
+/**
+ * Record an amendment as applied without touching phase state — the no-op path
+ * (AC-87). An accounted-for amendment must not become destructive later when
+ * `current_phase` moves on its own.
+ */
+export declare function recordApplied(projectRoot: string, instance: string, instanceState: InstanceState, amendmentNumber: number): void;
+/** Sorted, deduplicated union — so a repeat run is stable rather than growing. */
+export declare function mergeApplied(existing: number[] | undefined, n: number): number[];
+//# sourceMappingURL=reopen.d.ts.map

package/dist/change/reopen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reopen.d.ts","sourceRoot":"","sources":["../../src/change/reopen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH,OAAO,KAAK,EACV,aAAa,EACb,UAAU,EAEV,gBAAgB,EACjB,MAAM,kBAAkB,CAAC;AAK1B,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAYxD,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,SAAS,CAAC;IACrB,aAAa,EAAE,aAAa,CAAC;IAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,GAAG,EAAE,IAAI,CAAC;CACX;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CAoIvD;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC,UAAU,EAAE;QAAE,IAAI,EAAE,QAAQ,CAAA;KAAE,CAAC,CAAC;IAC9C,aAAa,EAAE,aAAa,CAAC;IAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,SAAS,EAAE,SAAS,CAAC;IACrB,GAAG,EAAE,IAAI,CAAC;CACX;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAuDnD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,aAAa,EAC5B,eAAe,EAAE,MAAM,GACtB,IAAI,CAON;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAEhF"}

package/dist/change/reopen.js

@@ -0,0 +1,227 @@
+/**
+ * Reopen planning and application (FR4).
+ *
+ * `planReopen` is pure — no I/O — so every refusal branch is testable without a
+ * filesystem. `applyReopen` is the single writing function in the module.
+ *
+ * **Why the range is contiguous.** Reopening only the phases an author named
+ * would leave a `complete` phase sitting behind an `in-progress` one, and two
+ * shipped behaviours then misfire: `findNextPendingPhase`
+ * (`core/lifecycle.ts:244-269`) jumps forward over the intermediates writing a
+ * `type: 'normal'` record with no skip recorded, and `checkDeploymentEntry`
+ * (`:491-505`) keys on template adjacency rather than the actual target, so a
+ * reopened `design` whose next pending phase is `deployment` would enter
+ * deployment with that gate never evaluated. A contiguous range fixes both
+ * without touching `evaluateTransition`, which is what lets this feature add no
+ * gate at all.
+ *
+ * **Why validation is an allowlist AND a character check.** Membership in
+ * `phasesForScope` serves three jobs — traversal guard, Gate-1 correctness guard
+ * (`lifecycle.ts:310-318` skips the required-artifacts gate entirely when
+ * `current_phase` is not in the list, so a typo silently switches the gate
+ * *off*), and scope guard. But membership alone is not enough:
+ * `validateTemplate` (`core/template-resolver.ts:323-326`) accepts any non-empty
+ * string as a phase name, so a project-local template declaring
+ * `- name: ../../evil` puts a traversal token *inside* the allowlist, and
+ * `saveSnapshot`'s `join` has no containment (`state/snapshot-store.ts:129-133`).
+ * This repo already treats `.aidlc/templates/` as hostile for exactly this
+ * reason (`traceability/gate-criterion.ts:64-71`).
+ *
+ * Requirements: change-management/AC-27, AC-50, AC-82, AC-83, AC-84, AC-85,
+ * AC-87, AC-89, AC-92
+ */
+import { join } from 'node:path';
+import { phasesForScope } from '../core/template-resolver.js';
+import { effectiveRequiredArtifacts } from '../core/gate.js';
+import { saveSnapshot } from '../state/snapshot-store.js';
+import { appendTransition } from '../state/transition-log.js';
+/**
+ * A phase name that could escape the instance directory, whatever list it
+ * appears in (AC-82). Applied to template members too, not only to author input.
+ */
+function isSafePhaseName(name) {
+    return (name !== '' && !name.includes('/') && !name.includes('\\') && !name.includes('..'));
+}
+/**
+ * Plan a reopen. Pure: one of five variants out, no writes, no reads.
+ */
+export function planReopen(input) {
+    const { amendment, instanceState, phaseStates, resolvedTemplate, actor, now } = input;
+    const applicable = phasesForScope(resolvedTemplate, instanceState.scope);
+    const order = applicable.map((p) => String(p.name));
+    // Every member of the allowlist itself must be filename-safe, because the
+    // template it came from is tracked and therefore untrusted.
+    const unsafeTemplatePhases = order.filter((name) => !isSafePhaseName(name));
+    if (unsafeTemplatePhases.length > 0) {
+        return {
+            kind: 'invalid-phase',
+            names: unsafeTemplatePhases,
+            validPhases: order.filter(isSafePhaseName),
+        };
+    }
+    const valid = new Set(order);
+    // AC-82: named phases must be members, and filename-safe.
+    const invalid = amendment.reopens.filter((name) => !valid.has(name) || !isSafePhaseName(name));
+    if (invalid.length > 0) {
+        return { kind: 'invalid-phase', names: invalid, validPhases: order };
+    }
+    const currentPhase = String(instanceState.current_phase);
+    const currentIndex = order.indexOf(currentPhase);
+    if (currentIndex === -1) {
+        // Reachable through a scope change. Also the state in which Gate 1 is off,
+        // so proceeding would write a reopen into an instance whose gates are not
+        // running (AC-92).
+        return {
+            kind: 'blocked',
+            code: 'current-phase-outside-template',
+            message: `current_phase "${currentPhase}" is not a phase of template ` +
+                `"${resolvedTemplate.name}" at scope "${instanceState.scope}" ` +
+                `(${order.join(' → ')}) — the required-artifacts gate is not running for ` +
+                `this instance, so a reopen would not re-arm anything`,
+        };
+    }
+    if (amendment.reopens.length === 0) {
+        return {
+            kind: 'noop',
+            reason: 'the amendment declares no Reopens: field',
+        };
+    }
+    const namedIndexes = amendment.reopens.map((name) => order.indexOf(name));
+    const earliest = Math.min(...namedIndexes);
+    // AC-83: a Reopens: naming only phases at or after the current one is a hard
+    // error with its own variant, never a silent drop.
+    if (earliest >= currentIndex) {
+        return {
+            kind: 'phase-ahead',
+            names: amendment.reopens.filter((name) => order.indexOf(name) >= currentIndex),
+            currentPhase,
+        };
+    }
+    // The contiguous range, `skipped` phases removed (AC-85). A skip is not a
+    // completion: resurrecting it would demand artifacts deliberately never
+    // produced and leave `skip_reason` dangling beside `status: in-progress`.
+    const range = [];
+    for (let i = earliest; i <= currentIndex; i++) {
+        const name = order[i];
+        const state = phaseStates.get(name);
+        if (!state) {
+            // 15 live instances have no `phase-design.yaml` while `design` is in
+            // their applicable list. Advancing into a phase with no state file leaves
+            // Gate 1 failing permanently with "missing (no phase state)", so refuse
+            // rather than fabricate one (AC-92).
+            return {
+                kind: 'blocked',
+                code: 'phase-state-missing',
+                message: `phase "${name}" lies in the reopen range but has no phase-${name}.yaml ` +
+                    `— refusing rather than creating one`,
+            };
+        }
+        if (state.status === 'skipped')
+            continue;
+        range.push(name);
+    }
+    if (range.length === 0) {
+        return {
+            kind: 'noop',
+            reason: 'every phase in the range is skipped, so there is nothing to reopen',
+        };
+    }
+    const to = range[0];
+    if (to === currentPhase) {
+        // `from === to` must never reach the log: `metrics/report.ts:204-213` sets
+        // `opened` from `r.to` BEFORE reading `r.from`, so a self-referential record
+        // overwrites the phase's real entry timestamp, computes a zero interval and
+        // then discards the open interval — losing the first visit rather than
+        // summing it. Made unrepresentable rather than handled (AC-87).
+        return {
+            kind: 'noop',
+            reason: `"${currentPhase}" is already the open phase, so nothing needs reopening`,
+        };
+    }
+    const record = {
+        at: now.toISOString(),
+        by: actor,
+        from: currentPhase,
+        to,
+        type: 'reopen',
+        detail: {
+            amendment: amendment.n,
+            retires: [...amendment.retires].sort((a, b) => a - b),
+            issues: [...amendment.issues].sort((a, b) => a - b),
+            // The range actually rewritten, not the names the author wrote — they
+            // differ, and this is the audit record (AC-84).
+            reopened: range,
+        },
+    };
+    return {
+        kind: 'reopen',
+        phases: range,
+        from: currentPhase,
+        to,
+        newCurrentPhase: to,
+        record,
+    };
+}
+/**
+ * Apply a reopen plan.
+ *
+ * **Write order is deliberate** (AC-89): every phase state file first, then
+ * `instance.yaml` (`current_phase` and `applied_amendments` in one write), then
+ * the appended record last. A failure part-way therefore leaves phases reopened
+ * with the amendment unrecorded, which a re-run completes; the reverse order
+ * would leave the amendment recorded with phases untouched, which a re-run would
+ * refuse to fix.
+ */
+export function applyReopen(input) {
+    const { projectRoot, instance, plan, instanceState, phaseStates, resolvedTemplate, amendment, now, } = input;
+    const stateDir = join(projectRoot, '.aidlc', 'state');
+    const stamp = now.toISOString();
+    // 1. Phase states.
+    for (const phaseName of plan.phases) {
+        const state = phaseStates.get(phaseName);
+        if (!state)
+            continue; // planReopen already refused this case.
+        const templatePhase = resolvedTemplate.phases.find((p) => String(p.name) === phaseName);
+        const required = templatePhase
+            ? effectiveRequiredArtifacts(templatePhase, state).map((decl) => decl.name)
+            : [];
+        const requiredNames = new Set(required);
+        state.status = 'in-progress';
+        state.completed_at = null;
+        state.completed_by = null;
+        state.reopened_at = stamp;
+        // `entered_at` is deliberately untouched — see the docblock on
+        // `PhaseState.reopened_at`.
+        // Only artifacts ALREADY TRACKED whose name is in the effective required
+        // set. No entry is added or removed, so the `tasks.md` legacy filter at
+        // `core/gate.ts:123-131` is not defeated, and optional artifacts and
+        // `metrics` are left alone (AC-85).
+        for (const artifact of state.artifacts) {
+            if (requiredNames.has(artifact.name) && artifact.status === 'complete') {
+                artifact.status = 'in-progress';
+            }
+        }
+        saveSnapshot(stateDir, instance, `phase-${phaseName}.yaml`, state);
+    }
+    // 2. instance.yaml — current_phase and applied_amendments in one write.
+    instanceState.current_phase = plan.newCurrentPhase;
+    instanceState.applied_amendments = mergeApplied(instanceState.applied_amendments, amendment.n);
+    saveSnapshot(stateDir, instance, 'instance.yaml', instanceState);
+    // 3. The record, last.
+    appendTransition(join(stateDir, instance, 'transitions.log'), plan.record);
+}
+/**
+ * Record an amendment as applied without touching phase state — the no-op path
+ * (AC-87). An accounted-for amendment must not become destructive later when
+ * `current_phase` moves on its own.
+ */
+export function recordApplied(projectRoot, instance, instanceState, amendmentNumber) {
+    const stateDir = join(projectRoot, '.aidlc', 'state');
+    instanceState.applied_amendments = mergeApplied(instanceState.applied_amendments, amendmentNumber);
+    saveSnapshot(stateDir, instance, 'instance.yaml', instanceState);
+}
+/** Sorted, deduplicated union — so a repeat run is stable rather than growing. */
+export function mergeApplied(existing, n) {
+    return [...new Set([...(existing ?? []), n])].sort((a, b) => a - b);
+}
+//# sourceMappingURL=reopen.js.map