@rasensio/aidlc 1.20.0 → 1.21.0

package/dist/roadmap/sync/plan.js

@@ -0,0 +1,272 @@
+/**
+ * The projection planner. Pure — and the purity is the point.
+ *
+ * This module imports no `node:fs`, no `node:child_process`, and not `gh.ts`. A test
+ * pins that over the import graph, which is what makes "planning needs no network" a
+ * property of the code rather than a claim about the test suite: hand the command a
+ * runner that throws on every invocation and planning still succeeds, because the
+ * planner never had one.
+ *
+ * Refusals are **values**, in a fixed order, so a tree with two problems always yields
+ * the same message and the command layer — not this module — decides the exit code.
+ *
+ * Requirements: roadmap-issue-projection/AC-14 … roadmap-issue-projection/AC-32,
+ * roadmap-issue-projection/AC-44
+ *
+ * @module
+ */
+import { ROADMAP_STATUSES } from '../paths.js';
+import { isStatusLabel, statusLabel } from './labels.js';
+import { findMarkerIds } from './marker.js';
+import { WRITE_ORDER, isWrite, } from './types.js';
+/** GitHub's own issue-title limit. */
+export const MAX_ISSUE_TITLE_LENGTH = 256;
+export function planProjection(input) {
+    const { config, items, unprojectable, issues, retireIneligible, repoLabel } = input;
+    const eligible = new Set(config.statuses);
+    // -------------------------------------------------------------------------
+    // Refusals, in a fixed order (design: one deterministic message per tree)
+    // -------------------------------------------------------------------------
+    const duplicateIds = findDuplicateIds(items);
+    if (duplicateIds !== null)
+        return { kind: 'refused', error: duplicateIds };
+    const blockingItems = unprojectable.filter((u) => eligible.has(u.status));
+    if (blockingItems.length > 0) {
+        return { kind: 'refused', error: unprojectableMessage(blockingItems) };
+    }
+    const markerIndex = indexByMarker(issues);
+    if (markerIndex.kind === 'ambiguous') {
+        return { kind: 'refused', error: markerIndex.error };
+    }
+    const overLong = items.filter((i) => eligible.has(i.status) && i.title.length > MAX_ISSUE_TITLE_LENGTH);
+    if (overLong.length > 0) {
+        return {
+            kind: 'refused',
+            error: `these item titles exceed GitHub's ${MAX_ISSUE_TITLE_LENGTH}-character issue title limit ` +
+                'and would fail mid-run, after consent:\n' +
+                overLong.map((i) => `  ${i.status}/${i.filename} (${i.title.length} characters)`).join('\n'),
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Outcomes
+    // -------------------------------------------------------------------------
+    const warnings = unprojectable
+        .filter((u) => !eligible.has(u.status))
+        .map((u) => `${u.label} is not projectable (${u.reason}), and its status is not projected`);
+    const byId = markerIndex.byId;
+    const lines = [];
+    const claimedIssues = new Set();
+    for (const item of items) {
+        const issue = byId.get(item.id) ?? null;
+        if (issue !== null)
+            claimedIssues.add(issue.number);
+        lines.push(...linesForItem(item, issue, eligible, retireIneligible));
+    }
+    // Issue-only lines: an issue nothing on disk claims.
+    for (const issue of issues) {
+        if (claimedIssues.has(issue.number))
+            continue;
+        const markers = findMarkerIds(issue.body);
+        if (markers.length === 0) {
+            lines.push(line('label-without-marker', null, issue.number, 'carries the discovery label but no aidlc-item marker'));
+        }
+        else {
+            lines.push(line('orphan-missing', null, issue.number, `marker names ${markers[0]}, which no item on disk has`));
+        }
+    }
+    return { kind: 'ok', plan: assemble(lines, config, repoLabel), warnings };
+}
+// ---------------------------------------------------------------------------
+// Outcome derivation
+// ---------------------------------------------------------------------------
+/**
+ * The lines one item produces.
+ *
+ * A **terminal report** — `state-divergent`, `ineligible-with-issue` — is the only line
+ * its item emits. That is not a stylistic choice: collecting outcomes unconditionally
+ * would emit `update-title` alongside `state-divergent`, writing to an issue a human
+ * deliberately closed. Closing an issue is the primary triage act of the very user this
+ * feature is for, so a projection that edits a closed issue relocates the two-writer
+ * loop rather than removing it.
+ *
+ * Non-terminal branches *are* collected, so a `done` item that was also retitled in the
+ * same run emits both `update-title` and `close` and converges in one pass.
+ */
+function linesForItem(item, issue, eligible, retireIneligible) {
+    const isEligible = eligible.has(item.status);
+    if (issue === null) {
+        if (!isEligible)
+            return [];
+        if (item.status === 'done') {
+            return [line('skip', item, null, 'not-backfilled')];
+        }
+        return [
+            {
+                outcome: 'create',
+                item,
+                issueNumber: null,
+                detail: null,
+                addLabels: [statusLabel(item.status)],
+                removeLabels: [],
+            },
+        ];
+    }
+    if (!isEligible) {
+        if (retireIneligible) {
+            return [line('close', item, issue.number, `${item.status} is not a projected status`)];
+        }
+        return [
+            line('ineligible-with-issue', item, issue.number, `item is in ${item.status}, which is not projected; the issue is still open`),
+        ];
+    }
+    if (item.status !== 'done' && issue.state === 'CLOSED') {
+        return [
+            line('state-divergent', item, issue.number, `issue is closed but the item is still in ${item.status} — left alone`),
+        ];
+    }
+    const collected = [];
+    if (issue.title !== item.title) {
+        collected.push(line('update-title', item, issue.number, null));
+    }
+    const wanted = statusLabel(item.status);
+    const stale = issue.labels.filter((l) => isStatusLabel(l) && l !== wanted);
+    const hasWanted = issue.labels.includes(wanted);
+    if (!hasWanted || stale.length > 0) {
+        collected.push({
+            outcome: 'update-labels',
+            item,
+            issueNumber: issue.number,
+            detail: null,
+            addLabels: hasWanted ? [] : [wanted],
+            removeLabels: stale,
+        });
+    }
+    if (item.status === 'done' && issue.state === 'OPEN') {
+        collected.push(line('close', item, issue.number, null));
+    }
+    if (collected.length === 0) {
+        return [line('unchanged', item, issue.number, null)];
+    }
+    return collected;
+}
+function line(outcome, item, issueNumber, detail) {
+    return { outcome, item, issueNumber, detail, addLabels: [], removeLabels: [] };
+}
+// ---------------------------------------------------------------------------
+// Indexing and refusal messages
+// ---------------------------------------------------------------------------
+/** Two items sharing an id would plan opposite writes against one issue, every run. */
+function findDuplicateIds(items) {
+    const seen = new Map();
+    const clashes = [];
+    for (const item of items) {
+        const prior = seen.get(item.id);
+        if (prior === undefined) {
+            seen.set(item.id, item);
+            continue;
+        }
+        clashes.push(`  ${item.id}\n    ${prior.status}/${prior.filename}\n    ${item.status}/${item.filename}`);
+    }
+    if (clashes.length === 0)
+        return null;
+    return ('two roadmap items share one id, so the projection cannot tell which one an issue ' +
+        'belongs to:\n' +
+        clashes.join('\n') +
+        '\nRemove or re-id one of each pair, then run again.');
+}
+/**
+ * Index issues by the item id in their marker.
+ *
+ * Two issues carrying one marker is refused rather than resolved: picking either would
+ * mean confidently retitling or closing the wrong one.
+ */
+function indexByMarker(issues) {
+    const byId = new Map();
+    const clashes = [];
+    for (const issue of issues) {
+        for (const id of findMarkerIds(issue.body)) {
+            const prior = byId.get(id);
+            if (prior === undefined) {
+                byId.set(id, issue);
+                continue;
+            }
+            clashes.push(`  ${id} — issues #${prior.number} and #${issue.number}`);
+        }
+    }
+    if (clashes.length > 0) {
+        return {
+            kind: 'ambiguous',
+            error: 'more than one issue carries the same aidlc-item marker, so the projection cannot ' +
+                'tell which is canonical:\n' +
+                clashes.join('\n') +
+                '\nRemove the marker from whichever issue is not the canonical one, then run again.',
+        };
+    }
+    return { kind: 'ok', byId };
+}
+/**
+ * The unprojectable-item refusal.
+ *
+ * Split by class, because the remedies differ and only one of them has a tool. Sending
+ * somebody to `aidlc doctor` for a missing `id` would send them to a command that reports
+ * nothing at all.
+ */
+function unprojectableMessage(blocking) {
+    const repairable = blocking.filter((u) => u.cls === 'unparseable');
+    const manual = blocking.filter((u) => u.cls === 'missing-id');
+    const parts = [
+        'these roadmap items are in a projected status but cannot be read, so the projection ' +
+            'would silently leave them out of both the repo and the tracker:',
+    ];
+    if (repairable.length > 0) {
+        parts.push('', '  frontmatter will not parse — run `aidlc doctor`, which repairs the common case ' +
+            '(an unquoted title):', ...repairable.map((u) => `    ${u.label} — ${u.reason}`));
+    }
+    if (manual.length > 0) {
+        parts.push('', '  no `id:` — `aidlc doctor` does not detect this class; add an id by hand:', ...manual.map((u) => `    ${u.label} — ${u.reason}`));
+    }
+    return parts.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Assembly and ordering
+// ---------------------------------------------------------------------------
+/**
+ * Total order (so two runs over identical inputs print byte-identically):
+ * item lines by status then filename then execution order; issue-only lines after them,
+ * by issue number.
+ *
+ * The outcome component is compared through `WRITE_ORDER`, not as a string, so two lines
+ * for one item appear in the order they will be executed rather than in alphabetical
+ * accident.
+ */
+function assemble(lines, config, repoLabel) {
+    const sorted = [...lines].sort(compareLines);
+    const counts = {};
+    let writeCount = 0;
+    for (const l of sorted) {
+        counts[l.outcome] = (counts[l.outcome] ?? 0) + 1;
+        if (isWrite(l.outcome))
+            writeCount += 1;
+    }
+    return { repoLabel, repo: config.repo, lines: sorted, counts, writeCount };
+}
+function compareLines(a, b) {
+    if (a.item === null && b.item === null)
+        return (a.issueNumber ?? 0) - (b.issueNumber ?? 0);
+    if (a.item === null)
+        return 1;
+    if (b.item === null)
+        return -1;
+    const statusDelta = ROADMAP_STATUSES.indexOf(a.item.status) - ROADMAP_STATUSES.indexOf(b.item.status);
+    if (statusDelta !== 0)
+        return statusDelta;
+    if (a.item.filename !== b.item.filename)
+        return a.item.filename < b.item.filename ? -1 : 1;
+    return outcomeRank(a.outcome) - outcomeRank(b.outcome);
+}
+/** Execution order first, then everything else in a fixed position. */
+function outcomeRank(outcome) {
+    const index = WRITE_ORDER.indexOf(outcome);
+    return index === -1 ? WRITE_ORDER.length : index;
+}
+//# sourceMappingURL=plan.js.map

package/dist/roadmap/sync/plan.js.map

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

package/dist/roadmap/sync/render.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Plan → text.
+ *
+ * Two rules the plan output has to keep:
+ *
+ * - **The resolved repository is named in the header.** A well-formed but wrong
+ *   repository coordinate publishes the roadmap to somebody else's repo, and that is only
+ *   reversible before the first write. Printing it is the whole mitigation.
+ * - **Every outcome prints as a word.** Colour, if ever added, is decoration; the
+ *   accessibility guidance forbids colour as the sole carrier of meaning, and a piped or
+ *   logged plan has no colour at all.
+ *
+ * Requirements: roadmap-issue-projection/AC-40
+ *
+ * @module
+ */
+import { type Plan } from './types.js';
+export declare function renderPlan(plan: Plan): string;
+/**
+ * The counts, writes first.
+ *
+ * Printed before consent so a first run against a mature roadmap — forty creates — is a
+ * visible decision rather than a surprise.
+ */
+export declare function summary(plan: Plan): string;
+/** The confirmation question. Names the repository again, deliberately. */
+export declare function confirmMessage(plan: Plan): string;
+//# sourceMappingURL=render.d.ts.map

package/dist/roadmap/sync/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../../src/roadmap/sync/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAyB,KAAK,IAAI,EAAiB,MAAM,YAAY,CAAC;AA8B7E,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAoB7C;AAwBD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAiB1C;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAEjD"}

package/dist/roadmap/sync/render.js

@@ -0,0 +1,110 @@
+/**
+ * Plan → text.
+ *
+ * Two rules the plan output has to keep:
+ *
+ * - **The resolved repository is named in the header.** A well-formed but wrong
+ *   repository coordinate publishes the roadmap to somebody else's repo, and that is only
+ *   reversible before the first write. Printing it is the whole mitigation.
+ * - **Every outcome prints as a word.** Colour, if ever added, is decoration; the
+ *   accessibility guidance forbids colour as the sole carrier of meaning, and a piped or
+ *   logged plan has no colour at all.
+ *
+ * Requirements: roadmap-issue-projection/AC-40
+ *
+ * @module
+ */
+import { isWrite } from './types.js';
+/** Display order for the counts summary: writes first, then reports. */
+const COUNT_ORDER = [
+    'create',
+    'update-title',
+    'update-labels',
+    'close',
+    'unchanged',
+    'skip',
+    'state-divergent',
+    'ineligible-with-issue',
+    'orphan-missing',
+    'label-without-marker',
+];
+/** One-line human gloss per outcome, so the plan reads without a legend. */
+const GLOSS = {
+    create: 'create an issue',
+    'update-title': 'update the issue title',
+    'update-labels': 'update the aidlc: status label',
+    close: 'close the issue',
+    unchanged: 'already matches',
+    skip: 'not projected',
+    'state-divergent': 'closed remotely, item still live — left alone',
+    'ineligible-with-issue': 'status no longer projected, issue still open',
+    'orphan-missing': 'no item on disk',
+    'label-without-marker': 'labelled but not projected by aidlc',
+};
+export function renderPlan(plan) {
+    const out = [];
+    out.push(`Roadmap projection plan — ${plan.repoLabel}`);
+    out.push('');
+    if (plan.lines.length === 0) {
+        out.push('  nothing to project: no items in a projected status, and no labelled issues.');
+        out.push('');
+        return out.join('\n');
+    }
+    for (const line of plan.lines) {
+        out.push(`  ${renderLine(line)}`);
+    }
+    out.push('');
+    out.push(summary(plan));
+    out.push('');
+    return out.join('\n');
+}
+function renderLine(line) {
+    const subject = line.item === null
+        ? `#${line.issueNumber}`
+        : `${line.item.status}/${line.item.filename}` +
+            (line.issueNumber === null ? '' : ` → #${line.issueNumber}`);
+    const parts = [pad(line.outcome), subject];
+    const notes = [];
+    if (line.addLabels.length > 0)
+        notes.push(`+${line.addLabels.join(' +')}`);
+    if (line.removeLabels.length > 0)
+        notes.push(`-${line.removeLabels.join(' -')}`);
+    if (line.detail !== null)
+        notes.push(line.detail);
+    if (notes.length > 0)
+        parts.push(`(${notes.join('; ')})`);
+    return parts.join(' ');
+}
+/** Left-pad the outcome word so the subjects line up without a table. */
+function pad(outcome) {
+    const width = Math.max(...COUNT_ORDER.map((o) => o.length));
+    return outcome.padEnd(width, ' ');
+}
+/**
+ * The counts, writes first.
+ *
+ * Printed before consent so a first run against a mature roadmap — forty creates — is a
+ * visible decision rather than a surprise.
+ */
+export function summary(plan) {
+    const present = COUNT_ORDER.filter((o) => (plan.counts[o] ?? 0) > 0);
+    const writes = present.filter(isWrite);
+    const reports = present.filter((o) => !isWrite(o));
+    const lines = [];
+    lines.push(plan.writeCount === 0
+        ? '  No writes. Nothing on GitHub would change.'
+        : `  ${plan.writeCount} write${plan.writeCount === 1 ? '' : 's'}:`);
+    for (const o of writes)
+        lines.push(`    ${plan.counts[o]} × ${o} — ${GLOSS[o]}`);
+    if (reports.length > 0) {
+        lines.push('  Reported only:');
+        for (const o of reports)
+            lines.push(`    ${plan.counts[o]} × ${o} — ${GLOSS[o]}`);
+    }
+    return lines.join('\n');
+}
+/** The confirmation question. Names the repository again, deliberately. */
+export function confirmMessage(plan) {
+    return `Apply ${plan.writeCount} write${plan.writeCount === 1 ? '' : 's'} to ${plan.repoLabel}?`;
+}
+//# sourceMappingURL=render.js.map

package/dist/roadmap/sync/render.js.map

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

package/dist/roadmap/sync/types.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Shared types for the roadmap → GitHub Issues projection.
+ *
+ * The projection is one-way: disk is the source of truth and the tracker is a
+ * rendering of it. Two consequences show up throughout these types.
+ *
+ * First, `sync` writes nothing to disk (design DD-1). There is no `remote:`
+ * frontmatter field and no cache: the durable link is the item `id`, carried in a
+ * body marker on the issue. Creating an issue and writing a local link would be two
+ * writes to two systems, and every failure of the second produces a duplicate on the
+ * next run.
+ *
+ * Second, an outcome is a *value*, not an action. `planProjection` returns a plan of
+ * outcomes and the command layer decides what to do with it, which is what makes the
+ * whole projection testable with no network and no `gh` binary.
+ *
+ * Requirements: roadmap-issue-projection/AC-14, roadmap-issue-projection/AC-46
+ *
+ * @module
+ */
+import type { RoadmapStatus } from '../paths.js';
+/**
+ * What the projection concluded about one item, or one issue.
+ *
+ * A closed set. The design review found that an open-ended vocabulary made two
+ * criteria unachievable — "the second plan contains only X or Y" cannot be checked
+ * against a list nobody wrote down.
+ */
+export type Outcome = 'create' | 'update-title' | 'update-labels' | 'close' | 'unchanged' | 'skip' | 'state-divergent' | 'ineligible-with-issue' | 'orphan-missing' | 'label-without-marker';
+/** The four outcomes that write. Everything else is a report. */
+export declare const WRITE_OUTCOMES: readonly Outcome[];
+/**
+ * Outcomes that suppress every write for their item (design DE-18).
+ *
+ * `state-divergent` means a human closed the issue while the item is still live.
+ * Reopening it would relocate the two-writer loop rather than remove it, and
+ * retitling it would write to an issue somebody deliberately closed. So a terminal
+ * report is the *only* line its item emits.
+ */
+export declare const TERMINAL_REPORTS: readonly Outcome[];
+/** Execution order within one item: edit while the issue is still open, then close. */
+export declare const WRITE_ORDER: readonly Outcome[];
+/** True when this outcome performs a `gh` write. */
+export declare function isWrite(outcome: Outcome): boolean;
+/** An item that can be projected: parseable, with an id. */
+export interface ProjectableItem {
+    id: string;
+    /** Falls back to the filename slug when frontmatter carries no title. */
+    title: string;
+    status: RoadmapStatus;
+    filename: string;
+    /** Repo-relative path, for the issue body. */
+    relPath: string;
+}
+/**
+ * Why an item cannot be projected.
+ *
+ * The two classes are distinguished because their remedies differ and only one of
+ * them has a tool. `aidlc doctor` repairs an unquoted title; nothing reports an item
+ * that parses fine with no `id`, so pointing a user at `doctor` for that class would
+ * send them to a command that says nothing (design DE-14).
+ */
+export type UnprojectableClass = 'unparseable' | 'missing-id';
+export interface UnprojectableRef {
+    /** `<status>/<filename>` — the form doctor output uses. */
+    label: string;
+    status: RoadmapStatus;
+    cls: UnprojectableClass;
+    reason: string;
+}
+/**
+ * One issue as the projection needs it.
+ *
+ * `labels` is already flattened to names. `gh issue list --json labels` returns
+ * objects (`{id,name,description,color}`), and treating them as strings would make
+ * every status-label comparison fail — so every item would plan `update-labels` on
+ * every run, forever, and the projection would never converge (design DE-9).
+ */
+export interface RemoteIssue {
+    number: number;
+    title: string;
+    state: 'OPEN' | 'CLOSED';
+    labels: readonly string[];
+    body: string;
+}
+/** One line of a plan. */
+export interface PlanLine {
+    outcome: Outcome;
+    /** null on issue-only lines (`orphan-missing`, `label-without-marker`). */
+    item: ProjectableItem | null;
+    issueNumber: number | null;
+    /** Short reason, e.g. `not-backfilled`, or the divergence in words. */
+    detail: string | null;
+    addLabels: readonly string[];
+    removeLabels: readonly string[];
+}
+export interface Plan {
+    /**
+     * Printed in the plan header *and* the confirmation prompt. A projection aimed at
+     * the wrong repository is only reversible before the first write, so the resolved
+     * target is stated at both moments a human can still stop it.
+     */
+    repoLabel: string;
+    /** `owner/name`, or null when `gh` resolves the current repository. */
+    repo: string | null;
+    lines: readonly PlanLine[];
+    /** Only outcomes actually present appear as keys. */
+    counts: Readonly<Partial<Record<Outcome, number>>>;
+    writeCount: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/roadmap/sync/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/roadmap/sync/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,GACf,QAAQ,GACR,cAAc,GACd,eAAe,GACf,OAAO,GACP,WAAW,GACX,MAAM,GACN,iBAAiB,GACjB,uBAAuB,GACvB,gBAAgB,GAChB,sBAAsB,CAAC;AAE3B,iEAAiE;AACjE,eAAO,MAAM,cAAc,EAAE,SAAS,OAAO,EAK5C,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,OAAO,EAAiD,CAAC;AAEjG,uFAAuF;AACvF,eAAO,MAAM,WAAW,EAAE,SAAS,OAAO,EAAyD,CAAC;AAEpG,oDAAoD;AACpD,wBAAgB,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEjD;AAED,4DAA4D;AAC5D,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG,YAAY,CAAC;AAE9D,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,aAAa,CAAC;IACtB,GAAG,EAAE,kBAAkB,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC;IACzB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,0BAA0B;AAC1B,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,2EAA2E;IAC3E,IAAI,EAAE,eAAe,GAAG,IAAI,CAAC;IAC7B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,uEAAuE;IACvE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,IAAI;IACnB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC3B,qDAAqD;IACrD,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACnD,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/roadmap/sync/types.js

@@ -0,0 +1,43 @@
+/**
+ * Shared types for the roadmap → GitHub Issues projection.
+ *
+ * The projection is one-way: disk is the source of truth and the tracker is a
+ * rendering of it. Two consequences show up throughout these types.
+ *
+ * First, `sync` writes nothing to disk (design DD-1). There is no `remote:`
+ * frontmatter field and no cache: the durable link is the item `id`, carried in a
+ * body marker on the issue. Creating an issue and writing a local link would be two
+ * writes to two systems, and every failure of the second produces a duplicate on the
+ * next run.
+ *
+ * Second, an outcome is a *value*, not an action. `planProjection` returns a plan of
+ * outcomes and the command layer decides what to do with it, which is what makes the
+ * whole projection testable with no network and no `gh` binary.
+ *
+ * Requirements: roadmap-issue-projection/AC-14, roadmap-issue-projection/AC-46
+ *
+ * @module
+ */
+/** The four outcomes that write. Everything else is a report. */
+export const WRITE_OUTCOMES = [
+    'create',
+    'update-title',
+    'update-labels',
+    'close',
+];
+/**
+ * Outcomes that suppress every write for their item (design DE-18).
+ *
+ * `state-divergent` means a human closed the issue while the item is still live.
+ * Reopening it would relocate the two-writer loop rather than remove it, and
+ * retitling it would write to an issue somebody deliberately closed. So a terminal
+ * report is the *only* line its item emits.
+ */
+export const TERMINAL_REPORTS = ['state-divergent', 'ineligible-with-issue'];
+/** Execution order within one item: edit while the issue is still open, then close. */
+export const WRITE_ORDER = ['create', 'update-title', 'update-labels', 'close'];
+/** True when this outcome performs a `gh` write. */
+export function isWrite(outcome) {
+    return WRITE_OUTCOMES.includes(outcome);
+}
+//# sourceMappingURL=types.js.map

package/dist/roadmap/sync/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/roadmap/sync/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAuBH,iEAAiE;AACjE,MAAM,CAAC,MAAM,cAAc,GAAuB;IAChD,QAAQ;IACR,cAAc;IACd,eAAe;IACf,OAAO;CACR,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAuB,CAAC,iBAAiB,EAAE,uBAAuB,CAAC,CAAC;AAEjG,uFAAuF;AACvF,MAAM,CAAC,MAAM,WAAW,GAAuB,CAAC,QAAQ,EAAE,cAAc,EAAE,eAAe,EAAE,OAAO,CAAC,CAAC;AAEpG,oDAAoD;AACpD,MAAM,UAAU,OAAO,CAAC,OAAgB;IACtC,OAAO,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AAC1C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasensio/aidlc",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "AI Development Lifecycle Framework — structured lifecycle guidance for AI coding agents across platforms",
   "type": "module",
   "main": "dist/cli.js",
@@ -24,7 +24,7 @@
     "commander": "15.0.0",
     "picomatch": "4.0.5",
     "yaml": "2.9.0",
-    "@rasensio/aidlc-content": "1.20.0"
+    "@rasensio/aidlc-content": "1.21.0"
   },
   "devDependencies": {
     "@types/node": "22.15.32",