First public release

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

test/hand-off.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it } from 'vitest'
+import { overall, validateReport } from '@extant2000/evidence-record'
+import { assess, formatHandOff, toReport, type Capability, type Dependency } from '../src/index.js'
+
+const dep = (p: Partial<Dependency> = {}): Dependency => ({
+  name: 'deploy-token',
+  kind: 'credential',
+  coupling: 'none',
+  where: 'config/deploy.env',
+  ...p,
+})
+
+const cap = (dependencies: Dependency[]): Capability =>
+  ({ name: 'release pipeline', recipient: 'the partner ops team', dependencies })
+
+describe('a personal credential is a blocker, not a documentation gap', () => {
+  // Several products authenticating with one engineer's personal token.
+  const personal = dep({ coupling: 'person', boundTo: 'alice', where: 'config/deploy.env' })
+
+  it('blocks regardless of how much is written down', () => {
+    const v = assess(cap([personal]))
+    expect(v.readiness).toBe('blocked')
+    expect(v.blockers.map(d => d.name)).toEqual(['deploy-token'])
+  })
+
+  it('says why documentation does not help', () => {
+    const f = toReport(cap([personal])).findings[0]!
+    expect(f.severity).toBe('critical')
+    expect(f.detail).toContain('dies with the account')
+    expect(f.detail).toContain('not a documentation gap')
+  })
+
+  it('is satisfied by a recorded and exercised substitute', () => {
+    const fixed = { ...personal, substitute: 'a group deploy token per project', substituteVerified: true }
+    expect(assess(cap([fixed])).readiness).toBe('transferable')
+  })
+
+  it('blocks a machine binding for the same reason', () => {
+    // A script that hard-codes a path on one laptop runs on that laptop only.
+    const machine = dep({ name: 'node-path', kind: 'runtime', coupling: 'machine', boundTo: 'dev-laptop-1', where: 'scripts/deploy.sh' })
+    expect(assess(cap([machine])).readiness).toBe('blocked')
+    expect(toReport(cap([machine])).findings[0]!.detail)
+      .toContain('forever, for one person')
+  })
+
+  it('treats an account binding as high, not critical — transferable in principle', () => {
+    const acct = dep({ coupling: 'account', boundTo: 'ops@example.com' })
+    const f = toReport(cap([acct])).findings[0]!
+    expect(f.severity).toBe('high')
+    expect(f.detail).toContain('which is not the same as transferred')
+  })
+
+  it('blocks undocumented operating knowledge', () => {
+    const k = dep({ name: 'restore-procedure', kind: 'knowledge', coupling: 'none' })
+    expect(assess(cap([k])).readiness).toBe('blocked')
+    expect(toReport(cap([k])).findings[0]!.detail).toContain('only while the author is available')
+  })
+})
+
+describe('a runbook nobody has followed is a draft', () => {
+  const unexercised = dep({
+    coupling: 'person', boundTo: 'alice',
+    substitute: 'issue a group deploy token', substituteVerified: false,
+  })
+
+  it('reports an unexercised substitute as not-assessed, never a pass', () => {
+    // It is written down, so it looks done. That is why it survives review.
+    const f = toReport(cap([unexercised])).findings[0]!
+    expect(f.determination).toBe('not-assessed')
+    expect(f.detail).toContain('A runbook nobody has followed is a draft')
+    expect(overall(toReport(cap([unexercised])))).toBe('not-assessed')
+  })
+
+  it('gives the capability its own readiness state', () => {
+    const v = assess(cap([unexercised]))
+    expect(v.readiness).toBe('unproven')
+    expect(v.blockers).toHaveLength(0)
+    expect(v.unproven).toHaveLength(1)
+  })
+
+  it('treats a missing substituteVerified the same as false', () => {
+    const { substituteVerified, ...rest } = unexercised
+    expect(assess(cap([rest as Dependency])).readiness).toBe('unproven')
+  })
+})
+
+describe('readiness is the worst dependency, never the average', () => {
+  it('one blocker sinks nine clean dependencies', () => {
+    const nineGood = Array.from({ length: 9 }, (_, i) =>
+      dep({ name: `ok-${i}`, coupling: 'none' }))
+    const v = assess(cap([...nineGood, dep({ name: 'pat', coupling: 'person', boundTo: 'alice' })]))
+    expect(v.readiness).toBe('blocked')
+    expect(formatHandOff(cap([...nineGood, dep({ name: 'pat', coupling: 'person' })])))
+      .toContain('never the average')
+  })
+
+  it('blocked outranks unproven', () => {
+    const v = assess(cap([
+      dep({ name: 'a', coupling: 'person' }),
+      dep({ name: 'b', coupling: 'person', substitute: 'x' }),
+    ]))
+    expect(v.readiness).toBe('blocked')
+    expect(v.unproven).toHaveLength(1)   // still reported
+  })
+})
+
+describe('conformance with the evidence-record standard', () => {
+  it('no dependencies enumerated is unknown, never transferable', () => {
+    const v = assess(cap([]))
+    expect(v.readiness).toBe('unknown')
+    expect(v.reason).toContain('has not been examined — it has been assumed')
+    expect(overall(toReport(cap([])))).toBe('not-assessed')
+  })
+
+  it('every conclusion carries a citation', () => {
+    expect(validateReport(toReport(cap([
+      dep({ name: 'a', coupling: 'person' }),
+      dep({ name: 'b', coupling: 'none' }),
+    ])))).toEqual([])
+  })
+
+  it('prints the readiness verdict', () => {
+    expect(formatHandOff(cap([dep()]))).toContain('readiness: TRANSFERABLE')
+    expect(formatHandOff(cap([dep({ coupling: 'person' })]))).toContain('readiness: BLOCKED')
+  })
+})