@rasensio/aidlc 1.20.0 → 1.22.0

package/dist/roadmap/sync/plan.js

@@ -0,0 +1,290 @@
+/**
+ * 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 { extractRegion, mergeBody, renderGeneratedRegion } from './body.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, bodyContext } = 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, bodyContext));
+    }
+    // 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, bodyContext) {
+    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: [],
+                newBody: renderGeneratedRegion(item, bodyContext),
+            },
+        ];
+    }
+    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,
+            newBody: null,
+        });
+    }
+    // Region-to-region comparison, not body-to-body: the whole point of the delimiters is
+    // that text outside them is not the projection's to have an opinion about, so an issue
+    // somebody added a note to must still read as `unchanged`.
+    const region = renderGeneratedRegion(item, bodyContext);
+    if (extractRegion(issue.body) !== region) {
+        collected.push({
+            outcome: 'update-body',
+            item,
+            issueNumber: issue.number,
+            detail: null,
+            addLabels: [],
+            removeLabels: [],
+            newBody: mergeBody(issue.body, region, item.id),
+        });
+    }
+    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: [], newBody: null };
+}
+// ---------------------------------------------------------------------------
+// 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;AAgC7E,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,112 @@
+/**
+ * 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',
+    'update-body',
+    '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',
+    'update-body': 'refresh the projected description',
+    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":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,OAAO,EAA0C,MAAM,YAAY,CAAC;AAE7E,wEAAwE;AACxE,MAAM,WAAW,GAAuB;IACtC,QAAQ;IACR,cAAc;IACd,eAAe;IACf,aAAa;IACb,OAAO;IACP,WAAW;IACX,MAAM;IACN,iBAAiB;IACjB,uBAAuB;IACvB,gBAAgB;IAChB,sBAAsB;CACvB,CAAC;AAEF,4EAA4E;AAC5E,MAAM,KAAK,GAAsC;IAC/C,MAAM,EAAE,iBAAiB;IACzB,cAAc,EAAE,wBAAwB;IACxC,eAAe,EAAE,gCAAgC;IACjD,aAAa,EAAE,mCAAmC;IAClD,KAAK,EAAE,iBAAiB;IACxB,SAAS,EAAE,iBAAiB;IAC5B,IAAI,EAAE,eAAe;IACrB,iBAAiB,EAAE,+CAA+C;IAClE,uBAAuB,EAAE,8CAA8C;IACvE,gBAAgB,EAAE,iBAAiB;IACnC,sBAAsB,EAAE,qCAAqC;CAC9D,CAAC;AAEF,MAAM,UAAU,UAAU,CAAC,IAAU;IACnC,MAAM,GAAG,GAAa,EAAE,CAAC;IAEzB,GAAG,CAAC,IAAI,CAAC,6BAA6B,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IACxD,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEb,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,GAAG,CAAC,IAAI,CAAC,+EAA+E,CAAC,CAAC;QAC1F,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACb,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAC9B,GAAG,CAAC,IAAI,CAAC,KAAK,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACb,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACxB,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACb,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACxB,CAAC;AAED,SAAS,UAAU,CAAC,IAAc;IAChC,MAAM,OAAO,GACX,IAAI,CAAC,IAAI,KAAK,IAAI;QAChB,CAAC,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE;QACxB,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE;YAC3C,CAAC,IAAI,CAAC,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;IAEnE,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC3E,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjF,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAClD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1D,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,yEAAyE;AACzE,SAAS,GAAG,CAAC,OAAgB;IAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5D,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AACpC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,IAAU;IAChC,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACrE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACvC,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAEnD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CACR,IAAI,CAAC,UAAU,KAAK,CAAC;QACnB,CAAC,CAAC,8CAA8C;QAChD,CAAC,CAAC,KAAK,IAAI,CAAC,UAAU,SAAS,IAAI,CAAC,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CACrE,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,MAAM;QAAE,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACjF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;QAC/B,KAAK,MAAM,CAAC,IAAI,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACpF,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,cAAc,CAAC,IAAU;IACvC,OAAO,SAAS,IAAI,CAAC,UAAU,SAAS,IAAI,CAAC,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,SAAS,GAAG,CAAC;AACnG,CAAC"}

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

@@ -0,0 +1,56 @@
+/**
+ * Make one item's prose safe to publish, and make its references clickable.
+ *
+ * The body used to carry no item prose at all, and the reason was three real hazards. Two
+ * of them are properties of GitHub's renderer and one is a property of this feature's own
+ * marker scanner:
+ *
+ * - **Marker injection.** The item↔issue link is an HTML comment. An item that quotes one
+ *   would stamp a second marker onto a different issue, and `indexByMarker` then refuses
+ *   the whole run as ambiguous — or, before that guard existed, retitled the wrong issue.
+ * - **Notification side effects.** `@name` and `#123` notify people and cross-link issues
+ *   the instant they are published. A sync is not a reason for somebody's inbox to move.
+ * - **Field limits.** GitHub caps a body at 65,536 characters, so the prose needs a budget
+ *   (that half lives in `body.ts`).
+ *
+ * The rejected alternative was to publish nothing and make the reader follow a link, which
+ * is what shipped in v1.21.0 and what this instance exists to undo: a body carrying no
+ * item-specific words is a redirect, and thirty of them on a board are thirty copies of one
+ * paragraph.
+ *
+ * **Everything here is code-aware, and that is the whole design.** Measured over this
+ * project's 76 items on 2026-09-07, 40 of the 41 hazard spans are inside a fence or an
+ * inline code span — `@clack/prompts`, `actions/checkout@v4`, colour hexes like `#0891b2`
+ * — and exactly one is in prose. A rule that ignored code would corrupt forty spans in
+ * order to defuse one. See `markdown.ts`.
+ *
+ * Requirements: richer-issue-bodies/AC-9, richer-issue-bodies/AC-10,
+ * richer-issue-bodies/AC-11, richer-issue-bodies/AC-12, richer-issue-bodies/AC-29
+ *
+ * @module
+ */
+export interface SanitizeContext {
+    /** Item id → repo-relative path. An empty map disables reference linking entirely. */
+    itemPaths: ReadonlyMap<string, string>;
+    /** Repo-relative path → absolute URL, or null when coordinates are unknown. */
+    fileUrl: ((relPath: string) => string) | null;
+}
+/**
+ * Sanitize and enrich an item body for publication.
+ *
+ * Four rules, and the **order is load-bearing**, because two of them insert text a later
+ * rule must not re-examine:
+ *
+ * 1. Item references become links. This runs first because it is the only rule that
+ *    deliberately rewrites a code span, and because the link it emits contains no `@`, `#`
+ *    or `<!--` for rules 2–4 to find.
+ * 2. Prose HTML comments are removed — the marker-injection defence, and lossless, since a
+ *    comment renders as nothing.
+ * 3. Prose mentions are wrapped in backticks.
+ * 4. Prose issue references are wrapped in backticks.
+ *
+ * Rules 2–4 run through `mapProse`, so code is untouched by construction rather than by a
+ * filter that could be got wrong.
+ */
+export declare function sanitizeItemBody(body: string, ctx: SanitizeContext): string;
+//# sourceMappingURL=sanitize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../../src/roadmap/sync/sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAsBH,MAAM,WAAW,eAAe;IAC9B,sFAAsF;IACtF,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,+EAA+E;IAC/E,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,IAAI,CAAC;CAC/C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,GAAG,MAAM,CAG3E"}

package/dist/roadmap/sync/sanitize.js

@@ -0,0 +1,140 @@
+/**
+ * Make one item's prose safe to publish, and make its references clickable.
+ *
+ * The body used to carry no item prose at all, and the reason was three real hazards. Two
+ * of them are properties of GitHub's renderer and one is a property of this feature's own
+ * marker scanner:
+ *
+ * - **Marker injection.** The item↔issue link is an HTML comment. An item that quotes one
+ *   would stamp a second marker onto a different issue, and `indexByMarker` then refuses
+ *   the whole run as ambiguous — or, before that guard existed, retitled the wrong issue.
+ * - **Notification side effects.** `@name` and `#123` notify people and cross-link issues
+ *   the instant they are published. A sync is not a reason for somebody's inbox to move.
+ * - **Field limits.** GitHub caps a body at 65,536 characters, so the prose needs a budget
+ *   (that half lives in `body.ts`).
+ *
+ * The rejected alternative was to publish nothing and make the reader follow a link, which
+ * is what shipped in v1.21.0 and what this instance exists to undo: a body carrying no
+ * item-specific words is a redirect, and thirty of them on a board are thirty copies of one
+ * paragraph.
+ *
+ * **Everything here is code-aware, and that is the whole design.** Measured over this
+ * project's 76 items on 2026-09-07, 40 of the 41 hazard spans are inside a fence or an
+ * inline code span — `@clack/prompts`, `actions/checkout@v4`, colour hexes like `#0891b2`
+ * — and exactly one is in prose. A rule that ignored code would corrupt forty spans in
+ * order to defuse one. See `markdown.ts`.
+ *
+ * Requirements: richer-issue-bodies/AC-9, richer-issue-bodies/AC-10,
+ * richer-issue-bodies/AC-11, richer-issue-bodies/AC-12, richer-issue-bodies/AC-29
+ *
+ * @module
+ */
+import { codeMask, inlineCodeSpans, mapProse } from './markdown.js';
+/** An item id, as the roadmap skill mints them. */
+const ITEM_ID_RE = /item-\d{8}-[a-z0-9](?:[a-z0-9-]*[a-z0-9])?/g;
+/**
+ * An HTML comment, terminated or not.
+ *
+ * The unterminated alternative matters: GitHub's renderer swallows everything after a bare
+ * `<!--` to the end of the document, so leaving one in would blank the rest of the body.
+ * Dropping it is both safer and closer to what a reader would have seen anyway.
+ */
+const HTML_COMMENT_RE = /<!--[\s\S]*?-->|<!--[\s\S]*$/g;
+/** A mention GitHub would linkify. Requires a letter or digit after the `@`. */
+const MENTION_RE = /@[A-Za-z0-9][-A-Za-z0-9]*/g;
+/** An issue or pull-request cross-reference GitHub would link and notify. */
+const ISSUE_REF_RE = /#[0-9]+/g;
+/**
+ * Sanitize and enrich an item body for publication.
+ *
+ * Four rules, and the **order is load-bearing**, because two of them insert text a later
+ * rule must not re-examine:
+ *
+ * 1. Item references become links. This runs first because it is the only rule that
+ *    deliberately rewrites a code span, and because the link it emits contains no `@`, `#`
+ *    or `<!--` for rules 2–4 to find.
+ * 2. Prose HTML comments are removed — the marker-injection defence, and lossless, since a
+ *    comment renders as nothing.
+ * 3. Prose mentions are wrapped in backticks.
+ * 4. Prose issue references are wrapped in backticks.
+ *
+ * Rules 2–4 run through `mapProse`, so code is untouched by construction rather than by a
+ * filter that could be got wrong.
+ */
+export function sanitizeItemBody(body, ctx) {
+    const linked = linkItemReferences(body, ctx);
+    return mapProse(linked, defuseProse);
+}
+/**
+ * Apply rules 2–4 to one prose run.
+ *
+ * Comments go first: a marker *is* a comment, so removing comments is what closes the
+ * injection hazard, and doing it before the backtick rules means a `@name` inside a
+ * comment is deleted rather than wrapped.
+ */
+function defuseProse(prose) {
+    return prose
+        .replace(HTML_COMMENT_RE, '')
+        .replace(MENTION_RE, (m) => `\`${m}\``)
+        .replace(ISSUE_REF_RE, (m) => `\`${m}\``);
+}
+/**
+ * Turn item references into links, in code spans and in prose alike.
+ *
+ * All 32 references in the real corpus are inline code spans whose **entire** content is
+ * the id (`` `item-20260902-review-gate-vs-tasks-review` ``) — measured, and the reason
+ * the first draft of this rule was retired by Amendment 1: a prose-only rule would never
+ * have fired once.
+ *
+ * The rewrite is deliberately narrow. Only a span whose whole content is a known id is
+ * touched, and the replacement re-wraps the same content in the same number of backticks
+ * inside a link, so a multi-backtick span stays valid. An id with no entry in `itemPaths`
+ * is left byte-identical, because an unresolvable link is worse than no link.
+ */
+function linkItemReferences(body, ctx) {
+    const { itemPaths, fileUrl } = ctx;
+    if (fileUrl === null || itemPaths.size === 0)
+        return body;
+    const edits = [];
+    // Code spans whose entire content is a known id.
+    const spans = inlineCodeSpans(body);
+    for (const span of spans) {
+        const relPath = itemPaths.get(span.content);
+        if (relPath === undefined)
+            continue;
+        const ticks = '`'.repeat(span.ticks);
+        edits.push({
+            start: span.start,
+            end: span.end,
+            text: `[${ticks}${span.content}${ticks}](${fileUrl(relPath)})`,
+        });
+    }
+    // Bare ids in prose. The mask — not `spans` — decides what counts as prose here:
+    // `inlineCodeSpans` deliberately omits spans inside fenced blocks, so testing against it
+    // alone would rewrite an id sitting in a code sample and corrupt the block.
+    const mask = codeMask(body);
+    ITEM_ID_RE.lastIndex = 0;
+    let match;
+    while ((match = ITEM_ID_RE.exec(body)) !== null) {
+        if (mask[match.index] === 1)
+            continue;
+        const relPath = itemPaths.get(match[0]);
+        if (relPath === undefined)
+            continue;
+        edits.push({
+            start: match.index,
+            end: match.index + match[0].length,
+            text: `[\`${match[0]}\`](${fileUrl(relPath)})`,
+        });
+    }
+    if (edits.length === 0)
+        return body;
+    // Right to left, so earlier offsets stay valid as later text is spliced in.
+    edits.sort((a, b) => b.start - a.start);
+    let out = body;
+    for (const edit of edits) {
+        out = out.slice(0, edit.start) + edit.text + out.slice(edit.end);
+    }
+    return out;
+}
+//# sourceMappingURL=sanitize.js.map