@specship/specship-win32-arm64 0.21.2 → 0.22.0

package/lib/dist/jira/regression-pack.js

@@ -0,0 +1,986 @@
+"use strict";
+/**
+ * Regression pack builder + upsert (JIRA-REGRESSION-DOC, REQ-JIRAREG-001).
+ *
+ * Reads the loaded spec set, filters to requirements whose acceptance-side
+ * link roll-up counts as implemented or verified (at least one implements-kind
+ * link on the requirement or one of its acceptance children reads implemented
+ * or verified), and expands each `REQ-*.A<N>` into a regression case grouped by
+ * a domain area. Domain-area derivation is REQ-JIRAREG-002's concern — this
+ * module files every case under the single `Uncategorised` placeholder area;
+ * `groupCasesByDomain` is a trivial passthrough so REQ-JIRAREG-002 has one
+ * seam to enrich later.
+ *
+ * The upsert side is a fingerprint-gated idempotent writer, mirroring
+ * `publish.ts`: one watermarked epic per project (found by label, never
+ * created twice), one Story per domain area (found by label), one Sub-task
+ * per case (found by label). Fingerprint drift on the rendered body drives
+ * create / update / skip.
+ *
+ * SECURITY (REQ-JIRA-009): only public keys + spec-derived text ever travel
+ * through here — no credential is handled or echoed.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REG_PACK_RUN_MARKER_PREFIX = exports.REG_PACK_OBSOLETE_WATERMARK_PREFIX = exports.REG_PACK_CASE_WATERMARK = exports.REG_PACK_STORY_WATERMARK = exports.REG_PACK_EPIC_WATERMARK = exports.REG_PACK_TIER_LABEL_BACKEND = exports.REG_PACK_TIER_LABEL_UI = exports.REG_PACK_OBSOLETE_LABEL = exports.REG_PACK_CASE_MARKER_LABEL = exports.REG_PACK_XREF_LABEL_PREFIX = exports.REG_PACK_CASE_LABEL_PREFIX = exports.REG_PACK_DOMAIN_LABEL_PREFIX = exports.REG_PACK_EPIC_LABEL = void 0;
+exports.regressionContentFingerprint = regressionContentFingerprint;
+exports.readStoredFingerprint = readStoredFingerprint;
+exports.deriveCaseTier = deriveCaseTier;
+exports.classifyCriterion = classifyCriterion;
+exports.renderCaseSteps = renderCaseSteps;
+exports.renderCrossReferenceBody = renderCrossReferenceBody;
+exports.renderRephraseReport = renderRephraseReport;
+exports.renderDomainGapReport = renderDomainGapReport;
+exports.computeDomainAreasByReqId = computeDomainAreasByReqId;
+exports.groupCasesByDomain = groupCasesByDomain;
+exports.buildRegressionPack = buildRegressionPack;
+exports.upsertRegressionPack = upsertRegressionPack;
+exports.findOrphanedCases = findOrphanedCases;
+exports.markCaseObsolete = markCaseObsolete;
+exports.recordRunResult = recordRunResult;
+exports.summarizePackRun = summarizePackRun;
+exports.finalizePackRun = finalizePackRun;
+const crypto = __importStar(require("crypto"));
+const spec_link_resolver_1 = require("../resolution/spec-link-resolver");
+const behaviour_surface_1 = require("../behaviour/behaviour-surface");
+const milestone_comment_1 = require("./milestone-comment");
+// ---------------------------------------------------------------------------
+// Labels + watermarks
+// ---------------------------------------------------------------------------
+exports.REG_PACK_EPIC_LABEL = 'specship-regression-pack';
+exports.REG_PACK_DOMAIN_LABEL_PREFIX = 'specship-regdomain-';
+exports.REG_PACK_CASE_LABEL_PREFIX = 'specship-regcase-';
+/**
+ * Cross-reference sub-tasks (REQ-JIRAREG-002.A1). Distinct prefix from the
+ * executable case label so a re-run finds the same cross-ref in the same area
+ * (idempotent) without conflating it with the primary case.
+ */
+exports.REG_PACK_XREF_LABEL_PREFIX = 'specship-regxref-';
+/**
+ * Stable marker label every regression case carries alongside its per-case
+ * slug label (REQ-JIRAREG-003). JIRA JQL cannot wildcard `labels`, so the
+ * orphan scan queries this fixed label to enumerate every case in the pack
+ * without touching the epic or area stories (which never carry it).
+ */
+exports.REG_PACK_CASE_MARKER_LABEL = 'specship-regcase';
+/**
+ * Board-filterable label attached to cases whose source criterion no longer
+ * exists in the spec set (REQ-JIRAREG-003.A3). A comment alone would be
+ * invisible in a JIRA filter — this label makes `labels = "specship-reg-obsolete"`
+ * a valid JQL query. Never removed automatically.
+ */
+exports.REG_PACK_OBSOLETE_LABEL = 'specship-reg-obsolete';
+/**
+ * Board-filterable tier labels (REQ-JIRAREG-004.A2) — testers can filter a
+ * board to just UI or just backend cases with a single label query. Attached
+ * to every executable + cross-ref case; the same tier is derived once per
+ * requirement so both rows in a two-area case carry the same label.
+ */
+exports.REG_PACK_TIER_LABEL_UI = 'specship-tier-ui';
+exports.REG_PACK_TIER_LABEL_BACKEND = 'specship-tier-backend';
+function tierLabel(tier) {
+    return tier === 'ui' ? exports.REG_PACK_TIER_LABEL_UI : exports.REG_PACK_TIER_LABEL_BACKEND;
+}
+exports.REG_PACK_EPIC_WATERMARK = '<!-- specship:regression-pack v1 -->';
+exports.REG_PACK_STORY_WATERMARK = '<!-- specship:regression-pack:story v1 -->';
+exports.REG_PACK_CASE_WATERMARK = '<!-- specship:regression-pack:case v1 -->';
+/**
+ * Stable prefix of the obsolete-marker comment (REQ-JIRAREG-003.A3). The
+ * per-run body carries a timestamp, but the idempotency key here does NOT
+ * include the timestamp — a re-run with the same `reason` finds the prior
+ * marker via `body.startsWith(prefix + reason + " -->")` and writes nothing
+ * (REQ-JIRAREG-003.A4).
+ */
+exports.REG_PACK_OBSOLETE_WATERMARK_PREFIX = '<!-- specship:regobsolete v1';
+function obsoleteWatermark(reason) {
+    return `${exports.REG_PACK_OBSOLETE_WATERMARK_PREFIX} reason=${reason} -->`;
+}
+const UNCATEGORISED_AREA = 'Uncategorised';
+// ---------------------------------------------------------------------------
+// Builder (pure)
+// ---------------------------------------------------------------------------
+/** States that count as implemented+ for regression-pack inclusion. */
+const IMPLEMENTED_PLUS_STATES = new Set([
+    'implemented',
+    'verified',
+]);
+/**
+ * Roll up the "implemented+" bit for one requirement: is there at least one
+ * implements-kind link (on the requirement itself or any of its acceptance
+ * children) whose state reads `implemented` or `verified`? This mirrors the
+ * funnel/coverage roll-up SpecQueries drives (per the approval correction).
+ */
+function isRequirementImplementedPlus(sq, reqId) {
+    const own = sq.getLinksBySpec(reqId);
+    if (own.some((lk) => lk.kind === 'implements' && IMPLEMENTED_PLUS_STATES.has(lk.state))) {
+        return true;
+    }
+    const children = sq.getSpecsByParent(reqId).filter((c) => c.kind === 'acceptance');
+    for (const child of children) {
+        const links = sq.getLinksBySpec(child.id);
+        if (links.some((lk) => lk.kind === 'implements' && IMPLEMENTED_PLUS_STATES.has(lk.state))) {
+            return true;
+        }
+    }
+    return false;
+}
+/** JIRA summaries cap at 255; stay well under. */
+const SUMMARY_MAX = 240;
+function oneLineTrim(text) {
+    const one = text.replace(/\s+/g, ' ').trim();
+    return one.length > SUMMARY_MAX ? `${one.slice(0, SUMMARY_MAX - 1)}…` : one;
+}
+/** `REQ-FOO-001.A2` → `A2` (criterion suffix without the requirement prefix). */
+function criterionSuffix(reqId, criterionId) {
+    return criterionId.startsWith(`${reqId}.`)
+        ? criterionId.slice(reqId.length + 1)
+        : criterionId;
+}
+/** Kebab-lowercase slug, filesystem/label-safe. */
+function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60);
+}
+/** Stable fingerprint of a rendered body — mirrors publish.ts. */
+function regressionContentFingerprint(summary, description) {
+    return crypto
+        .createHash('sha256')
+        .update(summary)
+        .update(' ')
+        .update(description)
+        .digest('hex')
+        .slice(0, 16);
+}
+/**
+ * Read a stored fingerprint from an issue description, or `null` when absent.
+ * The fingerprint travels as `<!-- specship:regfp:<hex> -->` on its own line.
+ */
+function readStoredFingerprint(description) {
+    if (!description)
+        return null;
+    const m = /<!--\s*specship:regfp:([a-f0-9]{6,32})\s*-->/i.exec(description);
+    return m && m[1] ? m[1] : null;
+}
+function fingerprintTag(fp) {
+    return `<!-- specship:regfp:${fp} -->`;
+}
+/** Strip a trailing `<!-- specship:regfp:... -->` tag (and its blank line) if present. */
+function stripFingerprintTag(description) {
+    return description.replace(/\n*<!--\s*specship:regfp:[a-f0-9]+\s*-->\s*$/i, '');
+}
+/**
+ * Derive a case's tier from the requirement's behaviour surface
+ * (REQ-JIRAREG-004.A2). Delegates the UI/backend split to
+ * {@link computeBehaviourSurface} so the classification stays consistent
+ * with `/ss-behaviour`. A requirement with no linked nodes (or a
+ * fixture-mode sq without graph accessors) resolves to `'backend'` —
+ * never spurious UI.
+ */
+function deriveCaseTier(req, sq) {
+    const linked = sq.getLinkedNodesForReq?.(req.id) ?? [];
+    if (linked.length === 0)
+        return 'backend';
+    const neighbours = sq.getNeighbourNodes?.(linked.map((n) => n.id)) ?? [];
+    const surface = (0, behaviour_surface_1.computeBehaviourSurface)({
+        requirementId: req.id,
+        requirementExists: true,
+        linkedNodes: linked,
+        neighbourNodes: neighbours,
+    });
+    return surface.ui.length > 0 ? 'ui' : 'backend';
+}
+/**
+ * Classify a criterion body for A3: does it name an observable outcome, and
+ * does it stay in black-box vocabulary? Two failure modes both flag the case
+ * for human rephrase (never silently vague, never leaking file paths /
+ * symbols into the pack):
+ *
+ * 1. **Vague** — no observable verb ("returns", "renders", "MUST", …) and
+ *    no reference to a concrete artefact ("response", "row", …).
+ * 2. **Code-shaped** — the text names a file path (`src/…`), a `.ts` / `.tsx`
+ *    / `.js` / `.jsx` extension, or a backticked identifier
+ *    (CamelCase / snake_case). Black-box cases must not echo white-box
+ *    detail; the flag drives a rephrase pass.
+ *
+ * Deterministic and cheap on purpose — the goal is surfacing the flags,
+ * not scoring prose.
+ */
+function classifyCriterion(text) {
+    const t = text.trim();
+    if (!t)
+        return { observable: false, reason: 'empty criterion text' };
+    // Code-shape check runs first: a criterion may name an observable outcome
+    // AND still leak code detail — the leak is the tighter constraint.
+    if (/(^|[\s(`'"])src\//.test(t) ||
+        /\.(tsx?|jsx?|py|rb|go|rs|java|kt|swift|cs|php|css|scss|md|yml|yaml|json|sql)\b/i.test(t) ||
+        /`[A-Za-z_][A-Za-z0-9_]*`/.test(t) ||
+        /`[A-Za-z0-9_.-]+\/[A-Za-z0-9_./-]+`/.test(t)) {
+        return { observable: true, reason: 'criterion text contains code references' };
+    }
+    const observable = /\b(MUST|SHOULD|shows?|displays?|renders?|returns?|responds?|emits?|creates?|updates?|deletes?|rejects?|accepts?|produces?|writes?|reads?|receives?|surfaces?|logs?|records?|sends?|opens?|closes?|starts?|stops?|fails?|succeeds?|passes?|blocks?|allows?|prevents?|prompts?|matches?|contains?|equals?|includes?|excludes?)\b/i.test(t) ||
+        /\b(response|request|message|row|file|status|code|body|header|payload|value|count|list|table|error|log|output|result|screen|button|link|form|field|dialog|banner|toast|page|route|endpoint)\b/i.test(t);
+    if (!observable)
+        return { observable: false, reason: 'no observable outcome in criterion text' };
+    return { observable: true };
+}
+/**
+ * Render the executable steps + reference section for a case
+ * (REQ-JIRAREG-001.A3, REQ-JIRAREG-004.A1). Black-box body: Steps carry no
+ * file paths, no code symbols, and no `- Spec:` pointer — those are
+ * white-box detail belonging on the source spec, not on the tester's
+ * checklist. The tier lands as a header line (readable) AND as a JIRA label
+ * on the issue (board-filterable, see {@link tierLabel}).
+ */
+function renderCaseSteps(rc) {
+    const lines = [];
+    lines.push(exports.REG_PACK_CASE_WATERMARK);
+    lines.push('');
+    lines.push(`Tier: ${rc.tier}`);
+    lines.push('');
+    lines.push('Steps:');
+    lines.push('- Given the feature is available in a bound test environment');
+    lines.push(`- When the tester exercises the behaviour: ${oneLineTrim(rc.criterionText)}`);
+    lines.push('- Then the observable outcome MUST match the criterion above');
+    lines.push('');
+    lines.push('Reference:');
+    lines.push(`- Source: ${rc.reqId}.${criterionSuffix(rc.reqId, rc.criterionId)} — ${oneLineTrim(rc.criterionText)}`);
+    lines.push(`- Domain: ${rc.domainArea}`);
+    if (rc.areasAll.length > 1) {
+        lines.push(`- Also files under: ${rc.areasAll.filter((a) => a !== rc.domainArea).join(', ')}`);
+    }
+    if (rc.needsRephrase && rc.rephraseReason) {
+        lines.push(`- Needs rephrase: ${rc.rephraseReason}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Render a cross-reference sub-task body (REQ-JIRAREG-002.A1). Same source
+ * id, no duplicate steps — just a pointer at the executable sibling so a
+ * tester scanning this area finds it. The label is separate so the same
+ * criterion produces one issue per area, and a re-run stays idempotent.
+ */
+function renderCrossReferenceBody(rc, executableAreaLabel) {
+    const lines = [];
+    lines.push(exports.REG_PACK_CASE_WATERMARK);
+    lines.push('');
+    lines.push(`Tier: ${rc.tier}`);
+    lines.push('');
+    lines.push(`This is a cross-reference. The executable case for ${rc.reqId}.${criterionSuffix(rc.reqId, rc.criterionId)} lives under the "${executableAreaLabel}" area — run it there.`);
+    lines.push('');
+    lines.push('Reference:');
+    lines.push(`- Source: ${rc.reqId}.${criterionSuffix(rc.reqId, rc.criterionId)} — ${oneLineTrim(rc.criterionText)}`);
+    lines.push(`- Executable area: ${executableAreaLabel}`);
+    lines.push(`- Cross-referenced here as: ${rc.domainArea}`);
+    return lines.join('\n');
+}
+function renderStoryDescription(area, caseCount) {
+    return [
+        exports.REG_PACK_STORY_WATERMARK,
+        '',
+        `Regression cases for the "${area}" domain area.`,
+        `${caseCount} case${caseCount === 1 ? '' : 's'} attached as Sub-tasks.`,
+    ].join('\n');
+}
+function renderEpicDescription(totals) {
+    const lines = [
+        exports.REG_PACK_EPIC_WATERMARK,
+        '',
+        'SpecShip Regression Pack.',
+        `${totals.stories} domain area${totals.stories === 1 ? '' : 's'}, ` +
+            `${totals.cases} case${totals.cases === 1 ? '' : 's'}.`,
+    ];
+    if (totals.domainGaps > 0) {
+        lines.push(`${totals.domainGaps} requirement${totals.domainGaps === 1 ? '' : 's'} filed under Uncategorised — capture the missing domain fact(s) with /specship:spec domain (REQ-JIRAREG-002.A2).`);
+    }
+    lines.push('', 'Each Sub-task under a domain-area Story is derived from one acceptance ' +
+        'criterion of an implemented (or verified) requirement. Human testers ' +
+        'can execute the cases directly; the agent can record run results (see ' +
+        'REQ-JIRAREG-005). Re-generating the pack is idempotent — a criterion ' +
+        'that has not changed produces zero JIRA writes.');
+    return lines.join('\n');
+}
+/**
+ * Render the domain-gap report the caller prints after upsert
+ * (REQ-JIRAREG-002.A2). Empty when there are no gaps.
+ */
+/**
+ * Render the rephrase report (REQ-JIRAREG-004.A3). Empty when zero flags —
+ * the caller conditionally prints it after the pack upsert, mirroring the
+ * domain-gap report shape.
+ */
+function renderRephraseReport(flags) {
+    if (flags.length === 0)
+        return '';
+    const lines = [];
+    lines.push(`Criteria needing rephrase — ${flags.length} criterion${flags.length === 1 ? '' : 'a'} flagged (REQ-JIRAREG-004.A3):`);
+    for (const f of flags)
+        lines.push(`  · ${f.criterionId} (${f.specPath}): ${f.reason}`);
+    lines.push('Rewrite the criterion body in black-box terms (name the observable outcome, drop file paths / symbols) and re-run the pack; the case updates in place.');
+    return lines.join('\n');
+}
+function renderDomainGapReport(gaps) {
+    if (gaps.length === 0)
+        return '';
+    const lines = [];
+    lines.push(`Domain gaps — ${gaps.length} requirement${gaps.length === 1 ? '' : 's'} filed under Uncategorised (REQ-JIRAREG-002.A2):`);
+    for (const g of gaps)
+        lines.push(`  · ${g.reqId} — ${g.specPath}`);
+    lines.push('Capture the missing domain fact(s) with `/specship:spec domain` and re-run the pack; the next update moves the affected cases into their new area without duplicating them.');
+    return lines.join('\n');
+}
+/**
+ * Compute the domain areas each requirement inherits transitively, keyed on
+ * requirement id (REQ-JIRAREG-002.A1).
+ *
+ * Direction: domain facts declare `depends_on: REQ-...` (they point AT
+ * requirements, per DOMAIN-KNOWLEDGE-DOC), so a requirement's own spec-tier
+ * chain does NOT reach the domain facts that govern it. We walk in the
+ * OTHER direction — for each `domain` spec, follow its parent /
+ * `metadata.depends_on` chain outward and register that domain fact against
+ * every requirement it reaches.
+ *
+ * This mirrors {@link SpecLinkResolver.getInheritedLinks} — same BFS, same
+ * `sourceSpecIds` traversal, same depth cap ({@link INHERITED_LINK_MAX_DEPTH}).
+ * `sourceSpecIds` is imported from the resolver (single source of truth for
+ * "the spec-tier edges a spec has"), but the walk itself is reproduced here
+ * to keep the regression-pack module free of a `SpecLinkResolver` dependency
+ * (which would require threading `QueryBuilder` all the way through). Per the
+ * approval note, the mirror is deliberate; `BuilderSpecQueries` exposes only
+ * the point-lookup surface it needs (`getAllSpecs`, `getSpecById`) so the
+ * builder stays trivially fixture-able.
+ *
+ * Per-domain-fact BFS is cycle-guarded and depth-capped. Ordering of the
+ * output list is deterministic: domain spec ids sorted lex, deduped.
+ */
+function computeDomainAreasByReqId(sq) {
+    const out = new Map();
+    const seenPairs = new Set(); // `${reqId}\0${domainId}`
+    const domainFacts = sq
+        .getAllSpecs()
+        .filter((s) => s.kind === 'domain')
+        // Deterministic outer order — matters for the primary-area pick.
+        .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    for (const fact of domainFacts) {
+        // BFS from the fact outward through parent / depends_on. Mirrors
+        // SpecLinkResolver.getInheritedLinks; visited-set = string ids (we may
+        // not resolve every hop to an indexed Spec).
+        const visited = new Set([fact.id]);
+        const queue = (0, spec_link_resolver_1.sourceSpecIds)(fact).map((id) => ({ id, depth: 1 }));
+        while (queue.length > 0) {
+            const { id, depth } = queue.shift();
+            if (visited.has(id))
+                continue;
+            visited.add(id);
+            const src = sq.getSpecById(id);
+            if (!src)
+                continue; // gap (unresolved id) — silently skip; not our concern
+            if (src.kind === 'requirement') {
+                const pairKey = `${src.id}${fact.id}`;
+                if (!seenPairs.has(pairKey)) {
+                    seenPairs.add(pairKey);
+                    const bucket = out.get(src.id);
+                    if (bucket)
+                        bucket.push(fact);
+                    else
+                        out.set(src.id, [fact]);
+                }
+                // Continue walking — a domain fact that reaches a requirement AND its
+                // parent document still covers both; the requirement is the interesting
+                // hit for the pack, but we don't prune.
+            }
+            if (depth < spec_link_resolver_1.INHERITED_LINK_MAX_DEPTH) {
+                for (const nextId of (0, spec_link_resolver_1.sourceSpecIds)(src)) {
+                    if (!visited.has(nextId))
+                        queue.push({ id: nextId, depth: depth + 1 });
+                }
+            }
+        }
+    }
+    // Post-sort each bucket by domain spec id — the executable case picks
+    // buckets[0], and IDs are stable across renames (unlike titles).
+    for (const [reqId, facts] of out) {
+        out.set(reqId, [...facts].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)));
+    }
+    return out;
+}
+/**
+ * Group cases by their pre-computed `domainArea`. In REQ-JIRAREG-001 every
+ * case was `Uncategorised`; REQ-JIRAREG-002 fills in real domain-fact areas
+ * — same input shape, same output shape, richer bucketing.
+ */
+function groupCasesByDomain(cases) {
+    const out = new Map();
+    for (const rc of cases) {
+        const bucket = out.get(rc.domainArea);
+        if (bucket)
+            bucket.push(rc);
+        else
+            out.set(rc.domainArea, [rc]);
+    }
+    return out;
+}
+/**
+ * Build a full regression pack plan from the loaded spec set (REQ-JIRAREG-001).
+ * Pure — no JIRA calls. Deterministic ordering: requirements sorted by id,
+ * criteria in the order they appear as `acceptance` children of the requirement.
+ */
+function buildRegressionPack(sq) {
+    const all = sq.getAllSpecs();
+    const requirements = all
+        .filter((s) => s.kind === 'requirement')
+        .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    // Precompute inverse map: which domain facts each requirement inherits.
+    // Ordering inside each list is stable-by-id so the "first area" pick below
+    // is deterministic across runs.
+    const domainAreasByReq = computeDomainAreasByReqId(sq);
+    const cases = [];
+    const domainGaps = [];
+    const rephraseFlags = [];
+    for (const req of requirements) {
+        if (!isRequirementImplementedPlus(sq, req.id))
+            continue;
+        const criteria = sq
+            .getSpecsByParent(req.id)
+            .filter((c) => c.kind === 'acceptance')
+            .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        if (criteria.length === 0)
+            continue;
+        const domainFacts = domainAreasByReq.get(req.id) ?? [];
+        const areaTitles = domainFacts.length === 0
+            ? [UNCATEGORISED_AREA]
+            : domainFacts.map((f) => f.title || f.id);
+        const primaryArea = areaTitles[0];
+        if (domainFacts.length === 0) {
+            // Once per requirement — A2 lists the REQ, not each criterion.
+            domainGaps.push({ reqId: req.id, specPath: req.sourcePath });
+        }
+        // Tier derived once per requirement (REQ-JIRAREG-004.A2): both executable
+        // and cross-ref rows for the same criterion carry the same tier.
+        const tier = deriveCaseTier(req, sq);
+        for (const c of criteria) {
+            const text = (c.title || c.body || '').trim();
+            if (!text)
+                continue;
+            const cls = classifyCriterion(text);
+            const needsRephrase = !cls.observable || Boolean(cls.reason);
+            if (needsRephrase && cls.reason) {
+                rephraseFlags.push({
+                    criterionId: c.id,
+                    specPath: req.sourcePath,
+                    reason: cls.reason,
+                });
+            }
+            const base = {
+                reqId: req.id,
+                criterionId: c.id,
+                criterionText: text,
+                specPath: req.sourcePath,
+                tier,
+                areasAll: areaTitles,
+                ...(needsRephrase
+                    ? { needsRephrase: true, rephraseReason: cls.reason ?? 'unspecified' }
+                    : {}),
+            };
+            // Executable case in the primary area.
+            cases.push({ ...base, domainArea: primaryArea, kind: 'executable' });
+            // Cross-references in every additional area.
+            for (const extra of areaTitles.slice(1)) {
+                cases.push({
+                    ...base,
+                    domainArea: extra,
+                    kind: 'crossref',
+                    crossReferenceOf: c.id,
+                });
+            }
+        }
+    }
+    const grouped = groupCasesByDomain(cases);
+    const stories = [];
+    const casePlans = [];
+    // Iterate areas in deterministic order — the map preserves insertion order,
+    // but a domain fact never inserted (all-crossref) shouldn't matter. Sort by
+    // area title so re-runs render stories in the same order regardless of
+    // requirement iteration order.
+    const areasSorted = [...grouped.keys()].sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+    for (const area of areasSorted) {
+        const group = grouped.get(area);
+        const areaLabel = `${exports.REG_PACK_DOMAIN_LABEL_PREFIX}${slugify(area)}`;
+        const areaCases = [];
+        for (const rc of group) {
+            const suffix = criterionSuffix(rc.reqId, rc.criterionId);
+            const isXref = rc.kind === 'crossref';
+            const label = isXref
+                ? `${exports.REG_PACK_XREF_LABEL_PREFIX}${slugify(rc.reqId)}-${slugify(suffix)}-${slugify(area)}`
+                : `${exports.REG_PACK_CASE_LABEL_PREFIX}${slugify(rc.reqId)}-${slugify(suffix)}`;
+            const summary = isXref
+                ? oneLineTrim(`${rc.reqId}.${suffix} (xref: ${area}) — ${rc.criterionText}`)
+                : oneLineTrim(`${rc.reqId}.${suffix} — ${rc.criterionText}`);
+            const body = isXref
+                ? renderCrossReferenceBody(rc, rc.areasAll[0])
+                : renderCaseSteps(rc);
+            const fp = regressionContentFingerprint(summary, body);
+            const description = `${body}\n\n${fingerprintTag(fp)}`;
+            areaCases.push({
+                reqId: rc.reqId,
+                criterionId: rc.criterionId,
+                summary,
+                description,
+                label,
+                specPath: rc.specPath,
+                kind: rc.kind,
+                tierLabel: tierLabel(rc.tier),
+            });
+        }
+        const storySummary = oneLineTrim(`Regression: ${area}`);
+        const storyDesc = renderStoryDescription(area, areaCases.length);
+        const storyFp = regressionContentFingerprint(storySummary, storyDesc);
+        stories.push({
+            domainArea: area,
+            summary: storySummary,
+            description: `${storyDesc}\n\n${fingerprintTag(storyFp)}`,
+            label: areaLabel,
+            cases: areaCases,
+        });
+        casePlans.push(...areaCases);
+    }
+    const epicSummary = oneLineTrim('SpecShip Regression Pack');
+    const epicDesc = renderEpicDescription({
+        stories: stories.length,
+        cases: casePlans.length,
+        domainGaps: domainGaps.length,
+    });
+    const epicFp = regressionContentFingerprint(epicSummary, epicDesc);
+    const epic = {
+        summary: epicSummary,
+        description: `${epicDesc}\n\n${fingerprintTag(epicFp)}`,
+        label: exports.REG_PACK_EPIC_LABEL,
+    };
+    return { epic, stories, cases: casePlans, domainGaps, rephraseFlags };
+}
+/**
+ * Find an existing SpecShip-owned issue by label — or create a fresh one and
+ * seed the fingerprint-gated body. When multiple labelled matches exist the
+ * OLDEST-lex (`key` sort) is picked as canonical; the rest are returned as
+ * orphans (single-canonical invariant, REQ-JIRAREG-001.A1).
+ */
+async function upsertLabelledIssue(client, ctx, label, issueType, summary, description, parentKey, extraLabels = []) {
+    const matches = await client.searchIssuesByLabel(ctx.projectKey, label);
+    const sorted = [...matches].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    const canonical = sorted[0];
+    const orphans = sorted.slice(1).map((m) => m.key);
+    if (canonical) {
+        // Fingerprint the WITHOUT-TAG body so a re-run compares apples-to-apples
+        // with the tag we previously stored (the tag itself is derived from the
+        // pre-tag content and would otherwise self-invalidate on rehash).
+        const newFp = regressionContentFingerprint(summary, stripFingerprintTag(description));
+        const detail = await client.getIssue(canonical.key);
+        const storedFp = readStoredFingerprint(detail.issue.description);
+        // Parent reassignment (REQ-JIRAREG-002.A3): a case can move areas without
+        // any body drift when its requirement gains a domain fact. We detect the
+        // move by comparing stored parent vs desired; only writes when they differ.
+        const storedParent = detail.issue.parentKey;
+        const parentChanged = parentKey !== undefined && storedParent !== parentKey;
+        if (storedFp === newFp && !parentChanged) {
+            // Backfill any missing extra labels on a canonical issue that pre-dates
+            // them (REQ-JIRAREG-003 marker label rollout). `addLabel` is idempotent —
+            // a no-op when already set, so a re-run stays zero-write.
+            if (!ctx.dryRun) {
+                for (const extra of extraLabels) {
+                    await client.addLabel(canonical.key, extra);
+                }
+            }
+            return { outcome: { key: canonical.key, action: 'skipped' }, orphans };
+        }
+        if (!ctx.dryRun) {
+            const patch = {};
+            if (storedFp !== newFp) {
+                patch.summary = summary;
+                patch.description = description;
+            }
+            if (parentChanged)
+                patch.parentKey = parentKey;
+            await client.updateIssue(canonical.key, patch);
+            for (const extra of extraLabels) {
+                await client.addLabel(canonical.key, extra);
+            }
+        }
+        return { outcome: { key: canonical.key, action: 'updated' }, orphans };
+    }
+    if (ctx.dryRun) {
+        // Synthesize a placeholder key so downstream planning has something to
+        // reference; no writes performed.
+        return {
+            outcome: { key: `DRYRUN-${label}`, action: 'created' },
+            orphans,
+        };
+    }
+    const created = await client.createIssue({
+        projectKey: ctx.projectKey,
+        issueType,
+        summary,
+        description,
+        labels: [label, ...extraLabels],
+        ...(parentKey ? { parentKey } : {}),
+    });
+    return { outcome: { key: created.key, action: 'created' }, orphans };
+}
+/**
+ * Idempotent regression-pack upsert (REQ-JIRAREG-001, REQ-JIRAREG-003 skeleton).
+ * Walks the model epic → story → case; each level is keyed on its SpecShip
+ * label and its body is fingerprint-gated so a re-run without spec changes
+ * writes nothing new. Extra epics under the pack label are refused (single-epic
+ * invariant, A1) and reported as orphans; the caller decides how to surface.
+ */
+async function upsertRegressionPack(client, model, ctx) {
+    const epicType = ctx.epicIssueType ?? 'Epic';
+    const storyType = ctx.storyIssueType ?? 'Story';
+    const caseType = ctx.caseIssueType ?? 'Sub-task';
+    const epicRes = await upsertLabelledIssue(client, ctx, model.epic.label, epicType, model.epic.summary, model.epic.description, undefined);
+    let storiesCreated = 0;
+    let storiesUpdated = 0;
+    let storiesSkipped = 0;
+    let casesCreated = 0;
+    let casesUpdated = 0;
+    let casesSkipped = 0;
+    let crossRefsCreated = 0;
+    let crossRefsUpdated = 0;
+    let crossRefsSkipped = 0;
+    const caseKeysByCriterion = {};
+    const crossRefKeys = [];
+    for (const story of model.stories) {
+        const storyRes = await upsertLabelledIssue(client, ctx, story.label, storyType, story.summary, story.description, epicRes.outcome.key);
+        if (storyRes.outcome.action === 'created')
+            storiesCreated++;
+        else if (storyRes.outcome.action === 'updated')
+            storiesUpdated++;
+        else
+            storiesSkipped++;
+        for (const c of story.cases) {
+            const caseRes = await upsertLabelledIssue(client, ctx, c.label, caseType, c.summary, c.description, storyRes.outcome.key, [exports.REG_PACK_CASE_MARKER_LABEL, c.tierLabel]);
+            if (c.kind === 'crossref') {
+                if (caseRes.outcome.action === 'created')
+                    crossRefsCreated++;
+                else if (caseRes.outcome.action === 'updated')
+                    crossRefsUpdated++;
+                else
+                    crossRefsSkipped++;
+                crossRefKeys.push(caseRes.outcome.key);
+            }
+            else {
+                if (caseRes.outcome.action === 'created')
+                    casesCreated++;
+                else if (caseRes.outcome.action === 'updated')
+                    casesUpdated++;
+                else
+                    casesSkipped++;
+                // The executable case's key is the traceability anchor. Cross-refs
+                // deliberately do NOT overwrite this — the spec-side back-link is
+                // one criterion → one canonical case key (the executable one).
+                caseKeysByCriterion[c.criterionId] = caseRes.outcome.key;
+            }
+        }
+    }
+    // Reconcile orphaned cases (REQ-JIRAREG-003.A3). Query every case in the
+    // pack via the fixed marker label — the epic and area stories never carry
+    // it, so this scan touches only cases. Any case whose key is not in the
+    // just-upserted set belongs to a criterion that no longer exists in the
+    // spec set (removed or superseded) → mark obsolete. Never deleted; run
+    // history stays intact.
+    const obsoletedCaseKeys = [];
+    let casesObsoleted = 0;
+    if (!ctx.dryRun) {
+        // Both executable and cross-ref sub-tasks carry the case marker label, so
+        // both must be in `expected` — otherwise a live cross-ref would trip the
+        // obsolete scan every run (`caseKeysByCriterion` records only executables).
+        const expected = new Set(Object.values(caseKeysByCriterion));
+        for (const k of crossRefKeys)
+            expected.add(k);
+        const orphans = await findOrphanedCases(client, ctx.projectKey, expected);
+        for (const orphan of orphans) {
+            const outcome = await markCaseObsolete(client, orphan.key, 'removed');
+            if (outcome.action === 'obsoleted') {
+                casesObsoleted++;
+                obsoletedCaseKeys.push(orphan.key);
+            }
+        }
+    }
+    return {
+        epicKey: epicRes.outcome.key,
+        epicCreated: epicRes.outcome.action === 'created',
+        storiesCreated,
+        storiesUpdated,
+        storiesSkipped,
+        casesCreated,
+        casesUpdated,
+        casesSkipped,
+        crossRefsCreated,
+        crossRefsUpdated,
+        crossRefsSkipped,
+        casesObsoleted,
+        obsoletedCaseKeys,
+        orphanedEpicKeys: epicRes.orphans,
+        caseKeysByCriterion,
+    };
+}
+// ---------------------------------------------------------------------------
+// Obsolete reconciliation (REQ-JIRAREG-003.A3)
+// ---------------------------------------------------------------------------
+/**
+ * Enumerate case issues in the pack (via the fixed case marker label) that are
+ * not in `expectedKeys` — the caller's set of case keys just upserted from the
+ * current model. The result is deterministic (sorted lex on key) so re-runs
+ * report obsolete work in the same order.
+ */
+async function findOrphanedCases(client, projectKey, expectedKeys) {
+    const all = await client.searchIssuesByLabel(projectKey, exports.REG_PACK_CASE_MARKER_LABEL);
+    return all
+        .filter((i) => !expectedKeys.has(i.key))
+        .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+}
+/**
+ * Mark a case obsolete on JIRA (REQ-JIRAREG-003.A3): attach a stable
+ * watermarked comment naming the reason AND add the board-filterable
+ * `specship-reg-obsolete` label. Both writes are idempotent — a re-run with
+ * the same reason finds the prior marker and adds nothing (A4).
+ *
+ * Never transitions the issue's workflow status (spec-driven correction:
+ * "no workflow transitions by default") and never deletes it — the run
+ * history and any prior evidence stay intact.
+ */
+async function markCaseObsolete(client, issueKey, reason) {
+    const watermark = obsoleteWatermark(reason);
+    const comments = await client.listCommentsDetailed(issueKey);
+    const hasMarker = comments.some((c) => c.body.startsWith(watermark));
+    const labelRes = await client.addLabel(issueKey, exports.REG_PACK_OBSOLETE_LABEL);
+    if (hasMarker) {
+        // Idempotency: the comment marker is the source-of-truth signal that
+        // this case has already been marked obsolete for `reason`. A label-only
+        // add (backfill) does not count as a fresh obsoletion — the previous
+        // run already recorded it.
+        return { action: 'skipped' };
+    }
+    const body = [
+        watermark,
+        '',
+        `This regression case is obsolete: ${reason}.`,
+        `Marked ${new Date().toISOString()}.`,
+        'The issue is preserved so past run history stays intact; the pack ' +
+            'will no longer regenerate it.',
+    ].join('\n');
+    await client.addComment(issueKey, body);
+    return { action: 'obsoleted', commentAdded: true, labelAdded: labelRes.added };
+}
+/** Prefix of the recorder-owned comment marker. Body carries the runId + status. */
+exports.REG_PACK_RUN_MARKER_PREFIX = '<!-- specship:regression-run';
+function runMarker(caseKey, runId) {
+    return `${exports.REG_PACK_RUN_MARKER_PREFIX} case=${caseKey} run=${runId} -->`;
+}
+/** Rendered triage pointer surfaced on `failed` results (REQ-JIRAREG-005.A3). */
+function triageHint(criterionId) {
+    return `Failed — triage with \`/specship:spec triage ${criterionId}\`.`;
+}
+function renderRunCommentBody(result, runId, timestamp) {
+    const lines = [];
+    lines.push(runMarker(result.caseKey, runId));
+    lines.push('');
+    lines.push(`SpecShip: regression run ${runId} recorded ${result.status}.`);
+    lines.push(`- Criterion: ${result.criterionId}`);
+    lines.push(`- Executor: ${result.executor}${result.harness ? ` (${result.harness})` : ''}`);
+    lines.push(`- Recorded: ${timestamp}`);
+    if (result.evidence?.logRef)
+        lines.push(`- Log: ${result.evidence.logRef}`);
+    if (result.evidence?.error)
+        lines.push(`- Error: ${result.evidence.error}`);
+    if (result.status === 'failed') {
+        lines.push('');
+        lines.push(triageHint(result.criterionId));
+    }
+    return lines.join('\n');
+}
+/**
+ * Record a pack-run result on a case issue (REQ-JIRAREG-005).
+ *
+ * Idempotent by (caseKey, runId): a second call with the same pair edits the
+ * prior comment in place. Pass → `Done` transition + validates-link state
+ * `verified`. Fail → `In Review` + `broken` + a triage hint line. Unexecuted →
+ * comment only; the case's workflow status and any existing validates-link
+ * state stay untouched (A3). External-evidence links use `jira://<CASE-KEY>`
+ * as the `targetFilePath` — {@link SpecLinkResolver} refuses to re-resolve
+ * that prefix, so a code-graph sync never flips the state to orphaned.
+ */
+async function recordRunResult(deps, result) {
+    const now = deps.now ?? Date.now;
+    const runId = (result.runId && result.runId.trim()) || `adhoc-${now()}`;
+    const marker = runMarker(result.caseKey, runId);
+    const body = renderRunCommentBody(result, runId, new Date(now()).toISOString());
+    // Comment upsert — keyed on (caseKey, runId) so a re-record edits in place.
+    const existing = await deps.client.listCommentsDetailed(result.caseKey);
+    const prior = existing.find((c) => c.body.startsWith(marker));
+    let commentAction;
+    if (prior) {
+        if (prior.body === body) {
+            commentAction = 'skipped';
+        }
+        else {
+            await deps.client.updateComment(result.caseKey, prior.id, body);
+            commentAction = 'updated';
+        }
+    }
+    else {
+        await deps.client.addComment(result.caseKey, body);
+        commentAction = 'created';
+    }
+    // Transition — pass/fail only. Unexecuted + obsolete never touch workflow.
+    const transitions = deps.transitions ?? { passed: 'Done', failed: 'In Review' };
+    let transitionAction = 'skipped';
+    if (result.status === 'passed' && transitions.passed) {
+        const t = await deps.client.transitionIssue(result.caseKey, transitions.passed);
+        transitionAction = t.transitioned ? 'moved' : 'skipped';
+    }
+    else if (result.status === 'failed' && transitions.failed) {
+        const t = await deps.client.transitionIssue(result.caseKey, transitions.failed);
+        transitionAction = t.transitioned ? 'moved' : 'skipped';
+    }
+    // Validates-link upsert — jira://<CASE-KEY> is the external evidence
+    // pointer. Unexecuted / obsolete leave any existing link's state UNTOUCHED.
+    let linked = false;
+    if (deps.specQueries && (result.status === 'passed' || result.status === 'failed')) {
+        const nextState = result.status === 'passed' ? 'verified' : 'broken';
+        const targetFilePath = `jira://${result.caseKey}`;
+        const targetQualifiedName = result.caseKey;
+        const existingLink = deps.specQueries.findLogicalLink(result.criterionId, targetFilePath, targetQualifiedName, 'validates');
+        const spec = deps.specQueries.getSpecById(result.criterionId);
+        const specHash = spec?.contentHash ?? existingLink?.specHashAtLink ?? '';
+        const ts = now();
+        const metadata = {
+            runId,
+            status: result.status,
+            executor: result.executor,
+        };
+        if (result.harness)
+            metadata.harness = result.harness;
+        if (result.evidence)
+            metadata.evidence = result.evidence;
+        if (existingLink) {
+            // Refresh metadata + state via updateSpecLinkState — the row already
+            // exists on the correct logical key so we don't need to re-upsert.
+            deps.specQueries.updateSpecLinkState(existingLink.id, nextState, null, ts);
+        }
+        else {
+            deps.specQueries.upsertSpecLink({
+                specId: result.criterionId,
+                targetFilePath,
+                targetQualifiedName,
+                targetNodeKind: 'file',
+                kind: 'validates',
+                state: nextState,
+                driftAxis: null,
+                specHashAtLink: specHash,
+                provenance: 'agent-asserted',
+                confidence: 1.0,
+                metadata,
+                createdAt: ts,
+                updatedAt: ts,
+            });
+        }
+        linked = true;
+    }
+    return {
+        pending: false,
+        status: result.status,
+        linked,
+        comment: commentAction,
+        transition: transitionAction,
+        ...(result.status === 'failed' ? { triageHint: triageHint(result.criterionId) } : {}),
+    };
+}
+/** Aggregate per-result counts + triage list from a run's recorded results. */
+function summarizePackRun(summary) {
+    let passed = 0;
+    let failed = 0;
+    let unexecuted = 0;
+    let obsolete = 0;
+    const triage = new Set();
+    for (const r of summary.results) {
+        switch (r.status) {
+            case 'passed':
+                passed++;
+                break;
+            case 'failed':
+                failed++;
+                triage.add(r.criterionId);
+                break;
+            case 'unexecuted':
+                unexecuted++;
+                break;
+            case 'obsolete':
+                obsolete++;
+                break;
+        }
+    }
+    const executed = passed + failed;
+    const ev = {
+        runId: summary.runId,
+        executed,
+        passed,
+        failed,
+        unexecuted,
+        obsolete,
+        triageCriterionIds: [...triage].sort(),
+    };
+    if (summary.startedAt)
+        ev.startedAt = summary.startedAt;
+    if (summary.finishedAt)
+        ev.finishedAt = summary.finishedAt;
+    return ev;
+}
+/**
+ * Close a pack run: post (or edit-in-place) the single summary comment on the
+ * pack epic. The marker keys on the epic + kind — never on the runId — so a
+ * subsequent run's summary edits the prior comment rather than appending
+ * (REQ-JIRAREG-005.A4).
+ */
+async function finalizePackRun(client, epicKey, summary) {
+    const evidence = summarizePackRun(summary);
+    return (0, milestone_comment_1.postMilestoneComment)(client, epicKey, 'pack_run_summary', {
+        // The pack epic is the "spec" the milestone comment records against here.
+        specId: epicKey,
+        packRun: evidence,
+    });
+}
+//# sourceMappingURL=regression-pack.js.map