trackfw 6.10.0 → 7.1.0

package/src/thirdparty/markers.js

@@ -0,0 +1,207 @@
+'use strict'
+
+// Node port of internal/thirdparty/markers.go — the D3 objective-refusal
+// marker check and the Checksum primitive. See:
+// docs/adr/ADR-2026-08-15-gate-de-duas-fases-para-artefatos-de-terceiro-quarentena-parecer-vinculado-por-checksum-e-deteccao-por-proveniencia-versionada.md
+// (D3, D6).
+
+const crypto = require('node:crypto')
+const { URL } = require('node:url')
+
+// LITERAL_MARKERS mirrors internal/thirdparty/markers.go:literalMarkers — an
+// objective, literal tripwire list, not a filter against a competent
+// adversary (see the ADR's "o que este critério NÃO cobre" section).
+const LITERAL_MARKERS = [
+  'git authority',
+  'mode lock',
+  'governance prerequisite',
+  'reporting boundary',
+  'scope boundary',
+  'dispatch contract',
+]
+
+// HTML_COMMENT_PATTERN matches HTML comments; step 1 of the D3 pipeline
+// NEUTRALIZES them (strips only the delimiters, keeping the inner content
+// in place to be scanned), mirroring internal/thirdparty/markers.go's
+// D3-ter(b) amendment — see neutralizeHTMLComments below.
+const HTML_COMMENT_PATTERN = /<!--([\s\S]*?)-->/g
+
+// neutralizeHTMLComments strips only the HTML comment delimiters ("<!--"
+// and "-->"), keeping whatever text was between them in place to be
+// scanned by the later steps of the pipeline. D3-ter(b): the previous
+// wholesale removal contradicted D3's own written justification for this
+// step ("an LLM reads HTML comments in the token stream") — a marker
+// hidden as `<!-- ## Git authority -->` passed clean.
+function neutralizeHTMLComments(text) {
+  return text.replace(HTML_COMMENT_PATTERN, '$1')
+}
+
+// FENCE_PREFIX_PATTERN detects a fence-opening/closing line: optional
+// leading whitespace followed by three or more backticks or tildes.
+//
+// Unlike the Go reference — which is forced into an explicit line-scanner
+// because Go's RE2-based regexp package rejects backreferences at runtime
+// (see vault/notes/go-regexp-re2-sem-backreference-fenced-block-removal-2026-08-15.md)
+// — JS RegExp does support backreferences. This port still uses the same
+// explicit line-scanner algorithm as the Go reference (removeFencedBlocks
+// below), NOT because JS requires it, but because the scanner is what
+// implements the actual CommonMark closing rule correctly (same delimiter
+// character, closer repeat count >= opener repeat count, unclosed fence
+// never re-opens a heading read). A single backreference regex here would
+// diverge from the Go reference on: an unclosed fence, a closing run
+// shorter than the opener, and an indented fence — porting the algorithm,
+// not the regex, is what keeps behavior byte-identical to Go.
+const FENCE_PREFIX_PATTERN = /^\s*(```+|~~~+)/
+
+// trimChar mirrors Go's strings.Trim(s, cutset) for a single-char cutset:
+// strips ONLY leading/trailing runs of ch, never occurrences in the middle.
+function trimChar(str, ch) {
+  let start = 0
+  let end = str.length
+  while (start < end && str[start] === ch) start++
+  while (end > start && str[end - 1] === ch) end--
+  return str.slice(start, end)
+}
+
+// removeFencedBlocks strips PROPERLY-CLOSED fenced code blocks (``` or
+// ~~~), step 2 of the D3 pipeline: lines inside a closed fence are not read
+// as headings, otherwise documentation that merely quotes the marker list
+// would be refused by its own criterion. A fence is closed by a line
+// starting with the same delimiter character, with at least as many
+// repeats as the opener — the CommonMark rule.
+//
+// D3-ter(a) amendment: an opener with NO matching closer before EOF is NOT
+// a fence for this check — the buffered lines (including the opener) are
+// replayed as ordinary text instead of being dropped. Before this
+// amendment, an unclosed fence swallowed the rest of the document as
+// "fenced" content, silently hiding any marker after it. Mirrors
+// internal/thirdparty/markers.go:removeFencedBlocks.
+function removeFencedBlocks(text) {
+  const lines = text.split('\n')
+  const out = []
+  let buffered = [] // lines consumed since the current fence opener; replayed verbatim if it never closes
+  let closer = '' // fence delimiter run that closes the current block, '' if not in a fence
+  for (const line of lines) {
+    if (closer === '') {
+      const match = FENCE_PREFIX_PATTERN.exec(line)
+      if (match) {
+        closer = match[1]
+        buffered = [line] // keep the opener in case this fence never closes
+        continue
+      }
+      out.push(line)
+      continue
+    }
+    // Inside a (possibly-never-closing) fence: buffer the line, then check
+    // if it closes the block.
+    buffered.push(line)
+    const trimmed = line.trim()
+    const delimChar = closer[0]
+    if (trimmed.startsWith(delimChar.repeat(closer.length)) && trimChar(trimmed, delimChar) === '') {
+      closer = ''
+      buffered = [] // closed properly: the buffered fenced content is discarded, as before
+    }
+  }
+  if (closer !== '') {
+    // Reached EOF still "inside" a fence that never closed (D3-ter(a)): not
+    // a fence at all — replay every buffered line, including the opener,
+    // as ordinary text to be scanned.
+    out.push(...buffered)
+  }
+  return out.join('\n')
+}
+
+// HEADING_LINE_PATTERN matches a single, already-collapsed Markdown heading
+// line (level 1-6). Applied per-line after step 5, on text that no longer
+// contains internal runs of whitespace.
+const HEADING_LINE_PATTERN = /^#{1,6}\s+(.*)$/
+
+// WHITESPACE_PATTERN collapses runs of internal whitespace, step 5.
+const WHITESPACE_PATTERN = /\s+/g
+
+// checkMarkers applies the D3 objective-refusal criterion to content and
+// returns the literal marker names (from LITERAL_MARKERS) that matched as a
+// heading. The normalization pipeline, in fixed order, mirrors
+// internal/thirdparty/markers.go:CheckMarkers exactly:
+//  1. remove HTML comments;
+//  2. remove fenced code blocks (``` and ~~~);
+//  3. NFKC normalize;
+//  4. casefold (String.prototype.toLowerCase(), matching Go's
+//     strings.ToLower — not a true Unicode casefold, deliberately, to stay
+//     byte-identical to the Go reference);
+//  5. collapse internal whitespace + strip, applied per line;
+//  6. match only lines matching ^#{1,6}\s+ against the literal marker list.
+//
+// content may be a Buffer or a string; Buffers are decoded as UTF-8,
+// mirroring Go's string(content) over raw bytes.
+function checkMarkers(content) {
+  let text = Buffer.isBuffer(content) ? content.toString('utf8') : String(content)
+
+  // 1. Neutralize HTML comments — strip only the delimiters, keep the
+  // inner content in place to be scanned (D3-ter(b)).
+  text = neutralizeHTMLComments(text)
+
+  // 2. Remove fenced code blocks — lines inside a fence are not headings.
+  text = removeFencedBlocks(text)
+
+  // 3. NFKC normalize.
+  text = text.normalize('NFKC')
+
+  // 4. Casefold.
+  text = text.toLowerCase()
+
+  const matched = []
+  const seen = new Set()
+  for (const line of text.split('\n')) {
+    // 5. Collapse internal whitespace + strip.
+    const collapsed = line.replace(WHITESPACE_PATTERN, ' ').trim()
+
+    // 6. Match only heading lines against the literal marker list.
+    const match = HEADING_LINE_PATTERN.exec(collapsed)
+    if (!match) continue
+    const body = match[1]
+    for (const marker of LITERAL_MARKERS) {
+      if (body === marker && !seen.has(marker)) {
+        matched.push(marker)
+        seen.add(marker)
+      }
+    }
+  }
+  return matched
+}
+
+// checksum returns the SHA-256 hex digest of the raw bytes, before any
+// normalization. Mirrors internal/thirdparty/markers.go:Checksum. raw may be
+// a Buffer or a string (encoded as UTF-8).
+function checksum(raw) {
+  const buf = Buffer.isBuffer(raw) ? raw : Buffer.from(String(raw), 'utf8')
+  return crypto.createHash('sha256').update(buf).digest('hex')
+}
+
+// redactURL returns rawURL with its query string — and userinfo, if
+// present — replaced by the literal marker "[redacted]" (D6-bis). Used
+// before persisting a third-party artifact's source URL to disk (the
+// quarantine record and the provenance entry): a pre-signed URL can carry a
+// bearer token in its query string, which would otherwise become a
+// permanent secret in the git history the moment either file is committed.
+// The full, unredacted URL is used only in memory, for the network fetch
+// itself (D7) — never for anything persisted. Mirrors
+// internal/thirdparty/markers.go:RedactURL. Deliberately constructs the
+// result manually (protocol/host/pathname/hash) rather than mutating and
+// re-serializing via the URL object's own .toString(), to stay
+// byte-identical to the Go/Python output shape rather than depend on
+// WHATWG URL serialization nuances.
+function redactURL(rawURL) {
+  let parsed
+  try {
+    parsed = new URL(rawURL)
+  } catch {
+    return rawURL
+  }
+  let result = `${parsed.protocol}//${parsed.host}${parsed.pathname}`
+  if (parsed.search !== '') result += '?[redacted]'
+  result += parsed.hash
+  return result
+}
+
+module.exports = { checkMarkers, checksum, redactURL, literalMarkers: LITERAL_MARKERS, removeFencedBlocks }

package/src/thirdparty/provenance.js

@@ -0,0 +1,114 @@
+'use strict'
+
+// Node port of internal/thirdparty/provenance.go — the D6/D8c provenance
+// record and TOCTOU-closing approval check. See:
+// docs/adr/ADR-2026-08-15-gate-de-duas-fases-para-artefatos-de-terceiro-quarentena-parecer-vinculado-por-checksum-e-deteccao-por-proveniencia-versionada.md
+// (D6, D8c, D8f).
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const { atomicWrite } = require('./quarantine')
+const { redactURL } = require('./markers')
+
+// PROVENANCE_SCHEMA_VERSION mirrors internal/thirdparty/provenance.go:provenanceSchemaVersion.
+//
+// Bumped 1 -> 2 (ADR-2026-08-15 D2-bis, ML-3B) to add the entry field
+// installed_sha256 (SHA-256 of the NORMALIZED bytes, computed at install
+// time). checksum_sha256 (SHA-256 of the RAW bytes, the D8c approval
+// anchor) is unchanged. No migration path exists or is needed: at the time
+// of the bump no provenance file existed anywhere with schema_version 1.
+const PROVENANCE_SCHEMA_VERSION = 2
+
+function emptyProvenance() {
+  return { schema_version: PROVENANCE_SCHEMA_VERSION, entries: {} }
+}
+
+// provenancePath returns the on-disk path of the provenance file, rooted at
+// root. Mirrors internal/thirdparty/provenance.go:ProvenancePath.
+function provenancePath(root) {
+  return path.join(root, '.trackfw', 'thirdparty-provenance.json')
+}
+
+// loadProvenance reads and validates the provenance file: a missing file is
+// a legitimate "nothing installed from a third party yet" state and returns
+// an empty, schema-valid Provenance; invalid JSON or an unsupported
+// schema_version are fatal and thrown as errors — never silently degraded
+// to empty (D8f). Deliberately asymmetric with readQuarantine (see
+// quarantine.js) — do NOT "fix" this asymmetry, it is intentional. Mirrors
+// internal/thirdparty/provenance.go:LoadProvenance.
+function loadProvenance(root) {
+  const filename = provenancePath(root)
+  let data
+  try {
+    data = fs.readFileSync(filename, 'utf8')
+  } catch (err) {
+    if (err.code === 'ENOENT') return emptyProvenance()
+    throw new Error(`read thirdparty provenance: ${err.message}`)
+  }
+  let prov
+  try {
+    prov = JSON.parse(data)
+  } catch (err) {
+    throw new Error(`decode thirdparty provenance: ${err.message}`)
+  }
+  if (prov.schema_version !== PROVENANCE_SCHEMA_VERSION) {
+    throw new Error(`unsupported thirdparty provenance schema ${prov.schema_version}`)
+  }
+  if (!prov.entries || Array.isArray(prov.entries)) prov.entries = {}
+  return prov
+}
+
+// writeProvenance persists prov atomically.
+//
+// Failure here MUST propagate to the caller and abort the installation
+// (D6) — the deliberate opposite of a best-effort/log-and-continue write.
+// Provenance is the only record of who approved a third-party artifact, so
+// losing a write silently would leave an unapproved artifact on disk
+// indistinguishable from an approved one.
+//
+// Every entry's url is passed through redactURL before serialization
+// (D6-bis) — defense-in-depth, mirroring
+// internal/thirdparty/provenance.go:WriteProvenance's doc comment: no
+// command in this codebase writes a provenance entry's url today (D10.2),
+// but this call site guarantees the query string is never persisted here
+// regardless. Idempotent: redacting an already-redacted url is a no-op.
+function writeProvenance(root, prov) {
+  const entries = prov.entries || {}
+  const redactedEntries = {}
+  for (const [dest, entry] of Object.entries(entries)) {
+    redactedEntries[dest] = { ...entry, url: redactURL(entry.url) }
+  }
+  const toWrite = { schema_version: PROVENANCE_SCHEMA_VERSION, entries: redactedEntries }
+  const data = `${JSON.stringify(toWrite, null, 2)}\n`
+  atomicWrite(provenancePath(root), data, 0o600)
+}
+
+// upsertProvenanceEntry loads the current provenance, sets
+// entries[dest] = entry, and writes it back. The write is fatal-on-failure
+// (see writeProvenance) — callers MUST treat a thrown error as
+// "installation aborted", never log-and-continue. Mirrors
+// internal/thirdparty/provenance.go:UpsertProvenanceEntry.
+function upsertProvenanceEntry(root, dest, entry) {
+  const prov = loadProvenance(root)
+  prov.entries[dest] = entry
+  writeProvenance(root, prov)
+}
+
+// verifyApproval is the D8c TOCTOU close: it only succeeds if dest has a
+// provenance entry whose checksum_sha256 matches checksum exactly and whose
+// approved_by is non-empty. A destination with no entry, an entry for a
+// different checksum, or an entry with an empty approved_by all fail
+// identically: not approved. Mirrors
+// internal/thirdparty/provenance.go:VerifyApproval.
+function verifyApproval(root, checksum, dest) {
+  const prov = loadProvenance(root)
+  const entry = prov.entries[dest]
+  if (!entry) throw new Error(`no provenance entry for destination "${dest}": not approved`)
+  if (entry.checksum_sha256 !== checksum) {
+    throw new Error(`provenance checksum mismatch for "${dest}": approved ${entry.checksum_sha256}, got ${checksum}`)
+  }
+  if (!entry.approved_by) throw new Error(`provenance entry for "${dest}" has no approved_by`)
+}
+
+module.exports = { provenancePath, loadProvenance, writeProvenance, upsertProvenanceEntry, verifyApproval, PROVENANCE_SCHEMA_VERSION }

package/src/thirdparty/quarantine.js

@@ -0,0 +1,113 @@
+'use strict'
+
+// Node port of internal/thirdparty/quarantine.go — the D8a/b on-disk
+// quarantine record for one fetched third-party artifact. See:
+// docs/adr/ADR-2026-08-15-gate-de-duas-fases-para-artefatos-de-terceiro-quarentena-parecer-vinculado-por-checksum-e-deteccao-por-proveniencia-versionada.md
+// (D8a, D8b, D8f).
+
+const crypto = require('node:crypto')
+const fs = require('node:fs')
+const path = require('node:path')
+
+const { checksum: sha256hex, redactURL } = require('./markers')
+
+// QUARANTINE_SCHEMA_VERSION mirrors internal/thirdparty/quarantine.go:quarantineSchemaVersion.
+const QUARANTINE_SCHEMA_VERSION = 1
+
+// atomicWrite writes data to filename via a temp file in the same
+// directory followed by fs.renameSync, so a reader never observes a
+// partially written file. Mirrors internal/thirdparty/quarantine.go's
+// atomicWrite (shared there by quarantine.go and provenance.go; replicated
+// here and in references.js, same rationale as the Go reference's own
+// per-package duplication of Checksum in markers.go's doc comment).
+function atomicWrite(filename, data, mode) {
+  const directory = path.dirname(filename)
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 })
+  const tmp = path.join(directory, `.trackfw-tmp-${process.pid}-${crypto.randomBytes(6).toString('hex')}`)
+  try {
+    fs.writeFileSync(tmp, data, { mode })
+    fs.chmodSync(tmp, mode)
+    fs.renameSync(tmp, filename)
+  } finally {
+    if (fs.existsSync(tmp)) fs.unlinkSync(tmp)
+  }
+}
+
+// quarantinePath returns the on-disk path of the quarantine record for
+// checksum, rooted at root — the project or home directory the caller is
+// operating on. Mirrors internal/thirdparty/quarantine.go:QuarantinePath.
+function quarantinePath(root, checksum) {
+  return path.join(root, '.trackfw', 'thirdparty-quarantine', `${checksum}.json`)
+}
+
+// newQuarantineEntry builds a quarantine entry from freshly fetched content.
+// matchedMarkers is checkMarkers()'s return value for raw; an empty array
+// yields marker_check.result === "pass". The content is embedded whole,
+// base64-encoded, in content_base64 — never a path to another file (D8b):
+// an indirection through a second file would reopen the TOCTOU window the
+// quarantine record exists to close.
+//
+// rawURL is stored via redactURL, not verbatim (D6-bis) — see
+// internal/thirdparty/quarantine.go:NewQuarantineEntry's doc comment.
+function newQuarantineEntry(rawURL, raw, matchedMarkers, kind, requestedTargets) {
+  const buf = Buffer.isBuffer(raw) ? raw : Buffer.from(String(raw), 'utf8')
+  return {
+    schema_version: QUARANTINE_SCHEMA_VERSION,
+    url: redactURL(rawURL),
+    checksum_sha256: sha256hex(buf),
+    fetched_at: new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
+    content_base64: buf.toString('base64'),
+    marker_check: {
+      result: matchedMarkers.length > 0 ? 'fail' : 'pass',
+      matched_markers: matchedMarkers,
+    },
+    kind,
+    requested_targets: requestedTargets || [],
+  }
+}
+
+// writeQuarantine persists entry atomically at
+// quarantinePath(root, entry.checksum_sha256). Mirrors
+// internal/thirdparty/quarantine.go:WriteQuarantine.
+function writeQuarantine(root, entry) {
+  const toWrite = { ...entry, schema_version: QUARANTINE_SCHEMA_VERSION }
+  const data = `${JSON.stringify(toWrite, null, 2)}\n`
+  atomicWrite(quarantinePath(root, entry.checksum_sha256), data, 0o600)
+}
+
+// readQuarantine reads and validates the quarantine record for checksum,
+// fail-closed (D8f): a missing file, invalid JSON, or an unsupported
+// schema_version are all thrown as errors, never degraded to an empty
+// value. Deliberately asymmetric with loadProvenance (see provenance.js):
+// here, the caller already holds a checksum obtained from a prior fetch and
+// is asking for that specific record, so its absence is itself the failure
+// being guarded against. Do NOT "fix" this asymmetry — it is intentional,
+// verified against the Go reference by audit. Mirrors
+// internal/thirdparty/quarantine.go:ReadQuarantine.
+function readQuarantine(root, checksum) {
+  const filename = quarantinePath(root, checksum)
+  let data
+  try {
+    data = fs.readFileSync(filename, 'utf8')
+  } catch (err) {
+    throw new Error(`read quarantine entry "${checksum}": ${err.message}`)
+  }
+  let entry
+  try {
+    entry = JSON.parse(data)
+  } catch (err) {
+    throw new Error(`decode quarantine entry "${checksum}": ${err.message}`)
+  }
+  if (entry.schema_version !== QUARANTINE_SCHEMA_VERSION) {
+    throw new Error(`unsupported quarantine schema ${entry.schema_version} for "${checksum}"`)
+  }
+  return entry
+}
+
+// decodeContent decodes entry.content_base64 back to the original raw
+// bytes (a Buffer). Mirrors internal/thirdparty/quarantine.go:QuarantineEntry.DecodeContent.
+function decodeContent(entry) {
+  return Buffer.from(entry.content_base64, 'base64')
+}
+
+module.exports = { quarantinePath, newQuarantineEntry, writeQuarantine, readQuarantine, decodeContent, atomicWrite, QUARANTINE_SCHEMA_VERSION }

package/src/thirdparty/references.js

@@ -0,0 +1,194 @@
+'use strict'
+
+// Node port of the D9 extension point from internal/integrations/render.go
+// (ThirdPartyReference, UpsertThirdPartyReference, ApplyThirdPartyReferences,
+// NormalizeThirdPartyContent, ResolveThirdPartySkillDestination) — see the
+// D9 amendment in
+// docs/adr/ADR-2026-08-15-gate-de-duas-fases-para-artefatos-de-terceiro-quarentena-parecer-vinculado-por-checksum-e-deteccao-por-proveniencia-versionada.md.
+//
+// D9 note (see docs/agents-working-context.md, ML-1A entry): this file
+// persists .trackfw/thirdparty-references.json, an artifact NOT mentioned
+// by the original ADR text (D1-D8) — it exists because a plain rendered
+// catalog agent file cannot simply have a reference block appended once:
+// the next `trackfw agents update` calls buildPlans -> render again, which
+// re-derives content straight from the catalog asset and knows nothing
+// about the appended block. Persisting the reference here and having
+// buildPlans call applyThirdPartyReferences after every render (see
+// ../integrations/index.js) makes the canonical render reproduce the
+// block, so repeated `agents update` runs settle at state "current"
+// instead of fighting the third-party attachment.
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const { atomicWrite } = require('./quarantine')
+const { target: catalogTarget, surfaceFor } = require('../integrations/catalog')
+
+const THIRDPARTY_REFERENCES_SCHEMA_VERSION = 1
+
+// truncateBeforeIdSegment drops the "{{id}}"-bearing path segment and
+// everything after it, returning the shared parent directory. Duplicated
+// (not imported) from npm/src/integrations/catalog.js — that module does
+// not export it, and this ML's file list does not include editing
+// catalog.js; this is the same small, pure, low-risk duplication already
+// used by the Go reference itself (see markers.go's doc comment on
+// Checksum) rather than widening catalog.js's public surface for one
+// caller.
+function truncateBeforeIdSegment(p) {
+  const segments = p.split('/')
+  const index = segments.findIndex(segment => segment.includes('{{id}}'))
+  if (index === -1) return p
+  return segments.slice(0, index).join('/')
+}
+
+function thirdPartyReferencesPath(root) {
+  return path.join(root, '.trackfw', 'thirdparty-references.json')
+}
+
+function emptyRegistry() {
+  return { schema_version: THIRDPARTY_REFERENCES_SCHEMA_VERSION, entries: {} }
+}
+
+function loadThirdPartyReferenceRegistry(root) {
+  const filename = thirdPartyReferencesPath(root)
+  let data
+  try {
+    data = fs.readFileSync(filename, 'utf8')
+  } catch (err) {
+    if (err.code === 'ENOENT') return emptyRegistry()
+    throw new Error(`read thirdparty reference registry: ${err.message}`)
+  }
+  let reg
+  try {
+    reg = JSON.parse(data)
+  } catch (err) {
+    throw new Error(`decode thirdparty reference registry: ${err.message}`)
+  }
+  if (reg.schema_version !== THIRDPARTY_REFERENCES_SCHEMA_VERSION) {
+    throw new Error(`unsupported thirdparty reference registry schema ${reg.schema_version}`)
+  }
+  if (!reg.entries || Array.isArray(reg.entries)) reg.entries = {}
+  return reg
+}
+
+function writeThirdPartyReferenceRegistry(root, reg) {
+  const toWrite = { schema_version: THIRDPARTY_REFERENCES_SCHEMA_VERSION, entries: reg.entries || {} }
+  const data = `${JSON.stringify(toWrite, null, 2)}\n`
+  atomicWrite(thirdPartyReferencesPath(root), data, 0o600)
+}
+
+// upsertThirdPartyReference records (or replaces, keyed by ref.slug) a
+// reference from the rendered catalog agent artifact (targetID,
+// agentItemID) to a third-party skill, persisted under root (project root
+// — D4). Idempotent: calling it twice with the same slug replaces the
+// prior entry instead of duplicating it. Mirrors
+// internal/integrations/render.go:UpsertThirdPartyReference.
+function upsertThirdPartyReference(root, targetID, agentItemID, ref) {
+  const reg = loadThirdPartyReferenceRegistry(root)
+  const key = `${targetID}/${agentItemID}`
+  const refs = reg.entries[key] || []
+  let replaced = false
+  for (let i = 0; i < refs.length; i++) {
+    if (refs[i].slug === ref.slug) {
+      refs[i] = ref
+      replaced = true
+      break
+    }
+  }
+  if (!replaced) refs.push(ref)
+  refs.sort((a, b) => a.slug.localeCompare(b.slug))
+  reg.entries[key] = refs
+  writeThirdPartyReferenceRegistry(root, reg)
+}
+
+// THIRD_PARTY_REF_START/END are the composition markers (D5), dedicated and
+// distinct from the auxiliary-rules-file markers (a different subsystem).
+// Mirrors internal/integrations/render.go:thirdPartyRefStart/thirdPartyRefEnd.
+const THIRD_PARTY_REF_START = '<!-- trackfw:thirdparty-skills:start -->'
+const THIRD_PARTY_REF_END = '<!-- trackfw:thirdparty-skills:end -->'
+
+// applyThirdPartyReferences injects or updates the third-party reference
+// block in content for (targetID, agentItemID), based on entries persisted
+// by upsertThirdPartyReference. When root is empty or there are no entries
+// for this key, content is returned byte-for-byte unchanged — this is the
+// guarantee that every agent artifact which never received a third-party
+// attachment renders exactly as it did before D5/D9 were introduced.
+// Mirrors internal/integrations/render.go:ApplyThirdPartyReferences.
+function applyThirdPartyReferences(root, content, targetID, agentItemID) {
+  if (!root) return content
+  const reg = loadThirdPartyReferenceRegistry(root)
+  const refs = reg.entries[`${targetID}/${agentItemID}`] || []
+  if (!refs.length) return content
+
+  let block = `${THIRD_PARTY_REF_START}\n`
+  for (const ref of refs) {
+    block += `- Third-party skill "${ref.slug}": ${ref.destination} (source: ${ref.url})\n`
+  }
+  block += THIRD_PARTY_REF_END
+
+  let text = content
+  const start = text.indexOf(THIRD_PARTY_REF_START)
+  if (start === -1) {
+    if (!text.endsWith('\n')) text += '\n'
+    text += `\n${block}\n`
+    return text
+  }
+  // Search for the end marker starting at start, not from the beginning of
+  // text (hefesto-tf finding, ML-4C): searching the whole text could find
+  // an END marker that appears BEFORE start, producing end < start and
+  // silently corrupting the composed output. Anchoring the search at start
+  // makes that impossible: end is either -1 or >= start.
+  const relEnd = text.slice(start).indexOf(THIRD_PARTY_REF_END)
+  if (relEnd === -1) {
+    // Malformed (start without end): append a fresh block rather than
+    // guess at repair.
+    text += `\n${block}\n`
+    return text
+  }
+  const end = start + relEnd
+  const newText = text.slice(0, start) + block + text.slice(end + THIRD_PARTY_REF_END.length)
+  return `${newText.replace(/\n+$/, '')}\n`
+}
+
+// normalizeThirdPartyContent applies the same normalization used for
+// managed catalog skill content (trim + single trailing newline) to raw
+// third-party bytes before they are written through IntegrationManager, so
+// third-party artifacts are stored with the same on-disk convention as
+// catalog artifacts. Mirrors
+// internal/integrations/render.go:NormalizeThirdPartyContent.
+function normalizeThirdPartyContent(content) {
+  const text = Buffer.isBuffer(content) ? content.toString('utf8') : String(content)
+  return `${text.trim()}\n`
+}
+
+// resolveThirdPartySkillDestination computes where a third-party artifact's
+// content should live for (targetID, scope), per D5: the shared parent
+// directory of the target's own canonical project/global Skills install
+// path template, followed by "/thirdparty/<slug>.md". The directory always
+// comes from the catalog's own path template — never a hardcoded
+// ".claude" — so every target the catalog declares a Skills capability for
+// is supported without per-target special-casing. Mirrors
+// internal/integrations/render.go:ResolveThirdPartySkillDestination.
+function resolveThirdPartySkillDestination(targetID, scope, slug) {
+  let targetEntry
+  try {
+    targetEntry = catalogTarget(targetID)
+  } catch {
+    throw new Error(`unknown target "${targetID}"`)
+  }
+  const surface = surfaceFor(targetEntry, undefined, 'skills')
+  const installPath = (surface.paths.skills || []).find(entry => entry.scope === scope)
+  if (!installPath) throw new Error(`target ${targetID} surface ${surface.id} has no ${scope} skills path`)
+  const baseDir = truncateBeforeIdSegment(installPath.path)
+  return { destination: `${baseDir}/thirdparty/${slug}.md`, surfaceID: surface.id }
+}
+
+module.exports = {
+  thirdPartyReferencesPath,
+  upsertThirdPartyReference,
+  applyThirdPartyReferences,
+  normalizeThirdPartyContent,
+  resolveThirdPartySkillDestination,
+  THIRD_PARTY_REF_START,
+  THIRD_PARTY_REF_END,
+}