@rasensio/aidlc 1.16.0 → 1.18.0

package/dist/compliance/findings.js

@@ -0,0 +1,132 @@
+/**
+ * The compliance findings stream: `<artifact>.compliance.md`.
+ *
+ * Deliberately a different filename from `<artifact>.review.md`. Findings files are
+ * discovered in exactly one place — `loadFindings` in `commands/transition.ts`,
+ * which filters on `f.endsWith('.review.md')` — so a compliance file cannot reach
+ * `checkReviewGate`. That is what buys advisory-by-default for nothing:
+ * `checkReviewGate` blocks on *any* critical open finding, pooled across artifacts,
+ * and `Finding` has no control field, so a critical control finding living in a
+ * review file would block a transition regardless of `compliance.enforce`.
+ *
+ * The grammar is the shared one in `../review/findings-parser.ts`, plus two
+ * additions:
+ *
+ * - a `Control` bullet on a finding block, naming the control id;
+ * - a `## Controls Checked` section whose lines record controls examined with no
+ *   issue found.
+ *
+ * The cleared list is a separate production because coverage is satisfiable two
+ * ways: a finding carrying a control id, **or** an explicit no-issues line naming
+ * it. A no-issues line is not a finding — it has no severity, status or suggestion —
+ * so folding it into the finding grammar would mean inventing values for all three.
+ * Without it, a phase where every control passes would write a file the parser reads
+ * as empty, and the criterion would block on the whole applicable set.
+ *
+ * Requirements: compliance-packs/AC-62, AC-81
+ */
+import { extractBulletField, parseFrontmatter, parseSingleFinding, splitBlocks, stripFrontmatter, } from '../review/findings-parser.js';
+/** The heading that introduces the cleared list. */
+export const CLEARED_HEADING = 'Controls Checked';
+/** The suffix that marks a cleared line. Matched case-insensitively. */
+const CLEARED_SUFFIX_RE = /—\s*no issues\s*$|-\s*no issues\s*$/i;
+/** `<artifact>.compliance.md` for an artifact name. */
+export function complianceFindingsFilename(artifact) {
+    return `${artifact}.compliance.md`;
+}
+/**
+ * Parse a compliance findings file.
+ *
+ * Never throws. A malformed section becomes a warning, because a compliance file
+ * that fails to parse must degrade to "nothing is covered" — the conservative
+ * direction — rather than break an unrelated transition.
+ */
+export function parseComplianceFindings(content) {
+    const meta = parseFrontmatter(content);
+    const findings = [];
+    const cleared = [];
+    const warnings = [];
+    for (const block of splitBlocks(stripFrontmatter(content))) {
+        const heading = block.split('\n')[0]?.trim() ?? '';
+        if (heading.toLowerCase() === CLEARED_HEADING.toLowerCase()) {
+            for (const line of block.split('\n').slice(1)) {
+                const trimmed = line.trim();
+                if (trimmed === '')
+                    continue;
+                const control = extractBulletField(line, 'Control');
+                if (control === undefined) {
+                    if (trimmed.startsWith('-')) {
+                        warnings.push(`unparseable line in ${CLEARED_HEADING}: ${trimmed}`);
+                    }
+                    continue;
+                }
+                // `- **Control:** CC6.1 — no issues` → the id, with the suffix stripped.
+                const id = control.replace(CLEARED_SUFFIX_RE, '').trim();
+                if (id === '') {
+                    warnings.push(`${CLEARED_HEADING} line names no control: ${trimmed}`);
+                    continue;
+                }
+                if (!CLEARED_SUFFIX_RE.test(control)) {
+                    // A control listed without the no-issues marker is ambiguous: it might mean
+                    // "checked, fine" or "checked, and I never finished writing it up". Neither
+                    // reading is safe to assume, so it is not counted as cleared.
+                    warnings.push(`${CLEARED_HEADING} line for ${id} does not say "no issues" — not counted as covered`);
+                    continue;
+                }
+                cleared.push(id);
+            }
+            continue;
+        }
+        const finding = parseSingleFinding(block, findings.length + 1);
+        if (!finding)
+            continue;
+        const control = extractBulletField(block, 'Control');
+        findings.push({ ...finding, ...(control !== undefined && { control: control.trim() }) });
+    }
+    const withoutControl = findings.filter((f) => f.control === undefined);
+    if (withoutControl.length > 0) {
+        // A control finding with no control id cannot satisfy coverage for anything, and
+        // an author who wrote it believes they covered something. Say so.
+        warnings.push(`${withoutControl.length} finding(s) in the compliance stream carry no Control field`);
+    }
+    return { meta, findings, cleared, warnings };
+}
+/** Ids a compliance file accounts for: raised against, or explicitly cleared. */
+export function accountedControls(file) {
+    const ids = new Set(file.cleared);
+    for (const finding of file.findings) {
+        if (finding.control !== undefined)
+            ids.add(finding.control);
+    }
+    return ids;
+}
+/**
+ * Render the scaffold of a compliance findings file.
+ *
+ * Lists every applicable control so the reviewing agent cannot forget one, and marks
+ * each as pending rather than cleared — an unwritten file must never read as covered.
+ */
+export function renderComplianceScaffold(artifact, reviewer, controls, now = new Date()) {
+    const lines = [
+        '---',
+        `artifact: ${artifact}`,
+        `reviewed_at: ${now.toISOString().replace(/\.\d{3}Z$/, 'Z')}`,
+        `reviewer: ${reviewer}`,
+        '---',
+        '',
+        '<!--',
+        'For each control below: either write a finding block carrying its Control id, or',
+        `move it to the ${CLEARED_HEADING} section with "— no issues".`,
+        'A control left in neither place counts as uncovered.',
+        '-->',
+        '',
+        `## ${CLEARED_HEADING}`,
+        '',
+    ];
+    for (const control of controls) {
+        lines.push(`- **Control:** ${control.id} — PENDING: ${control.fails_when}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+//# sourceMappingURL=findings.js.map

package/dist/compliance/findings.js.map

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

package/dist/compliance/gate-criterion.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Compliance gate criterion, computed at the command layer after `evaluateGate`.
+ *
+ * Follows the convention `knowledge/`, `traceability/` and `tasks/` established: a
+ * `gate-criterion.ts` per concern, exporting an evaluator plus message helpers, and
+ * registered at both wiring sites. `core/gate.ts` and `core/lifecycle.ts` are not
+ * modified at all.
+ *
+ * Two properties matter more than the coverage arithmetic:
+ *
+ * **A project with no pack installed sees nothing.** The evaluator returns `null`,
+ * the command layer assigns no field, and behaviour is what it was before this
+ * feature existed. That is the constraint the whole design is organised around, and
+ * `null` is the mechanism.
+ *
+ * **Advisory is the default.** Findings are computed and reported whether or not
+ * enforcement is on; only `compliance.enforce: true` turns them into gate failures.
+ * Because control findings live in their own stream, the pre-existing review gate
+ * never sees them, so advisory costs no change to gate logic.
+ *
+ * Coverage is measured over the **effective** required artifacts, not the template's
+ * raw list. The repo is already inconsistent here — `checkRequiredArtifacts` applies
+ * the legacy `tasks.md` filter and `checkReviewGate` does not — and using the raw
+ * list would block a pre-existing design-phase instance from transitioning under
+ * enforcement until someone wrote a compliance file for an artifact the
+ * required-artifacts gate agrees is optional.
+ *
+ * Requirements: compliance-packs/AC-25, AC-26, AC-55, AC-56, AC-62, AC-82
+ */
+import type { WorkflowTemplate } from '../core/types.js';
+import type { Control } from './types.js';
+/** One control that applies to the phase under evaluation. */
+export interface ApplicableControl {
+    packId: string;
+    control: Control;
+}
+/** A control that no artifact accounted for. */
+export interface UncoveredControl {
+    controlId: string;
+    artifact: string;
+}
+/** A critical control finding left open. */
+export interface OpenCriticalControl {
+    controlId: string;
+    findingId: string;
+    artifact: string;
+}
+/** Outcome of the compliance criterion for one phase. */
+export interface ComplianceResult {
+    /** Packs consulted, by id. */
+    packs: string[];
+    /** Whether `compliance.enforce` is on. Drives failure, never computation. */
+    enforce: boolean;
+    /** Controls applying to this phase. */
+    applicable: string[];
+    /** Artifacts whose coverage was measured. */
+    artifacts: string[];
+    /** Control/artifact pairs with neither a finding nor a cleared line. */
+    uncovered: UncoveredControl[];
+    /** Critical control findings still open. */
+    openCritical: OpenCriticalControl[];
+    /** Non-fatal problems: unparseable lines, packs that no longer resolve. */
+    warnings: string[];
+}
+/** Message for a control no artifact accounted for. */
+export declare function uncoveredControlMessage(controlId: string, artifact: string): string;
+/** Message for an open critical control finding. */
+export declare function criticalControlMessage(controlId: string, findingId: string): string;
+/** Message for an installed pack that will not load. */
+export declare function packLoadErrorMessage(packId: string, detail: string): string;
+/**
+ * Evaluate the compliance criterion for one phase.
+ *
+ * @returns `null` when the criterion does not apply — no pack installed, or no
+ *   control applies to this phase. Never an empty result standing in for "off":
+ *   the command layer distinguishes the two by the null.
+ */
+export declare function evaluateComplianceCriterion(projectRoot: string, instanceName: string, phaseName: string, template: WorkflowTemplate | null): ComplianceResult | null;
+/**
+ * The gate failures a result implies.
+ *
+ * Empty unless `enforce` is on. Advisory mode still produces the result — the
+ * findings are recorded and reported — it simply produces no failures, which is the
+ * whole meaning of advisory.
+ */
+export declare function complianceFailures(result: ComplianceResult): string[];
+//# sourceMappingURL=gate-criterion.d.ts.map

package/dist/compliance/gate-criterion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate-criterion.d.ts","sourceRoot":"","sources":["../../src/compliance/gate-criterion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAOH,OAAO,KAAK,EAAc,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAQrE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,gDAAgD;AAChD,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAC/B,8BAA8B;IAC9B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAC;IACjB,uCAAuC;IACvC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,wEAAwE;IACxE,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,4CAA4C;IAC5C,YAAY,EAAE,mBAAmB,EAAE,CAAC;IACpC,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,uDAAuD;AACvD,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEnF;AAED,oDAAoD;AACpD,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEnF;AAED,wDAAwD;AACxD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE3E;AAaD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,gBAAgB,GAAG,IAAI,GAChC,gBAAgB,GAAG,IAAI,CAiGzB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAMrE"}

package/dist/compliance/gate-criterion.js

@@ -0,0 +1,168 @@
+/**
+ * Compliance gate criterion, computed at the command layer after `evaluateGate`.
+ *
+ * Follows the convention `knowledge/`, `traceability/` and `tasks/` established: a
+ * `gate-criterion.ts` per concern, exporting an evaluator plus message helpers, and
+ * registered at both wiring sites. `core/gate.ts` and `core/lifecycle.ts` are not
+ * modified at all.
+ *
+ * Two properties matter more than the coverage arithmetic:
+ *
+ * **A project with no pack installed sees nothing.** The evaluator returns `null`,
+ * the command layer assigns no field, and behaviour is what it was before this
+ * feature existed. That is the constraint the whole design is organised around, and
+ * `null` is the mechanism.
+ *
+ * **Advisory is the default.** Findings are computed and reported whether or not
+ * enforcement is on; only `compliance.enforce: true` turns them into gate failures.
+ * Because control findings live in their own stream, the pre-existing review gate
+ * never sees them, so advisory costs no change to gate logic.
+ *
+ * Coverage is measured over the **effective** required artifacts, not the template's
+ * raw list. The repo is already inconsistent here — `checkRequiredArtifacts` applies
+ * the legacy `tasks.md` filter and `checkReviewGate` does not — and using the raw
+ * list would block a pre-existing design-phase instance from transitioning under
+ * enforcement until someone wrote a compliance file for an artifact the
+ * required-artifacts gate agrees is optional.
+ *
+ * Requirements: compliance-packs/AC-25, AC-26, AC-55, AC-56, AC-62, AC-82
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { effectiveRequiredArtifacts } from '../core/gate.js';
+import { readComplianceConfig } from './config.js';
+import { accountedControls, complianceFindingsFilename, parseComplianceFindings, } from './findings.js';
+import { controlsForPhase, resolvePack } from './resolver.js';
+/** Message for a control no artifact accounted for. */
+export function uncoveredControlMessage(controlId, artifact) {
+    return `control ${controlId} is not accounted for in "${artifact}" (compliance)`;
+}
+/** Message for an open critical control finding. */
+export function criticalControlMessage(controlId, findingId) {
+    return `control ${controlId} has an open critical finding "${findingId}" (compliance)`;
+}
+/** Message for an installed pack that will not load. */
+export function packLoadErrorMessage(packId, detail) {
+    return `installed pack '${packId}' did not load: ${detail} (compliance)`;
+}
+/** Read one phase state file, or undefined. */
+function loadPhaseState(instanceDir, phase) {
+    const path = join(instanceDir, `phase-${phase}.yaml`);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        return parseYaml(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Evaluate the compliance criterion for one phase.
+ *
+ * @returns `null` when the criterion does not apply — no pack installed, or no
+ *   control applies to this phase. Never an empty result standing in for "off":
+ *   the command layer distinguishes the two by the null.
+ */
+export function evaluateComplianceCriterion(projectRoot, instanceName, phaseName, template) {
+    const config = readComplianceConfig(projectRoot);
+    if (config.packs.length === 0)
+        return null;
+    const warnings = [];
+    const applicable = [];
+    for (const record of config.packs) {
+        const resolved = resolvePack(record.id);
+        if (!resolved.ok) {
+            // An installed pack that will not load is loud, never an empty result — the
+            // silent-no-op shape this project has already been burned by.
+            warnings.push(packLoadErrorMessage(record.id, resolved.error.errors.join('; ')));
+            continue;
+        }
+        for (const control of controlsForPhase(resolved.pack, phaseName)) {
+            applicable.push({ packId: record.id, control });
+        }
+    }
+    if (applicable.length === 0) {
+        // Packs are installed but none of their controls touch this phase. Not a
+        // failure, and not nothing: reported with an empty applicable set so the caller
+        // can say "no applicable controls" rather than staying silent.
+        return {
+            packs: config.packs.map((p) => p.id),
+            enforce: config.enforce,
+            applicable: [],
+            artifacts: [],
+            uncovered: [],
+            openCritical: [],
+            warnings,
+        };
+    }
+    const instanceDir = join(projectRoot, '.aidlc', 'state', instanceName);
+    const templatePhase = template?.phases.find((p) => p.name === phaseName);
+    const phaseState = loadPhaseState(instanceDir, phaseName);
+    const artifacts = templatePhase
+        ? effectiveRequiredArtifacts(templatePhase, phaseState).map((a) => a.name)
+        : [];
+    const uncovered = [];
+    const openCritical = [];
+    for (const artifact of artifacts) {
+        const path = join(instanceDir, complianceFindingsFilename(artifact));
+        if (!existsSync(path)) {
+            for (const { control } of applicable) {
+                uncovered.push({ controlId: control.id, artifact });
+            }
+            continue;
+        }
+        let file;
+        try {
+            file = parseComplianceFindings(readFileSync(path, 'utf8'));
+        }
+        catch (err) {
+            warnings.push(`compliance findings for "${artifact}" are unreadable (${err.message}) — treated as uncovered`);
+            for (const { control } of applicable) {
+                uncovered.push({ controlId: control.id, artifact });
+            }
+            continue;
+        }
+        warnings.push(...file.warnings.map((w) => `${artifact}: ${w}`));
+        const accounted = accountedControls(file);
+        for (const { control } of applicable) {
+            if (!accounted.has(control.id)) {
+                uncovered.push({ controlId: control.id, artifact });
+            }
+        }
+        for (const finding of file.findings) {
+            if (finding.control !== undefined &&
+                finding.severity === 'critical' &&
+                finding.status === 'open' &&
+                finding.placeholder !== true) {
+                openCritical.push({ controlId: finding.control, findingId: finding.id, artifact });
+            }
+        }
+    }
+    return {
+        packs: config.packs.map((p) => p.id),
+        enforce: config.enforce,
+        applicable: applicable.map((a) => a.control.id),
+        artifacts,
+        uncovered,
+        openCritical,
+        warnings,
+    };
+}
+/**
+ * The gate failures a result implies.
+ *
+ * Empty unless `enforce` is on. Advisory mode still produces the result — the
+ * findings are recorded and reported — it simply produces no failures, which is the
+ * whole meaning of advisory.
+ */
+export function complianceFailures(result) {
+    if (!result.enforce)
+        return [];
+    return [
+        ...result.uncovered.map((u) => uncoveredControlMessage(u.controlId, u.artifact)),
+        ...result.openCritical.map((c) => criticalControlMessage(c.controlId, c.findingId)),
+    ];
+}
+//# sourceMappingURL=gate-criterion.js.map

package/dist/compliance/gate-criterion.js.map

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

package/dist/compliance/install.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Pack install, remove and upgrade.
+ *
+ * Uses the layer-install primitive with the **recorded-hash** detector, never the
+ * bundled-body one. That choice is the whole reason the primitive takes a detector:
+ * comparing a pack layer against the currently bundled body conflates "the user
+ * edited this" with "we published a new version", which would make every layer read
+ * as edited after any content update — so `remove` would refuse to delete anything
+ * and corrected control text would never land.
+ *
+ * Three rules govern what happens to files:
+ *
+ * - **Install never overwrites.** A layer already on disk is left alone and
+ *   classified, exactly as framework install does.
+ * - **Remove deletes only what it can prove it wrote.** Unmodified means the disk
+ *   hash matches the hash recorded at install. Anything else is the project's file
+ *   now, and stays.
+ * - **A left-behind file loses its registration.** Keeping bytes is respect for the
+ *   user's edit; keeping the registration would keep feeding an uninstalled pack's
+ *   constraints to every agent.
+ *
+ * Requirements: compliance-packs/AC-9, AC-10, AC-11, AC-12, AC-13, AC-16, AC-54,
+ * AC-68, AC-69, AC-70, AC-71, AC-72
+ */
+import type { PackError } from './types.js';
+/** Outcome of an install attempt. */
+export type InstallResult = {
+    ok: true;
+    /** Layer names newly written. */
+    installed: string[];
+    /** Layer names already present and matching what we recorded. */
+    alreadyCurrent: string[];
+    /** Layer names present but changed since install — left untouched. */
+    locallyModified: string[];
+    /** True when this was a no-op because the pack was already installed. */
+    unchanged: boolean;
+    warnings: string[];
+} | {
+    ok: false;
+    error: PackError;
+};
+/**
+ * Install a pack into a project.
+ *
+ * Idempotent: a second run writes nothing new and reports `unchanged`. Validation
+ * happens first and covers the whole pack, so a pack with one malformed control
+ * installs nothing at all.
+ */
+export declare function installPack(projectRoot: string, id: string, opts?: {
+    dryRun?: boolean;
+    now?: Date;
+}): InstallResult;
+/** Outcome of a remove attempt. */
+export type RemoveResult = {
+    ok: true;
+    /** Files deleted, repo-relative. */
+    deleted: string[];
+    /**
+     * Files left on disk because they no longer match what we wrote, repo-relative.
+     * Their registrations were still dropped, so they no longer reach any agent.
+     */
+    keptPaths: string[];
+    /** Layer registrations dropped from the index. */
+    unregistered: string[];
+    warnings: string[];
+} | {
+    ok: false;
+    error: PackError;
+};
+/**
+ * Remove an installed pack.
+ *
+ * Deletes only layers whose on-disk hash matches the hash recorded at install.
+ * Every registration is dropped either way, so nothing an uninstalled pack owns
+ * keeps influencing an agent.
+ *
+ * Resolution of the pack is **not** required: a pack must remain removable after the
+ * content package stops shipping it, which is precisely when a user most wants it
+ * gone. The config record alone is enough.
+ */
+export declare function removePack(projectRoot: string, id: string, opts?: {
+    dryRun?: boolean;
+}): RemoveResult;
+/** What `aidlc compliance list` needs to say about one pack. */
+export interface PackStatus {
+    id: string;
+    regime: string;
+    /** Version available in the content package, or null when it no longer ships. */
+    available: string | null;
+    /** Version recorded at install, or null when not installed. */
+    installed: string | null;
+    /** Recorded version differs from the available one. */
+    stale: boolean;
+    /** Whether the pack's control text has been reviewed by a practitioner. */
+    reviewed: boolean;
+    /**
+     * Installed layer files whose on-disk hash no longer matches the recorded one.
+     *
+     * Reported for every installed pack, not only when a notice is missing: in a cloned
+     * repository an installed layer is content the repo author could have changed, and a
+     * locally edited layer is preserved forever by design.
+     */
+    drifted: string[];
+}
+/** Status of every available pack, plus any installed pack that no longer ships. */
+export declare function packStatuses(projectRoot: string): {
+    statuses: PackStatus[];
+    errors: PackError[];
+};
+/** Outcome of an upgrade attempt. */
+export type UpgradeResult = {
+    ok: true;
+    from: string;
+    to: string;
+    replaced: string[];
+    keptPaths: string[];
+    warnings: string[];
+} | {
+    ok: false;
+    error: PackError;
+};
+/**
+ * Upgrade an installed pack to the version the content package ships.
+ *
+ * Deliberately its own command. Neither `aidlc update` nor `aidlc doctor` may do
+ * this: pack content is what a buyer is told they are being governed by, and
+ * changing it under them without a word is not an upgrade, it is a substitution.
+ *
+ * A locally edited layer is never overwritten. It is left in place and reported, so
+ * the user decides whether to discard their edit.
+ */
+export declare function upgradePack(projectRoot: string, id: string, opts?: {
+    dryRun?: boolean;
+}): UpgradeResult;
+//# sourceMappingURL=install.d.ts.map

package/dist/compliance/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/compliance/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAiBH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAO5C,qCAAqC;AACrC,MAAM,MAAM,aAAa,GACrB;IACE,EAAE,EAAE,IAAI,CAAC;IACT,iCAAiC;IACjC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,iEAAiE;IACjE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,sEAAsE;IACtE,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,yEAAyE;IACzE,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC;AAEpC;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAA;CAAO,GAC1C,aAAa,CA6Ef;AAED,mCAAmC;AACnC,MAAM,MAAM,YAAY,GACpB;IACE,EAAE,EAAE,IAAI,CAAC;IACT,oCAAoC;IACpC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;OAGG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,kDAAkD;IAClD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC;AAEpC;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CACxB,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAC9B,YAAY,CAyEd;AAeD,gEAAgE;AAChE,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,uDAAuD;IACvD,KAAK,EAAE,OAAO,CAAC;IACf,2EAA2E;IAC3E,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;IAAC,MAAM,EAAE,SAAS,EAAE,CAAA;CAAE,CA0CjG;AAWD,qCAAqC;AACrC,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GACnG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC;AAEpC;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAC9B,aAAa,CAqCf"}