@koreanhole/requirement-agent 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 koreanhole
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# Koreanhole Requirement Agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+요구사항 문서(스펙·기획서)를 여러 코딩 에이전트에 병렬로 리뷰시켜 모호성,
+누락, 검증 불가 항목을 **근거 인용**과 함께 찾아내는 local-first CLI + 로컬 웹 UI.
+
+## 설치
+
+```bash
+npm install -g @koreanhole/requirement-agent
+requirement-agent --help
+```
+
+Node.js 22 이상. PDF는 `pdftotext`(poppler-utils), DOCX는 `unzip`이 필요합니다.
+선택 사항: `codex`, `gemini`, `cline` 중 최소 하나.
+
+## 사용
+
+```bash
+# 리뷰 실행 (처음 실행 시 문서를 받을 에이전트 목록 확인)
+requirement-agent review ./specs --yes
+
+# 역할·에이전트·예산 지정
+requirement-agent review ./specs --roles ambiguity,testability --agent codex \
+  --max-doc-chars 60000 --max-total-chars 80000 --exclude 'drafts/**'
+
+# 결과
+requirement-agent runs
+requirement-agent show <run-id>
+requirement-agent show <run-id> --raw ambiguity
+requirement-agent export <run-id> --format md
+requirement-agent export <run-id> --format json
+
+# 로컬 웹 UI (127.0.0.1 전용, 실행마다 새 토큰)
+requirement-agent serve --allow-root ~/Documents
+```
+
+산출물 기본 위치: `${XDG_STATE_HOME:-~/.local/state}/requirement-agent/runs/<run-id>/`
+(`run.json`, `findings.json`, `report.md`, `context.json`, `snapshot.json`, `raw/`).
+
+## 동작
+
+- 입력: Markdown, TXT, PDF, DOCX — 파일 1개 또는 디렉터리
+- 6개 역할: ambiguity, completeness, testability, consistency, scope, feasibility
+- 인용 검증: 원문에서 찾으면 `located`, 여러 번 나오면 `ambiguous`,
+  없으면 `not_located`; 누락 주장은 `anchor_located`
+- 실패 격리: 한 리뷰어가 실패/타임아웃해도 나머지 결과 유지
+- 리뷰 대상 트리의 순변경은 스냅샷 비교로 탐지 (종료 코드 5)
+
+## 종료 코드
+
+`0` 성공 · `1` 사용 오류 · `2` 성공한 리뷰어 없음 · `3` 사전 점검 실패 ·
+`4` 산출물 경로가 리뷰 대상 내부 · `5` 리뷰 중 파일 변경.
+
+## 보안·한계
+
+- 로컬 단일 사용자, 웹은 loopback + 실행 토큰 + Host/Origin 검사만 지원
+- **OS 수준 샌드박스 없음**: 리뷰어는 문서의 지시를 따르지 않도록 프롬프트로
+  지시받고 read-only 모드로 실행되지만, 강제되지는 않습니다. 순변경만 탐지합니다.
+- 자격증명 스크리닝은 패턴 기반입니다. 알려진 형식(`sk-`, `ghp_`, `AKIA`,
+  Bearer, JWT 등)만 걸러지며, 미등록 형식은 통과할 수 있습니다.
+- HWP/HWPX, OCR, 다중 사용자, 원격 모드는 범위 밖입니다.
+
+## 개발
+
+```bash
+npm test          # 단위 테스트
+npm run test:e2e  # 결정적 fake agent E2E
+```
+
+Spec Kit 산출물: `specs/001-requirement-document-review/`.
+리뷰 게이트: `REVIEW-GATE.md`. 구현 시 결정: `DECISIONS.md`.
+
+## 라이선스
+
+MIT

package/bin/requirement-agent.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+main(process.argv.slice(2)).then(
+  (code) => { process.exitCode = code; },
+  (err) => {
+    process.stderr.write(`requirement-agent: ${err?.message ?? err}\n`);
+    process.exitCode = 1;
+  },
+);

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@koreanhole/requirement-agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Local-first review agent for requirement documents: parallel roles, citation-verified findings, CLI and loopback UI.",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "requirement-agent": "bin/requirement-agent.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "schemas/",
+    "public/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test tests/unit/*.test.js",
+    "test:e2e": "node --test e2e/*.e2e.mjs",
+    "check": "node scripts/check-docs.mjs"
+  },
+  "keywords": [
+    "requirements",
+    "review",
+    "specification",
+    "cli",
+    "local-first"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/koreanhole/koreanhole-requirement-agent.git"
+  }
+}

package/public/app.js

@@ -0,0 +1,76 @@
+const token = new URLSearchParams(location.search).get('token') ?? localStorage.getItem('reqagent-token') ?? '';
+if (token) localStorage.setItem('reqagent-token', token);
+const api = (path, options = {}) => fetch(path, { ...options, headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...(options.headers ?? {}) } });
+const $ = (id) => document.getElementById(id);
+const text = (tag, value, cls) => { const el = document.createElement(tag); el.textContent = value; if (cls) el.className = cls; return el; };
+
+let acknowledged = null;
+
+$('preflight').onclick = async () => {
+  const res = await api('/api/agents');
+  const body = await res.json();
+  const box = $('egress'); box.replaceChildren();
+  box.append(text('p', 'Agents that will receive document text:'));
+  acknowledged = body.agents.filter((a) => a.state !== 'missing').map((a) => a.id);
+  for (const a of body.agents) {
+    const label = document.createElement('label');
+    const cb = document.createElement('input'); cb.type = 'checkbox'; cb.checked = a.state !== 'missing'; cb.disabled = a.state === 'missing';
+    cb.onchange = () => { acknowledged = [...box.querySelectorAll('input:checked')].map((x) => x.value); };
+    cb.value = a.id;
+    label.append(cb, text('span', ` ${a.id} (${a.state})`));
+    box.append(label);
+  }
+};
+
+$('start').onclick = async () => {
+  const status = $('status'); status.replaceChildren(text('p', 'Running…'));
+  const body = {
+    path: $('path').value.trim(),
+    exclude: $('exclude').value.split(',').map((s) => s.trim()).filter(Boolean),
+    agent: $('agent').value.trim() || undefined,
+    acknowledgedEgress: acknowledged ?? [],
+  };
+  const res = await api('/api/reviews', { method: 'POST', body: JSON.stringify(body) });
+  const data = await res.json();
+  if (!res.ok) { status.replaceChildren(text('pre', JSON.stringify(data.error ?? data, null, 2))); return; }
+  await showRun(data.runId);
+  await loadRuns();
+};
+
+async function showRun(id) {
+  const res = await api(`/api/runs/${id}`);
+  const run = await res.json();
+  const findingsRes = await api(`/api/runs/${id}/findings`);
+  const findings = await findingsRes.json();
+  const box = $('status'); box.replaceChildren();
+  box.append(text('h2', `Run ${run.runId} — ${run.status}`));
+  box.append(text('p', `blocker ${run.counts?.findingsBySeverity?.blocker ?? 0} · major ${run.counts?.findingsBySeverity?.major ?? 0} · minor ${run.counts?.findingsBySeverity?.minor ?? 0}`));
+  const sections = ['located', 'anchor_only', 'ambiguous', 'partial', 'unlocated'];
+  for (const section of sections) {
+    const list = findings.filter((f) => f.locatorState === section);
+    if (!list.length) continue;
+    box.append(text('h3', `${section} (${list.length})`));
+    for (const f of list) {
+      const div = document.createElement('div'); div.className = 'finding';
+      div.append(text('div', `${f.id} · ${f.severity} · ${f.roles.join(', ')}`, `sev-${f.severity}`));
+      for (const c of f.citations) {
+        div.append(text('div', `${c.document} ${c.lineStart ? `lines ${c.lineStart}-${c.lineEnd}` : '(no line range)'} · ${c.status}`));
+        div.append(text('pre', c.quote));
+      }
+      for (const c of f.contributions) div.append(text('p', `${c.role}: ${c.explanation}`));
+      box.append(div);
+    }
+  }
+}
+
+async function loadRuns() {
+  const res = await api('/api/runs');
+  const { runs } = await res.json();
+  const box = $('runs'); box.replaceChildren(text('h2', 'History'));
+  for (const run of runs) {
+    const btn = text('button', `${run.runId} · ${run.status} · ${run.counts?.findingsBySeverity?.total ?? 0} findings`);
+    btn.onclick = () => showRun(run.runId);
+    box.append(btn);
+  }
+}
+loadRuns();

package/public/index.html

@@ -0,0 +1,40 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Requirement Agent</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font: 15px/1.5 system-ui, sans-serif; max-width: 960px; margin: 2rem auto; padding: 0 1rem; }
+  fieldset { border: 1px solid #8884; border-radius: 8px; margin: 1rem 0; }
+  label { display: block; margin: .35rem 0; }
+  input[type=text] { width: 100%; padding: .45rem; }
+  button { padding: .5rem .9rem; margin-top: .5rem; cursor: pointer; }
+  pre { white-space: pre-wrap; word-break: break-word; background: #8881; padding: .8rem; border-radius: 8px; }
+  .finding { border-top: 1px solid #8884; padding: .8rem 0; }
+  .sev-blocker { color: #d33; font-weight: 700; }
+  .sev-major { color: #c80; font-weight: 600; }
+  .muted { color: #888; }
+</style>
+</head>
+<body>
+<h1>Requirement Agent</h1>
+<p class="muted">Local only. Document text goes to the agents you confirm.</p>
+
+<fieldset>
+  <legend>New review</legend>
+  <label>Path <input id="path" type="text" placeholder="/absolute/path/to/specs"></label>
+  <label>Exclude globs (comma separated) <input id="exclude" type="text" placeholder="drafts/**, *.tmp"></label>
+  <label>Agent <input id="agent" type="text" placeholder="(per-role default)"></label>
+  <button id="preflight">Check agents</button>
+  <button id="start">Start review</button>
+  <div id="egress"></div>
+</fieldset>
+
+<div id="status"></div>
+<div id="runs"></div>
+
+<script type="module" src="/app.js"></script>
+</body>
+</html>

package/schemas/findings.input.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://koreanhole.local/requirement-agent/findings-input.schema.json",
+  "title": "ReviewerOutput",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["findings"],
+  "properties": {
+    "findings": {
+      "type": "array",
+      "maxItems": 50,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["severity", "citations", "explanation"],
+        "properties": {
+          "severity": { "enum": ["blocker", "major", "minor"] },
+          "evidenceKind": { "enum": ["quoted", "absent"] },
+          "citations": {
+            "type": "array", "minItems": 1, "maxItems": 12,
+            "items": {
+              "type": "object", "additionalProperties": false,
+              "required": ["document", "quote"],
+              "properties": {
+                "document": { "type": "string" },
+                "quote": { "type": "string" },
+                "section": { "type": ["string", "null"] },
+                "lineHint": { "type": ["integer", "null"] }
+              }
+            }
+          },
+          "explanation": { "type": "string" },
+          "suggestion": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/src/agents.js

@@ -0,0 +1,131 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { accessSync, constants, readFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const QUOTE = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+
+function onPath(bin) {
+  for (const dir of (process.env.PATH ?? '').split(':')) {
+    try { accessSync(join(dir, bin), constants.X_OK); return true; } catch { /* next */ }
+  }
+  return false;
+}
+
+export class Adapter {
+  constructor(id) { this.id = id; }
+  probe() {
+    if (this.id === 'fake') return process.env.REQUIREMENT_AGENT_FAKE ? 'authenticated' : 'missing';
+    return onPath(this.bin) ? 'authenticated' : 'missing';
+  }
+  supportsModel() { return true; }
+}
+
+export class FakeAdapter extends Adapter {
+  constructor() { super('fake'); this.bin = 'node'; }
+  async run({ prompt, cwd, timeoutMs, onStart }) {
+    const script = process.env.REQUIREMENT_AGENT_FAKE;
+    if (!script) return { status: 'failed', error: 'REQUIREMENT_AGENT_FAKE is not set', raw: '' };
+    return runProcess(process.execPath, [script], { prompt, cwd, timeoutMs, onStart });
+  }
+}
+
+export class CodexAdapter extends Adapter {
+  constructor() { super('codex'); this.bin = 'codex'; }
+  async run({ prompt, schemaPath, cwd, timeoutMs, model, onStart }) {
+    if (!onPath('script')) return { status: 'failed', error: 'script utility missing; codex needs a pty', raw: '' };
+    const dir = mkdtempSync(join(tmpdir(), 'reqagent-'));
+    const out = join(dir, 'out.json');
+    const cmd = [
+      'codex exec --sandbox read-only --skip-git-repo-check',
+      `-C ${QUOTE(cwd)}`, `--output-schema ${QUOTE(schemaPath)}`,
+      model ? `-m ${QUOTE(model)}` : '', `-o ${QUOTE(out)} -`,
+    ].filter(Boolean).join(' ');
+    try {
+      const res = await runProcess('script', ['-qfc', `${cmd}; printf '\\n__AGENT_EXIT=%s\\n' $?`, '/dev/null'], { prompt, cwd, timeoutMs, onStart });
+      const code = Number((res.raw.match(/__AGENT_EXIT=(\d+)/) ?? [])[1] ?? 0);
+      let parsed = res.output;
+      try { parsed = JSON.parse(readFileSync(out, 'utf8')); } catch { /* stdout fallback */ }
+      if (code !== 0) return { ...res, status: 'failed', error: `codex exited ${code}` };
+      return { ...res, output: parsed, status: 'succeeded' };
+    } finally { rmSync(dir, { recursive: true, force: true }); }
+  }
+}
+
+export class GeminiAdapter extends Adapter {
+  constructor() { super('gemini'); this.bin = 'gemini'; }
+  async run({ prompt, cwd, timeoutMs, model, onStart }) {
+    const args = ['-p', '-', '-o', 'json', '--approval-mode', 'plan'];
+    if (model) args.push('-m', model);
+    return runProcess('gemini', args, { prompt, cwd, timeoutMs, onStart });
+  }
+}
+
+export class ClineAdapter extends Adapter {
+  constructor() { super('cline'); this.bin = 'cline'; }
+  async run({ prompt, cwd, timeoutMs, model, onStart }) {
+    const args = ['-p', '--auto-approve', 'false'];
+    if (model) args.push('-m', model);
+    return runProcess('cline', args, { prompt, cwd, timeoutMs, onStart });
+  }
+}
+
+export function createAdapter(id) {
+  switch (id) {
+    case 'fake': return new FakeAdapter();
+    case 'codex': return new CodexAdapter();
+    case 'gemini': return new GeminiAdapter();
+    case 'cline': return new ClineAdapter();
+    default: throw new Error(`unknown agent: ${id}`);
+  }
+}
+
+export const AGENT_IDS = ['codex', 'gemini', 'cline'];
+
+export function probeAgents() {
+  return ['fake', ...AGENT_IDS].map((id) => ({ id, state: createAdapter(id).probe() }));
+}
+
+function runProcess(cmd, args, { prompt, cwd, timeoutMs, onStart }) {
+  return new Promise((resolvePromise) => {
+    const child = spawn(cmd, args, { cwd, stdio: ['pipe', 'pipe', 'pipe'], detached: true });
+    onStart?.(child.pid);
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try { process.kill(-child.pid, 'SIGKILL'); } catch { try { child.kill('SIGKILL'); } catch { /* gone */ } }
+    }, timeoutMs);
+    child.stdout.on('data', (d) => { stdout += d.toString(); });
+    child.stderr.on('data', (d) => { stderr += d.toString(); });
+    child.on('error', (err) => { clearTimeout(timer); resolvePromise({ status: 'failed', output: null, raw: stderr, error: err.message }); });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (timedOut) return resolvePromise({ status: 'timed_out', output: null, raw: `${stdout}\n${stderr}`, error: `timed out after ${timeoutMs}ms` });
+      if (code !== 0) return resolvePromise({ status: 'failed', output: null, raw: `${stdout}\n${stderr}`, error: `exit ${code}` });
+      const parsed = extractJson(stdout);
+      if (!parsed) return resolvePromise({ status: 'invalid_output', output: null, raw: `${stdout}\n${stderr}`, error: 'no JSON object in output' });
+      resolvePromise({ status: 'succeeded', output: parsed, raw: `${stdout}\n${stderr}`, error: null });
+    });
+    child.stdin.end(prompt);
+  });
+}
+
+export function extractJson(text) {
+  const s = String(text ?? '');
+  for (let i = s.lastIndexOf('{'); i >= 0; i = s.lastIndexOf('{', i - 1)) {
+    const tail = s.slice(i);
+    try { return JSON.parse(tail); } catch { /* keep scanning */ }
+    const end = tail.lastIndexOf('}');
+    if (end > 0) { try { return JSON.parse(tail.slice(0, end + 1)); } catch { /* continue */ } }
+  }
+  return null;
+}
+
+export function sshQuote(s) { return QUOTE(s); }
+export function verifyEscaping() {
+  const probe = `x'; echo PWNED; echo '$(id)`;
+  const r = spawnSync('sh', ['-c', `printf %s ${QUOTE(probe)}`]);
+  return r.stdout.toString() === probe;
+}

package/src/citations.js

@@ -0,0 +1,114 @@
+import { createHash } from 'node:crypto';
+
+const MIN_QUOTE_CHARS = 8;
+
+export function normalizeWithMap(input) {
+  const s = String(input ?? '').normalize('NFC');
+  let out = '';
+  const map = [];
+  let pendingSpace = false;
+  for (let i = 0; i < s.length; i += 1) {
+    const ch = s[i];
+    if (/\s/.test(ch)) { pendingSpace = out.length > 0; continue; }
+    if (pendingSpace) { out += ' '; map.push(i); pendingSpace = false; }
+    const folded = ch.toLowerCase();
+    for (let k = 0; k < folded.length; k += 1) { out += folded[k]; map.push(i); }
+  }
+  return { text: out, map };
+}
+
+export const normalize = (input) => normalizeWithMap(input).text;
+
+export function countLines(text, index) {
+  let line = 1;
+  for (let i = 0; i < index && i < text.length; i += 1) if (text[i] === '\n') line += 1;
+  return line;
+}
+
+export function lineRange(text, start, end) {
+  const lineStart = countLines(text, start);
+  const lineEnd = countLines(text, Math.max(start, end - 1));
+  return { lineStart, lineEnd };
+}
+
+export function sectionFor(text, lineStart) {
+  if (!lineStart) return null;
+  const lines = text.split('\n');
+  for (let i = Math.min(lineStart - 1, lines.length - 1); i >= 0; i -= 1) {
+    const m = lines[i].match(/^\s{0,3}(#{1,6})\s+(.+?)\s*#*\s*$/);
+    if (m) return m[2].trim();
+  }
+  return null;
+}
+
+export function makeCitation(document, quote, section = null, lineHint = null) {
+  return { document, quote, section, lineHint, lineStart: null, lineEnd: null, status: 'not_located', reason: null };
+}
+
+export function verifyCitation(citation, doc) {
+  const out = { ...citation, lineStart: null, lineEnd: null, section: citation.section ?? null, status: 'not_located', reason: null };
+  if (!doc) { out.reason = 'document_not_found'; return out; }
+  const raw = String(citation.quote ?? '');
+  const nq = normalize(raw).replace(/^ | $/g, '');
+  if (nq.replace(/\s/g, '').length < MIN_QUOTE_CHARS) { out.reason = 'quote_too_short'; return out; }
+  const { text, map } = normalizeWithMap(doc.text);
+  const hits = [];
+  let idx = text.indexOf(nq);
+  while (idx !== -1) { hits.push(idx); idx = text.indexOf(nq, idx + 1); }
+  if (!hits.length) { out.reason = 'quote_not_found'; return out; }
+  let chosen = null;
+  if (hits.length === 1) chosen = hits[0];
+  else if (citation.lineHint != null) {
+    chosen = hits.find((h) => lineRange(doc.text, map[h], map[h] + nq.length).lineStart === Number(citation.lineHint)) ?? null;
+    if (chosen == null) { out.status = 'ambiguous'; out.reason = 'repeated_occurrence'; return out; }
+  } else { out.status = 'ambiguous'; out.reason = 'repeated_occurrence'; return out; }
+  const start = map[chosen];
+  const end = map[chosen + nq.length - 1] + 1;
+  const range = lineRange(doc.text, start, end);
+  out.lineStart = range.lineStart;
+  out.lineEnd = range.lineEnd;
+  out.section = sectionFor(doc.text, out.lineStart);
+  out.status = 'located';
+  return out;
+}
+
+export function verifyFinding(finding, docsByPath) {
+  const citations = (finding.citations ?? []).map((c) => {
+    const doc = docsByPath.get(c.document);
+    if (finding.evidenceKind === 'absent') {
+      const out = { ...c, lineStart: null, lineEnd: null, section: c.section ?? null, status: 'not_located', reason: null };
+      if (!doc) { out.reason = 'document_not_found'; return out; }
+      const anchor = normalize(String(c.quote ?? ''));
+      if (anchor.replace(/\s/g, '').length < MIN_QUOTE_CHARS) { out.reason = 'quote_too_short'; return out; }
+      const { text, map } = normalizeWithMap(doc.text);
+      const at = text.indexOf(anchor);
+      if (at === -1) { out.reason = 'anchor_not_found'; return out; }
+      const start = map[at];
+      const end = map[at + anchor.length - 1] + 1;
+      const range = lineRange(doc.text, start, end);
+      out.lineStart = range.lineStart;
+      out.lineEnd = range.lineEnd;
+      out.section = sectionFor(doc.text, out.lineStart);
+      out.status = 'anchor_located';
+      return out;
+    }
+    return verifyCitation(c, doc);
+  });
+  const statuses = citations.map((c) => c.status);
+  let locatorState = 'unlocated';
+  if (statuses.length && statuses.every((s) => s === 'located')) locatorState = 'located';
+  else if (statuses.length && statuses.every((s) => s === 'anchor_located')) locatorState = 'anchor_only';
+  else if (statuses.length && statuses.every((s) => s === 'ambiguous')) locatorState = 'ambiguous';
+  else if (statuses.some((s) => s === 'located' || s === 'anchor_located')) locatorState = 'partial';
+  return { ...finding, citations, locatorState };
+}
+
+export function citationDigest(citation, docPath) {
+  const line = citation.lineStart ?? -1;
+  return `${docPath}\u0000${createHash('sha256').update(normalize(citation.quote)).digest('hex')}\u0000${line}`;
+}
+
+export function findingIdentity(finding) {
+  const basis = [...(finding.citations ?? []).map((c) => citationDigest(c, c.document))].sort().join('|');
+  return createHash('sha256').update(`${finding.evidenceKind}\u0000${basis}`).digest('hex');
+}