empirical-sdd 0.26.1 → 0.27.0

package/CHANGELOG.md

@@ -8,6 +8,21 @@ under the alpha rules in [docs/versioning.md](docs/versioning.md).
 
 ## [Unreleased]
 
+## [0.27.0] - 2026-08-21
+
+### Changed
+
+- Made Tracker Policy v2 lifecycle comments human-first across GitHub, Linear,
+  and Jira, with plain-language status, focused action requests, friendly
+  evidence links, native Jira formatting, and provider-safe exact recovery
+  markers that remain compatible with existing comments.
+
+### Migration
+
+- Existing Schema 5 and Tracker Policy v1/v2 repositories require no state
+  migration. Visibility cadence, ticket bindings, issue descriptions, and
+  historical comments remain compatible.
+
 ## [0.26.1] - 2026-08-21
 
 ### Fixed
@@ -193,7 +208,8 @@ Published through GitHub Actions trusted publishing with npm provenance.
 
 - Prepared and released package version `0.20.2`.
 
-[Unreleased]: https://github.com/goempirical/empirical-sdd/compare/v0.26.1...HEAD
+[Unreleased]: https://github.com/goempirical/empirical-sdd/compare/v0.27.0...HEAD
+[0.27.0]: https://github.com/goempirical/empirical-sdd/compare/v0.26.1...v0.27.0
 [0.26.1]: https://github.com/goempirical/empirical-sdd/compare/v0.26.0...v0.26.1
 [0.26.0]: https://github.com/goempirical/empirical-sdd/compare/v0.25.0...v0.26.0
 [0.25.0]: https://github.com/goempirical/empirical-sdd/compare/v0.24.1...v0.25.0

package/README.md

@@ -4,7 +4,7 @@ Agent-neutral, resumable spec-driven development for coding agents. Empirical
 turns an ordinary change request into a deterministic workflow with durable
 state, reviewable evidence, and safe Git integration.
 
-> Empirical 0.26 is alpha software. It requires Node.js 22 or newer.
+> Empirical 0.27 is alpha software. It requires Node.js 22 or newer.
 
 ## Install
 

package/dist/cli.js

@@ -14862,7 +14862,7 @@ function verifyReceiptDigest(receipt) {
     throw new Error(`Evidence receipt ${parsed.id} has an asserted result inconsistent with its provenance.`);
   }
 }
-var SCHEMA_VERSION = 5, POLICY_SCHEMA_VERSION = 2, MANIFEST_SCHEMA_VERSION = 2, RECEIPT_SCHEMA_VERSION = 1, PRODUCT_VERSION = "0.26.1", workflowSchema, executionModeSchema, riskFloorSchema, completionLevelSchema, phaseSchema, workflowStatusSchema, criterionSchema, evidenceKindSchema, commandPolicySchema, evidencePolicySchema, projectPolicySchema, impactManifestSchema, authorizationSchema, COMPLETION_ORDER, receiptProvenanceSchema, receiptBaseSchema, executedReceiptSchema, artifactRecordSchema, collectedReceiptSchema, evidenceReceiptSchema;
+var SCHEMA_VERSION = 5, POLICY_SCHEMA_VERSION = 2, MANIFEST_SCHEMA_VERSION = 2, RECEIPT_SCHEMA_VERSION = 1, PRODUCT_VERSION = "0.27.0", workflowSchema, executionModeSchema, riskFloorSchema, completionLevelSchema, phaseSchema, workflowStatusSchema, criterionSchema, evidenceKindSchema, commandPolicySchema, evidencePolicySchema, projectPolicySchema, impactManifestSchema, authorizationSchema, COMPLETION_ORDER, receiptProvenanceSchema, receiptBaseSchema, executedReceiptSchema, artifactRecordSchema, collectedReceiptSchema, evidenceReceiptSchema;
 var init_protocol = __esm(() => {
   init_zod();
   workflowSchema = exports_external.enum(["fast", "complex"]);
@@ -24050,7 +24050,7 @@ class ProjectStore {
       return { ...await migrateSchema4To5(this.root) };
     }
     if (rawVersion !== SCHEMA_VERSION) {
-      throw new EmpiricalError("MIGRATION_REQUIRED", `Schema ${rawVersion} is unsupported; Empirical 0.26 migrates only Schema 4 to Schema 5`);
+      throw new EmpiricalError("MIGRATION_REQUIRED", `Schema ${rawVersion} is unsupported; Empirical 0.27 migrates only Schema 4 to Schema 5`);
     }
     await project.ensureProjectMetadata();
     return project.withResourceLock("specs", async () => {
@@ -37258,6 +37258,341 @@ function isMissingFile(error51) {
   return isRecord4(error51) && error51.code === "ENOENT";
 }
 
+// src/tracker-comments.ts
+var TRACKER_MARKER_ORIGIN = "https://github.com/goempirical/empirical-sdd";
+var EFFECT_KEY = /^sha256:[a-f0-9]{64}$/;
+var HUMAN_TEXT_LIMIT = 320;
+var WORK_LABEL_LIMIT = 96;
+var EVIDENCE_LIMIT = 10;
+var JIRA_SCAN_LIMIT = 1e4;
+var COMMENT_PROPERTY = "empirical-sdd-effect";
+function renderTrackerMilestone(provider, projection, effectKey) {
+  const identity = trackerMilestoneIdentity(effectKey);
+  const view = createTrackerMilestoneView(projection);
+  if (provider === "github") {
+    return {
+      provider,
+      body: [...renderMarkdownSections(view), "", identity.github].join(`
+`)
+    };
+  }
+  if (provider === "linear") {
+    return {
+      provider,
+      body: [...renderMarkdownSections(view), "", identity.linear].join(`
+`)
+    };
+  }
+  return {
+    provider,
+    body: renderJiraMilestone(view, identity),
+    property: { key: COMMENT_PROPERTY, value: identity.effectKey }
+  };
+}
+function createTrackerMilestoneView(projection) {
+  const summary = humanText(projection.summary, HUMAN_TEXT_LIMIT);
+  const stopped = projection.status === "blocked" || projection.status === "awaiting_human";
+  const actionText = stopped ? humanText(projection.blocker ?? projection.summary, HUMAN_TEXT_LIMIT) ?? (projection.status === "awaiting_human" ? "A decision or input is required before work can continue." : "Work cannot continue until this blocker is resolved.") : null;
+  return {
+    headline: milestoneHeadline(projection),
+    work: humanizeFeature(projection.feature),
+    summary: summary === actionText ? null : summary,
+    action: actionText ? {
+      label: projection.status === "awaiting_human" ? "Action needed" : "Blocker",
+      text: actionText
+    } : null,
+    evidence: milestoneEvidence(projection.artifacts ?? [])
+  };
+}
+function inspectTrackerMilestoneMarker(provider, comment, effectKey) {
+  const identity = trackerMilestoneIdentity(effectKey);
+  if (provider === "github" || provider === "linear") {
+    if (typeof comment.body !== "string")
+      return "absent";
+    return inspectMarkdownMarker(comment.body, provider === "github" ? identity.github : identity.linear, identity);
+  }
+  const body = inspectJiraBodyMarker(comment.body, identity);
+  const property = inspectJiraPropertyMarker(comment.properties, identity);
+  if (body === "malformed" || property === "malformed")
+    return "malformed";
+  return body === "match" || property === "match" ? "match" : "absent";
+}
+function trackerMilestoneIdentity(effectKey) {
+  if (!EFFECT_KEY.test(effectKey)) {
+    throw new EmpiricalError("TRACKER_MARKER_INVALID", "Tracker milestone identity requires one exact effect digest");
+  }
+  const url2 = `${TRACKER_MARKER_ORIGIN}#empirical-milestone:${effectKey}`;
+  return {
+    effectKey,
+    url: url2,
+    legacyMarkdown: `[Empirical milestone](<${url2}>)`,
+    github: `<!-- empirical-sdd-effect:${effectKey} -->`,
+    linear: `_[Managed by Empirical](<${url2}>)_`
+  };
+}
+function milestoneHeadline(projection) {
+  if (projection.status === "awaiting_human")
+    return "Input needed";
+  if (projection.status === "blocked")
+    return "Work is blocked";
+  if (projection.status === "done" || projection.phase === "done") {
+    switch (projection.completionLevel) {
+      case "implemented":
+        return "Implementation complete";
+      case "verified":
+        return "Verification complete";
+      case "integrated":
+        return "Integration complete";
+      case "delivered":
+        return "Delivery complete";
+      case "published":
+        return "Publication complete";
+      default:
+        return "Workflow complete";
+    }
+  }
+  switch (projection.phase) {
+    case "idle":
+    case "shape":
+    case "specify":
+    case "design":
+      return "Defining the work";
+    case "plan":
+      return "Plan ready";
+    case "implement":
+    case "context":
+      return "Implementation in progress";
+    case "verify":
+      return "Verification in progress";
+    case "review":
+      return "Ready for review";
+    case "integrate":
+      return "Integration in progress";
+    case "deliver":
+      return "Delivery in progress";
+    case "publish":
+      return "Publication in progress";
+    case "archive":
+      return "Wrapping up";
+    default:
+      return "Work in progress";
+  }
+}
+function humanizeFeature(feature) {
+  const value = feature.split("-").filter(Boolean).join(" ");
+  const sentence = `${value[0]?.toUpperCase() ?? ""}${value.slice(1)}`;
+  return boundText(sentence, WORK_LABEL_LIMIT) ?? "Empirical work";
+}
+function humanText(value, limit) {
+  if (!value?.trim())
+    return null;
+  const normalized = value.normalize("NFKC").replace(/\[([^\]\r\n]{0,128})\]\([^\)\r\n]{1,2048}\)/g, "$1").replace(/\bhttps?:\/\/\S+/gi, "[link omitted]").replace(/\b(?:bearer|basic)\s+[A-Za-z0-9._~+/=-]+/gi, "[REDACTED]").replace(/\b(?:gh[pousr]_|github_pat_|lin_api_)[A-Za-z0-9_]{16,}\b/gi, "[REDACTED]").replace(/((?:authorization|password|secret|api[_ -]?key|token)\s*[:=]\s*)\S+/gi, "$1[REDACTED]").replace(/\b(?:executed|collected)-[a-z0-9-]+\b/gi, "[REDACTED]").replace(/\b(?:sha256:)?[a-f0-9]{40,64}\b/gi, "[REDACTED]").replace(/empirical-(?:milestone|sdd-effect):/gi, "Empirical update ").replace(/<!--|-->/g, " ").replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, " ").replace(/@/g, "＠").replace(/\s+/g, " ").trim();
+  return boundText(normalized, limit);
+}
+function boundText(value, limit) {
+  const points = [...value.trim()];
+  if (points.length === 0)
+    return null;
+  if (points.length <= limit)
+    return points.join("");
+  return `${points.slice(0, Math.max(1, limit - 1)).join("").trimEnd()}…`;
+}
+function milestoneEvidence(artifacts) {
+  const candidates = artifacts.flatMap((artifact) => {
+    const url2 = safeEvidenceUrl(artifact.url);
+    return url2 ? [{ base: evidenceLabel(artifact.mediaType), url: url2 }] : [];
+  }).slice(0, EVIDENCE_LIMIT);
+  const totals = new Map;
+  for (const candidate of candidates) {
+    totals.set(candidate.base, (totals.get(candidate.base) ?? 0) + 1);
+  }
+  const seen = new Map;
+  return candidates.map((candidate) => {
+    const index = (seen.get(candidate.base) ?? 0) + 1;
+    seen.set(candidate.base, index);
+    return {
+      label: (totals.get(candidate.base) ?? 0) > 1 ? `${candidate.base} ${index}` : candidate.base,
+      url: candidate.url
+    };
+  });
+}
+function evidenceLabel(mediaType) {
+  if (mediaType.startsWith("image/"))
+    return "Screenshot";
+  if (mediaType === "application/pdf")
+    return "Document";
+  if (mediaType === "application/json")
+    return "Report";
+  if (mediaType === "text/plain" || mediaType === "text/markdown")
+    return "Notes";
+  return "Evidence";
+}
+function safeEvidenceUrl(value) {
+  if (!value || value !== value.trim() || value.length > 2048 || /[\u0000-\u001f\u007f<>]/.test(value)) {
+    return null;
+  }
+  if (hasUnsafeLinkMaterial(value))
+    return null;
+  try {
+    const url2 = new URL(value);
+    if (url2.protocol !== "https:" || url2.username || url2.password)
+      return null;
+    let decoded;
+    try {
+      decoded = decodeURIComponent(`${url2.pathname}${url2.search}${url2.hash}`);
+    } catch {
+      return null;
+    }
+    if (hasUnsafeLinkMaterial(decoded))
+      return null;
+    return url2.toString();
+  } catch {
+    return null;
+  }
+}
+function hasUnsafeLinkMaterial(value) {
+  return /\b(?:bearer|basic)\s+/i.test(value) || /\b(?:gh[pousr]_|github_pat_|lin_api_)[A-Za-z0-9_]{16,}\b/i.test(value) || /(?:authorization|password|secret|api[_ -]?key|token)\s*[:=]/i.test(value) || /(?:empirical-(?:milestone|sdd-effect):|sha256:)/i.test(value);
+}
+function renderMarkdownSections(view) {
+  const lines = [
+    `## ${escapeMarkdown(view.headline)}`,
+    `**${escapeMarkdown(view.work)}**`
+  ];
+  if (view.summary)
+    lines.push("", escapeMarkdown(view.summary));
+  if (view.action) {
+    lines.push("", `### ${view.action.label}`, escapeMarkdown(view.action.text));
+  }
+  if (view.evidence.length > 0) {
+    lines.push("", "### Evidence", ...view.evidence.map((entry) => `- [${entry.label}](<${entry.url}>)`));
+  }
+  return lines;
+}
+function escapeMarkdown(value) {
+  return value.replace(/([!"#$%&'()*+,\-./:;<=>?@[\\\]^_`{|}~])/g, "\\$1");
+}
+function renderJiraMilestone(view, identity) {
+  const content = [
+    jiraHeading(view.headline, 2),
+    jiraParagraph(view.work, [{ type: "strong" }])
+  ];
+  if (view.summary)
+    content.push(jiraParagraph(view.summary));
+  if (view.action) {
+    content.push(jiraHeading(view.action.label, 3), jiraParagraph(view.action.text));
+  }
+  if (view.evidence.length > 0) {
+    content.push(jiraHeading("Evidence", 3), {
+      type: "bulletList",
+      content: view.evidence.map((entry) => ({
+        type: "listItem",
+        content: [jiraParagraph(entry.label, [{ type: "link", attrs: { href: entry.url } }])]
+      }))
+    });
+  }
+  content.push(jiraParagraph("Managed by Empirical", [
+    { type: "em" },
+    { type: "link", attrs: { href: identity.url } }
+  ]));
+  return { version: 1, type: "doc", content };
+}
+function jiraHeading(text, level) {
+  return {
+    type: "heading",
+    attrs: { level },
+    content: [{ type: "text", text }]
+  };
+}
+function jiraParagraph(text, marks = []) {
+  return {
+    type: "paragraph",
+    content: [{ type: "text", text, ...marks.length > 0 ? { marks } : {} }]
+  };
+}
+function inspectMarkdownMarker(body, current, identity) {
+  const related = countOccurrences(body, identity.effectKey);
+  if (related === 0)
+    return "absent";
+  const lines = body.split(/\r?\n/);
+  const recognized = lines.filter((line) => line === current || line === identity.legacyMarkdown).length;
+  return related === 1 && recognized === 1 ? "match" : "malformed";
+}
+function inspectJiraBodyMarker(body, identity) {
+  const scan = { related: 0, recognized: 0 };
+  let visited = 0;
+  const walk = (value) => {
+    visited += 1;
+    if (visited > JIRA_SCAN_LIMIT) {
+      scan.related += 1;
+      return;
+    }
+    if (typeof value === "string") {
+      scan.related += countOccurrences(value, identity.effectKey);
+      if (value === identity.legacyMarkdown)
+        scan.recognized += 1;
+      return;
+    }
+    if (Array.isArray(value)) {
+      for (const entry of value)
+        walk(entry);
+      return;
+    }
+    if (!isRecord5(value))
+      return;
+    if (value.type === "text" && value.text === "Managed by Empirical" && Array.isArray(value.marks)) {
+      for (const rawMark of value.marks) {
+        if (!isRecord5(rawMark) || rawMark.type !== "link" || !isRecord5(rawMark.attrs))
+          continue;
+        if (rawMark.attrs.href === identity.url)
+          scan.recognized += 1;
+      }
+    }
+    for (const entry of Object.values(value))
+      walk(entry);
+  };
+  walk(body);
+  if (scan.related === 0)
+    return "absent";
+  return scan.related === 1 && scan.recognized === 1 ? "match" : "malformed";
+}
+function inspectJiraPropertyMarker(properties, identity) {
+  const values = [];
+  if (Array.isArray(properties)) {
+    for (const rawProperty of properties) {
+      if (isRecord5(rawProperty) && rawProperty.key === COMMENT_PROPERTY)
+        values.push(rawProperty.value);
+    }
+  } else if (isRecord5(properties) && Object.hasOwn(properties, COMMENT_PROPERTY)) {
+    values.push(properties[COMMENT_PROPERTY]);
+  }
+  if (values.length === 0)
+    return "absent";
+  let related = 0;
+  let recognized = 0;
+  for (const value of values) {
+    if (typeof value !== "string")
+      continue;
+    related += countOccurrences(value, identity.effectKey);
+    if (value === identity.effectKey || value === identity.legacyMarkdown)
+      recognized += 1;
+  }
+  if (related === 0)
+    return "absent";
+  return related === 1 && recognized === 1 ? "match" : "malformed";
+}
+function countOccurrences(value, token) {
+  let count = 0;
+  let offset = 0;
+  while ((offset = value.indexOf(token, offset)) !== -1) {
+    count += 1;
+    offset += token.length;
+  }
+  return count;
+}
+function isRecord5(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 // src/tracking.ts
 init_protocol();
 var TRACKER_SCHEMA_VERSION = 2;
@@ -38535,8 +38870,7 @@ async function projectRemoteTicketV2(root, policy, binding, pending, credentials
   if (shouldPublishMilestone(policy, binding, pending.projection)) {
     const commentKey = trackerEffectKey(policy, pending.projection, "comment");
     if (!hasTrackerEffect(activePending, commentKey)) {
-      const marker2 = milestoneMarker(commentKey);
-      const commentId = await publishRemoteMilestone(policy, binding, renderMilestone(pending.projection, marker2), marker2, credentials, dependencies);
+      const commentId = await publishRemoteMilestone(policy, binding, pending.projection, commentKey, credentials, dependencies);
       activePending = await acknowledgeTrackerEffect(root, activePending, { key: commentKey, kind: "comment", remoteId: commentId, at: now(dependencies) });
     }
     for (const artifact of pending.projection.artifacts ?? []) {
@@ -38626,8 +38960,12 @@ async function transitionRemoteTicketV2(policy, binding, projection, credentials
   }
   return { ...binding, url: `${jiraOrigin(policy)}/browse/${encodeURIComponent(binding.remoteKey)}` };
 }
-async function publishRemoteMilestone(policy, binding, body, marker2, credentials, dependencies) {
+async function publishRemoteMilestone(policy, binding, projection, effectKey, credentials, dependencies) {
   if (policy.provider === "github") {
+    const milestone2 = renderTrackerMilestone("github", projection, effectKey);
+    if (milestone2.provider !== "github") {
+      throw new EmpiricalError("TRACKER_RENDERER_MISMATCH", "GitHub milestone renderer returned another provider payload");
+    }
     const token = accessTokenFor(credentials, "github");
     const found2 = [];
     let complete2 = false;
@@ -38639,8 +38977,16 @@ async function publishRemoteMilestone(policy, binding, body, marker2, credential
       }, [200], [token]);
       if (!Array.isArray(comments))
         throw new EmpiricalError("TRACKER_MALFORMED_RESPONSE", "GitHub milestone comments are malformed");
-      const matches = comments.map((entry) => record4(entry, "GitHub milestone comment")).filter((comment) => typeof comment.body === "string" && comment.body.includes(marker2));
-      found2.push(...matches.map((comment) => String(requiredNumber(comment, "id", "GitHub milestone comment id"))));
+      for (const entry of comments) {
+        const comment = record4(entry, "GitHub milestone comment");
+        const inspection = inspectTrackerMilestoneMarker("github", comment, effectKey);
+        if (inspection === "malformed") {
+          throw new EmpiricalError("TRACKER_MARKER_MALFORMED", "A GitHub comment contains malformed milestone ownership evidence");
+        }
+        if (inspection === "match") {
+          found2.push(String(requiredNumber(comment, "id", "GitHub milestone comment id")));
+        }
+      }
       if (comments.length < 100) {
         complete2 = true;
         break;
@@ -38656,11 +39002,15 @@ async function publishRemoteMilestone(policy, binding, body, marker2, credential
       method: "POST",
       url: `https://api.github.com/repos/${encodeURIComponent(policy.target.owner)}/${encodeURIComponent(policy.target.repository)}/issues/${encodeURIComponent(binding.remoteKey)}/comments`,
       headers: githubHeaders(token),
-      body: JSON.stringify({ body })
+      body: JSON.stringify({ body: milestone2.body })
     }, [201], [token]);
     return String(requiredNumber(created2, "id", "GitHub milestone comment id"));
   }
   if (policy.provider === "linear") {
+    const milestone2 = renderTrackerMilestone("linear", projection, effectKey);
+    if (milestone2.provider !== "linear") {
+      throw new EmpiricalError("TRACKER_RENDERER_MISMATCH", "Linear milestone renderer returned another provider payload");
+    }
     const accessToken = linearAuthorizationFor(credentials);
     let after = null;
     const cursors = new Set;
@@ -38672,8 +39022,16 @@ async function publishRemoteMilestone(policy, binding, body, marker2, credential
         }`, { id: binding.remoteId, after }, accessToken, dependencies);
       const issue2 = record4(data2.issue, "Linear milestone issue");
       const comments = connection(issue2.comments, "Linear milestone comments");
-      const matches = comments.nodes.map((entry) => record4(entry, "Linear milestone comment")).filter((comment) => typeof comment.body === "string" && comment.body.includes(marker2));
-      found2.push(...matches.map((comment) => requiredString(comment, "id", "Linear milestone comment id")));
+      for (const entry of comments.nodes) {
+        const comment = record4(entry, "Linear milestone comment");
+        const inspection = inspectTrackerMilestoneMarker("linear", comment, effectKey);
+        if (inspection === "malformed") {
+          throw new EmpiricalError("TRACKER_MARKER_MALFORMED", "A Linear comment contains malformed milestone ownership evidence");
+        }
+        if (inspection === "match") {
+          found2.push(requiredString(comment, "id", "Linear milestone comment id"));
+        }
+      }
       if (!comments.hasNextPage) {
         complete2 = true;
         break;
@@ -38688,12 +39046,16 @@ async function publishRemoteMilestone(policy, binding, body, marker2, credential
       return found2[0];
     const data = await linearGraphql(`mutation Milestone($input: CommentCreateInput!) {
         commentCreate(input: $input) { success comment { id body } }
-      }`, { input: { issueId: binding.remoteId, body } }, accessToken, dependencies);
+      }`, { input: { issueId: binding.remoteId, body: milestone2.body } }, accessToken, dependencies);
     const create = record4(data.commentCreate, "Linear commentCreate");
     if (create.success !== true)
       throw new EmpiricalError("TRACKER_MALFORMED_RESPONSE", "Linear did not confirm milestone comment creation");
     return requiredString(record4(create.comment, "Linear milestone comment"), "id", "Linear milestone comment id");
   }
+  const milestone = renderTrackerMilestone("jira", projection, effectKey);
+  if (milestone.provider !== "jira") {
+    throw new EmpiricalError("TRACKER_RENDERER_MISMATCH", "Jira milestone renderer returned another provider payload");
+  }
   const jira = jiraRequestContext(policy.target.siteUrl, credentials);
   let startAt = 0;
   const found = [];
@@ -38701,13 +39063,21 @@ async function publishRemoteMilestone(policy, binding, body, marker2, credential
   for (let page = 0;page < TRACKER_DISCOVERY_LIMIT; page += 1) {
     const response = record4(await requestJson(dependencies, {
       method: "GET",
-      url: `${jira.apiOrigin}/rest/api/3/issue/${encodeURIComponent(binding.remoteKey)}/comment?startAt=${startAt}&maxResults=100`,
+      url: `${jira.apiOrigin}/rest/api/3/issue/${encodeURIComponent(binding.remoteKey)}/comment?startAt=${startAt}&maxResults=100&expand=properties`,
       headers: jira.headers
     }, [200], jira.secrets), "Jira milestone comments");
     if (!Array.isArray(response.comments))
       throw new EmpiricalError("TRACKER_MALFORMED_RESPONSE", "Jira milestone comments are malformed");
-    const matches = response.comments.map((entry) => record4(entry, "Jira milestone comment")).filter((comment) => JSON.stringify(comment.body ?? {}).includes(marker2));
-    found.push(...matches.map((comment) => requiredString(comment, "id", "Jira milestone comment id")));
+    for (const entry of response.comments) {
+      const comment = record4(entry, "Jira milestone comment");
+      const inspection = inspectTrackerMilestoneMarker("jira", comment, effectKey);
+      if (inspection === "malformed") {
+        throw new EmpiricalError("TRACKER_MARKER_MALFORMED", "A Jira comment contains malformed milestone ownership evidence");
+      }
+      if (inspection === "match") {
+        found.push(requiredString(comment, "id", "Jira milestone comment id"));
+      }
+    }
     const total = optionalFiniteNumber(response.total) ?? response.comments.length;
     if (startAt + response.comments.length >= total) {
       complete = true;
@@ -38727,7 +39097,7 @@ async function publishRemoteMilestone(policy, binding, body, marker2, credential
     method: "POST",
     url: `${jira.apiOrigin}/rest/api/3/issue/${encodeURIComponent(binding.remoteKey)}/comment`,
     headers: jira.headers,
-    body: JSON.stringify({ body: jiraAdf(body), properties: [{ key: "empirical-sdd-effect", value: marker2 }] })
+    body: JSON.stringify({ body: milestone.body, properties: [milestone.property] })
   }, [201], jira.secrets), "Jira milestone comment");
   return requiredString(created, "id", "Jira milestone comment id");
 }
@@ -38849,27 +39219,6 @@ function trackerEffectKey(policy, projection, kind, artifactDigest = null) {
     artifactDigest
   });
 }
-function milestoneMarker(key) {
-  return `[Empirical milestone](<${LINEAR_MARKER_ORIGIN}#empirical-milestone:${key}>)`;
-}
-function renderMilestone(projection, marker2) {
-  const clean = (value) => value?.replace(/<!--|-->/g, "").replace(/\s+/g, " ").trim();
-  const summary = clean(projection.summary);
-  const blocker = clean(projection.blocker);
-  const artifacts = projection.artifacts ?? [];
-  return [
-    `## Empirical milestone · ${readableTrackerToken(projection.phase)}`,
-    marker2,
-    `- Feature: ${projection.feature}`,
-    `- Revision: ${projection.revision}`,
-    `- Progress: ${readableTrackerToken(projection.progress)}`,
-    `- Completion: ${readableCompletionLevel(projection.completionLevel)}`,
-    ...summary ? [`- Summary: ${summary}`] : [],
-    ...blocker ? [`- Blocker: ${blocker}`] : [],
-    ...artifacts.length ? ["- Reviewable artifacts:", ...artifacts.map((artifact) => artifact.url ? `  - ${artifact.path} · ${artifact.receiptId} · ${artifact.url}` : `  - ${artifact.path} · ${artifact.receiptId} · provider upload/link pending or unsupported`)] : []
-  ].join(`
-`);
-}
 function hasTrackerEffect(pending, key) {
   return (pending.effects ?? []).some((effect) => effect.key === key);
 }
@@ -40301,14 +40650,13 @@ Gate: ${summary}` : "";
   ].join(`
 `);
 }
-var LINEAR_MARKER_ORIGIN = "https://github.com/goempirical/empirical-sdd";
 function linearProjectionBoundary(feature, boundary) {
   const label = boundary === "start" ? "Delivery status" : "Managed by Empirical SDD · local workflow is authoritative";
   const heading = boundary === "start" ? "## " : "";
-  return `${heading}[${label}](<${LINEAR_MARKER_ORIGIN}#empirical-sdd:${feature}:${boundary}>)`;
+  return `${heading}[${label}](<${TRACKER_MARKER_ORIGIN}#empirical-sdd:${feature}:${boundary}>)`;
 }
 function linearCreateMarkerLine(intent, idempotencyKey) {
-  return `[Crash-safe synchronization enabled](<${LINEAR_MARKER_ORIGIN}#${intent.marker}:${idempotencyKey}>)`;
+  return `[Crash-safe synchronization enabled](<${TRACKER_MARKER_ORIGIN}#${intent.marker}:${idempotencyKey}>)`;
 }
 function readableTrackerToken(value) {
   return value.split(/[-_]/).filter(Boolean).map((part) => `${part[0]?.toUpperCase() ?? ""}${part.slice(1)}`).join(" ");
@@ -40320,7 +40668,7 @@ function renderLinearProjection(projection) {
   const summary = projection.summary?.replace(/<!--|-->/g, "").replace(/\s+/g, " ").trim();
   return [
     linearProjectionBoundary(projection.feature, "start"),
-    `[${readableTrackerToken(projection.progress)}](<${LINEAR_MARKER_ORIGIN}#${projection.marker}>)`,
+    `[${readableTrackerToken(projection.progress)}](<${TRACKER_MARKER_ORIGIN}#${projection.marker}>)`,
     `- Phase: ${readableTrackerToken(projection.phase)}`,
     `- Workflow: ${readableTrackerToken(projection.status)}`,
     `- Revision: ${projection.revision}`,
@@ -40337,11 +40685,11 @@ function upsertLinearMarkerBlock(existing, projection) {
   const legacyEnd = `<!-- empirical-sdd:${projection.feature}:end -->`;
   const readableStart = linearProjectionBoundary(projection.feature, "start");
   const readableEnd = linearProjectionBoundary(projection.feature, "end");
-  const priorReadableStart = `[**Empirical SDD**](${LINEAR_MARKER_ORIGIN}#empirical-sdd:${projection.feature}:start)`;
-  const priorCanonicalStart = `**[Empirical SDD](<${LINEAR_MARKER_ORIGIN}#empirical-sdd:${projection.feature}:start>)`;
-  const priorReadableEnd = `[Managed projection](${LINEAR_MARKER_ORIGIN}#empirical-sdd:${projection.feature}:end)`;
-  const priorCanonicalEnd = `[Managed projection](<${LINEAR_MARKER_ORIGIN}#empirical-sdd:${projection.feature}:end>)`;
-  const priorHeadingStart = `## [Empirical SDD](<${LINEAR_MARKER_ORIGIN}#empirical-sdd:${projection.feature}:start>)`;
+  const priorReadableStart = `[**Empirical SDD**](${TRACKER_MARKER_ORIGIN}#empirical-sdd:${projection.feature}:start)`;
+  const priorCanonicalStart = `**[Empirical SDD](<${TRACKER_MARKER_ORIGIN}#empirical-sdd:${projection.feature}:start>)`;
+  const priorReadableEnd = `[Managed projection](${TRACKER_MARKER_ORIGIN}#empirical-sdd:${projection.feature}:end)`;
+  const priorCanonicalEnd = `[Managed projection](<${TRACKER_MARKER_ORIGIN}#empirical-sdd:${projection.feature}:end>)`;
+  const priorHeadingStart = `## [Empirical SDD](<${TRACKER_MARKER_ORIGIN}#empirical-sdd:${projection.feature}:start>)`;
   const priorIndentedReadableEnd = `  ${readableEnd}`;
   const markerFragments = [
     `empirical-sdd:${projection.feature}:start`,
@@ -40382,12 +40730,12 @@ function linearCreateMarkerMatches(value, marker2) {
   const markerPrefix2 = `${marker2}:`;
   const legacyStartPrefix = `<!-- ${markerPrefix2}`;
   const readablePrefixes = [
-    `[Recovery reference](${LINEAR_MARKER_ORIGIN}#${markerPrefix2}`,
-    `[Crash-safe synchronization enabled](${LINEAR_MARKER_ORIGIN}#${markerPrefix2}`
+    `[Recovery reference](${TRACKER_MARKER_ORIGIN}#${markerPrefix2}`,
+    `[Crash-safe synchronization enabled](${TRACKER_MARKER_ORIGIN}#${markerPrefix2}`
   ];
   const canonicalReadablePrefixes = [
-    `[Recovery reference](<${LINEAR_MARKER_ORIGIN}#${markerPrefix2}`,
-    `[Crash-safe synchronization enabled](<${LINEAR_MARKER_ORIGIN}#${markerPrefix2}`
+    `[Recovery reference](<${TRACKER_MARKER_ORIGIN}#${markerPrefix2}`,
+    `[Crash-safe synchronization enabled](<${TRACKER_MARKER_ORIGIN}#${markerPrefix2}`
   ];
   const matches = [];
   const consumed = new Set;
@@ -40445,7 +40793,7 @@ function migrateLinearCreateMarker(existing, feature) {
   const lines = existing.replace(/\r\n/g, `
 `).split(`
 `);
-  const replacement = `[Crash-safe synchronization enabled](<${LINEAR_MARKER_ORIGIN}#${marker2}:${match.idempotencyKey}>)`;
+  const replacement = `[Crash-safe synchronization enabled](<${TRACKER_MARKER_ORIGIN}#${marker2}:${match.idempotencyKey}>)`;
   return [
     ...lines.slice(0, match.start),
     replacement,
@@ -44091,7 +44439,7 @@ function mcpDefaultRoot() {
 }
 async function prepareTrackerOAuthHandoff(server, subject, dependencies) {
   const elicitation = server.server.getClientCapabilities()?.elicitation;
-  if (!isRecord5(elicitation) || !isRecord5(elicitation.url))
+  if (!isRecord6(elicitation) || !isRecord6(elicitation.url))
     return;
   const authorization = await trackerOAuthAuthorization(subject, dependencies);
   if (!authorization)
@@ -44113,13 +44461,13 @@ async function toolResult(operation2) {
     const value = await operation2();
     return {
       content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
-      structuredContent: isRecord5(value) ? value : { value }
+      structuredContent: isRecord6(value) ? value : { value }
     };
   } catch (error51) {
     return { isError: true, content: [{ type: "text", text: asErrorMessage(error51) }] };
   }
 }
-function isRecord5(value) {
+function isRecord6(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }