@agfpd/iapeer 0.2.33 → 0.2.35

package/src/identity/profileStandard.ts

@@ -0,0 +1,218 @@
+// Profile standard — the CODE-formalized schema of peer-profile.json, the source
+// of truth being the contract zone "Идентичность пира — модель, профиль, реестр".
+//
+// Two classes of fields (contract §"структура — два класса полей, не плоская каша"):
+//   • CORE identity (foundation-owned, validated here): personality (system mirror,
+//     self-heal = normalize(basename(cwd))), default_runtime (contract field; legacy
+//     `runtime` accepted during the staged migration), runtimes[] (incl. the default,
+//     ORDER = preference, first = primary), description, intelligence ∈
+//     {artificial|natural|absent}. Optional lifecycle: initial_prompt, wake_policy.
+//   • OWNER sections (validated only as well-typed, NEVER restructured here): interfaces
+//     (telegram/capability passport), aliases (legacy persistent-peer → contract
+//     relocates to interfaces.telegram.aliases, telegram-runtime owns the migration),
+//     notifier (notifier-runtime), <plugin> sections — each plugin writes only its own
+//     field via atomic merge.
+//
+// peers-profiles.json is a regenerable self-heal PROJECTION of the local profiles —
+// projectProfileToRecord builds the record the index SHOULD hold; verify compares the
+// live index against it, reindex rewrites it. The index is never the source of truth.
+
+import { basename } from 'path'
+import { isRuntime, normalizeIntelligenceValue, normalizeNameCandidate } from '../core/constants.ts'
+import {
+  clampDescription,
+  readPeersIndex,
+  updatePeersIndex,
+  type PeerRecord,
+  type PeersUpdateOptions,
+} from '../registry/index.ts'
+import { readPeerProfile } from './index.ts'
+
+export type IssueSeverity = 'error' | 'warn'
+export interface ProfileIssue {
+  severity: IssueSeverity
+  field: string
+  message: string
+}
+
+/**
+ * Validate a RAW peer-profile.json object (already JSON-parsed) against the standard.
+ * `cwd` is required for the personality self-heal check (the mirror must equal
+ * normalize(basename(cwd))). Returns every issue found; an `error` means the profile
+ * is non-conformant, a `warn` is a transition/owner note that self-heal or a later
+ * owner migration resolves (a profile with only warnings still PASSES — `isConformant`).
+ */
+export function validateProfileStandard(raw: unknown, cwd: string): ProfileIssue[] {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return [{ severity: 'error', field: '<root>', message: 'peer-profile.json must be a JSON object' }]
+  }
+  const obj = raw as Record<string, unknown>
+  const issues: ProfileIssue[] = []
+
+  // personality — system mirror, self-healed from the cwd (never a source). A stored
+  // value that disagrees is a WARN (self-heal rewrites it), not an error.
+  const expected = normalizeNameCandidate(basename(cwd))
+  if (typeof obj.personality !== 'string' || obj.personality !== expected) {
+    issues.push({
+      severity: 'warn',
+      field: 'personality',
+      message: `mirror "${String(obj.personality ?? '')}" ≠ normalize(basename(cwd)) "${expected}" — self-heal will rewrite`,
+    })
+  }
+
+  // default_runtime (contract) / runtime (legacy, staged migration).
+  const dr = obj.default_runtime ?? obj.runtime
+  if (!isRuntime(dr)) {
+    issues.push({ severity: 'error', field: 'default_runtime', message: `must be a valid runtime id, got "${String(dr ?? '')}"` })
+  } else if (obj.default_runtime === undefined) {
+    issues.push({ severity: 'warn', field: 'default_runtime', message: 'legacy field name `runtime` — standard is `default_runtime` (staged migration)' })
+  }
+
+  // runtimes[] — array of valid runtime ids that includes the default_runtime.
+  if (!Array.isArray(obj.runtimes)) {
+    issues.push({ severity: 'error', field: 'runtimes', message: 'must be an array of runtime ids' })
+  } else {
+    for (const r of obj.runtimes) {
+      if (!isRuntime(r)) issues.push({ severity: 'error', field: 'runtimes', message: `invalid runtime "${String(r)}"` })
+    }
+    if (isRuntime(dr) && !(obj.runtimes as unknown[]).includes(dr)) {
+      issues.push({ severity: 'error', field: 'runtimes', message: `must include the default_runtime "${dr}"` })
+    }
+  }
+
+  // description — string (may be empty).
+  if (obj.description !== undefined && typeof obj.description !== 'string') {
+    issues.push({ severity: 'error', field: 'description', message: 'must be a string' })
+  }
+
+  // intelligence — artificial|natural|absent (legacy human|scripted accepted on read).
+  if (obj.intelligence !== undefined && !normalizeIntelligenceValue(obj.intelligence)) {
+    issues.push({
+      severity: 'error',
+      field: 'intelligence',
+      message: `must be artificial|natural|absent (legacy human|scripted accepted), got "${String(obj.intelligence)}"`,
+    })
+  }
+
+  // Optional lifecycle fields (foundation-owned).
+  if (obj.initial_prompt !== undefined && typeof obj.initial_prompt !== 'string') {
+    issues.push({ severity: 'error', field: 'initial_prompt', message: 'must be a string' })
+  }
+  if (obj.wake_policy !== undefined && obj.wake_policy !== 'ephemeral') {
+    issues.push({ severity: 'warn', field: 'wake_policy', message: `unknown value "${String(obj.wake_policy)}" — only 'ephemeral' is honored` })
+  }
+
+  // Owner sections — well-typed only; foundation never restructures them.
+  if (obj.interfaces !== undefined && (typeof obj.interfaces !== 'object' || obj.interfaces === null || Array.isArray(obj.interfaces))) {
+    issues.push({ severity: 'error', field: 'interfaces', message: 'must be a JSON object' })
+  }
+  // Legacy top-level aliases — contract relocates to interfaces.telegram.aliases with
+  // the /alias-* namespace (clean slash-keys are reserved for the control layer).
+  // telegram-runtime owns that migration; flagged, not an error.
+  if (obj.aliases !== undefined) {
+    issues.push({
+      severity: 'warn',
+      field: 'aliases',
+      message: 'legacy top-level `aliases` — contract relocates to interfaces.telegram.aliases (/alias-* namespace); telegram-runtime migration pending',
+    })
+  }
+
+  return issues
+}
+
+/** A profile passes the standard when it has no `error`-severity issues. */
+export function isConformant(issues: readonly ProfileIssue[]): boolean {
+  return !issues.some(i => i.severity === 'error')
+}
+
+/**
+ * The PeerRecord the index SHOULD hold for the peer at `cwd`, projected from its LOCAL
+ * profile (the self-heal source of truth) — readPeerProfile already self-heals the
+ * personality mirror and dual-reads default_runtime/runtime. null when the cwd has no
+ * profile. Used by verify (compare against the live index) and reindex (rewrite it).
+ */
+export function projectProfileToRecord(cwd: string): PeerRecord | null {
+  const profile = readPeerProfile(cwd)
+  if (!profile) return null
+  return {
+    personality: profile.personality,
+    runtime: profile.runtime,
+    runtimes: profile.runtimes,
+    // The registry clamps the description to MAX_DESCRIPTION_LEN on read; project the
+    // SAME clamp so a long local description (timer/watcher run ~1000 chars) does not
+    // read back as a perpetual drift the index can never physically close.
+    description: clampDescription(profile.description).description,
+    intelligence: profile.intelligence,
+    cwd,
+    ...(profile.interfaces ? { interfaces: profile.interfaces } : {}),
+  }
+}
+
+/** The index↔local drift for one peer: the fields where the live registry record
+ *  disagrees with the projection from the local profile (the self-heal source). Empty
+ *  array = in sync. cwd is the registry pointer, never compared. */
+export function recordDrift(indexRecord: PeerRecord, projected: PeerRecord): string[] {
+  const drift: string[] = []
+  if (indexRecord.personality !== projected.personality) drift.push('personality')
+  if (indexRecord.runtime !== projected.runtime) drift.push('default_runtime')
+  if (indexRecord.runtimes.join(',') !== projected.runtimes.join(',')) drift.push('runtimes')
+  if (indexRecord.description !== projected.description) drift.push('description')
+  if (indexRecord.intelligence !== projected.intelligence) drift.push('intelligence')
+  return drift
+}
+
+export interface ReconcileEntry {
+  personality: string
+  cwd: string
+  /** null when the local profile is absent (the registry points at a gone cwd). */
+  drift: string[] | null
+}
+
+/** READ-ONLY index↔local reconciliation: per registry entry, the drift vs its local
+ *  profile projection (drift=null → local profile missing). The read-only half of the
+ *  self-heal invariant — verify reports it, reindex repairs it. */
+export function reconcileIndex(options: PeersUpdateOptions = {}): ReconcileEntry[] {
+  const index = readPeersIndex(options)
+  return index.peers.map(rec => {
+    const projected = projectProfileToRecord(rec.cwd)
+    return {
+      personality: rec.personality,
+      cwd: rec.cwd,
+      drift: projected ? recordDrift(rec, projected) : null,
+    }
+  })
+}
+
+/**
+ * Self-heal the index: REPLACE every registry record with the projection from its
+ * local profile (the source of truth). Unlike upsertPeer (which UNIONs runtimes so a
+ * boot never drops one), reindex is a deliberate REWRITE — it is how a local profile's
+ * narrowed runtimes (e.g. arthur dropped to [telegram]) propagate to the index. A peer
+ * whose local profile is missing is left untouched (and surfaced in `missing`). The
+ * legacy-safe intelligenceRaw is preserved when the nature is unchanged (never silently
+ * migrate the live vocab — the human→natural incident class).
+ */
+export async function reindexFromLocals(
+  options: PeersUpdateOptions = {},
+): Promise<{ healed: string[]; missing: string[] }> {
+  const healed: string[] = []
+  const missing: string[] = []
+  await updatePeersIndex(index => {
+    const peers = index.peers.map(rec => {
+      const projected = projectProfileToRecord(rec.cwd)
+      if (!projected) {
+        missing.push(rec.personality)
+        return rec
+      }
+      const drift = recordDrift(rec, projected)
+      if (drift.length > 0) healed.push(`${rec.personality}: ${drift.join(', ')}`)
+      const intelligenceRaw =
+        rec.intelligenceRaw !== undefined && normalizeIntelligenceValue(rec.intelligenceRaw) === projected.intelligence
+          ? rec.intelligenceRaw
+          : undefined
+      return { ...projected, ...(intelligenceRaw !== undefined ? { intelligenceRaw } : {}) }
+    })
+    return { ...index, peers }
+  }, options)
+  return { healed, missing }
+}

package/src/launch/composeSystemPrompt.layers.test.ts

@@ -97,15 +97,28 @@ describe('composeSystemPrompt — layer 4 (other domains)', () => {
     expect(out).not.toMatch(/\n{4,}/) // no 3+ blank lines = no empty block injected
   })
 
-  test('within a domain, global precedes local (general → specific)', () => {
+  test('within a domain, global precedes local (general → specific), each its own section', () => {
     const out = composeSystemPrompt({
       ...base,
       pluginDomains: [dom({ domain: 'MM', global: 'mm-global', local: 'mm-local' })],
     })
-    expect(out).toContain('mm-global\nmm-local')
+    // per-file now: global and local are SEPARATE sections (blank line between),
+    // not a tight single-newline merge
+    expect(out).toContain('mm-global\n\nmm-local')
     expect(out.indexOf('mm-global')).toBeLessThan(out.indexOf('mm-local'))
   })
 
+  test('per-file path markers: each half carries its <!-- path --> marker', () => {
+    const out = composeSystemPrompt({
+      ...base,
+      pluginDomains: [
+        dom({ domain: 'MM', global: 'mm-global\n', globalPath: '~/.iapeer/MERGEMIND.md', local: 'mm-local\n', localPath: '~/p/.iapeer/MERGEMIND.md' }),
+      ],
+    })
+    expect(out).toContain('<!-- ~/.iapeer/MERGEMIND.md -->\nmm-global')
+    expect(out).toContain('<!-- ~/p/.iapeer/MERGEMIND.md -->\nmm-local')
+  })
+
   test('layer 4 sits after layer 3; domains kept in the order given', () => {
     const out = composeSystemPrompt({
       ...base,
@@ -156,7 +169,7 @@ describe('composeSystemPrompt — layer 5 (doctrine fragments)', () => {
       ...base,
       promptFragments: [frag({ domain: 'MEM', global: 'mem-guide', local: 'mem-index' })],
     })
-    expect(out).toContain('mem-guide\nmem-index')
+    expect(out).toContain('mem-guide\n\nmem-index') // per-file: separate sections
     expect(out.indexOf('mem-guide')).toBeLessThan(out.indexOf('mem-index'))
   })
 
@@ -268,13 +281,19 @@ describe('gatherPromptInput — FS discovery of all 4 layers', () => {
     expect((input.pluginDomains ?? []).map(d => d.domain)).toEqual(['AAA', 'MARKER', 'MERGEMIND', 'ZZZ'])
   })
 
-  test('layer 4: per-domain global/local halves resolved correctly', () => {
+  test('layer 4: per-domain global/local halves resolved correctly, each with its display path', () => {
     const input = gather()
     const byName = Object.fromEntries((input.pluginDomains ?? []).map(d => [d.domain, d]))
-    expect(byName.MERGEMIND).toEqual({ domain: 'MERGEMIND', global: 'mm-global\n', local: 'mm-local\n' })
-    expect(byName.AAA).toEqual({ domain: 'AAA', global: 'aaa-global-only\n' })
-    expect(byName.ZZZ).toEqual({ domain: 'ZZZ', local: 'zzz-local-only\n' })
-    expect(byName.MARKER).toEqual({ domain: 'MARKER', local: '' }) // present but empty
+    expect(byName.MERGEMIND).toEqual({
+      domain: 'MERGEMIND',
+      global: 'mm-global\n',
+      globalPath: join(globalRoot, 'MERGEMIND.md'),
+      local: 'mm-local\n',
+      localPath: join(localRoot, 'MERGEMIND.md'),
+    })
+    expect(byName.AAA).toEqual({ domain: 'AAA', global: 'aaa-global-only\n', globalPath: join(globalRoot, 'AAA.md') })
+    expect(byName.ZZZ).toEqual({ domain: 'ZZZ', local: 'zzz-local-only\n', localPath: join(localRoot, 'ZZZ.md') })
+    expect(byName.MARKER).toEqual({ domain: 'MARKER', local: '', localPath: join(localRoot, 'MARKER.md') }) // present but empty
   })
 
   test('layer 5: fragments/ subdir scanned, paired by stem (guide global + index local), sorted', () => {
@@ -282,8 +301,16 @@ describe('gatherPromptInput — FS discovery of all 4 layers', () => {
     const frags = input.promptFragments ?? []
     expect(frags.map(f => f.domain)).toEqual(['iapeer-memory', 'other-primitive'])
     const byName = Object.fromEntries(frags.map(f => [f.domain, f]))
-    expect(byName['iapeer-memory']).toEqual({ domain: 'iapeer-memory', global: 'mem-guide\n', local: 'mem-index\n' })
-    expect(byName['other-primitive']).toEqual({ domain: 'other-primitive', global: 'other-frag\n' })
+    const gfrag = join(globalRoot, 'fragments')
+    const lfrag = join(localRoot, 'fragments')
+    expect(byName['iapeer-memory']).toEqual({
+      domain: 'iapeer-memory',
+      global: 'mem-guide\n',
+      globalPath: join(gfrag, 'iapeer-memory.md'),
+      local: 'mem-index\n',
+      localPath: join(lfrag, 'iapeer-memory.md'),
+    })
+    expect(byName['other-primitive']).toEqual({ domain: 'other-primitive', global: 'other-frag\n', globalPath: join(gfrag, 'other-primitive.md') })
     // the non-.md notes.txt never became a fragment
     expect(frags.map(f => f.domain)).not.toContain('notes')
   })
@@ -320,12 +347,15 @@ describe('gatherPromptInput — FS discovery of all 4 layers', () => {
     expect(prompt).toContain('## Known peers')
     expect(prompt).toContain('- arthur — owner')
     expect(prompt).toContain('- boris — PM')
-    // Layer 4 (markers excluded, others merged, sorted)
+    // Layer 4 (presence-marker file excluded, others per-file with path markers, sorted)
     expect(prompt).toContain('aaa-global-only')
-    expect(prompt).toContain('mm-global\nmm-local')
     expect(prompt).toContain('zzz-local-only')
-    // Layer 5 (fragments: guide+index paired, global-only fragment)
-    expect(prompt).toContain('mem-guide\nmem-index')
+    // global half then a fresh marker then the local half (each its own marked section)
+    expect(prompt).toContain(`<!-- ${join(globalRoot, 'MERGEMIND.md')} -->\nmm-global`)
+    expect(prompt).toContain(`mm-global\n\n<!-- ${join(localRoot, 'MERGEMIND.md')} -->\nmm-local`)
+    // Layer 5 (fragments: guide+index paired as separate marked sections, global-only fragment)
+    expect(prompt).toContain(`<!-- ${join(globalRoot, 'fragments', 'iapeer-memory.md')} -->\nmem-guide`)
+    expect(prompt).toContain(`mem-guide\n\n<!-- ${join(localRoot, 'fragments', 'iapeer-memory.md')} -->\nmem-index`)
     expect(prompt).toContain('other-frag')
 
     const order = [
@@ -357,10 +387,13 @@ describe('gatherPromptInput — FS discovery of all 4 layers', () => {
     expect(input.pluginDomains).toEqual([])
     expect(input.promptFragments).toEqual([]) // no fragments/ subdir → empty layer
     expect(input.peers).toEqual([])
-    // composes to just the YAML block (+ empty doctrine), no extra layers
+    // composes to just the YAML block (no doctrine, no layers); the per-file
+    // assembly normalizes the single section's trailing newlines to exactly one.
     const prompt = composeSystemPrompt(input)
     expect(prompt).not.toContain('## Known peers')
-    expect(prompt.endsWith('---\n\n')).toBe(true)
+    expect(prompt).not.toContain('<!--') // no files → no markers
+    expect(prompt.endsWith('---\n')).toBe(true)
+    expect(prompt.endsWith('---\n\n')).toBe(false)
   })
 
   test('doctrine excluded from Layer 4 case-INSENSITIVELY; .MD ext picked up (verify edge-lens fix)', () => {

package/src/launch/composeSystemPrompt.test.ts

@@ -1,8 +1,8 @@
-// Golden-equivalence test: composeSystemPrompt MUST produce byte-for-byte the
-// same output as the real jq doctrine-merge in claude-start.sh:264-290. Each
-// case runs the ACTUAL jq pipeline (extracted verbatim) and the TS function,
-// then byte-compares. This is the durable form of the Ф3 adversarial-verify
-// (which caught a 1-byte divergence on the empty-global-file case).
+// composeSystemPrompt — the YAML identity block (Layer 1) stays byte-for-byte the
+// claude-start.sh:264-290 jq layout (the durable golden); the file-sourced layers
+// (2/4/5) are now rendered PER FILE, each prefixed by a `<!-- <path> -->` marker.
+// This test pins BOTH: the jq-equivalent YAML prefix, and the marker format /
+// empty-file-drops rules of the per-file assembly.
 
 import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
 import { spawnSync } from 'child_process'
@@ -15,7 +15,7 @@ import type { ComposePromptInput } from './types.ts'
 let dir: string
 let jqProg: string
 
-// The jq program verbatim from claude-start.sh:274-284.
+// The jq program verbatim from claude-start.sh:274-284 — the YAML identity block.
 const JQ_PROGRAM = `"---",
 "personality: \\($personality | @json)",
 "description: \\($description | @json)",
@@ -39,16 +39,9 @@ beforeAll(() => {
 })
 afterAll(() => rmSync(dir, { recursive: true, force: true }))
 
-/** Run the exact bash/jq pipeline; `globalDoctrine` undefined = file absent. */
-function bashReference(input: ComposePromptInput): string {
-  const peerPath = join(dir, 'peer.md')
-  writeFileSync(peerPath, input.peerDoctrine)
-  let globalBlock = ''
-  if (input.globalDoctrine !== undefined) {
-    const gp = join(dir, 'global.md')
-    writeFileSync(gp, input.globalDoctrine)
-    globalBlock = `if [ -f ${shq(gp)} ]; then cat ${shq(gp)}; printf "\\n"; fi`
-  }
+/** The jq YAML identity block alone (no doctrine appended) — the byte-for-byte
+ *  Layer-1 golden every composed prompt must START with. */
+function jqYamlBlock(input: ComposePromptInput): string {
   const script = `set -e
 jq -n --raw-output \
   --arg personality ${shq(input.personality)} \
@@ -59,9 +52,7 @@ jq -n --raw-output \
   --arg user ${shq(input.user)} \
   --arg hostname ${shq(input.hostname)} \
   --arg today ${shq(input.today)} \
-  -f ${shq(jqProg)}
-${globalBlock}
-cat ${shq(peerPath)}`
+  -f ${shq(jqProg)}`
   const r = spawnSync('bash', ['-c', script], { encoding: 'utf8' })
   if (r.status !== 0) throw new Error(`bash reference failed: ${r.stderr}`)
   return r.stdout
@@ -77,22 +68,78 @@ const base = {
   today: '2026-06-06',
 }
 
-const cases: Array<{ name: string; input: ComposePromptInput }> = [
-  { name: 'basic, no global', input: { ...base, description: 'owner', peerDoctrine: 'Be helpful.\n' } },
-  { name: 'present non-empty global', input: { ...base, description: 'owner', peerDoctrine: 'peer\n', globalDoctrine: 'GLOBAL\n' } },
-  { name: 'EMPTY-but-present global (the 1-byte divergence the verify caught)', input: { ...base, description: 'owner', peerDoctrine: 'peer', globalDoctrine: '' } },
-  { name: 'hostile description: colon + quote + newline', input: { ...base, description: 'a: "b"\nc', peerDoctrine: 'doc\n' } },
-  { name: 'unicode + emoji description', input: { ...base, description: 'Артур 🦊 №2', peerDoctrine: 'док\n', globalDoctrine: 'гл\n' } },
-  { name: 'multiline peer doctrine, no trailing newline', input: { ...base, description: 'd', peerDoctrine: 'line1\nline2' } },
-  { name: 'description with backslash and slash', input: { ...base, description: 'a\\b/c', peerDoctrine: 'x\n' } },
-]
-
-describe('composeSystemPrompt golden-equivalence vs claude-start.sh jq', () => {
+// ─────────────────────────────────────────────────────────────────────────────
+// Layer 1 — the YAML identity block is byte-for-byte the jq layout
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('composeSystemPrompt — Layer 1 YAML block is byte-for-byte the jq layout', () => {
+  const cases: Array<{ name: string; input: ComposePromptInput }> = [
+    { name: 'basic', input: { ...base, description: 'owner', peerDoctrine: 'Be helpful.\n' } },
+    { name: 'hostile description: colon + quote + newline', input: { ...base, description: 'a: "b"\nc', peerDoctrine: 'doc\n' } },
+    { name: 'unicode + emoji description', input: { ...base, description: 'Артур 🦊 №2', peerDoctrine: 'док\n' } },
+    { name: 'description with backslash and slash', input: { ...base, description: 'a\\b/c', peerDoctrine: 'x\n' } },
+    { name: 'empty description', input: { ...base, description: '', peerDoctrine: 'x\n' } },
+  ]
   for (const c of cases) {
     test(c.name, () => {
-      const ref = bashReference(c.input)
-      const got = composeSystemPrompt(c.input)
-      expect(got).toBe(ref)
+      const yaml = jqYamlBlock(c.input)
+      // the composed prompt opens with the exact jq YAML block (the `---…---\n\n`)
+      expect(composeSystemPrompt(c.input).startsWith(yaml)).toBe(true)
     })
   }
 })
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Layer 2 — IAPEER.md doctrine is rendered per-file with a path marker
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('composeSystemPrompt — per-file path markers (Layer 2 doctrine)', () => {
+  const input: ComposePromptInput = {
+    ...base,
+    description: 'owner',
+    peerDoctrine: 'Be the implementer.\n',
+    peerDoctrinePath: '~/Peers/arthur/.iapeer/IAPEER.md',
+    globalDoctrine: 'Host rules.\n',
+    globalDoctrinePath: '~/.iapeer/IAPEER.md',
+  }
+
+  test('each doctrine file is prefixed by its <!-- path --> marker, global before local', () => {
+    const out = composeSystemPrompt(input)
+    expect(out).toContain('<!-- ~/.iapeer/IAPEER.md -->\nHost rules.')
+    expect(out).toContain('<!-- ~/Peers/arthur/.iapeer/IAPEER.md -->\nBe the implementer.')
+    expect(out.indexOf('<!-- ~/.iapeer/IAPEER.md -->')).toBeLessThan(
+      out.indexOf('<!-- ~/Peers/arthur/.iapeer/IAPEER.md -->'),
+    )
+  })
+
+  test('marker sits AFTER the YAML block (one blank line between)', () => {
+    const out = composeSystemPrompt(input)
+    expect(out).toContain('---\n\n<!-- ~/.iapeer/IAPEER.md -->')
+  })
+
+  test('a path-less content (pure-renderer caller) renders WITHOUT a marker', () => {
+    const out = composeSystemPrompt({ ...base, description: 'd', peerDoctrine: 'no marker here\n' })
+    expect(out).toContain('no marker here')
+    expect(out).not.toContain('<!--')
+  })
+
+  test('an EMPTY doctrine file contributes no section and no dangling marker', () => {
+    const out = composeSystemPrompt({
+      ...base,
+      description: 'd',
+      peerDoctrine: 'real\n',
+      peerDoctrinePath: '~/p/IAPEER.md',
+      globalDoctrine: '', // present but empty → dropped
+      globalDoctrinePath: '~/.iapeer/IAPEER.md',
+    })
+    expect(out).not.toContain('~/.iapeer/IAPEER.md') // empty global marker absent
+    expect(out).toContain('<!-- ~/p/IAPEER.md -->\nreal')
+  })
+
+  test('output ends with exactly one newline; no 3+ blank-line gaps', () => {
+    const out = composeSystemPrompt(input)
+    expect(out.endsWith('\n')).toBe(true)
+    expect(out.endsWith('\n\n')).toBe(false)
+    expect(out).not.toMatch(/\n{3,}/)
+  })
+})